# SU → Unity Walkthrough

把已有 SketchUp 模型制作成可编辑的 Unity 第一人称漫游。AI 通过标准 MCP 分析模型、建立配置、执行和检查；用户只确认关键歧义与体验效果。

支持行走、开关门、多个模型/入口、源材质与可逆纯白显示、鼠标灵敏度、直观日照和画质设置。原 SKP 只读。自有代码 MIT。

![合成样件：源材质、透明玻璃与平开门](docs/images/synthetic-sample.png)

## 安装

需要 macOS Apple Silicon、Python 3.11+、已有 Unity 6 URP 工程、Input System、Unity CLI/Pipeline、可合法使用的本机 SketchUpAPI 和字体。实际验证版本见 [验证记录](docs/validation.md)。安装本项目不安装或升级这些软件。

```sh
uv sync --extra convert --extra dev --locked
.venv/bin/su-unity-walkthrough environment
.venv/bin/su-unity-walkthrough-mcp --root /absolute/path/to/your/workspace
```

解析器在独立 Python 环境中运行，不需要 Blender。配置中的 `python` 应指向该 `.venv/bin/python`，不要把它改成解引用后的系统 Python。第三方包通过原始包分发和锁文件安装，本仓库不附带 SDK、字体或二进制依赖。

把 `skills/su-unity-walkthrough` 安装到 AI 客户端可发现的技能目录。标准 stdio MCP 客户端配置示例：

```json
{
  "mcpServers": {
    "su-unity-walkthrough": {
      "command": "/absolute/path/to/repository/.venv/bin/su-unity-walkthrough-mcp",
      "args": ["--root", "/absolute/path/to/your/workspace"]
    }
  }
}
```

工作区应包含输入模型、配置、Unity 工程和输出目录；MCP 拒绝越出该根目录的工程数据路径。软件可执行文件、SDK 与字体是显式环境输入，不复制到开源仓库。

## 使用

对 AI 说：

> 使用 su-unity-walkthrough，把这些 SKP 制作成 Mac 漫游。保留源文件，先核对隐藏状态、入口和门，样件确认后完成完整场景、程序与检查记录。

AI 用 `project_create` 建草案，在原生清单出来后补齐入口和门。入口、门轴和隐藏状态不能从名字猜。当前磁盘哈希不证明 SketchUp 窗口没有未保存改动。

阶段顺序：

```text
preflight → convert → inspect → assemble(sample) → verify(sample)
→ 样件目视检查 → assemble → verify → build → 独立程序实际输入
```

长任务返回 job ID，用 `job_get` 查询。未知状态先 `job_reconcile`，不重复导入。每轮使用新 output、scene 和 assetRoot。配置生成后可通过 MCP 完成分析、核对、预览与执行，人工观察单独记录。

[完整工作流](skills/su-unity-walkthrough/SKILL.md) · [MCP 接口](docs/mcp.md) · [合成样例](examples/README.md) · [依赖与恢复](docs/installation.md)

## 范围与验证

首发仅承诺经过实测的 Mac Apple Silicon 链路。Windows/WebGL 接口留待各自真实环境验收。门的动画和配置路线检查不等于全屋任意通行、完整门扇扫掠或建筑专业合规。

构建成功与独立程序体验分别登记。`workflow_status` 只有在所有阶段及当前绑定的观察记录完成后才返回 `ready_for_observed_scope`。具体已查与未查见 [验证记录](docs/validation.md)。

仓库仅包含工具、合成样例生成器和提炼后的经验。真实建筑项目与原始聊天留在本地回归。

## 开发

```sh
.venv/bin/python -m pytest -q
.venv/bin/python skills/su-unity-walkthrough/scripts/test_workflow.py
uv build
```

源码技能是唯一维护源；wheel 包包含同一份 toolkit。不要在发行包、项目副本和全局技能目录各自维护分叉。贡献前看 [贡献说明](CONTRIBUTING.md) 与 [第三方说明](THIRD_PARTY_NOTICES.md)。