focus-creative-games/luban: a game config pipeline that compiles Excel into code and data

What luban actually replaces in a game project

Every project with more than a few hundred configuration rows eventually grows a private exporter: a script that reads spreadsheets, emits a data file, and emits a matching set of structs or classes. That script is usually correct for the first format and quietly wrong for the fifth. Luban takes that role and standardizes it. It reads source data from the Excel family (csv, tsv, xls, xlsx, xlsm) plus json, xml, yaml and lua, and writes data out as binary, json, bson, xml, lua or yaml, with generated code for c#, java, go, cpp, lua, python, javascript, typescript, rust, php, erlang and godot. The README describes the goal as covering the configuration workflow of projects from small to very large.

The audience is not only programmers. The README states the project standardizes the game configuration workflow and raises the efficiency of designers and programmers alike, which is the honest description of a tool whose input format is a spreadsheet. Designers keep editing tables; the pipeline is what changes. The second audience is tooling developers: the README calls the generation pipeline modular and plugin-friendly and says adapting luban to a custom configuration format is straightforward. If you have ever maintained a bespoke exporter, that sentence is the actual pitch.

What it is not is a runtime library. Nothing here loads your tables at runtime for you; it produces code and data files that your engine loads. That boundary explains most of the design choices below.

The type system is the reason to use it, not the file conversion

Converting xlsx to json is a solved problem. The interesting part of luban is that it gives you a real type system over the tables, and the README singles out one feature in particular: support for OOP type inheritance. That is what lets a table describe behaviour trees, skills, story scripts or dungeon definitions, where the rows are not uniform records but variants of a common shape. A flat row-and-column model forces you to either flatten those variants into nullable columns or split them across tables and join them by hand. Inheritance lets the schema express the variant directly.

On top of the types sit the validation rules the README lists: ref checks, path checks for resource paths, range checks, and more. This is the difference between a converter and a compiler. A converter will happily emit a table where a skill references a monster id that does not exist, and you find out at runtime. A pipeline with ref checking fails the build instead. The same logic applies to localisation, which the README lists as a supported feature rather than an afterthought.

Two smaller decisions are worth noting because they constrain later choices. The README states the generated code calls no reflection interfaces, and that this keeps it compatible with obfuscation and hardening tools such as Obfuz, Obfuscator, Confuser and .Net Refactor. For teams shipping with HybridCLR, ILRuntime, xlua or puerts, that is a real constraint on how the generated code can be written, and it is a deliberate one.

The trade-off is that a type system has to be described somewhere, and that description is a new artifact your team maintains. The README does not claim the schema writes itself.

Install and a first export

The README does not give install commands. It points to the official documentation and to a quick start page at https://www.datable.cn/docs/guide/install, and it points to a separate examples repository, focus-creative-games/luban_examples, with mirrors on GitHub and Gitee. Get the tool from those sources; the repository itself is the source tree, not a package listing.

What the repository does document is how to run its own tests, which is also the fastest way to confirm a working .NET environment before you point luban at your own tables. The README gives this command:

dotnet test src/Luban.Tests/Luban.Tests.csproj

According to the README, the main repository carries xUnit integration tests that do not depend on the external luban_examples repository. The fixtures and expected outputs live in tests/fixtures/ and tests/golden/. If you change export behaviour, the README says to refresh the golden files with either of these:

pwsh tests/scripts/update-goldens.ps1

bash tests/scripts/update-goldens.sh

There is also an environment variable that updates golden files in place while tests run: set LUBAN_UPDATE_GOLDEN=1. That is the extent of the runnable commands the README supplies. For the actual configuration workflow, the schema definition format, the table layout rules and the export flags, the README defers entirely to the documentation site, so budget time for reading it before your first real table.

On the AI side, the README states that from 5.0.0 onward luban exposes machine-readable schema and errors through -c schema-json and --errorFormat json, plus a Luban.Agent CLI for validation, table lookup and describe, and a Luban.Mcp server for IDE tool invocation. The repository keeps these resources under the ai/ directory. Those are the documented entry points; the exact flags and their output shapes are in the AI documentation, not in the README.

Where the pipeline breaks down

The first limitation is geographic and linguistic. The README's primary text is Chinese, with a separate README_EN.md for English, and the documentation site is the same. The README does not state which parts of the docs are translated. If your team cannot read Chinese, expect to work from the English README and the examples repository, and expect gaps.

