引擎参考文档¶

此目录包含本项目所用的游戏引擎的精选、版本固定的文档快照。这些文件的存在是因为 LLM 知识存在截止日期，而游戏引擎更新频繁。

为什么存在¶

Claude 的训练数据存在知识截止日期（目前为 2025 年 5 月）。Godot、Unity 和 Unreal 等游戏引擎发布的更新会引入破坏性 API 变更、新功能和已弃用的模式。如果没有这些参考文件，代理会建议过时的代码。

结构¶

每个引擎都有自己的目录：

<engine>/
├── VERSION.md              # Pinned version, verification date, knowledge gap window
├── breaking-changes.md     # API changes between versions, organized by risk level
├── deprecated-apis.md      # "Don't use X → Use Y" lookup tables
├── current-best-practices.md  # New practices not in model training data
└── modules/                # Per-subsystem quick references (~150 lines max each)
    ├── rendering.md
    ├── physics.md
    └── ...

代理如何使用这些文件¶

引擎专家代理被指示：

1. 阅读 VERSION.md 以确认当前引擎版本
2. 在建议任何引擎 API 之前检查 deprecated-apis.md
3. 查阅 breaking-changes.md 以了解特定版本的注意事项
4. 阅读相关的 modules/*.md 以进行子系统相关工作

维护¶

何时更新¶

• 升级引擎版本后
• 当 LLM 模型更新时（新的知识截止日期）
• 运行 /refresh-docs 之后（如果可用）
• 当你发现模型对某个 API 的理解有误时

如何更新¶

1. 使用新的引擎版本和日期更新 VERSION.md
2. 在 breaking-changes.md 中为版本过渡添加新条目
3. 将新弃用的 API 移入 deprecated-apis.md
4. 使用新模式更新 current-best-practices.md
5. 使用 API 变更更新相关的 modules/*.md
6. 在所有修改过的文件上设置“Last verified”日期

质量规则¶

• 每个文件都必须有一个“Last verified: YYYY-MM-DD”日期
• 保持模块文件在 150 行以内（上下文预算）
• 包含展示正确/不正确模式的代码示例
• 链接到官方文档 URL 以供验证
• 只记录与模型训练数据不同的内容