Luban

https://luban.doc.code-philosophy.com/docs/other
Admin
Luban is a powerful tool for generating code and data from configurations, supporting custom types,...
Tokens:14,721
Snippets:58
Trust Score:6
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example Luban Configuration with Groups

Source: https://luban.doc.code-philosophy.com/docs/other/3.x/manual/schema

An example `luban.conf` file demonstrating the `groups` configuration, `schemaFiles`, `dataDir`, and `targets` sections, illustrating how different targets can have specific group settings and their impact on type export.

```JSON
{
    "groups":
    [
        {"names":["c"], "default":true},
        {"names":["s"], "default":true},
        {"names":["e"], "default":true},
        {"names":["t"], "default":false}
    ],
    "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":"test", "manager":"Tables", "groups":["t"], "topModule":"cfg"},
        {"name":"server", "manager":"Tables", "groups":["s"], "topModule":"cfg"},
        {"name":"client", "manager":"Tables", "groups":["c"], "topModule":"cfg"},
        {"name":"editor", "manager":"Tables", "groups":["c"], "topModule":"editor.cfg"},
        {"name":"all", "manager":"Tables", "groups":["c","s","e"], "topModule":"cfg"}
    ]
}
```

--------------------------------

### Generate Unity C# Binaries with Luban

Source: https://luban.doc.code-philosophy.com/docs/other/3.x/manual/commandtools

Example batch script to generate C# code and binary data for a Unity project using Luban. This configuration targets `cs-bin` for code and `bin` for data, specifying output directories and localization settings.

```Batch
set WORKSPACE=..\..

set LUBAN_DLL=%WORKSPACE%\Tools\Luban\Luban.dll
set CONF_ROOT=%WORKSPACE%\DataTables

dotnet %LUBAN_DLL% ^
    -t all ^
    -c cs-bin ^
    -d bin  ^
    --conf %CONF_ROOT%\luban.conf ^
    -x outputCodeDir=Assets/Gen ^
    -x outputDataDir=..\GenerateDatas\bytes ^
    -x pathValidator.rootDir=%WORKSPACE%\Projects\Csharp_Unity_bin ^
    -x l10n.textProviderFile=*@%WORKSPACE%\DataTables\Datas\l10n\texts.json
```

--------------------------------

### Example Luban Configuration File (luban.conf)

Source: https://luban.doc.code-philosophy.com/docs/other/manual/schema

This JSON snippet provides an example of a `luban.conf` file, demonstrating the definition of export `groups`, `schemaFiles`, `dataDir`, and multiple `targets`. It illustrates how different `groups` can be configured for various build outputs like client, server, and editor.

```JSON
{
    "groups":
    [
        {"names":["c"], "default":true},
        {"names":["s"], "default":true},
        {"names":["e"], "default":true},
        {"names":["t"], "default":false}
    ],
    "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":"test", "manager":"Tables", "groups":["t"], "topModule":"cfg"},
        {"name":"server", "manager":"Tables", "groups":["s"], "topModule":"cfg"},
        {"name":"client", "manager":"Tables", "groups":["c"], "topModule":"cfg"},
        {"name":"editor", "manager":"Tables", "groups":["c"], "topModule":"editor.cfg"},
        {"name":"all", "manager":"Tables", "groups":["c","s","e"], "topModule":"cfg"}
    ]
}
```

--------------------------------

### Generate DotNet C# Binaries with Luban

Source: https://luban.doc.code-philosophy.com/docs/other/3.x/manual/commandtools

Example batch script to generate C# code and binary data for a .NET project using Luban. This configuration targets `cs-bin` for code and `bin` for data, specifying output directories and localization settings.

```Batch
set WORKSPACE=..\..

set LUBAN_DLL=%WORKSPACE%\Tools\Luban\Luban.dll
set CONF_ROOT=%WORKSPACE%\DataTables

dotnet %LUBAN_DLL% ^
    -t all ^
    -c cs-bin ^
    -d bin  ^
    --conf %CONF_ROOT%\luban.conf ^
    -x outputCodeDir=Gen ^
    -x outputDataDir=..\GenerateDatas\bytes ^
    -x pathValidator.rootDir=%WORKSPACE%\Projects\Csharp_Unity_bin ^
    -x l10n.textProviderFile=*@%WORKSPACE%\DataTables\Datas\l10n\texts.json
```

--------------------------------

### Generate Unity C# JSON Data with Luban

Source: https://luban.doc.code-philosophy.com/docs/other/3.x/manual/commandtools

Example batch script to generate C# code and JSON data for a Unity project using Luban. This configuration targets `cs-simple-json` for code and `json` for data, specifying output directories and localization settings.

```Batch
set WORKSPACE=..\..

set GEN_CLIENT=%WORKSPACE%\Tools\Luban\Luban.dll
set CONF_ROOT=%WORKSPACE%\DataTables

dotnet %GEN_CLIENT% ^
    -t all ^
    -c cs-simple-json ^
    -d json  ^
    --conf %CONF_ROOT%\luban.conf ^
    -x outputCodeDir=Assets/Gen ^
    -x outputDataDir=..\GenerateDatas\json ^
    -x pathValidator.rootDir=D:\workspace2\luban_examples\Projects\Csharp_Unity_bin ^
    -x l10n.textProviderFile=*@D:\workspace2\luban_examples\DataTables\Datas\l10n\texts.json
```