The second is the schema burden. Every validation luban performs is validation against a schema you wrote. If the schema is loose, ref checks and range checks have nothing to enforce. Teams that expect the tool to infer intent from the spreadsheets will be disappointed; the README frames the value as the type system plus the checks, and both are authored artifacts.

The third is the Excel layout. The README advertises an enhanced Excel format that can express simple lists, substructures, lists of structures and deeply nested structures. That expressiveness comes with layout rules. A table that a human reads comfortably is not automatically a table luban reads correctly, and the README does not promise otherwise. Migrating an existing pile of spreadsheets is the risky part of adoption, not the export step.

The fourth is the AI surface. The README marks AI Native as a 5.0.0-and-later capability, and the release history shows v5.0.0, v5.1.0 and v4.12.0 all landing within days of each other in September 2026. Features that new move quickly. Treat the Skills, the Agent CLI and the MCP server as interfaces that can shift between minor versions, and pin the luban version your build uses.

Finally, luban is the wrong tool when your configuration is small and stable. A few hundred rows read once at startup does not justify a schema, a pipeline and a code generation step. The README's own framing is projects from small to very large, but the cost curve favours the large end.

Alternatives and how they differ in approach

The README names the message-scheme alternatives directly: protobuf (schema plus binary plus json), flatbuffers (schema plus json) and msgpack (binary). Luban supports all three as export targets, so the comparison is not luban versus protobuf; it is luban versus using protobuf or flatbuffers alone.

The difference in approach is where the schema comes from and what it can express. With protobuf or flatbuffers you write the schema by hand in .proto or .fbs, and your designers then have to fit their tables to it. There is no spreadsheet step, no ref checking against other tables, and no notion of a designer editing the source of truth. You get a mature serialization format with bindings in many languages, and you own the entire path from spreadsheet to schema yourself.

Luban inverts that. The schema is the primary artifact, the spreadsheets are structured to match it, and the export formats are outputs. You get validation, localisation and code generation for a long list of languages in exchange for adopting luban's table conventions and its schema language. If your team already writes .proto files and is happy doing so, luban adds a layer rather than removing one.

Flatbuffers is the sharper contrast on the runtime side. It is designed for zero-copy reads of serialized data, and luban can emit flatbuffers schema and json as one of its targets. So the honest framing is: flatbuffers is a data format, luban is the pipeline that can produce that format along with the typed accessors and the checks.

Licence, maintenance and what an upgrade costs

Luban is MIT licensed, per the README and the LICENSE file at the repository root. MIT is permissive: you can use, modify and redistribute it, including in closed-source products, provided the copyright notice and permission notice are preserved. That is the general shape of the licence, not legal advice; read LICENSE and your own counsel's guidance for your situation. The README does not discuss generated-code licensing separately, and it does not describe any commercial edition or support contract, so there is no dual-licensing question raised by the material.

The repository is not archived, and the last push was on 2026-09-10. Releases are frequent and versioned, with v5.1.0 (table variant support) on 2026-09-10, v5.0.0 (AI Native) on 2026-09-07 and v4.12.0 on the same day. That cadence is a maintenance cost as much as a benefit: minor versions carry named features, and 5.0.0 introduced a whole AI surface.

The upgrade cost is concentrated in generated output. The repository ships golden files under tests/golden/ precisely because export behaviour is expected to change; the README provides update-goldens.ps1, update-goldens.sh and the LUBAN_UPDATE_GOLDEN=1 variable for refreshing them. If you generate code and data into your project, a luban upgrade can change that output, which means a diff in your repository and a recompile. Pin the version, regenerate deliberately, and read the release notes for the version you are moving to rather than tracking the main branch.

Editorial conclusion

Adopt luban if your project already has more than a handful of config tables and at least one non-programmer editing them, because the type system and the ref/path/range checks are what you are buying, not the export step. Skip it if your configuration is a few dozen rows that a hand-written parser handles, or if you cannot commit to keeping the schema definitions and the source tables in step, since luban validates against the schema rather than against your intentions. Before you commit, verify three things against your own tables: that your Excel layout survives the enhanced Excel format rules, that the languages and export formats you need appear in the documented lists, and that the generated code compiles in your engine version. The AI Native surface added in 5.0.0 is the part that will change fastest, so treat the Skills, Luban.Agent and Luban.Mcp entry points as versioned dependencies rather than as a stable interface.

Frequently asked questions

Official sources

1. focus-creative-games/luban on GitHub
2. License: MIT
3. Project website
4. README
5. Releases