# Technical Documentation: focus-creative-games/luban

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/focus-creative-games/luban)

### Overview (`README.md`)

# Luban



[](https://opensource.org/licenses/MIT) 

**中文** | [English](./README_EN.md)

luban是一个强大、易用、优雅、稳定的游戏配置解决方案。它设计目标为满足从小型到超大型游戏项目的简单到复杂的游戏配置工作流需求。

luban可以处理丰富的文件类型，支持主流的语言，可以生成多种导出格式，支持丰富的数据检验功能，具有良好的跨平台能力，并且生成极快。
luban有清晰优雅的生成管线设计，支持良好的模块化和插件化，方便开发者进行二次开发。开发者很容易就能将luban适配到自己的配置格式，定制出满足项目要求的强大的配置工具。

luban标准化了游戏配置开发工作流，可以极大提升策划和程序的工作效率。

自 **5.0.0** 起，Luban 面向 AI Agent / IDE 提供 **AI Native** 能力：官方 Skills、机器可读 schema 与报错、`Luban.Agent` CLI，以及 MCP Server，让加表、查 schema、校验与生成可以稳定地交给 Agent 完成。

## 核心特性

- 丰富的源数据格式。支持excel族(csv,tsv,xls,xlsx,xlsm)、json、xml、yaml、lua等
- 丰富的导出格式。 支持生成binary、json、bson、xml、lua、yaml等格式数据
- 增强的excel格式。可以简洁地配置出像简单列表、子结构、结构列表，以及任意复杂的深层次的嵌套结构
- 完备的类型系统。不仅能表达常见的规范行列表，由于**支持OOP类型继承**，能灵活优雅表达行为树、技能、剧情、副本之类复杂GamePlay数据
- 支持多种的语言。内置支持生成c#、java、go、cpp、lua、python、javascript、typescript、rust、php、erlang、godot 等语言代码，同时还能通过protobuf之类消息方案支持其他语言
- 支持主流的消息方案。 protobuf(schema + binary + json)、flatbuffers(schema + json)、msgpack(binary)
- 强大的数据校验能力。ref引用检查、path资源路径、range范围检查等等
- 完善的本地化支持
- **AI Native（5.0.0+）**。官方 Agent Skills、`-c schema-json`、`--errorFormat json`、`Luban.Agent`（校验 / 查表 / describe）、`Luban.Mcp`（IDE 工具调用）
- 支持所有主流的游戏引擎和平台。支持Unity、Unreal、Cocos2x、Godot、微信小游戏等
- 良好的跨平台能力。能在Win,Linux,Mac平台良好运行。
- 支持所有主流的热更新方案。hybridclr、ilruntime、{x,t,s}lua、puerts等
- 生成的代码未调用任何反射接口，兼容[Obfuz](https://github.com/focus-creative-games/obfuz)、Obfuscator、Confuser、.Net Refactor等常见代码混淆和加固工具。
- 清晰优雅的生成管线，很容易在luban基础上进行二次开发，定制出适合自己项目风格的配置工具。

## 文档

- [官方文档](https://www.datable.cn/docs/intro)
- [快速上手](https://www.datable.cn/docs/guide/install)
- [AI 支持（Skills / Agent / MCP / schema-json）](https://www.datable.cn/docs/ai/overview)
- **示例项目** ([github](https://github.com/focus-creative-games/luban_examples)) ([gitee](https://gitee.com/focus-creative-games/luban_examples))

仓库内 AI 资源见 [`ai/`](./ai/README.md)。

## 开发者：运行测试

主仓自带 xUnit 集成测试（不依赖外部 `luban_examples`）：

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

- 夹具与期望输出：`tests/fixtures/`、`tests/golden/`
- 刷新 golden（改导出行为后）：`pwsh tests/scripts/update-goldens.ps1` 或 `bash tests/scripts/update-goldens.sh`
- 也可在跑测试时设置环境变量 `LUBAN_UPDATE_GOLDEN=1` 就地更新 golden

## 支持与联系

- QQ群: 692890842 （Luban开发交流群）
- discord: <https://discord.gg/dGY4zzGMJ4>
- 邮箱: <luban@code-philosophy.com>

## license

Luban is licensed under the [MIT](https://github.com/focus-creative-games/luban/blob/main/LICENSE) license

---

### Overview (`ai/README.md`)

# Luban AI 资源

本目录提供官方 Agent Skills，与文档站「AI 支持」章节配套。

## 内容

- `skills/`：可复制到 `.cursor/skills/` 的 Skill 包
- 源码侧能力：
  - `src/Luban.Agent`：Agent CLI（validate / schema / list-tables / describe）
  - 主 `Luban`：`-c schema-json`、`--errorFormat json`
  - `src/Luban.Mcp`：MCP Server（优先调 Agent，生成走主 CLI）

## 构建（示例工程）

`luban` 与 `luban_examples` 并列时，运行：

```bash
luban_examples/Tools/build-luban.bat   # 或 build-luban.sh
```

产出：`Tools/Luban`、`Tools/Luban.Agent`、`Tools/Luban.Mcp`。

## 文档

见 luban-doc：`docs/ai/`，以及站点 `/llms.txt`。

## 示例工程模板

`luban_examples/MiniTemplate` 与 `DataTables` 含 `AGENTS.md` 与 `.cursor/rules`，可复制到自有项目。

---

### Overview (`tests/README.md`)

# Luban test suite

Self-contained fixtures and goldens for `src/Luban.Tests`.

## Layout

- `fixtures/` — input schemas and source data (prefer text formats)
- `golden/` — expected data-target outputs
- `scripts/update-goldens.ps1` / `update-goldens.sh` — regenerate goldens via Luban CLI

## Run

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

---

### Overview (`src/Luban.Agent/README.md`)

# Luban.Agent

Agent-oriented CLI for Luban: validate, export/query schema, list/describe types.

Keeps the main `Luban` tool focused on generation. This host always prints a single
`AgentResult` JSON document on **stdout**.

## Build

```bash
dotnet build src/Luban.Agent/Luban.Agent.csproj -c Release
```

## Usage

```bash
dotnet Luban.Agent.dll capabilities
dotnet Luban.Agent.dll list-tables --conf path/to/luban.conf -t all
dotnet Luban.Agent.dll describe --conf path/to/luban.conf -t all --name TbItem
dotnet Luban.Agent.dll schema --conf path/to/luban.conf -t all
dotnet Luban.Agent.dll validate --conf path/to/luban.conf -t all
```

First positional argument is the mode (also accepted as `--mode`).

## Modes

| Mode | Purpose |
|------|---------|
| `capabilities` | Machine-readable feature list |
| `list-tables` | Table summaries |
| `describe` | One table/bean/enum (`--name` required) |
| `schema` | Full or filtered schema JSON |
| `validate` | Load + validate data, no file output |

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | OK |
| 1 | Data / validation |
| 2 | Schema / config |
| 3 | Usage |
| 4 | Internal |

See also: `Luban.Mcp` (IDE MCP) and main `Luban` (`--errorFormat json` for generate).

---

### Overview (`src/Luban.Mcp/README.md`)

# Luban.Mcp

stdio MCP Server for Luban: list/get schema, validate, generate, search docs.

## Build

Preferred (with sibling `luban_examples`):

```bash
# Windows
luban_examples/Tools/build-luban.bat

# macOS / Linux
luban_examples/Tools/build-luban.sh
```

Outputs under `luban_examples/Tools/`:

- `Luban/` — main generator
- `Luban.Agent/` — agent CLI
- `Luban.Mcp/` — this MCP server

Or from the luban repo:

```bash
dotnet build src/Luban/Luban.csproj -c Release -o <out>/Luban
dotnet build src/Luban.Agent/Luban.Agent.csproj -c Release -o <out>/Luban.Agent
dotnet build src/Luban.Mcp/Luban.Mcp.csproj -c Release -o <out>/Luban.Mcp
```

## Env

- `LUBAN_AGENT_DLL` — path to `Luban.Agent.dll`
- `LUBAN_DLL` — path to `Luban.dll`
- `LUBAN_DOC` — path to `luban-doc/docs`

## Tools

- `ListTables` / `GetSchema` / `Describe` / `Validate` / `Generate` / `SearchDocs`

See documentation: `docs/ai/mcp` in luban-doc.

---

--- METRICS ---
- Files Extracted: 5
- Estimated Token Budget: ~1428 tokens
- Canonical Reference: https://codewiki.google/github.com/focus-creative-games/luban