技术方向

• 动手实现之前，先读相关的 issue 和门禁，并核对当前代码：旧的 issue 可能把已经并入的功能描述成缺失。
• 每个切片：实现功能，新增或调整行为检查，证明它能发现缺陷，用隔离的配置运行整套测试，记入 CHANGELOG_3D，并在 commit 正文中引用 issue。新工作放在 feature/<nome> 分支上，再向 main 提 PR。
• 整套测试：.\tools\prototipo_3d\testar.ps1（或 -Teste salvamento）。测试以无头模式运行；截图以及依赖鼠标的测试（smoke_opening、mapa_fluxo、smoke_test）使用常规渲染器。
• 首次导入前先执行 git lfs pull：如果模型或 WAV 仍是 LFS 指针文件，预检会判定失败。
• Windows 导出通过 export_presets.cfg 输出到 build/windows/（需先创建该文件夹），使用与 Godot 版本一致的导出模板。
• 按键写在代码里，而不是 Input Map：teclas_movimento.gd（WASD、方向键或两者兼用）和 atalhos.gd（字母键可重新映射，冲突时自动互换；W、A、S、D 为保留键），保存在 user://controles.cfg 中。
• 共享规则是由门禁逐字节核对的副本；分叉文件清单（截至 2026年10月1日为 catalogo、inventario、equipamento、mochila）在任何同步之前，都要等作者做出决定。
• 位置和视觉决策不以 Vector3 的形式留在 world_builder 里：生成器读取的是已保存的编排。
• 调试：JOGAR_3D.cmd -Lugar igreja 会直接从山谷中的指定地点开始；-Compatibility 切换渲染器；-Godot CAMINHO.exe 指定另一个可执行文件。

体现在哪里

• 代码规模
  游戏脚本、测试和工具各有自己的文件夹。文件数、代码行数、自动加载项、场景、着色器和 JSON 数据从统计中记录的 Git 快照测量；项目页面展示当前代码、测试和数据的数量。
• 一行未改就迁移过来的 Salvamento
  它看起来是最盘根错节的一个，迁移时却一行都没改，因为它处处使用 get_node_or_null，在某个系统不存在的地方会自行降级；只有 Versao 需要在本地重新实现，改为读取 historico_3d.json。
• CadernoDoVale 与 CadeiaDeMissoes
  山谷独立的任务机制：每项任务有一条进度记录，任务链关联村民并读取各自的数据文件。目标包括材料、交付、对话、事件、计数、建造、访问和供奉；测试门禁检查任务链及完成任务所需的资源。
• 小地图门禁
  任务目标原本指向刚刚说过话的人，而不是玩家在面板上固定的那一项——这个毛病能存在那么久，是因为小地图从来没有门禁。现在有了，共七个问题。
• 菜单的飞越镜头
  依据山谷真实的三角面离线规划，记录在 data/sobrevoo_menu.json 中，并由 tests/sobrevoo_livre.gd 逐帧检查；如果锚点或比例发生变化，菜单会发出警告，并退回原来的椭圆轨迹。