--------------------------------

### Luban xargs Command-Line Parameters Reference

Source: https://luban.doc.code-philosophy.com/docs/other/3.x/manual/commandtools

Comprehensive list of custom command-line parameters available through the `-x --xargs` option in Luban, detailing their purpose, available values, and usage examples. These parameters control various aspects of code and data generation, including output directories, naming conventions, post-processing, and localization.

```APIDOC
Parameter: {codeTarget}.outputCodeDir
  Description: Code target's output directory
  Example: -x outputCodeDir=/my/output/dir

Parameter: {dataTarget}.outputDataDir
  Description: Data target's output directory
  Example: -x outputDataDir=/my/output/dir

Parameter: codeStyle
  Description: Naming style for code targets. Built-in Code Targets automatically set matching codeStyle, no explicit specification needed.
  Available Values: none, csharp-default, java-default, go-default, lua-default, typescript-default, cpp-default, python-default, dart-default
  Example: -x codeStyle=csharp-default

Parameter: namingConvention.{codeTarget}.{location}
  Description: codeTarget is the target name specified in `--codeTarget`. location is the style position, optional values are namespace, type, method, property, field, enumItem (see Code Style documentation). This is a hierarchical option; if {codeTarget} is not specified, it applies to all targets.
  Available Values: none, pascal, camel, upper, snake
  Example: -x namingConvention.cs-bin.field=pascal

Parameter: dataExporter
  Description: Data exporter
  Available Values: null, default
  Example: -x dataExporter=default

Parameter: codePostprocess
  Description: Code post-processor, can be multiple.
  Available Values: No built-in postprocesses implemented.
  Example: -x codePostProcess=a,b,c

Parameter: dataPostprocess
  Description: Data post-processor, can be multiple.
  Available Values: No built-in postprocesses implemented.
  Example: -x dataPostProcess=a,b

Parameter: outputSaver
  Description: Data saver, defaults to 'local' (output to local directory). Use 'null' to prevent any file output. Currently implemented savers are 'local' and 'null'.
  Available Values: null, local
  Example: -x outputSaver=local

Parameter: outputSaver.{codeTarget|dataTarget}.cleanUpOutputDir
  Description: Whether to clean up extra files in outputCodeDir or outputDataDir before outputting files, defaults to true.
  Example: -x outputSaver.cs-bin.cleanUpOutputDir=0

Parameter: l10n.provider
  Description: Localization text Provider. If not set, no localization operations (including text validation and static conversion) are performed.
  Available Values: default
  Example: -x l10n.provider=default

Parameter: l10n.textFile.path
  Description: Localization text data file. Required when l10.provider is set.
  Example: -x l10n.textFile.path=xxxx

Parameter: l10n.textFile.keyFieldName
  Description: Field name for the key field of data items in the localization text data file.
  Example: -x l10n.textFile.keyFieldName=key

Parameter: l10n.textFile.languageFieldName
  Description: Field name for the text value field corresponding to the language in the localization text data file.
  Example: -x l10n.languageFieldName=en

Parameter: l10n.convertTextKeyToValue
  Description: Perform static localization, replacing keys with corresponding language text values.
  Example: -x l10n.convertTextKeyToValue=1

Parameter: l10n.textListFile
  Description: File for the list of all text keys in the output configuration, used with DataTarget text-list.

Parameter: pathValidator.rootDir
  Description: Root directory used by the path validator to search for files.
  Example: -x pathValidator.rootDir=/xx/yy

Parameter: {code|data}.lineEnding
  Description: Line ending for generated code and data files. This option is only valid for text output files, not for binary formats like bin, bson. If not specified, Environment.NewLine is used.
  Available Values: CR, LF, CRLF
  Example: -x lineEnding=LF, -x code.LineEnding=LF, -x data.lineEnding=LF

Parameter: json.compact
  Description: Whether to output compact, unindented JSON data, used with json or json2 dataTarget. Defaults to 0.
  Available Values: 0, 1, true, false
  Example: -x compact=1

Parameter: {dataTarget}.fileExt
  Description: File name suffix for output data files.
  Example: -x bin.fileExt=bin

Parameter: ~~{dataTarget}.outputDataExtension~~
  Description: File name suffix for output data files. Removed in v2.12.0, renamed to fileExt.
  Example: -x bin.outputDataExtension=bin

Parameter: {codeTarget|dataTarget}.fileEncoding
  Description: Character encoding for output files.
  Example: -x lua.fileEncoding=gb2313
```

--------------------------------

### Example XML Definition File Structure

Source: https://luban.doc.code-philosophy.com/docs/other/manual/defaultschemacollector

A comprehensive example demonstrating the structure of an XML definition file, including `module`, `enum`, `bean`, `table`, and `refgroup` elements. This snippet showcases how data types, configurations, and relationships are defined within a typical XML definition.

