<!-- 本文件为机器翻译，原文：/tmp/woc_kit/WorldOfOldcraft-build-kit/KIT_README.md -->

# World of Oldcraft 构建套件

从零开始构建 World of Oldcraft——一个用 Unity 制作的经典 MMO 切片——Claude Code 所需的一切：任务说明、工作规则、hooks、项目技能、来自早期项目的管线经验、辅助脚本、已批准的概念图，以及由安装程序下载的风格参考图和 Mixamo 动画列表。

本套件会被复制到一个空白 Unity 项目的根目录。

## 内容

| 套件中的路径 | 复制到 | 说明 |
|---|---|---|
| `CLAUDE.md` | 项目根目录 | 代理的工作规则（自主性、分工线、记录、生成纪律、Unity/Blender 经验） |
| `Docs/TASK.md` | `Docs/` | 完整任务说明：MVP 路径、优先级与验收测试、种族与职业、管线、世界路线、UI、预算、里程碑、进度文档 |
| `Docs/KICKOFF.md` | `Docs/` | 要粘贴使用的启动、恢复、状态和收尾消息 |
| `Docs/PIPELINE_LESSONS.md` | `Docs/` | 来自早期代理运行的精炼经验，附来源 |
| `Docs/refs/manifest.json` | `Docs/refs/` | 70 张经典《魔兽世界》及高清粉丝重制的风格参考：来源页面、署名，以及每张应借鉴之处。图片不在套件中，由安装程序下载（`scripts/refs/fetch_refs.py`） |
| `Docs/concepts/approved/` | 同路径 | 已批准的概念图：种族、生物群系、城市、界面（代理的风格锚点） |
| `Docs/concepts/candidates/` | 同路径 | 所有生成的候选图 |
| `dot-claude/` | `.claude/` | 带 Stop hook 与压缩 hook 的 `settings.json`，以及项目技能 |
| `mcp.json` | `.mcp.json` | Unity、Blender 和 Higgsfield 的 MCP 服务器配置（路径由安装程序填写） |
| `env.example` | `.env` | `FAL_KEY=`，留空：在这里填入你自己的 fal.ai 密钥 |
| `knowledge/`、`processes/`、`projects/` | 同路径 | 技能链接到的文档：Mixamo 获取、Blender 动画经验、Unity 输入测试、角色创建、提示词编写、Higgsfield CLI |
| `scripts/` | 同路径 | `animation/download_mixamo.py` + `mixamo_core_set.json`（90 个动画片段）、`refs/fetch_refs.py`、`image-gen/generate.py`、`3d/center_glb_bottom.py`、`capture/make_timelapse.py` |
| `host-tools/` | 同路径 | 给你用的桌面延时摄影（不是给代理的） |
| `install_kit.ps1` | – | 安装程序 |

Mixamo 动画片段同样不在套件中：安装程序会把 90 个精选片段下载到 `Assets/_Source/Mixamo/`。

`knowledge/`、`processes/` 和 `projects/` 中的部分文档来自更早的一个 Unity 项目（Overlord），其中以其文件路径 `<Overlord project>/...` 的形式引用。那些文件不属于本套件；这些经验本身仍然成立。

## 一次性设置

1. **Unity Hub** 和 **Unity 6000.5.9f1**（Windows Build Support）。
2. **Node.js 22+**、**Python 3.11+**、**Git**、**ffmpeg**（`winget install Gyan.FFmpeg`）。
3. **Claude Code**，最新版本，用 Max 套餐登录。较新的版本会在用量限制重置后自行恢复。
4. **Unity MCP**（AnkleBreaker）：
   `git clone https://github.com/AnkleBreaker-Studio/unity-mcp-server C:\GIT\unity-mcp-server`，然后在其目录内执行 `npm install`。
5. **Blender 5.1**，安装 Blender MCP 插件及其 `blender-mcp` 服务器，并设置为随 Blender 启动。同时安装 Higgsfield 的 Blender 插件。
6. **Higgsfield CLI：** `npm install -g @higgsfield/cli`（最初那次运行用的是 1.1.24），然后 `higgsfield auth login`。检查额度。
7. `pip install -r requirements.txt`（fal-client、requests、pillow）。安装程序下载时需要这些依赖。

## 将套件安装到新项目

1. Unity Hub → New project → 6000.5.9f1 → Universal 3D → 例如 `C:\GIT\WorldOfOldcraft`。先打开一次。
2. 在 Unity 中：Package Manager → + → Add package from git URL → `https://github.com/AnkleBreaker-Studio/unity-mcp-plugin.git`。Console 应显示 `[MCP Bridge] Server started on port 7890`。Player Settings → Resolution → 打开 **Run In Background**。
3. 在项目里执行 `git init`，并配合 Unity 的 `.gitignore`。
4. 在套件文件夹中执行：
   ```powershell
   powershell -ExecutionPolicy Bypass -File install_kit.ps1 -Target "C:\GIT\WorldOfOldcraft" `
     -UnityMcpServerDir "C:\GIT\unity-mcp-server" -BlenderMcpCommand "C:\Users\<you>\.local\bin\blender-mcp.exe" `
     -BlenderExe "C:\Program Files\Blender Foundation\Blender 5.1\blender.exe" -FalKey "<your fal.ai key>"
   ```
   文档中已经写明 World of Oldcraft、100 美元的 fal.ai 预算上限以及约 10,000 点 Higgsfield 额度；加上 `-FalBudgetUsd 50` 可以调低上限。
   它会复制所有内容，把 `dot-claude` 重命名为 `.claude`、`mcp.json` 重命名为 `.mcp.json`，填好 MCP 路径，把 Mixamo 片段下载到 `Assets/_Source/Mixamo/`、参考图下载到 `Docs/refs/`，并从 `env.example` 生成 `.env`（绝不覆盖已存在的文件）。重复运行会保留已有的内容。
