luban是一个强大、易用、优雅、稳定的游戏配置解决方案。它设计目标为满足从小型到超大型游戏项目的简单到复杂的游戏配置工作流需求。
luban可以处理丰富的文件类型，支持主流的语言，可以生成多种导出格式，支持丰富的数据检验功能，具有良好的跨平台能力，并且生成极快。 luban有清晰优雅的生成管线设计，支持良好的模块化和插件化，方便开发者进行二次开发。开发者很容易就能将luban适配到自己的配置格式，定制出满足项目要求的强大的配置工具。
luban标准化了游戏配置开发工作流，可以极大提升策划和程序的工作效率。
- 丰富的源数据格式。支持excel族(csv,xls,xlsx,xlsm)、json、xml、yaml、lua等
- 丰富的导出格式。 支持生成binary、json、bson、xml、lua、yaml等格式数据
- 增强的excel格式。可以简洁地配置出像简单列表、子结构、结构列表，以及任意复杂的深层次的嵌套结构
- 完备的类型系统。不仅能表达常见的规范行列表，由于支持OOP类型继承，能灵活优雅表达行为树、技能、剧情、副本之类复杂GamePlay数据
- 支持多种的语言。内置支持生成c#、java、go、cpp、lua、python、typescript、rust、php、erlang 等语言代码，同时还能通过protobuf之类消息方案支持其他语言
- 支持主流的消息方案。 protobuf(schema + binary + json)、flatbuffers(schema + json)、msgpack(binary)
- 强大的数据校验能力。ref引用检查、path资源路径、range范围检查等等
- 完善的本地化支持
- 支持所有主流的游戏引擎和平台。支持Unity、Unreal、Cocos2x、Godot、微信小游戏等
- 良好的跨平台能力。能在Win,Linux,Mac平台良好运行。
- 支持所有主流的热更新方案。hybridclr、ilruntime、{x,t,s}lua、puerts等
- 清晰优雅的生成管线，很容易在luban基础上进行二次开发，定制出适合自己项目风格的配置工具。
在不破坏原有代码生成目标的前提下，新增一组以原目标名称追加 -split 后缀的代码生成目标。
split 目标用于将生成代码拆分为更细粒度的文件：定义信息输出到面向阅读、审查和 AI 上下文使用的 Def 文件中，解析、加载和运行时代码保留在 Impl 或运行时文件中。这样在只关注单个配置类型时，可以读取对应的 Def 文件，而不需要读取完整的全量 schema 文件。
命名规则：
原代码生成目标 + -split
已支持的 split 目标：
| 语言 | 目标 |
|---|---|
| C# | cs-simple-json-split, cs-bin-split, cs-dotnet-json-split, cs-dotnet-bin-split |
| Go | go-json-split, go-bin-split |
| Rust | rust-json-split, rust-bin-split |
| C++ | cpp-rawptr-bin-split, cpp-sharedptr-bin-split |
| Java | java-json-split, java-bin-split |
| TypeScript | typescript-json-split, typescript-bin-split, typescript-protobuf-split |
| Python | python-json-split |
| Lua | lua-bin-split, lua-lua-split |
| PHP | php-json-split |
| GDScript | gdscript-json-split |
拆分规则按语言能力保持一致语义：
- C#、Go、C++ 输出 Def/Impl 风格文件，便于区分定义上下文和运行时实现。
- Java 由于不支持跨文件拆分同一个 public class，输出运行时类和
XxxDef定义伴生类。 - TypeScript、Python、Lua、PHP、GDScript 保留运行时 schema 文件，同时额外输出每个类型对应的
*.def.*定义文件。
本地验收脚本：
BASE=/tmp/luban-split-code-targets-acceptance scripts/accept-split-code-targets.sh
在项目中。经常会出现语言表在协作的时候有冲突。这个时候就需要按照每个模块来做表格文件本身的分离，已经不是Sheet的分离的问题了。所以将本地化文件夹配置支持文件夹下的所有文件都识别为本地化文件。
- l10n.provider=
gameframex
这里必须为 gameframex 否则会导致本地化文件识别失败。
- l10n.textFile.path=
./Excels/Tables/Localization/
这里值必须为 文件夹路径 否则会导致本地化文件识别失败。
导出参数参考
--xargs l10n.provider=gameframex --xargs l10n.textFile.keyFieldName=key --xargs l10n.textFile.path=./Excels/Tables/Localization/
--xargs tableImporter.name=gameframex
格式 [任意字母]-[导出的表名称]-[导出的组名]-[表名称注释].xlsx
表格以任意字母-开头。
中间部分的表名称为英文且不能有空格可以有下划线
导出的组名称必须是定义的s、 c 之一，可选
后面表名称注释可以接任意长度。程序只取第一个- 和第二个- 之间的内容加上 Tb 为最终表名称。
L-Localization.xlsx => TbLocalization
C-Achievement-成就表.xlsx => TbAchievement
C-Achievement-成就表-AAA.xlsx => TbAchievement
C-Achievement-成就表-AAA-BBB.xlsx => TbAchievement
C-Achievement-成就表-AAA-BBB-CCC.xlsx => TbAchievement
C-Achievement-s-成就表.xlsx => TbAchievement, 当前导出目标为 s 时才会导出
C-Achievement-c-成就表-AAA.xlsx => TbAchievement, 当前导出目标为 c 时才会导出
C-Achievement-s-成就表-AAA-BBB.xlsx => TbAchievement, 当前导出目标为 s 时才会导出
C-Achievement-c-成就表-AAA-BBB-CCC.xlsx => TbAchievement, 当前导出目标为 c 时才会导出
Luban 提供 Docker 镜像，版本 tag 与 Git tag 保持一致，使用无 v 前缀的 SemVer 格式，例如 3.12.0。
镜像地址：
| Registry | Image |
|---|---|
| Docker Hub | docker.io/gameframex/gameframex-luban:<version> |
| GitHub Container Registry | ghcr.io/gameframex/gameframex-luban:<version> |
| Aliyun Container Registry | <ALIYUN_REGISTRY_URL>/<ALIYUN_NAMESPACE>/gameframex-luban:<version> |
示例：
docker run --rm docker.io/gameframex/gameframex-luban:3.12.0 --help在当前项目目录中运行 Luban 时，可以挂载工作目录：
docker run --rm -v "$PWD:/work" -w /work docker.io/gameframex/gameframex-luban:3.12.0 --help发布镜像只提供精确版本 tag，不提供 latest、3、3.12 等浮动 tag。
- QQ群: 692890842 （Luban开发交流群）
- discord: https://discord.gg/dGY4zzGMJ4
- 邮箱: luban@code-philosophy.com
Luban is licensed under the MIT license