```XML
<module name="item">

<enum name="Quality">
  <var name="WHITE" alias="白"/>
  <var name="RED" alias="红"/>
  <var name="GREEN" alias="绿"/>
</enum>

<bean name="Item">
  <var name="id" type="int"/>
  <var name="count" type="int"/>
</bean>

<bean name="Item2">
  <var name="id" type="int"/>
  <var name="count" type="int"/>
  <var name="desc" type="string"/>
</bean>

<table name="TbItem" value="Item" input="item.xlsx"/>
<table name="TbItem2" value="Item2" input="item2.xlsx"/>

<refgroup name="item.TbItem,item.TbItem2"/>

<enum name="AudioType">
    <var name="UNKNOWN" value="0"/>
    <var name="ACC" value="1"/>
    <var name="AIFF" value="2"/>
    <mapper target="client" codeTarget="cs-bin">
        <option name="type" value="UnityEngine.AudioType"/>
    </mapper>
</enum>
<bean name="vector2" valueType="1" sep=",">
    <var name="x" type="float"/>
    <var name="y" type="float"/>
    <mapper target="client" codeTarget="cs-bin">
        <option name="type" value="UnityEngine.Vector2"/>
        <option name="constructor" value="ExternalTypeUtil.NewVector2"/>
    </mapper>
</bean>

<module name="subModule">
  <bean name="SubModuleType">
    <var name="id" type="int"/>
    <var name="count" type="int"/>
  </bean>
  <table name="TbSubItem" value="SubModuleType" input="submodule.xlsx"/>
</module>

</module>
```

--------------------------------

### Load Luban Configurations with C# and JSON in Unity

Source: https://luban.doc.code-philosophy.com/docs/other/3.x/manual/loadconfigatruntime

This C# code snippet demonstrates how to load all Luban configurations from JSON files in a Unity project. It initializes cfg.Tables with a JSON loader function and shows examples of accessing singleton tables, key-value tables, and using array-like access for table entries.

```C#
    void Load()
    {
        // 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。
        var tables = new cfg.Tables(Loader);
        // 访问一个单例表
        Console.WriteLine(tables.TbGlobal.Name);
        // 访问普通的 key-value 表
        Console.WriteLine(tables.TbItem.Get(12).Name);
        // 支持 operator []用法
        Console.WriteLine(tables.TbMail[1001].Desc);
    }

    private static JSONNode LoadJson(string file)
    {
        return JSON.Parse(File.ReadAllText($"{your_json_dir}/{file}.json", System.Text.Encoding.UTF8));
    }
```

--------------------------------

### Lite Data Format Example - Multi Line for Readability

Source: https://luban.doc.code-philosophy.com/docs/other/manual/otherdatasource

Provides a more readable, multi-line example of the Luban Lite format. This format is unique to Luban, does not require field names, and supports various data types. It demonstrates how whitespace and newlines are handled, and how strings with special characters require escaping.

```Lite
{
  1122,
  false,
  2,
  128,
  112233445566,
  1.3,
  1122,
  yf,
  {1},
  D,
  {DemoD2,1,3},
  1970-01-01 00:00:00,
  {1,2},
  {2,3},
  {{2,10},{3,12}},
  {{1,true},{2,false}},
  {{DemoD2,1,3}}
}
```

--------------------------------

### Luban `gen_types` Parameter Reference

Source: https://luban.doc.code-philosophy.com/docs/other/1.x/manual/commandtools

A comprehensive list of `gen_types` parameters supported by the Luban tool, categorized by code generation, data generation, and source data conversion. Each entry specifies the target platform, language, and data format, along with a brief description of its purpose and unique characteristics.

```APIDOC
gen_types:
  Code Generation:
    - code_cs_bin: Generates C# code for .NET platform to read binary data. Uses System.Numerics.Vector{2,3,4}.
    - code_cs_unity_bin: Generates C# code suitable for Unity to read binary data. Uses UnityEngine.Vector{2,3,4}.
    - code_cs_dotnet_json: Generates C# code for .NET platform to read JSON data. Uses System.Numerics.Vector{2,3,4}.
    - code_cs_unity_json: Generates C# code suitable for Unity to read JSON data. Uses UnityEngine.Vector{2,3,4}.
    - code_cs_unity_editor_json: Generates C# code suitable for Unity editor development. Allows individual records to be loaded or saved to JSON files.
    - code_lua_bin: Generates Lua code to read binary data.
    - code_java_bin: Generates Java code to read binary data.
    - code_java_json: Generates Java code to read JSON data.
    - code_go_bin: Generates Go code to read binary data.
    - code_go_json: Generates Go code to read JSON data.
    - code_cpp_bin: Generates C++ code to read binary data.
    - code_cpp_ue_editor_json: Generates C++ code suitable for UE4 editor development. Allows individual records to be loaded or saved to JSON files.
    - code_python27_json: Generates Python 2.7 code to read JSON data.
    - code_python3_json: Generates Python 3 code to read JSON data.
    - code_gdscript_json: Generates GDScript code to read JSON data.
    - code_typescript_bin: Generates TypeScript code to read binary data.
    - code_typescript_json: Generates TypeScript code to read JSON data.
    - code_rust_json: Generates Rust code to read JSON data.
    - code_protobuf2: Generates Protobuf 2 schema files.
    - code_protobuf3: Generates Protobuf 3 schema files.
    - code_template: Indicates the use of custom code templates.

```

