游戏开发【免费下载链接】TEngineUnity 商用级别开发框架原生内置 AI 工作流支持集成 HybridCLR 高性能热更、Obfuz 代码混淆加固、YooAssets 企业级资源管理方案构建高效、安全、可扩展的工业化开发底座。项目地址https://gitcode.com/gh_mirrors/teng/TEngine点击查看免费下载本篇指南面向在 TEngine 仓库中直接维护 Luban 游戏配置数据的开发者与 AI 编程代理完整讲解luban_helper.py这一底层 Excel 编辑器的命令用法、参数约定、Excel 结构解析原理以及如何与workflow.py导出工作流安全衔接。读完本文你将掌握用命令行安全完成表/字段/数据行/枚举/Bean 的增删改查、引用检查、批量导入导出与校验并学会在操作后交付 diff、校验与导出证据的完整闭环。一、工具定位这是低层编辑器不是事务服务luban_helper.py是 TEngine 仓库内为 AI 与开发者准备的 Luban 配置编辑器辅助脚本源码位于 UnityProject/.codex/skills/luban-dev/scripts/luban_helper.py其自身 docstring 即声明为Luban 配置编辑器辅助脚本用于 AI 操作 Luban 配置表、枚举、Bean 等。使用前必须明确三条边界它是底层 CRUD 工具脚本直接基于openpyxl读写.xlsx文件属于低层编辑器其成功输出与退出码不能当作完整业务校验。脚本开头即对 openpyxl 做了硬依赖检查缺少时直接打印错误: 请先安装 openpyxl: pip install openpyxl并退出源码 L28-L33且按 SKILL.md 约定缺少 openpyxl 时阻塞不自动安装。校验以真实 Luban 为准helper 的validate_all()只做结构级诊断无法完整解析多行 Bean 表头等语义工作流会保留该诊断并拒绝零表但最终依据是 Luban 在隔离目录生成的类型/引用校验结果详见 SKILL.md。导出入口已收口脚本中旧gen入口已被显式禁用gen()方法直接抛出RuntimeError源码 L2606-L2608生产导出统一走workflow.py工作流详见后文与导出工作流衔接一节。二、环境与命令基础约定helper 脚本约定在Unity 项目UnityProject/目录下执行数据源位于仓库Configs/GameConfig即从 Unity 项目出发的../Configs/GameConfig其中配置数据目录为Configs/GameConfig/Datas对应 luban.conf 中的dataDir: Datas。先查看全部能力python .codex/skills/luban-dev/scripts/luban_helper.py --help基础命令一览均以 Unity 项目为当前目录# 列出所有表 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table list # 获取某张表按注册名 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table get registered-name # 列出某张表的字段 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field list registered-name # 查询某个 Bean / 枚举被哪些位置引用 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas ref bean-or-enum四条必须遵守的参数约定--data-dir必须在子命令之前如上面示例所示table/field/row等的名称是位置参数不要随意调换顺序。写入类操作之前先读对应子命令的--help以脚本真实参数为准不要照抄或猜测参数名。复杂 JSON 一律用命令支持的--file从文件读取不要手拼 PowerShell 转义脚本在 Windows 下会强制重开 stdout/stderr 为 UTF-8 编码以兼容中文输出源码 L11-L19。表名、行索引、字段名都先查询再操作特别注意row update/delete使用的行索引是数据行在表中的物理索引从 0 开始不是默认主键值。helper 的能力面覆盖enum、bean、table、field、row以及批量batch、导入导出export/import、引用检查ref、类型系统type、模板template、别名alias、标签tag、变体variant、缓存cache等。以下各节逐一展开。三、子命令体系全览来自 argparse 定义从脚本 argparse 注册段L4322-L4698 可以看到完整的命令树顶层命令子命令作用enumlist/get/add/update/delete枚举维护delete支持--forcebeanlist/get/add/update/deleteBean结构体维护delete支持--forcetablelist/get/add/delete/update/check-legacy/migrate-auto表注册与数据查看fieldlist/add/update/delete/disable/enable字段级编辑disable是注释列不导出但保留数据rowlist/add/update/delete/get/query数据行编辑与查询batchfields/rows批量添加字段 / 数据行export/import—JSON 导出 / 导入--mode append\|replacevalidate—单表或全部表结构校验ref—引用完整性检查入参为 Bean/枚举名typeinfo/list/validate/suggest/search/guide类型系统辅助templatelist/create配置模板操作rename/copy/diff—表迁移与对比autolist/create自动导入表#前缀文件管理aliaslist/add/delete/resolve常量别名taglist/add/remove数据行标签variantlist/add字段变体如 zh/enmultirow—多行结构列表开关--disablecachebuild/clear缓存操作gen—已禁用导出统一走工作流prefset/get/list用户偏好如prefer_auto_import类型、别名、标签、变体等能力属于进阶维护手段使用前同样先查询对应子命令--help并以 type-system.md、schema.md 的语义约束为准。四、Excel 结构与解析原理先理解再动手helper 内置统一的 Sheet 结构解析器LubanSheetStructure源码 L36-L55核心是识别以下标记行##var字段名行##type类型行##注释行可有多行##group分组行可选数据起始行由这些标记行共同决定因此不要假设固定前四行。extra 注释行和纵表会改变数据起点。helper 新建横表时按##var行 →##type行 → 多行##注释 → 可选##group行 → 数据行的布局生成见_create_table_excel源码 L847-L941纵表则以##column开头、每行一个字段字段名 | 类型 | 注释 | 值适合单例表。定义类文件有三张均位于Configs/GameConfig/Datas__tables__.xlsx表注册表列含 full_name、value、input、index、mode、comment 等__beans__.xlsxBean 定义表__enums__.xlsx枚举定义表这三张是定义表不按业务行表的列格式处理。此外 helper 支持自动导入表约定以#开头的 xlsx 文件会被自动扫描注册源码 L545-L593命名规则为#Item.xlsx→ 表名TbItem记录类型Item#Item-道具表.xlsx→ 表名TbItem注释道具表reward/#Reward.xlsx→ 表名reward.TbReward子目录表示模块前缀默认偏好prefer_auto_import False即默认在__tables__.xlsx正式注册源码 L604-L606。另外注意保留 Sheet 名、表头、批注、公式和非目标单元格不要把整个 workbook 重建为纯值表容器与 Bean 的分隔符来自类型/schema不能普遍将中文逗号替换后认为合法详见 excel-format.md。五、表级操作实战table查看python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table list python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table get registered-nametable list会合并输出__tables__.xlsx中的正式注册表与#前缀自动导入表并标注source字段。新增表python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table add test.TbItem --fields id:int:ID:c,name:string:名称:c --value-type TbItem --input item.xlsx --mode map --index id --groups c,s --comment 物品表关键参数源码 L4382-L4394参数说明name表全名如test.TbItem可带模块前缀--fields字段定义格式name:type:comment:group,...或用 JSON 数组--value-type记录类型如TbItem--input输入文件名缺省时从表名自动推导如Item→item.xlsx--sheetSheet 名默认新文件用Sheet1已有文件用表名--mode表模式map/list 等--index主键定义如id或复合id1id2--groups分组列表如c,s会生成##group行--auto-import改用#前缀自动导入格式默认不推荐--vertical纵表模式适合单例表helper 在add_table后会自动对新建表执行一次validate_table并打印发现的错误/警告源码 L725-L732。分组group的显式性写入字段时必须显式给出groupc/s/e。虽然脚本提供了_infer_field_group关键词推断如字段名含name/icon/model/ui/texture推断为c含hp/mp/rate/cooldown推断为s源码 L1171-L1209但helper 的关键词推断不是业务分组依据不可依赖。业务分组以 luban.conf 的groupsc/s/e三组与targets定义为准新增字段和表时必须检查客户端/服务端影响且不要把c,s与[c,s]两种写法机械互换。其他表操作table update --comment/--input/--mode/--value-type修改表属性table delete [--delete-data]删除注册行可选同时删除数据文件table check-legacy检查可迁移到自动导入格式的老表table migrate-auto [name]迁移老表到#前缀格式不指定 name 则迁移所有rename old new [--migrate-data]、copy source target [--copy-data]、diff table1 table2 [--json]六、字段级操作实战field# 列出字段 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field list table # 添加字段--position 控制插入位置从 0 开始-1 为末尾 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field add table name --type int --comment 说明 --group c --position -1 # 修改字段 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field update table name --new-name new --type type --comment c --group g # 禁用字段注释列不导出但保留数据 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field disable table name # 启用字段 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field enable table name # 删除字段危险操作--force 跳过确认 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field delete table name多 Sheet 文件需追加--sheet sheet名。批量添加字段用batch fields table --data [{name:f1,type:int}]。类型写法遵循 type-system.md 的约定常用源类型为bool/byte/short/int/long/float/double/string/text/datetime及自定义 enum/bean容器示例list,int、array,string、map,string,int。源类型名不保证等于 C# 类型尤其 datetime、text、mapper、容器必须以当前 cs-bin 生成结果为准。七、数据行操作实战row# 列出数据行--start 从 0 开始--limit 默认 100 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row list table --start 0 --limit 100 # 按字段值取单行 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row get table --field id --value 1001 # 多条件查询 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row query table --conditions {type:Weapon,quality:5} # 新增行复杂 JSON 推荐 --file python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row add table --file row.json # 更新行index 为物理行索引从 0 开始不是主键值 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row update table 3 --file row.json # 删除行index 同上--force 跳过确认 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas row delete table 3批量新增用batch rows table --data [{id:1,...},{id:2,...}]。row add同时支持--data内联 JSON与--file推荐规避 PowerShell 转义问题两者在 源码 L4930-L4953 中统一经json.loads解析。红线row update/delete的INDEX参数是行索引而非主键值操作前务必先row list确认物理行位置。另外复杂/多行表头不要使用假定单行扁平结构的 CRUD——对纵表、多行列表等结构先读源码确认 helper 支持情况使用能保留单元格结构的编辑方式不支持时停止自动批量改写excel-format.md。八、枚举与 Bean 维护含引用安全删除枚举# 新增--values 格式 name1value1:alias1,name2value2:alias2 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas enum add test.EQuality --values Normal1:普通,Rare2:稀有 --comment 品质枚举 # 更新注释 / 切换 flags python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas enum update test.EQuality --comment 新注释 # 删除默认受引用检查保护--force 强制忽略引用 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas enum delete test.EQualityenum add的--flags用于标志枚举flags 必须验证值组合type-system.md枚举别名只是数据输入便利不可随意重编号。Bean# 新增--fields 支持 CSV 简写或 --file JSON 数组 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas bean add test.EquipInfo --fields id:int:ID,quality:test.EQuality:品质 --value-type 0 --sep | # 更新属性--sep/--comment/--alias/--parent/--value-type python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas bean update test.EquipInfo --value-type 1bean add关键参数--value-type 1表示值类型/struct用于listBean中的 Bean 必须设为 1--sep为 list 类型元素分隔符--parent支持继承多态、mapper、refgroup 等高级规则需先检查已安装 Luban 版本与现有示例再以隔离数据生成验证见 schema.md。引用安全删除ref delete_*_safe删除 Bean/枚举前必须先ref检查引用禁止为完成任务使用--force忽略引用。底层实现中check_references(type_name)构建类型引用索引_build_type_index()递归解析 Bean 字段与表字段中的list...、mapk,v容器引用返回referenced_by与can_delete源码 L2688-L2722delete_bean_safe()/delete_enum_safe()会先做引用检查存在引用时打印引用者列表并拒绝删除除非显式--force源码 L2724-L2749。正确姿势# 先查引用 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas ref test.EQuality # 确认无引用后删除不加 --force python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas enum delete test.EQuality九、校验、导入导出与批量校验 validate / validate_all# 校验单表 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas validate table # 校验全部表 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas validate --allvalidate_all()源码 L2576-L2602返回结构{total, valid, invalid, details[]}其中details逐表给出valid/errors/warnings。类型校验覆盖 int/float/bool 等基础类型源码 L2550-L2574对list/map/vector/array复杂类型跳过验证。必须牢记的局限helper 校验不能完整解析多行 Bean 表头等语义工作流会保留该诊断并拒绝零表total 为 0 时拒绝通过但最终以真实 Luban 在 runs 隔离目录生成的类型/引用校验为最终依据SKILL.md。导入导出# 导出表数据为 JSON默认打印到控制台--output 指定文件 python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas export table --output export.json # 从 JSON 导入--mode append 默认replace 未实现时必须明确失败不能退化为 append python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas import table import.json --mode appendJSON 导入契约详见>python .codex/scripts/workflow.py luban validate python .codex/scripts/workflow.py luban preview --mode lazyload # 展示预览收到真实确认后才执行 python .codex/scripts/workflow.py approve --plan preview.json --by reviewer --reason confirmation --high-risk python .codex/scripts/workflow.py luban apply --plan preview.json --approval approval.json python .codex/scripts/workflow.py luban test工作流validate会保存 helper 诊断再用当前 Luban 在runs隔离目录校验并导出不写生产产物preview --mode lazyload复用现有bin-sharded、dataExportersharded与自定义懒加载模板standard必须显式选择普通bin不是分片模式的故障回退。生成代码与 bytes 的目标目录为Assets/GameScripts/HotFix/GameProto与Assets/AssetRaw/Configs/bytes模板位于Configs/GameConfig/CustomTemplate加载器 ConfigSystem.cs运行时依赖说明见 runtime.md。缓存纪律缓存是派生数据不能覆盖源不要对任意目录执行cache clear。缓存命令cache build/clear只应在明确了解其语义后使用。证据交付每次操作后的源文件 diff、校验结果与导出证据必须一并交付SKILL.md 输出约定失败时保留输入与日志不回滚用户已有数据不将缺失产物或 Editor 离线写成通过。十一、安全红线与最佳实践小结红线正确做法--data-dir位置必须在子命令之前名称是位置参数参数猜测写入前先读子命令--helpPowerShell 转义复杂 JSON 一律--file行索引 vs 主键row update/delete用物理行索引先row list确认分组显式给group不依赖关键词推断删除 Bean/枚举先ref无引用才删禁止--force忽略引用复杂/多行表头不用单行扁平 CRUD先读源码确认导出禁用gen统一走workflow.py闭环JSON 导入replace未实现时明确失败不退化append缓存派生数据不覆盖源不做任意目录cache clear校验结论helper 成功输出 ≠ 完整业务校验以真实 Luban 隔离校验为最终依据交付附上源文件 diff、校验与导出证据按照以上约定你可以在 TEngine 仓库中安全、可审计地完成 Luban 配置的日常维护并与 TEngine 的 Lazyload/分片导出流水线无缝衔接。赞分享游戏开发【免费下载链接】TEngineUnity 商用级别开发框架原生内置 AI 工作流支持集成 HybridCLR 高性能热更、Obfuz 代码混淆加固、YooAssets 企业级资源管理方案构建高效、安全、可扩展的工业化开发底座。项目地址https://gitcode.com/gh_mirrors/teng/TEngine点击查看免费下载相关推荐LunaTranslator 实战指南日文游戏屏幕上直接出中文字幕LunaTranslator 实战指南日文游戏屏幕上直接出中文字幕 玩日文视觉小说最崩溃的时刻是什么不是读不懂假名而是每翻一句就切一次窗口、截一次图、粘一游戏开发Plate 编辑器行为维护命令手册双车道操作面与五命令工作流实战指南Plate 编辑器行为维护命令手册双车道操作面与五命令工作流实战指南 本文是 Plate基于 Slate 的富文本编辑器内置 AI 与 shadcn/ui前端富文本UI组件Emscripten SDKemsdk完全指南命令语法、安装配置与多版本维护实战Emscripten SDKemsdk完全指南命令语法、安装配置与多版本维护实战 Emscripten SDK简称 emsdk 是 Emscripte编译器WebAssembly开发工具构建工具上一篇TypeScript设计模式终极指南23种经典模式完整解析下一篇终极图片格式转换指南如何用docker-icloudpd实现HEIC到WebP批量处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考