前言
Luban是一个强大的游戏配置管理工具，支持多种数据格式和编程语言。本教程将详细介绍如何将Luban集成到CocosCreator项目中，实现高效的配置数据管理。
Luban简介
Luban是一个专业的游戏配置管理工具，具有以下特点：
- 多格式支持：支持JSON、二进制等多种数据格式
- 多语言支持：支持TypeScript、C#、Java等多种编程语言
- 类型安全：自动生成类型安全的访问代码
- 高效性能：二进制格式提供更快的加载速度和更小的文件体积
- 易于维护：Excel编辑，支持数据验证和引用检查
项目结构概览
本教程的项目结构如下：
bash
LubanDemo/
├── LubanConfig/ # Luban配置目录
│ ├── luban.conf # Luban主配置文件
│ ├── genjson.bat # JSON格式生成脚本
│ ├── genBin.bat # 二进制格式生成脚本
│ ├── Datas/ # 数据源目录
│ │ ├── __tables__.xlsx # 表定义
│ │ ├── __beans__.xlsx # Bean定义
│ │ ├── __enums__.xlsx # 枚举定义
│ │ ├── #item.xlsx # 道具表数据
│ │ ├── #role.xlsx # 角色表数据
│ │ └── reward.xlsx # 奖励表数据
│ └── Defines/
│ └── builtin.xml # 内置类型定义
├── Tools/Luban/ # Luban工具目录
└── assets/ # CocosCreator资源目录
├── resources/
│ ├── configJson/ # JSON配置文件
│ └── configBin/ # 二进制配置文件
└── Script/
└── Config/
├── ConfigManager.ts # 配置管理器
├── schema/ # JSON格式Schema
├── BinSchema/ # 二进制格式Schema
└── luban/ # 二进制Luban运行时库环境准备
1. 安装.NET运行时
Luban是基于.NET开发的工具，需要安装.NET运行时环境。
2. 下载Luban工具
将Luban工具文件放置在Tools/Luban/目录下，包含以下关键文件：
Luban.dll- 主程序Luban.Typescript.dll- TypeScript支持- 其他依赖库文件
3. CocosCreator项目准备
确保已创建CocosCreator项目，并准备好TypeScript开发环境。
Luban配置详解
主配置文件 (luban.conf)
json
{
"groups": [
{"names":["c"], "default":true}, // 客户端组
{"names":["s"], "default":true}, // 服务器组
{"names":["e"], "default":true} // 编辑器组
],
"schemaFiles": [
{"fileName":"Defines", "type":""},
{"fileName":"Datas/__tables__.xlsx", "type":"table"},
{"fileName":"Datas/__beans__.xlsx", "type":"bean"},
{"fileName":"Datas/__enums__.xlsx", "type":"enum"}
],
"dataDir": "Datas",
"targets": [
{"name":"server", "manager":"Tables", "groups":["s"], "topModule":"cfg"},
{"name":"client", "manager":"Tables", "groups":["c"], "topModule":"cfg"},
{"name":"all", "manager":"Tables", "groups":["c","s","e"], "topModule":"cfg"}
]
}配置说明：
groups: 定义数据分组，可用于区分客户端、服务器等不同用途的数据schemaFiles: 定义元数据文件，包括表定义、Bean定义和枚举定义dataDir: 数据文件所在目录targets: 定义生成目标，可指定不同的生成格式和输出目录
数据表设计
1. 表定义 (tables.xlsx)
在__tables__.xlsx中定义配置表的基本信息：
| 表名 | 变量名 | 分组 | 备注 |
|---|---|---|---|
| item | Tbitem | c | 道具表 |
| role | Tbrole | c | 角色表 |
| reward | TbReward | c | 奖励表 |
2. 枚举定义 (enums.xlsx)
定义游戏中使用的枚举类型：
| 枚举名 | 变量名 | 值 | 注释 |
|---|---|---|---|
| MyColor | RED | 1 | 红色 |
| MyColor | GREEN | 2 | 绿色 |
| MyColor | BLUE | 3 | 蓝色 |
| MyColor | WHITE | 4 | 白色 |
3. 数据表示例
道具表 (#item.xlsx)
| id | name | desc | count |
|---|---|---|---|
| 1001 | 道具1 | 描述1 | 10 |
| 1002 | 道具2 | 描述2 | 100 |
奖励表 (reward.xlsx)
| id | name | desc | count | x1 |
|---|---|---|---|---|
| 1001 | 奖励1 | 碎片 | 100 | 1 |
| 1002 | 奖励2 | 金币 | 1000 | 2 |
生成脚本配置
JSON格式生成脚本 (genjson.bat)
batch
set WORKSPACE=..
set LUBAN_DLL=%WORKSPACE%\Tools\Luban\Luban.dll
set CONF_ROOT=.
dotnet %LUBAN_DLL% ^
-t client ^
-d json ^
-c typescript-json ^
--conf %CONF_ROOT%\luban.conf ^
-x outputDataDir=%WORKSPACE%\assets\resources\configJson ^
-x outputCodeDir=%WORKSPACE%\assets\Script\Config\schema
pause二进制格式生成脚本 (genBin.bat)
batch
set WORKSPACE=..
set LUBAN_DLL=%WORKSPACE%\Tools\Luban\Luban.dll
set CONF_ROOT=.
dotnet %LUBAN_DLL% ^
-t client ^
-d bin ^
-c typescript-bin ^
--conf %CONF_ROOT%\luban.conf ^
-x outputDataDir=%WORKSPACE%\assets\resources\configBin ^
-x outputCodeDir=%WORKSPACE%\assets\Script\Config\BinSchema ^
-x bin.fileExt=bin
pause参数说明：
-t client: 指定目标为客户端-d json/bin: 指定数据格式（JSON或二进制）-c typescript-json/typescript-bin: 指定代码生成器--conf: 配置文件路径-x outputDataDir: 数据文件输出目录-x outputCodeDir: 代码文件输出目录-x bin.fileExt: 数据文件后缀格式（这个很重要）
CocosCreator集成
1. 配置管理器 (ConfigManager.ts)
typescript
import ByteBuf from './luban/ByteBuf';
import * as cfg from './schema/schema';
import * as binCfg from './BinSchema/schema';
import { Asset, BufferAsset, JsonAsset, resources } from 'cc';
export class ConfigManager {
public static tables: cfg.Tables = null;
public static tables_bin: binCfg.Tables = null;
private static dataMap = new Map<string, any>();
public static async loadDir<T extends Asset>(path: string): Promise<T[]> {
return new Promise((resolve, reject) => {
resources.loadDir<T>(path, (err, res) => {
if (err) {
reject(err);
} else {
resolve(res);
}
});
});
}
// 加载JSON格式配置
public static async loadAllJsonConfig() {
try {
let datas = await this.loadDir<JsonAsset>('configJson');
datas.forEach((data) => {
ConfigManager.dataMap.set(data.name, data.json);
});
ConfigManager.tables = new cfg.Tables((file_name: string) => ConfigManager.dataMap.get(file_name));
} catch (error) {
throw error;
}
}
// 加载二进制格式配置
public static async loadAllBinConfig() {
try {
let datas = await this.loadDir<BufferAsset>('configBin');
datas.forEach((data) => {
ConfigManager.dataMap.set(data.name, new Uint8Array(data.buffer().slice(0, data.buffer().byteLength)));
});
ConfigManager.tables_bin = new binCfg.Tables((file_name: string) => new ByteBuf(ConfigManager.dataMap.get(file_name)));
} catch (error) {
console.log(error);
throw error;
}
}
}2. ByteBuf运行时库
ByteBuf运行时库可以从luban_examples\Projects\TypeScript_Cocos3_bin或者luban_examples\Projects\TypeScript_Cocos2_bin中拷贝
Luban提供了ByteBuf类用于处理二进制数据的读写操作，支持：
- 变长整数编码
- 字符串编码
- 浮点数处理
- 高效的内存管理
使用示例
1. 基本使用
typescript
import { ConfigManager } from './Config/ConfigManager';
export class Test extends Component {
async testConfig() {
// 使用JSON方式加载
await ConfigManager.loadAllJsonConfig();
const reward = ConfigManager.tables.TbReward.get(1001);
console.log(`奖励名称: ${reward.name}, 数量: ${reward.count}`);
// 使用二进制方式加载
//await ConfigManager.loadAllBinConfig();
//const rewardBin = ConfigManager.tables_bin.TbReward.get(1001);
//console.log(`奖励名称: ${rewardBin.name}, 数量: ${rewardBin.count}`);
}
}📂 核心代码与完整示例： LubanDemo
结语
点个赞，关注我获取更多实用 CocosCreator 技术干货！如果觉得有用，记得收藏本文！