--------------------------------

### Luban Lua Data Format Examples

Source: https://luban.doc.code-philosophy.com/docs/other/manual/excelcompactformat

This section outlines how to enter data using the Lua table format in Luban. To enable this format, specify 'format=lua' in the title header. This is useful for integrating with Lua-based systems.

```Lua
{x=1.0, y=2.0, z=3.0}
```

```Lua
{id=1, name="xxxx", pos={"x":1, "y":2, "z":3}}
```

--------------------------------

### YAML Data Format Example

Source: https://luban.doc.code-philosophy.com/docs/other/manual/otherdatasource

Illustrates data representation using YAML, highlighting its similarity to JSON. It demonstrates how set, map, and polymorphic bean types are represented, with $type used for specific type naming. Files with .yaml or .yml extensions are recognized.

```YAML
x1: true
x2: 3
x3: 128
x4: 40
x5: 11223344
x6: 1.2
x7: 1.23432
x10: hq
x12:
  x1: 10
x13: B
x14:
  $type: DemoD2
  x1: 1
  x2: 2
t1: '1970-01-01 00:00:00'
k1:
- 1
- 2
k2:
- 2
- 3
k8:
- - 2
  - 2
- - 4
  - 10
k9:
- y1: 1
  y2: true
- y1: 2
  y2: false
k15:
- $type: DemoD2
  x1: 1
  x2: 2
```

--------------------------------

### XML Data Format Example

Source: https://luban.doc.code-philosophy.com/docs/other/manual/otherdatasource

Demonstrates the structure of data in XML format, showcasing various primitive types, nested elements, and collections (lists and maps). This format is used for structured data representation within the Luban system.

```XML
<data>
  <x1>true</x1>
  <x2>4</x2>
  <x3>128</x3>
  <x4>1</x4>
  <x5>112233445566</x5>
  <x6>1.3</x6>
  <x7>1112232.43123</x7>
  <x10>yf</x10>
  <x12> <x1>1</x1> </x12>
  <x13>C</x13>
  <x14 type="DemoD2">  <x1>1</x1>  <x2>2</x2> </x14>
  <k1> <item>1</item> <item>2</item> </k1>
  <k2> <item>1</item> <item>2</item> </k2>
  <k8>
      <item> <key>2</key><value>10</value></item>
      <item> <key>3</key><value>30</value></item>
  </k8>
  <k9>
      <item> <y1>1</y1> <y2>true</y2> </item>
      <item> <y1>2</y1> <y2>false</y2> </item>
  </k9>
  <k15>
      <item type="DemoD2"> <x1>1</x1> <x2>2</x2> </item>
  </k15>
</data>
```

--------------------------------

### Lite Data Format Example - Single Line

Source: https://luban.doc.code-philosophy.com/docs/other/manual/otherdatasource

Shows a single-line representation of the proprietary Luban Lite format. This format is concise, omitting field names, and supports various data types including primitives, arrays, lists, sets, maps, enums, and beans. Nullable polymorphic beans can be represented by null.

```Lite
{ 1122, false, 2, 128, 112233445566, 1.3, 1122, yf, {1}, D, {DemoD2,1,3}, 1970-01-01 00:00:00, {1,2}, {2,3}, {{2,10},{3,12}}, {{1,true},{2,false}}, {{DemoD2,1,3}}}
```

--------------------------------

### Luban JSON Data Format Examples

Source: https://luban.doc.code-philosophy.com/docs/other/manual/excelcompactformat

This section describes how to enter data using the standard JSON format in Luban. It's used by specifying 'format=json' in the title header. This format is suitable when standard JSON representation is preferred.

```JSON
{"x":1.0, "y":2.0, "z":3.0}
```

```JSON
{"id":1, "name":"xxxx", "pos":{"x":1, "y":2, "z":3}}
```

--------------------------------

### Luban Lite Data Format Examples

Source: https://luban.doc.code-philosophy.com/docs/other/manual/excelcompactformat

The 'lite' format is unique to Luban, designed for highly complex nested data structures. It's a field-name-less format, offering conciseness and efficient parsing. It's recommended for complex composite data. To use, specify 'format=lite' in the title header.

```Luban Lite Format
{1.0, 2.0, 3.0}
```

```Luban Lite Format
{1, xxxx, {1,2,3}}
```

--------------------------------

### Load JSON Configurations in Go Project

Source: https://luban.doc.code-philosophy.com/docs/other/1.x/manual/loadconfigatruntime

Shows how to load all configurations from JSON files in a Go project using Luban. It demonstrates accessing singleton and key-value tables. Users need to implement a suitable loader function that returns a JSON object based on the configuration file.

```Go
// 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。
if tables , err := cfg.NewTables(loader) ; err != nil {
 println(err.Error())
 return
}
// 访问一个单例表
println(tables.TbGlobal.Name)
// 访问普通的 key-value 表
println(tables.TbItem.Get(12).Name)
```

--------------------------------

### 生成Luban配置数据

