Luban集成CocosCreator完整教程

烛阴2025-11-26 10:25

前言

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 技术干货！如果觉得有用，记得收藏本文！

相关推荐
恋猫de小郭1 天前
Flutter Zero 是什么？它的出现有什么意义？为什么你需要了解下？
android·前端·flutter
崔庆才丨静觅1 天前
hCaptcha 验证码图像识别 API 对接教程
前端
passerby60611 天前
完成前端时间处理的另一块版图
前端·github·web components
掘了1 天前
「2025 年终总结」在所有失去的人中，我最怀念我自己
前端·后端·年终总结
崔庆才丨静觅1 天前
实用免费的 Short URL 短链接 API 对接说明
前端
崔庆才丨静觅1 天前
5分钟快速搭建 AI 平台并用它赚钱！
前端
崔庆才丨静觅1 天前
比官方便宜一半以上！Midjourney API 申请及使用
前端
Moment1 天前
富文本编辑器在 AI 时代为什么这么受欢迎
前端·javascript·后端
崔庆才丨静觅1 天前
刷屏全网的“nano-banana”API接入指南！0.1元/张量产高清创意图，开发者必藏
前端
剪刀石头布啊1 天前
jwt介绍
前端
热门推荐
01GitHub 镜像站点02Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services03openclaw配置教程（linux+局域网ollama）04UV安装并设置国内源05Linux下V2Ray安装配置指南06AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南07openclaw使用nginx反代部署过程 与disconnected (1008): pairing required解决08Claude Code Skills 实用使用手册09在Trae中使用Pencil MCP10OpenClaw Chrome扩展使用教程 - 浏览器中继控制