TECH-06 · 目录与代码结构

1. 工程目录#

res://
  content/       compiled packs and schemas
  native/        C++ GDExtension hotspots
  scripts/       UI, services, commands, queries
  scenes/        Godot scenes only
  tools/         compiler, validator, inspectors
  tests/         data, simulation, save, platform, workshop
  docs/          contracts and release records

2. 模块职责#

建造域使用整数网格和 StructureReport；UI 只消费查询结果，不能直接写楼格、地基或结构数组。

模块	允许内容
content	定义、索引、manifest，不保存玩家状态
simulation	权威状态和批处理，不引用 Control/Node
commands	玩家意图和参数校验
queries	分页、排序、摘要、只读 DTO
save	分块编码、迁移、备份、恢复
platform	Steam/本地替身/Workshop 适配
ui	显示、输入、焦点和错误提示

3. C++ GDExtension 边界#

C++ 只承载通过基准证明为热点的数组运算、批处理、压缩或索引。接口以稳定的输入快照和结果包为单位，不把 C++ 指针暴露给 UI。每个原生模块必须有 GDScript 参考实现或校验实现。

4. 版本控制#

源码、Schema、制作源、编译器、测试夹具和文档进入版本控制；编译缓存、用户存档、Workshop 缓存、导出包和本机绝对路径不进入仓库。

5. 内容生产目录#

资料片源数据按 pack/id 分目录；共享定义放 core；覆盖和扩展必须显式声明。目录结构不承担依赖语义，依赖只由 manifest 表达。

6. 代码审查清单#

审查时检查：是否绕过 Command；是否让 UI 写权威数据；是否全量扫描世界；是否创建实体级 Node；是否在线程中写共享容器；是否没有迁移和回滚；是否直接调用 Steam API。