Source: https://luban.doc.code-philosophy.com/docs/other/beginner/quickstart

执行平台特定的脚本，从已定义的Excel数据表中编译并生成配置数据。生成的JSON文件将位于 MiniTemplate/output 目录下。

```Batch
MiniTemplate/gen.bat
```

```Shell
MinTemplate/gen.sh
```

--------------------------------

### Auto-detect and Load JSON or Binary Configurations in Unity C#

Source: https://luban.doc.code-philosophy.com/docs/other/1.x/manual/loadconfigatruntime

Shows how to dynamically load configurations as either JSON or binary (BIN) in a Unity C# project without changing code, by using reflection to determine the appropriate loader based on the cfg.Tables constructor. This is useful for switching between development (JSON) and production (BIN) formats.

```C#
    void Start()
    {
        var tablesCtor = typeof(cfg.Tables).GetConstructors()[0];
        var loaderReturnType = tablesCtor.GetParameters()[0].ParameterType.GetGenericArguments()[1];
        // 根据cfg.Tables的构造函数的Loader的返回值类型决定使用json还是ByteBuf Loader
        System.Delegate loader = loaderReturnType == typeof(ByteBuf) ?
            new System.Func<string, ByteBuf>(LoadByteBuf)
            : (System.Delegate)new System.Func<string, JSONNode>(LoadJson);
        var tables = (cfg.Tables)tablesCtor.Invoke(new object[] {loader});

        // 访问一个单例表
        Console.WriteLine(tables.TbGlobal.Name);
        // 访问普通的 key-value 表
        Console.WriteLine(tables.TbItem.Get(12).Name);
        // 支持 operator []用法
        Console.WriteLine(tables.TbMail[1001].Desc);
    }

    private static JSONNode LoadJson(string file)
    {
        return JSON.Parse(File.ReadAllText($"{Application.dataPath}/../../GenerateDatas/json/{file}.json", System.Text.Encoding.UTF8));
    }

    private static ByteBuf LoadByteBuf(string file)
    {
        return new ByteBuf(File.ReadAllBytes($"{Application.dataPath}/../../GenerateDatas/bytes/{file}.bytes"));
    }
```

--------------------------------

### Load JSON Configurations in Unity C#

Source: https://luban.doc.code-philosophy.com/docs/other/1.x/manual/loadconfigatruntime

Demonstrates how to load all configurations from JSON files in a Unity C# project using LubanLib. It shows accessing singleton tables, key-value tables, and using the operator [] syntax. Users need to implement a suitable Loader function.

```C#
// 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。
var tables = new cfg.Tables(Loader);
// 访问一个单例表
Console.WriteLine(tables.TbGlobal.Name);
// 访问普通的 key-value 表
Console.WriteLine(tables.TbItem.Get(12).Name);
// 支持 operator []用法
Console.WriteLine(tables.TbMail[1001].Desc);
```

--------------------------------

### Auto-Detect and Load Luban Configurations (BIN/JSON) in Unity C#

Source: https://luban.doc.code-philosophy.com/docs/other/3.x/manual/loadconfigatruntime

This C# code snippet illustrates an advanced method for loading Luban configurations in Unity, allowing automatic detection of whether to load from JSON or binary (BIN) files. It uses reflection to determine the appropriate loader based on the cfg.Tables constructor, enabling seamless switching between development (JSON) and production (BIN) data formats without code changes.

```C#
    void Start()
    {
        var tablesCtor = typeof(cfg.Tables).GetConstructors()[0];
        var loaderReturnType = tablesCtor.GetParameters()[0].ParameterType.GetGenericArguments()[1];
        // 根据cfg.Tables的构造函数的Loader的返回值类型决定使用json还是ByteBuf Loader
        System.Delegate loader = loaderReturnType == typeof(ByteBuf) ?
            new System.Func<string, ByteBuf>(LoadByteBuf)
            : (System.Delegate)new System.Func<string, JSONNode>(LoadJson);
        var tables = (cfg.Tables)tablesCtor.Invoke(new object[] {loader});

        // 访问一个单例表
        Console.WriteLine(tables.TbGlobal.Name);
        // 访问普通的 key-value 表
        Console.WriteLine(tables.TbItem.Get(12).Name);
        // 支持 operator []用法
        Console.WriteLine(tables.TbMail[1001].Desc);
    }

    private static JSONNode LoadJson(string file)
    {
        return JSON.Parse(File.ReadAllText($"{your_json_dir}/{file}.json", System.Text.Encoding.UTF8));
    }

    private static ByteBuf LoadByteBuf(string file)
    {
        return new ByteBuf(File.ReadAllBytes($"{your_json_dir}/{file}.bytes"));
    }
```

--------------------------------

### Luban Supported Code Targets

Source: https://luban.doc.code-philosophy.com/docs/other/manual/commandtools

Lists the various code generation targets supported by Luban, detailing the language and the data format they are designed to read. It is crucial that the generated code target matches its corresponding data target to avoid loading failures. When generating multiple code targets simultaneously, a unique output directory must be specified for each using the `<code target name>.outputCodeDir` parameter, as different code outputs cannot share the same directory.

