{"id":51302440,"url":"https://github.com/killop/puerts-unity-mcp","last_synced_at":"2026-07-02T23:00:46.317Z","repository":{"id":368394508,"uuid":"1281200786","full_name":"killop/puerts-unity-mcp","owner":"killop","description":"unity-mcp driven by tencent puerts , invoke js/ts  call c#  in your cell phone and unity editor","archived":false,"fork":false,"pushed_at":"2026-07-01T11:37:55.000Z","size":85923,"stargazers_count":34,"open_issues_count":0,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T22:28:16.584Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/killop.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-26T10:13:34.000Z","updated_at":"2026-07-01T19:05:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/killop/puerts-unity-mcp","commit_stats":null,"previous_names":["killop/puerts-unity-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/killop/puerts-unity-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/killop%2Fpuerts-unity-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/killop%2Fpuerts-unity-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/killop%2Fpuerts-unity-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/killop%2Fpuerts-unity-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/killop","download_url":"https://codeload.github.com/killop/puerts-unity-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/killop%2Fpuerts-unity-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35065702,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-30T21:02:09.753Z","updated_at":"2026-07-02T23:00:46.274Z","avatar_url":"https://github.com/killop.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003ePuerTS Unity MCP\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e通过 MCP 控制 Unity Editor、Play Mode 和真实手机游戏，并在运行中的游戏里动态执行 PuerTS JavaScript。\u003c/strong\u003e\n  \u003cbr /\u003e\n  \u003cem\u003eAndroid · iOS · IL2CPP · Editor JS · Runtime JS · C# 和 JS MCP Tool · Domain Reload 恢复\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#快速开始\"\u003e\u003cimg src=\"https://img.shields.io/badge/Quick_Start-4CAF50?style=for-the-badge\" alt=\"Quick Start\" /\u003e\u003c/a\u003e\n  \u003ca href=\"#agent-puerts-js-速查\"\u003e\u003cimg src=\"https://img.shields.io/badge/Agent_JS_Guide-1976D2?style=for-the-badge\" alt=\"Agent JS Guide\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Unity-2021.3%2B-black?style=flat\u0026logo=unity\u0026logoColor=white\" alt=\"Unity 2021.3+\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PuerTS-3.0.2-blue?style=flat\" alt=\"PuerTS 3.0.2\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/MCP-JSON--RPC-6A5ACD?style=flat\" alt=\"MCP JSON-RPC\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/IL2CPP-supported-2E7D32?style=flat\" alt=\"IL2CPP supported\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e · 中文\n\u003c/p\u003e\n\n---\n\n## 功能特性\n\n| 能力 | 说明 |\n|---|---|\n| 手机直连动态调试 | Agent 可以直接连接 Android、iOS 或 standalone Unity Player，在真实运行中的游戏里执行 PuerTS JavaScript。 |\n| 支持 IL2CPP Player | 构建脚本会加入 PuerTS 包、native plugin、StreamingAssets 配置、Android 权限库和保留提示，用于手机和 IL2CPP 构建。 |\n| Editor 执行 JS 不触发 Domain Reload | `editor.js.eval` 在 Editor PuerTS VM 里执行 JS，不生成 C# 文件，不调用 `AssetDatabase.Refresh`，正常自动化流程不会触发 Unity domain reload。 |\n| Runtime 执行 JS | `runtime.js.eval` 可以指向本地 Play Mode，也可以指向远程 Player MCP，包括手机。 |\n| C# 和 JS 扩展 MCP Tool | 核心工具用 C# 写，项目工具可以放在 `puerts-unity-mcp-extension/Editor/editor-tools` 和 `Runtime/runtime-tools` 里用 JS 写。 |\n| Domain Reload 稳定性 | Editor MCP 会持久化 operation、compile result、reload hint，并在 Unity domain reload 后自动恢复 HTTP endpoint。 |\n\n## 它控制什么\n\nPuerTS Unity MCP 把每个可控制的 Unity 整体都看成一个 endpoint。\n\n```text\nAgent / MCP client\n  |\n  | stdio JSON-RPC\n  v\nNode stdio proxy\n  |\n  | HTTP JSON-RPC POST /mcp\n  v\n+----------------------+      direct C# route      +-----------------------+\n| Unity Editor MCP     | ------------------------\u003e | Play Mode Runtime MCP |\n| endpointKind=editor  |                           | endpointKind=player   |\n| C# + Editor PuerTS   |                           | C# + Runtime PuerTS   |\n+----------------------+                           +-----------------------+\n        |\n        | LAN discovery or direct target URL\n        v\n+----------------------+\n| Phone / Player MCP   |\n| Android, iOS, build  |\n| C# + Runtime PuerTS  |\n+----------------------+\n```\n\nEditor Play Mode 不是第三种 MCP。它是运行在 Unity Editor 进程内的同一套 Runtime MCP 实现。\n\n## 快速开始\n\n### 拉取 PuerTS 依赖\n\n```bash\nnode Packages/puerts-unity-mcp/Tools~/vendor-puerts.mjs\n```\n\n这个命令会下载并校验 PuerTS `Unity_v3.0.2` Core 和 V8 包，放到 `third_party/puerts`。\n\n### 同步到 Unity 工程\n\n```bash\nnode Packages/puerts-unity-mcp/Tools~/sync-local-package.mjs --unity-project-root \u003cUnityProject\u003e\n```\n\nUnity 工程里会出现：\n\n```text\n\u003cUnityProject\u003e/puerts-unity-mcp\n\u003cUnityProject\u003e/puerts-unity-mcp-extension\n\u003cUnityProject\u003e/.puerts-unity-mcp\n```\n\n### 注册本地 UPM 包\n\n同步脚本会在 `Packages/manifest.json` 里加入三个本地依赖：\n\n```json\n{\n  \"dependencies\": {\n    \"com.tencent.puerts.core\": \"file:../puerts-unity-mcp/third_party/puerts/unity/upms/core\",\n    \"com.tencent.puerts.v8\": \"file:../puerts-unity-mcp/third_party/puerts/unity/upms/v8\",\n    \"puerts-unity-mcp\": \"file:../puerts-unity-mcp/Packages/puerts-unity-mcp\"\n  }\n}\n```\n\n### 配置 Agent\n\n同步后打开 Unity 工程内的 Agent 配置说明：\n\n```text\n\u003cUnityProject\u003e/puerts-unity-mcp/Packages/puerts-unity-mcp/setup-for-agent.md\n```\n\nCodex 的 MCP 配置示例：\n\n```toml\n[mcp_servers.\"puerts-unity-mcp\"]\ncommand = \"node\"\nargs = [\n  \"\u003cUnityProject\u003e/puerts-unity-mcp/Packages/puerts-unity-mcp/Tools~/puerts-unity-mcp-stdio-proxy.js\",\n  \"--config\",\n  \"\u003cUnityProject\u003e/puerts-unity-mcp-extension/editor-mcp-config.json\"\n]\n```\n\n## 手机和 IL2CPP 构建\n\nQA 手机和真实 Player 构建需要把 Runtime MCP 编进包：\n\n```bash\nnode \u003cUnityProject\u003e/puerts-unity-mcp/Packages/puerts-unity-mcp/Tools~/add-pum-to-build.mjs --unity-project-root \u003cUnityProject\u003e\n```\n\n从 Player 构建里移除：\n\n```bash\nnode \u003cUnityProject\u003e/puerts-unity-mcp/Packages/puerts-unity-mcp/Tools~/remove-pum-from-build.mjs --unity-project-root \u003cUnityProject\u003e\n```\n\n`add-pum-to-build.mjs` 会做这些事：\n\n- 添加本地 PuerTS 和 PuerTS Unity MCP package 依赖\n- 把 `puerts-unity-mcp-extension/mobile-mcp-config.json` 复制到 `Assets/StreamingAssets/PuertsUnityMcp/mobile-mcp-config.json`\n- 确认 `third_party/puerts` 下官方 PuerTS Android native libraries 存在，并使用 `Packages/puerts-unity-mcp/Runtime/Plugins/Android` 下随包提供的 MCP Android 权限库\n- 使用适合手机的低 IO 默认配置\n\n`remove-pum-from-build.mjs` 会移除构建依赖和复制到 `StreamingAssets` 的配置，但不会删除 package 自带的 Android plugin 文件。\n\n手机里的 Runtime MCP 会暴露：\n\n```text\nGET  /health\nPOST /mcp\n```\n\nAgent 不开 Unity Editor 也可以直接连手机：\n\n```bash\nnode \u003cUnityProject\u003e/puerts-unity-mcp/Packages/puerts-unity-mcp/Tools~/puerts-unity-mcp-stdio-proxy.js \\\n  --config \u003cUnityProject\u003e/puerts-unity-mcp-extension/editor-mcp-config.json \\\n  --target-kind player \\\n  --target-url http://PHONE_IP:18991\n```\n\nLAN discovery 使用 UDP `18992` 和 `name_group`。如果办公 Wi-Fi、AP 隔离、跨 VLAN、VPN 策略或防火墙禁掉 UDP broadcast/multicast，可以使用 HTTP fallback：\n\n```json\n{\n  \"selectedTargetKind\": \"player\",\n  \"name_group\": \"default\",\n  \"lanHttpProbeHosts\": [\"192.168.1.55\"],\n  \"lanHttpProbeCidrs\": [\"192.168.1.0/24\"],\n  \"lanHttpProbeTimeoutMs\": 1000\n}\n```\n\n## Editor JS 不触发 Domain Reload\n\n使用 `editor.js.eval` 做 Editor 自动化。它在现有 Editor PuerTS VM 中执行 JS，不创建 C# 脚本，也不触发编译。\n\n```json\n{\n  \"name\": \"editor.js.eval\",\n  \"arguments\": {\n    \"mode\": \"expression\",\n    \"code\": \"CS.UnityEditor.EditorApplication.isPlaying\"\n  }\n}\n```\n\n这和临时生成 C# 文件完全不同。JS eval 不调用 `AssetDatabase.Refresh`，所以常规 Editor 自动化流程不会触发 Unity domain reload，操作会更流畅。\n\n如果项目 C# 修改导致 domain reload 无法避免，Editor MCP 会把 operation 状态写到 `.puerts-unity-mcp/ops`，保存 compile result hint，并在 `afterAssemblyReload` 后恢复 HTTP endpoint。\n\n## MCP Tool 扩展\n\n核心工具由 C# 注册。项目工具可以用 JS 写，放在 Unity 工程的 extension 目录里。\n\n```text\n\u003cUnityProject\u003e/puerts-unity-mcp-extension\n  Editor/editor-tools      Editor 侧 JavaScript MCP tools\n  Runtime/runtime-tools    Runtime / Player 侧 JavaScript MCP tools\n  skills                   给 Agent 使用的项目技能\n```\n\n每个 JavaScript MCP tool 使用一个 manifest 指向模块：\n\n```json\n{\n  \"name\": \"runtime.activeScene\",\n  \"description\": \"Return the active Unity scene through the runtime PuerTS VM.\",\n  \"modulePath\": \"active-scene.mjs\",\n  \"functionName\": \"execute\",\n  \"inputSchema\": {\n    \"type\": \"object\",\n    \"additionalProperties\": true\n  }\n}\n```\n\nRuntime JS tool 会通过 `runtime.js.eval` 执行，所以同一套工具模型可以同时用于 Play Mode 和真实手机。\n\n## 内置 MCP Tools\n\n`tools/list` 会返回当前 endpoint 实际可用的工具。下面是 package 自带的 C# 内置工具；项目自己的 JS tools 会额外从 `puerts-unity-mcp-extension` 加载，例如 `game.*` 这类工具不属于通用内置工具。\n\n### Editor MCP\n\n| Tool | 用途 |\n|---|---|\n| `mcp.info` | 返回 Editor endpoint metadata、health 和 capability。 |\n| `editor.state` | 返回 Unity Editor 当前状态。 |\n| `editor.buildSettings.startupScene` | 返回 Build Settings 第一个启用场景。 |\n| `editor.js.eval` | 在 Editor PuerTS VM 中执行 JS，不生成 C#，正常情况下不触发 domain reload。 |\n| `editor.scriptTools.list` | 列出 `puerts-unity-mcp-extension/Editor/editor-tools` 中的项目 JS tools。 |\n| `editor.scriptTools.reload` | 重新加载 Editor 项目 JS tools。 |\n| `editor.skills.list` | 列出 `puerts-unity-mcp-extension/skills` 中的项目 skills。 |\n| `editor.skill.load` | 加载一个项目 skill。 |\n| `editor.playmode.set` | 延迟进入、退出或切换 Play Mode。 |\n| `editor.playmode.state` | 返回 Play Mode 状态。 |\n| `editor.playmode.set.immediate` | 立即进入、退出或切换 Play Mode。 |\n| `editor.targets.list` | 列出当前 Editor 和同 `name_group` 的 LAN Editor endpoints。 |\n| `runtime.targets.list` | 列出本地 Play Mode Runtime 和发现到的 Player endpoints。 |\n| `targets.list` | 列出 Editor、Play Mode Runtime、LAN Editors 和真实 Player targets。 |\n| `lan.discovery.scan` | 发送 LAN discovery，并按配置执行 HTTP fallback 探测。 |\n| `runtime.js.eval` | 从 Editor 转发 JS 到本地 Play Mode Runtime 或远程 Player/手机。 |\n| `runtime.tool.call` | 从 Editor 调用本地 Play Mode 或远程 Player 的 runtime MCP tool。 |\n| `editor.compile` | 触发 `AssetDatabase.Refresh`，并持久化编译结果 hint，用于 domain reload 恢复测试。 |\n| `op.status` | 读取持久 operation 状态或结果。 |\n\n### Runtime / Player MCP\n\n这些工具在 Editor Play Mode、Android、iOS 和 standalone Player 中可用；手机直连时 Agent 也是调用这一组。\n\n| Tool | 用途 |\n|---|---|\n| `mcp.info` | 返回 Runtime/Player endpoint metadata、health 和 capability。 |\n| `runtime.status` | 返回 Runtime/Player endpoint 状态。 |\n| `runtime.targets.list` | 列出当前 Player endpoint 和该 Player 发现到的 LAN endpoints。 |\n| `targets.list` | `runtime.targets.list` 的别名。 |\n| `lan.discovery.scan` | 发送同 `name_group` 的 LAN discovery query。 |\n| `runtime.js.eval` | 在 Runtime PuerTS VM 中执行 JS。 |\n| `runtime.reflection.invoke` | 通过反射 gateway 调用静态 C# 方法。 |\n| `runtime.scriptTools.list` | 列出 `puerts-unity-mcp-extension/Runtime/runtime-tools` 中的项目 JS tools。 |\n| `runtime.scriptTools.reload` | 重新加载 Runtime 项目 JS tools。 |\n| `runtime.skills.list` | 列出项目 skills。 |\n| `runtime.skill.load` | 加载一个项目 skill。 |\n| `op.status` | 读取持久 operation 状态或结果。 |\n| `runtime.logs` | 返回 Runtime log ring buffer 中的最近日志。 |\n| `runtime.logs.clear` | 清空 Runtime log ring buffer。 |\n| `screen.screenshot` | 截取 Player 画面；手机默认使用 memory PNG base64，减少设备 IO。 |\n| `runtime.ui.snapshot` | 返回可见 UGUI canvas、button 和可点击控件快照。 |\n| `runtime.ui.find` | 按 text、name、path 或 canvas 查找 UGUI 控件。 |\n| `runtime.ui.raycast` | 对屏幕点或目标控件执行 UI raycast。 |\n| `runtime.ui.click` | 按坐标、path 或 instanceId 点击 UGUI 控件。 |\n| `input.tap` | `runtime.ui.click` 的别名。 |\n\n## Agent PuerTS JS 速查\n\n这一节是专门写给 Agent 的，用于生成 `editor.js.eval`、`runtime.js.eval` 或项目 JavaScript MCP tool 的代码。\n\n### 选择目标 VM\n\n| 任务 | Tool | VM |\n|---|---|---|\n| Unity Editor 自动化 | `editor.js.eval` | Editor PuerTS VM |\n| Play Mode Runtime 自动化 | `runtime.js.eval` 指向本地 Play Mode target | Runtime PuerTS VM |\n| Android、iOS、standalone 自动化 | `runtime.js.eval` 指向 `targetId` 或 `httpUrl` | 手机或 Player 里的 Runtime PuerTS VM |\n\nEditor 和 Runtime 是两个独立的 PuerTS `ScriptEnv`。Editor 代码可以使用 `UnityEditor` API。Runtime 和手机代码应使用运行时安全的 API。\n\n### 基础 PuerTS 写法\n\n优先使用 PuerTS 的 `CS` 全局对象。\n\n```js\nCS.UnityEngine.Debug.Log(\"hello from PuerTS Unity MCP\");\n\nvar productName = CS.UnityEngine.Application.productName;\nvar sceneName = CS.UnityEngine.SceneManagement.SceneManager.GetActiveScene().name;\n\nreturn {\n  ok: true,\n  productName: productName,\n  sceneName: sceneName\n};\n```\n\n`mode: \"expression\"` 会自动返回表达式：\n\n```js\nCS.UnityEngine.Application.version\n```\n\n`mode: \"script\"` 需要显式 `return`：\n\n```js\nvar go = CS.UnityEngine.GameObject.Find(\"Canvas\");\nreturn {\n  found: !!go,\n  name: go ? go.name : \"\"\n};\n```\n\n### 反射 fallback\n\n如果某个 C# 类型没有生成 wrap，使用 `__unity_mcp`。这个项目当前走 reflection-first，适合开发阶段和项目特有的 IL2CPP 排查。\n\n```js\nreturn __unity_mcp.invokeStatic(\n  \"UnityEngine.Debug\",\n  \"Log\",\n  \"hello through reflection\"\n);\n```\n\n常用 helper：\n\n```js\n__unity_mcp.typeExists(\"UnityEngine.Application\");\n__unity_mcp.getStatic(\"UnityEngine.Application\", \"productName\");\n__unity_mcp.getStaticPath(\"UnityEngine.Screen\", \"width\");\n__unity_mcp.setStatic(\"UnityEngine.Time\", \"timeScale\", 1);\n__unity_mcp.invokeStatic(\"UnityEngine.Debug\", \"Log\", \"message\");\n```\n\n在 IL2CPP 包里，反射取决于类型和成员是否被 stripping。遇到被裁剪的类型时，用 link.xml 或项目包装类补保留。\n\n### 手机 UI 自动化模式\n\n黑盒自动玩手机游戏时，先观察，再操作。\n\n```js\nvar root = CS.UnityEngine.GameObject.Find(\"UICanvas\");\nreturn {\n  hasUiCanvas: !!root,\n  screen: {\n    width: CS.UnityEngine.Screen.width,\n    height: CS.UnityEngine.Screen.height\n  }\n};\n```\n\n然后组合 runtime MCP 工具：\n\n- `screen.screenshot`\n- `runtime.ui.snapshot`\n- `runtime.ui.find`\n- `runtime.ui.raycast`\n- `runtime.ui.click`\n- `input.tap`\n\n稳定的项目流程不要一直生成一次性 eval 脚本，应该沉淀到 `puerts-unity-mcp-extension/Runtime/runtime-tools`。\n\n### 返回值规则\n\n返回 JSON 可序列化数据：字符串、数字、布尔值、数组和普通对象。不要直接返回 Unity 对象。\n\n```js\nvar camera = CS.UnityEngine.Camera.main;\nreturn {\n  hasMainCamera: !!camera,\n  cameraName: camera ? camera.name : \"\"\n};\n```\n\n## 协议表面\n\nHTTP endpoints：\n\n| Endpoint | 用途 |\n|---|---|\n| `GET /health` | endpoint 元数据、运行状态、能力摘要 |\n| `GET /api/ping` | 轻量 health alias |\n| `POST /mcp` | 同步 JSON-RPC MCP 调用 |\n\n主要 MCP methods：\n\n- `initialize`\n- `ping`\n- `tools/list`\n- `tools/call`\n\nC# 侧 JSON 序列化只使用 Unity `JsonUtility`。项目不依赖 Newtonsoft.Json 或其他第三方 JSON 库。\n\n## 配置和状态目录\n\n持久项目配置：\n\n| 路径 | 用途 |\n|---|---|\n| `puerts-unity-mcp-extension/editor-mcp-config.json` | Editor、Agent、target 选择、LAN discovery 配置 |\n| `puerts-unity-mcp-extension/mobile-mcp-config.json` | Runtime / Player 配置，会复制进构建 |\n| `Packages/puerts-unity-mcp/Runtime/Plugins/Android` | 随包提供的 MCP Android 权限库；PuerTS native libraries 来自 `third_party/puerts` 官方 UPM 包 |\n| `Assets/puerts-unity-mcp/Runtime/Generated/Plugins/puerts_il2cpp` | 当前 Unity 工程生成的 PuerTS IL2CPP bridge 文件；应忽略并按工程重新生成，不要当成通用 package 源码提交 |\n| `puerts-unity-mcp-extension/Editor/editor-tools` | 项目 Editor JS MCP tools |\n| `puerts-unity-mcp-extension/Runtime/runtime-tools` | 项目 Runtime JS MCP tools |\n| `puerts-unity-mcp-extension/skills` | 给 Agent 使用的项目技能 |\n\n临时状态和 operation 数据：\n\n| 路径 | 用途 |\n|---|---|\n| `.puerts-unity-mcp/editors/{editorId}/heartbeat.json` | Editor heartbeat |\n| `.puerts-unity-mcp/players/{playerId}/heartbeat.json` | 可选 Player heartbeat |\n| `.puerts-unity-mcp/ops/{operationId}` | 持久 operation 状态和结果 |\n| `.puerts-unity-mcp/temp/compile-results` | 编译结果提示 |\n\n## Unity 工程 `.gitignore`\n\n在 Unity 工程的 `.gitignore` 里加入：\n\n```gitignore\n# PuerTS Unity MCP 运行状态和工程本地生成文件\n.puerts-unity-mcp/\nAssets/puerts-unity-mcp/Runtime/Generated/\nAssets/puerts-unity-mcp/Runtime/Generated/Plugins/puerts_il2cpp/\n```\n\n不要忽略整个 `puerts-unity-mcp-extension` 目录。这个目录里的项目配置、JS tools、skills 属于持久项目资产，如果它们需要随项目走，可以提交。也不要忽略 `puerts-unity-mcp/Packages/puerts-unity-mcp/Runtime/Plugins/Android`，这里是 package 自带的 Android 权限库。PuerTS 官方 `.so` 来自 `third_party/puerts`，不要在 MCP package 里重复提交。\n\n`puerts-unity-mcp/third_party/puerts/unity/.gitignore` 来自官方 PuerTS，会忽略 Unity 为 vendored PuerTS UPM 包自动生成的 `*.meta`。这些文件在本机打开 Unity 后出现是正常的，不需要提交；官方已经提供的 native plugin `.meta` 会随源码保留。\n\n## 目录结构\n\n```text\npuerts-unity-mcp\n  Packages/puerts-unity-mcp\n    Editor/      Editor MCP endpoint 和 Unity 菜单\n    Runtime/     Editor Play Mode、Android、iOS 和 standalone 共用的 Runtime MCP assembly\n      Plugins/   随 package 提供的 Runtime native/plugin assets\n    Tools~/      Node 安装、构建、同步和 stdio proxy 工具\n    Tests/       Unity Editor tests\n  docs/\n    protocol.md\n  third_party/puerts/\n    Vendored PuerTS UPM packages 和 native plugins\n```\n\n## 发布前注意\n\n当前根目录没有 `LICENSE` 文件。公开发布前建议补一个 license。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkillop%2Fpuerts-unity-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkillop%2Fpuerts-unity-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkillop%2Fpuerts-unity-mcp/lists"}