# CLAUDE.md — World of Oldcraft 你正在一个长会话中自主构建 World of Oldcraft——一个使用 Unity 开发的经典奇幻 MMO MVP。完整任务见 `Docs/TASK.md`。这些规则在整个会话期间有效，优先级高于你此后推断出的任何内容。 **语言：** 一切内容都使用英文：代码、注释、文档、日志、提交信息和所有生成提示词。 ## 1. 每次启动、重启或上下文压缩之后 在做任何其他事情之前，按以下顺序阅读： 1. 本文件； 2. `Docs/PLAN.md`（里程碑、当前里程碑）和 `Docs/TODO.md`（按优先级排序的队列）； 3. `Docs/DEVLOG.md` 的最后三条记录和 `Docs/STATS.json`； 4. 在任何生成之前，阅读 `Docs/STYLE_BIBLE.md` 以及 `Docs/concepts/approved/` 中的图片； 5. 运行 `date` 以了解当前时间。 上下文会被压缩很多次。任何重要的事情都必须在决定的同时写入这些文件。如果某件事没有写进文件，就假定你会忘记它。 ## 2. 自主性 - 所有者不可用。绝不提问，也绝不等待答复。做出决定，把决定及其理由写入 `Docs/DECISIONS.md`，然后继续。 - 不要自行结束会话。当前任务完成后，从 `Docs/TODO.md` 取下一项。当 `TODO.md` 为空时，运行验收测试（`Docs/TASK.md` §2），把最薄弱环节的修复加入队列，然后继续。由所有者结束会话。 - 如果某个工具、API 或 MCP 服务器失败：短暂等待后重试两次，然后切换到替代路线，记录在案，继续推进。在下一个里程碑再次检查失败的工具。 - 在同一个问题上卡住超过 45 分钟真实时间：写下你尝试过的方法，选择回退方案或砍掉该项，继续前进。 ## 3. 记录与节奏 - `Docs/DEVLOG.md` 只可追加，带 UTC 时间戳：每个里程碑、每次已恢复的失败，以及至少每小时一条记录。 - 每小时：更新 `Docs/STATS.json`（耗时、提交数、C# 代码行数、各类资产尝试/接受/拒绝的数量、fal.ai 花费、Higgsfield 已用积分、生成调用次数、已修复缺陷数、FPS），并提交。 - 进度截图遵循 `Docs/TASK.md` §18：每次重大改动之后都要截图，且在你正在开发的特性上至少每 5 分钟真实时间截一次。这是工作的一部分。如果发现漏截，立即补截并继续。 ## 4. 编排（ultracode） 使用多代理工作流进行并行工作，每个共享资源有且仅有一个所有者： | 车道 | 负责 | 写入位置 | |---|---|---| | **Integrator**（主循环） | Unity 编辑器、场景、预制体摆放、项目设置、git | `Assets/_Project/`、场景 | | Characters | 种族身体、部件、头发、装备、NPC 身体、骨骼绑定、动画重定向 | `Assets/_Generated/characters/` | | Creatures | 小怪、狼、小动物 | `Assets/_Generated/creatures/` | | World kit | 建筑、道具、树、岩石、地形材质、天空、水面 | `Assets/_Generated/world/` | | UI & 2D | 边框、图标、光标、登录美术、加载画面、头像、logo | `Assets/_Generated/ui/` | | VFX | 特效贴图、粒子系统、着色器 | `Assets/_Generated/vfx/` | | Audio | 音乐、环境音、音效、语音 | `Assets/_Generated/audio/` | | Content | NPC 台词、任务文本 (P1)、假玩家名 (P1) | `Assets/_Data/` | | Reviewer | 阅读截图、概念图和参考图，打分，提交缺陷报告 | `Docs/reviews/` | - **只有 Integrator 可以通过 Unity MCP 修改打开的 Unity 编辑器**。其他车道产出文件加一份 `asset.json` 清单，并在 `Docs/INTEGRATION_QUEUE.md` 中添加一条条目。某个车道可以在自己的文件夹里为其系统编写 C#；由 Integrator 负责编译、接线和测试。 - **同一时刻只允许一个代理通过 Blender MCP 操作交互式 Blender 实例**。批处理工作（清理、减面、重置轴心、权重传递、烘焙、导出）在后台 Blender 进程中运行，可以并行。 - 保持工作流聚焦：一个车道、一个交付物、一个验证步骤、一个写入文件的结果。 ## 5. 永远可玩 - 从里程碑 M1 开始，黄金路径（登录 → 创建角色 → 进入世界 → 战斗 → 升级 → 主城）必须在每次提交时都能跑通。每个集成批次之后运行黄金路径驱动。 - 如果某项改动破坏了黄金路径，且 20 分钟内找不到明显的修复方法，就回滚它并重新入队。 - 至少每 30–60 分钟提交一次，提交信息要说明改了什么。绝不 force-push，绝不改写历史，绝不删除生成的源码。 ## 6. 生成纪律 - **优先使用 Higgsfield，并用得克制。** 它是主力生成器；一个典型资产用 1–3 次尝试即可，不做批量生成。**fal.ai 有硬性预算上限**（100 美元，`Docs/TASK.md` §15）。当 fal 额度用到 80% 时，只在 Higgsfield 没有对应能力的地方使用 fal；用到 100% 时，停止使用 fal。 - **允许使用免费资产**，凡是不定义整体视觉的东西（道具、贴图、声音、音乐）都可以：CC0 或免费许可，在 `Docs/LICENSES.md` 中记录来源和许可，存放在 `Assets/_External//` 下。绝不使用从商业游戏中提取的文件。 - 每次付费调用都要记录到 `Docs/COSTS.md` 和该资产的 `asset.json` 中：UTC 时间、提供方、端点或任务类型、请求或任务 ID、用途、资产 id、费用或积分、本地输出路径、结果（accepted/rejected + 原因）。 - 轮询超时不算失败。按 ID 恢复任务；只有在提供方确认失败后才重新提交。 - 同一资产在同一阶段最多尝试 3 次，之后改用替代路线或更简单的资产，并记录在案。 - 先出概念图，与已批准的概念图和风格圣经核对之后，再做 3D。保持一致的风格；拒绝破坏风格或比例的资产。 - 保持多边形数量在可玩范围内（`Docs/TASK.md` §14）：始终设置 `face_limit`，必要时再减面。 - 绝不在生成提示词中加入品牌词。以已批准的概念图为主要输入；`Docs/refs/` 中的截图仅作为 2D 概念图的风格参考（`Docs/TASK.md` §3）。拒绝任何出现真实游戏 logo 或名称的输出。 ## 7. 验证 - 你不给自己的作品打分。Reviewer 车道（一个全新上下文的代理）依据 `Docs/concepts/approved/`、`Docs/refs/` 和风格圣经为 Game View 截图打分。你提到的每张截图都必须亲自看过；绝不描述你没有打开过的图片。 - 状态词：*implemented*（已实现，即已存在）、*agent-verified*（代理已验证，即由测试夹具、探针或 Reviewer 在 Game View 中确认过）、*pending owner review*（待所有者审查，一切视觉内容的默认状态）。绝不可把任何东西标记为已获所有者接受。 - 在每个门禁处：控制台零错误、零缺失引用、黄金路径通过、在城市中实测 FPS。 ## 8. Unity 与 Blender 实践 来自所有者早期 Unity/Blender 代理项目的教训。每一条都曾耗费数小时。 **Unity** - 每次会话开始时，为本项目调用 `unity_list_instances` 和 `unity_select_instance`。如果另一个编辑器里开着别的项目，绝不要去碰它。 - 编译：先停止 Play Mode，刷新，然后轮询 `unity_editor_state` / `unity_get_compilation_errors`，直到 compiling 为 false，再继续。编译期间出现 60 秒的桥接超时，通常意味着编译其实已经成功。要轮询；不要盲目重试。 - 在 Play 期间刷新脚本会强制域重载：静态变量重置、运行时列表清空、雾效和单例重置。在刷新和预制体编辑之前先停止 Play。 - 如果调用挂起，先检查编辑器里是否有隐藏的模态对话框。保持勾选 "Run in Background"：未聚焦的编辑器会被降频，并返回过期的截图。 - 只使用 Input System。模拟的按下与释放必须落在不同的帧上。每次自动化测试结束后，在 `finally` 中恢复真实输入设备，并确认键盘和鼠标仍然可用（`knowledge/overlord-unity-test-input.md`）。 - HUD 只用 uGUI。IMGUI 和 overlay canvas 可能不会出现在相机截图中；用帧末的 Game View 截图来验证 UI。 - 长时间运行的检查以游戏内 Play Mode 测试夹具的形式运行并写出 JSON 结果；用一次短调用启动，然后轮询该文件。`unity_execute_code` 无法引用测试程序集：使用静态 `Run()` 入口点加反射。 - 材质：从 shader 全新创建，绝不 `new Material(existing)`。多子网格网格上只有一个材质时只会绘制 submesh 0。glTF 导入时强制 metallic 为 0。确认法线贴图是真正的 PNG 文件。对生成的 4K 贴图做降采样。 - FBX 导入：scale 1（检查是否出现 100 倍导入），关闭 root motion，关闭动画压缩，关闭重采样，30 fps。 - 录制：用一个隐藏的相机副本管道输出到 ffmpeg，设置 `Time.captureDeltaTime = 1/30`，预热约 20 帧；确认录制确实完成。 - 对 VFX 和飘字使用对象池。只按 PID 杀进程。崩溃后，在动任何东西之前先备份 `Assets/_Recovery/0.unity`。 **Blender** - MCP 脚本要保持简短且自包含（Python 全局变量在调用之间不会保留）。重活放在后台进程中运行：`blender --background --factory-startup --python