```APIDOC
Code Target:
  cs-bin: C#, reads bin format files
  cs-simple-json: C#, uses SimpleJSON to read json files, recommended for Unity client
  cs-dotnet-json: C#, uses System.Text.Json library to read json files, recommended for dotnet core server
  cs-newtonsoft-json: C#, uses Newtonsoft.Json library to read json files
  cs-editor-json: C#, reads and saves records as a single json file, suitable for custom editor saving and loading original configuration files
  cs-protobuf2: Generates code to load all protobuf bin and json format data, only includes Tables class
  cs-protobuf3: Generates code to load all protobuf bin and json format data, only includes Tables class
  lua-lua: lua, reads lua format files
  lua-bin: lua, reads bin format files
  java-bin: java, reads bin format files
  java-json: java, uses gson library to read json format files
  cpp-bin: cpp, reads bin format files. Removed since v2.3.0
  cpp-sharedptr-bin: cpp, uses smart pointers to save dynamically allocated objects, reads bin format files
  cpp-rawptr-bin: cpp, uses raw pointers to save dynamically allocated objects, reads bin format files
  go-bin: go, reads bin format files
  go-json: go, reads json format files
  python-json: python, reads json format files
  gdscript-json: gdscript, reads json format files. Note: If you develop in C#, it is recommended to use the more efficient cs-bin format
  typescript-bin: typescript, reads json format files
  typescript-json: typescript, reads json format files
  typescript-protobuf: typescript, generates code to read protobuf format data, only includes Tables class
  rust-bin: Generates rust code, reads bin format files
  rust-json: Generates rust code, reads json format files
  php-json: php, reads json format files
  dart-json: Generates dart code, reads json format files
  protobuf2: Generates proto2 syntax schema file
  protobuf3: Generates proto3 syntax schema file
  flatbuffers: Generates flatbuffers schema file
```

--------------------------------

### Load JSON Configurations in Unity Puerts TypeScript

Source: https://luban.doc.code-philosophy.com/docs/other/1.x/manual/loadconfigatruntime

Illustrates how to load all configurations from JSON files in a Unity project using Puerts and TypeScript. It demonstrates accessing singleton and key-value tables. Users need to implement a loader function that returns a parsed JSON object.

```TypeScript
// 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。
let tables = new cfg.Tables(loader)
// 访问一个单例表
console.log(tables.TbGlobal.name)
// 访问普通的 key-value 表
console.log(tables.TbItem.get(12).Name)
```

--------------------------------

### Luban Default Pipeline and Customization

Source: https://luban.doc.code-philosophy.com/docs/other/manual/commandtools

Describes the default pipeline 'default' implemented in Luban.Core and notes that users can implement their own custom pipelines for data processing.

```APIDOC
Pipeline:
  DefaultPipeline:
    name: default
    description: Implemented in Luban.Core
  Custom Pipelines:
    description: Users can implement their own Pipeline
```

--------------------------------

### Luban Supported Data Targets

Source: https://luban.doc.code-philosophy.com/docs/other/manual/commandtools

Lists the various data export targets supported by Luban, detailing the format and its characteristics. Similar to code targets, when exporting multiple data targets at once, a separate output directory must be specified for each using the `<data target name>.outputDataDir` parameter to prevent overwriting. Each code target is designed to read only one specific matching data format (e.g., cs-bin reads bin, java-json reads json).

```APIDOC
Data Target:
  bin: Luban's unique binary format, compact and efficient, recommended for official release
  bin-offset: Records the index position of each record in the bin format exported data file, can be used for record-grained lazy loading
  json: json format, map output as [[key, value]] format
  json2: Similar to json format, but map output as {"key":"value"} format
  lua: lua format
  xml: xml format
  yml: yaml format
  bson: bson format
  msgpack: msgpack binary format
  protobuf2-bin: protobuf2 binary format
  protobuf3-bin: protobuf3 binary format
  protobuf2-json: protobuf2 supported json format
  protobuf3-json: protobuf3 supported json format
  flatbuffers-json: flatbuffers supported json format
  text-list: Outputs all text keys appearing in the configuration, sorted from smallest to largest
```

--------------------------------

### Table Input Source Configuration

Source: https://luban.doc.code-philosophy.com/docs/other/1.x/manual/define

The 'input' attribute specifies data sources, allowing multiple sources separated by commas. It supports various flexible definitions including entire Excel files, specific Excel sheets, JSON/XML/Lua/YAML/Unity Scriptable Asset files, sub-fields within these files, and directories containing data files. Combinations of these sources are also supported.

```APIDOC
"input" attribute syntax:
  Type: string (comma-separated list of source paths)
  Description: Specifies one or more data sources for the table.
  Supported Source Formats:
    - Excel File: "filename.xlsx" (all sheets)
    - Excel Sheet: "sheetname@filename.xlsx" (specific sheet)
    - Single File (JSON, XML, Lua, YAML, Unity Scriptable Asset): "filename.json", "filename.xml", "filename.lua", "filename.yml"
    - Sub-field within a File: "*items@module.json", "item.consts@module.json" (similar for other formats)
    - Directory: "directory_name" (all files recursively, each file as a record, except Excel)
    - Combinations: "xx.xlsx,sheet2@yy.xls,abc@zz.json,ccc_dir"
```