5. 确认 `.env` 中有你的 `FAL_KEY`（或现在粘贴进去）。提交；`.env` 已在 `.gitignore` 中。

## 开始之前

- 关闭所有其他 Unity 编辑器（否则 MCP 可能连到错误的项目）。
- 打开 Blender，MCP 已连接。Unity 已打开该项目。
- 电源计划设为从不睡眠；暂停 Windows Update；不要最小化 Unity 和 Blender 窗口。
- 在项目文件夹中运行 `claude --dangerously-skip-permissions`（仅限本项目），选择 1M 上下文的 Opus 5.5，运行 `/mcp`：unity、blender 和 higgsfield 均已连接（如提示则登录 Higgsfield）。
- 两分钟的冒烟测试，然后 `/clear`：“调用 unity_editor_ping，截一张 Blender 屏幕截图，运行 `higgsfield --version`，并用 `--dry-run` 运行 fal 辅助脚本。”
- 开始录制：OBS，以及下面的桌面延时摄影。

## 启动、查看进度、停止

- **启动：** 粘贴 `Docs/KICKOFF.md` §1 的启动消息。开头的 `ultracode` 一词会开启多代理工作流。
- **查看进度：** 输入状态消息（§3）；它会回答并继续工作。
- **崩溃或重启后：** `claude --continue`（或 `--resume`），然后粘贴恢复消息（§2）。
- **它不会自行停止。** Stop hook 会阻止每一次结束会话的尝试。要结束会话：按 Esc 并关闭会话，或创建 `.claude/ALLOW_STOP`，或把 `{"until": "2026-09-25T20:00:00+07:00"}` 写入 `.claude/session_window.json`，让它在该时间之后可以停止。先使用收尾消息（§4），让构建、视频和报告都完成。

## 桌面延时摄影（给你用的）

`host-tools/desktop_timelapse.ps1` 会以固定间隔把整个桌面的截图（用 ffmpeg，几乎不占 CPU）保存到 `Downloads\Oldcraft-desktop-timelapse\<date-time>\`。

```powershell
# 每 60 秒一张，在后台隐藏运行
powershell -ExecutionPolicy Bypass -File host-tools\desktop_timelapse.ps1 -Every 60 -Hidden
# 每 5 分钟一张，在可见窗口中运行（Ctrl+C 或关闭窗口即停止）
powershell -ExecutionPolicy Bypass -File host-tools\desktop_timelapse.ps1 -Every 300
# 只截一个显示器
powershell -ExecutionPolicy Bypass -File host-tools\desktop_timelapse.ps1 -Every 60 -Hidden -Region "0,0,2560,1440"
```

**停止：** `powershell -ExecutionPolicy Bypass -File host-tools\stop_desktop_timelapse.ps1`（对隐藏和可见运行都有效；已保存的帧会保留）。当一个运行实例还在进行时，第二次启动会被拒绝。

**生成视频：** `powershell -ExecutionPolicy Bypass -File host-tools\make_desktop_timelapse.ps1`（取最近一次会话）。每分钟一帧、持续 24 小时是 1,440 帧，按 30 fps 约 48 秒；每 5 分钟一帧是 288 帧，约 10 秒。替代方案：ShareX（Tools → Auto capture）或低帧率的 OBS。

代理自己也会记录工作：`Docs/progress/` 里按功能保存的进度截图，由 `scripts/capture/make_timelapse.py` 合成为按功能的延时视频、分镜脚本，以及一支总的“制作幕后”延时视频。

## 预算

- **fal.ai：** 硬性上限 100 美元（用 `-FalBudgetUsd` 修改）。代理会把每一次调用记录在 `Docs/COSTS.md`。
- **Higgsfield：** 主力生成器（约 10,000 点额度），合理使用。
- **免费资源：** 允许用于道具、贴图、音效和音乐（CC0 或免费许可，记录在 `Docs/LICENSES.md`）。

## 密钥

套件不含任何密钥。你的 fal.ai 密钥放在 `.env` 中，安装程序会把 `.env` 加入项目的 `.gitignore`；Higgsfield 使用 CLI 登录。不要提交或分享 `.env`。

## 许可

- **Mixamo 动画片段**受 Adobe 的 Mixamo 条款约束。安装程序在你自己的机器上下载它们；不要再分发原始文件。
- **风格参考**是第三方截图（Blizzard Entertainment）和粉丝作品，署名见 `Docs/refs/manifest.json`。它们只作为代理的风格参考：绝不用作贴图、绝不作为 3D 输入、绝不进入构建产物。
- `Docs/concepts/` 中的**概念图**是为本项目用 AI 图像模型生成的。