Unity-Skills新手实战：一句话让AI帮你建场景、挂脚本、改材质

Unity-Skills是一款专为 Unity 打造的 AI 自动化技能工具包，它让 AI 通过本地 REST API 直接操作 Unity 编辑器：一句话建场景、挂脚本、改材质。本文面向新手，带你用三步完成安装，再用三句大白话完成建场景、挂脚本、改材质的实战。

什么是 Unity-Skills？

传统的 AI 编程助手只能"聊天"，而你让它"帮我在 Unity 里建个场景"，它只能给你贴一段操作步骤。Unity-Skills 不一样：

• 🛠️805 个 REST Skills，覆盖 54 个分类（GameObject、材质、脚本、灯光、地形、URP……），AI 像调用函数一样操作编辑器
• 🤖6 大 IDE 原生支持：Claude Code、Cursor、Codex、Kimi Code 等，一键安装即用
• 🛡️防呆设计：操作失败自动回滚、高危操作需审批、全程审计日志，新手也能放心让 AI 动手

一句话概括：你在聊天框说话，AI 在编辑器里干活。

安装：3步搞定（最快配置方法）

📦 环境要求：Unity 2022.3+ / Unity 6

第 1 步：通过 Package Manager 安装插件

打开 Unity 的 Package Manager，选择 Git URL 方式，粘贴仓库地址后指向/SkillsForUnity路径即可。仓库地址：

https://gitcode.com/gh_mirrors/un/Unity-Skills

第 2 步：打开面板并启动服务

在 Unity 菜单执行Window > UnitySkills（快捷键Alt + Shift + U），用顶栏的开关启动服务。服务启动后会跨 Domain Reload 自动恢复，不用反复开启。

第 3 步：一键配置 AI Skills

在面板中切到AI Config标签页，选择你正在使用的 AI 终端图标，点击Install——安装包会自动把技能模板复制到对应目录，无需手动拷贝。

📘 更完整的图文安装说明见 安装指南（中文） 与 安装指南（英文）。

实战 1：一句话建场景

安装完成后，直接对你的 AI 终端说人话：

"在场景里创建一个木箱 Cube，放在位置 (4, 1.5, -2)，再在它旁边创建一盏聚光灯，强度 3。"

AI 会自动做这几件事（你完全不用管）：

1. 调用gameobject_create创建 Cube 并指定坐标
2. 调用light_*相关技能创建聚光灯并配置参数
3. 读回验证：每次写入后返回编辑器中的真实状态（位置、旋转、缩放），确认没做错

如果你要批量建几十个物体，AI 会自动改用gameobject_create_batch等批处理技能——一次调用代替 N 次调用，失败时整体回滚，场景不会残留半成品。

📖 该模块的技能清单与规则：gameobject/SKILL.md

实战 2：一句话挂脚本

继续对话：

"写一个 Spin.cs 脚本，让物体每帧绕 Y 轴旋转 9 度，然后挂到刚才的木箱上。"

这里涉及一个新手常踩的坑：先挂组件、后写脚本会失败，因为新脚本要等编译完成才可见。Unity-Skills 已内置正确的流程：

1. script_create写入脚本源码 → 等待编译完成（AI 会自动轮询waitUrl拿到编译结果）
2. 编译通过后才component_add把 Spin 组件挂到木箱上
3. component_set_property把speed属性设为 9，并读回验证写入值

写脚本属于高危操作（会触发编译和域重载），所以受权限模式管控：Approval 和 Auto 模式下需要你在 Unity 面板里点一下批准，Bypass 模式则直接执行。这是刻意的安全设计，不是故障。

📖 脚本模块文档：script/SKILL.md ｜ 组件模块文档：component/SKILL.md

实战 3：一句话改材质

"把木箱变成红色。"

听起来简单，实则暗藏新手大坑：直接改 Cube 的颜色，Unity 会修改共享的默认材质资源，导致项目里所有用这个材质的物体全变红——也就是经典的"我一个箱子涂色，整个场景都变色"事故。

Unity-Skills 的材质模块内置了安全路由：AI 会先新建一个材质→ 给新材质上色 → 再分配给木箱，保证只影响这一个物体。三条指令背后是material_create→material_set_color→material_assign的组合，你在聊天框里说"变红"就够了。

📖 材质模块文档（含管线兼容性说明）：material/SKILL.md

安全网：AI 做错了会怎样？

让 AI 直接写真实场景，新手最担心的就是"做错怎么办"。Unity-Skills 在调用生命周期的四个节点都有兜底：

完整机制说明见 操作模式与治理层（中文）。

新手速查：常见问题

Q：支持哪些 AI 终端？A：Claude Code、Antigravity、Codex、Cursor、Kimi Code、OpenCode 均可一键安装；其他支持 Skills 的工具可通过"Custom Path"自定义安装。

Q：AI 干活时服务突然连不上？A：正常现象。写脚本、改宏定义等操作会触发编译/域重载，服务会短暂不可达，稍等片刻重试即可。

Q：新安装默认是什么权限模式？A：Auto 模式——常规技能直接执行，高危操作自动拦截，兼顾效率与安全。老版本升级用户则保持 Bypass 不变。

Q：AI 会不会"幻觉"出不存在的技能？A：每个技能模块都内置了 DO NOT 清单（常见幻觉名称 → 正确技能的映射表），配合服务端的路由规则，AI 只会调用真实存在的技能。主定义见 SKILL.md。

进阶资料

• 📚 中文 README（含 805 个技能分类总表）
• 📚 操作模式与治理层详解
• 🗂️ 技能模板根目录：SkillsForUnity/unity-skills~/（含skills/82 个模块文档与references/参考文档）
• 🔧 Python 客户端库：unity_skills.py

装好 Unity-Skills 后，下次别再问 AI"怎么做"——直接说"帮我做"，剩下的交给它。