--------------------------------

### Typical XML Definition File Structure

Source: https://luban.doc.code-philosophy.com/docs/other/3.x/manual/defaultschemacollector

This XML snippet illustrates the typical structure of a Luban definition file, including module, enum, bean, table, and refgroup elements. It demonstrates how to define data types, relationships, and external mappings for game data.

```XML
<module name="item">

<enum name="Quality">
  <var name="WHITE" alias="白"/>
  <var name="RED" alias="红"/>
  <var name="GREEN" alias="绿"/>
</enum>

<bean name="Item">
  <var name="id" type="int"/>
  <var name="count" type="int"/>
</bean>

<bean name="Item2">
  <var name="id" type="int"/>
  <var name="count" type="int"/>
  <var name="desc" type="string"/>
</bean>

<table name="TbItem" value="Item" input="item.xlsx"/>
<table name="TbItem2" value="Item2" input="item2.xlsx"/>

<refgroup name="item.TbItem,item.TbItem2"/>

<enum name="AudioType">
    <var name="UNKNOWN" value="0"/>
    <var name="ACC" value="1"/>
    <var name="AIFF" value="2"/>
    <mapper target="client" codeTarget="cs-bin">
        <option name="type" value="UnityEngine.AudioType"/>
    </mapper>
</enum>
<bean name="vector2" valueType="1" sep=",">
    <var name="x" type="float"/>
    <var name="y" type="float"/>
    <mapper target="client" codeTarget="cs-bin">
        <option name="type" value="UnityEngine.Vector2"/>
        <option name="constructor" value="ExternalTypeUtil.NewVector2"/>
    </mapper>
</bean>

<module name="subModule">
  <bean name="SubModuleType">
    <var name="id" type="int"/>
    <var name="count" type="int"/>
  </bean>
  <table name="TbSubItem" value="SubModuleType" input="submodule.xlsx"/>
</module>

</module>
```

--------------------------------

### Luban Table Configuration Schema

Source: https://luban.doc.code-philosophy.com/docs/other/manual/schema

Defines the schema for a `table` in Luban, outlining its fields such as `namespace`, `name`, `index`, `mode`, `valueType`, `inputFiles`, and `outputFileName`. It also clarifies `TableMode` and the flexible `inputFiles` specification.

```APIDOC
table:
  description: Logical representation of a data table. Not a type, cannot be used for field type definition.
  fields:
    - name: namespace
      type: string
      nullable: true
      description: string
    - name: name
      type: string
      nullable: false
      description: Type name
    - name: index
      type: string
      nullable: true
      description: Index field list, 0 to many. If empty and mode=map or empty, automatically uses the first field of valueType as index. For multiple primary keys, use 'key1+key2+...+keyn' for composite, 'key1,key2,...,keyn' for independent.
    - name: mode
      type: TableMode
      nullable: true
      description: Table mode enumeration, can be one (or singleton), map, list. If left empty, the specific mode is determined by index: map if index is empty or a single primary key (index is the 1st field of valueType); list if index has multiple primary keys.
    - name: valueType
      type: string
      nullable: false
      description: Record type
    - name: readSchemaFromFile
      type: bool
      nullable: false
      description: Whether to parse valueType definition from inputFiles
    - name: comment
      type: string
      nullable: true
      description: Comment
    - name: tags
      type: map<string,string>
      nullable: true
      description: Custom tag pairs, 0 to many
    - name: groups
      type: list<string>
      nullable: true
      description: Export groups, 0 to many
    - name: inputFiles
      type: list<string>
      nullable: false
      description: List of input data files, cannot be empty. Each source can be an excel file (all sheets or specified sheet), json/xml/lua/yaml/unity scriptable asset files, subfields (e.g., *items@item_module.json), or directories (all files recursively).
    - name: outputFileName
      type: string
      nullable: true
      description: Output file name. If empty, defaults to FullName.LowerCase().Replace('.', '_')
```

--------------------------------

### Luban Table Structure Definition

Source: https://luban.doc.code-philosophy.com/docs/other/3.x/manual/schema

Defines the fields and properties of a `table` in Luban, including its name, index, mode, value type, input files, and output file name. It also explains how `index` and `mode` interact, and the flexibility of `inputFiles`.

```APIDOC
table:
  description: "Logical representation of a data table. Not a type, cannot be used for field type definition."
  fields:
    - name: "namespace"
      type: "string"
      nullable: "Yes"
      description: "Namespace string."
    - name: "name"
      type: "string"
      nullable: "No"
      description: "Type name."
    - name: "index"
      type: "string"
      nullable: "Yes"
      description: "List of index fields (0 to many). If empty and mode is map or empty, the first field of valueType is automatically used as index. For multiple primary keys: 'key1+key2+...+keyn' for composite keys, 'key1,key2,...,keyn' for independent keys."
    - name: "mode"
      type: "TableMode"
      nullable: "Yes"
      description: "Table mode enum, can be one (or singleton), map, list. If left empty, the specific mode is determined by index: if index is empty or has 1 primary key, it's map (index is the first field of valueType); if index has multiple primary keys, it's list."
    - name: "valueType"
      type: "string"
      nullable: "No"
      description: "Record type."
    - name: "readSchemaFromFile"
      type: "bool"
      nullable: "No"
      description: "Whether to parse valueType definition from inputFiles."
    - name: "comment"
      type: "string"
      nullable: "Yes"
      description: "Comment."
    - name: "tags"
      type: "map<string,string>"
      nullable: "Yes"
      description: "Custom tag pairs (0 to many)."
    - name: "groups"
      type: "list<string>"
      nullable: "Yes"
      description: "Export groups (0 to many)."
    - name: "inputFiles"
      type: "list<string>"
      nullable: "No"
      description: "List of input data files, cannot be empty. Each data source can be:\n* From all sheets of an Excel file. E.g., xxx.xlsx\n* From a specified sheet of an Excel file. E.g., sheet@xxx.xlsx\n* From JSON, XML, Lua, YAML, Unity Scriptable Asset files. E.g., xx.json or xx.xml or xx.lua or xx.yml\n* From JSON, XML, Lua, YAML, Unity Scriptable Asset sub-fields. E.g., *items@item_module.json or item.consts@item_module.json, other formats similar\n* From a directory. All files (including recursive subdirectories) under the directory tree will be read as data sources, each file (except Excel family) corresponds to a record. E.g., skill_json_dir\n* Any combination of the above. E.g., xx.xlsx,sheet2@yy.xls,abc@zz.json,ccc_dir"
    - name: "outputFileName"
      type: "string"
      nullable: "Yes"
      description: "Output file name. If empty, it defaults to `FullName.LowerCase().Replace('.', '_')`."

```

--------------------------------

### Luban Configuration Type Mapper Property

Source: https://luban.doc.code-philosophy.com/docs/other/3.x/manual/schema

Explains the `typeMapper` mechanism in Luban, which allows mapping generated types to existing external struct types (e.g., `UnityEngine.Vector3`). It details the `targets`, `codeTargets`, and `options` fields for conditional mapping across different output targets and languages.

```APIDOC
typeMapper:
  description: "Allows generated code to directly use existing struct types instead of generating new ones. For example, mapping a configured 'vector3' type to 'UnityEngine.Vector3' in C#."
  fields:
    - name: "targets"
      type: "list<string>"
      nullable: "No"
      description: "Matching output targets. This target refers to the global definition's target."
    - name: "codeTargets"
      type: "list<string>"
      nullable: "No"
      description: "Matching code targets."
    - name: "options"
      type: "map<string,string>"
      nullable: "No"
      description: "Parameters required for generation, entirely determined by the specific CodeTarget. Different codeTargets require different parameters."

```

--------------------------------

### Luban Composite File Configuration

Source: https://luban.doc.code-philosophy.com/docs/other/manual/otherdatasource

Illustrates how to configure Luban to read data from multiple files or specific fields within files, using XML. It defines bean structures and table inputs, demonstrating patterns like *@ for record lists, field@ for specific fields, and *field@ for lists from specific fields.

```XML
<bean name="CompositeJsonTable1">
    <var name="id" type="int"/>
    <var name="x" type="string"/>
</bean>
<bean name="CompositeJsonTable2">
    <var name="id" type="int"/>
    <var name="y" type="int"/>
</bean>
<bean name="CompositeJsonTable3">
    <var name="a" type="int"/>
    <var name="b" type="int"/>
</bean>

<table name="TbCompositeJsonTable1" value="CompositeJsonTable1" input="*table1@composite_tables.json,*@composite_tables2.json,one_record.json"/>
<table name="TbCompositeJsonTable2" value="CompositeJsonTable2" input="*table2@composite_tables.json"/>
<table name="TbCompositeJsonTable3" value="CompositeJsonTable3" mode="one" input="table3@composite_tables.json"/>
```

--------------------------------

### 定义Luban Excel数据表格式

Source: https://luban.doc.code-philosophy.com/docs/other/beginner/quickstart

详细说明了Luban工具所需的Excel数据表结构。这包括字段名、类型、分组的特定标题行约定，以及注释行的使用，确保Luban工具能够正确解析数据。

```Excel Format Description
第1行: 字段名行 (单元格 A1 必须以##开头)
第2行: 字段类型行 (第1个单元格必须为 ##type)
第3行: 分组行 (c表示客户端, s表示服务器, c,s或留空表示所有)
第4行起: 注释行 (以##开头, 可以有0-N个, 且可以出现在任何位置)
第5行起: 数据行

推荐使用 xx_yy_zz 风格的字段名，Luban会根据生成的语言自动转换为该语言推荐的命名风格。
```

--------------------------------

### Define Table with Map Mode

Source: https://luban.doc.code-philosophy.com/docs/other/1.x/manual/define

Defines a table in map mode, which is a standard key-value table. If 'mode' and 'index' are not specified, it defaults to map mode, using the first field of 'value_type' as the key.

```XML
<table name="TbNormalMap" value="NormalMap" index="key1" input="normal_map.xlsx"/>
```
Tokens:
Raw