new-unity-project

新建 Unity 项目

通过引导流程，将一个想法变成可运行且受版本控制的 Unity 项目。本技能负责流程——问题及其顺序、在提问时于后台运行耗时安装，以及各项交接。它不会刻意重复记录命令；具体操作会委托给其他技能。

委托给（请阅读这些技能以了解实际命令——不要另行编造）：

• unity-cli — CLI 安装、身份验证／许可证、Editor 安装、项目创建、源代码管理、打开项目。其中“从头开始引导新项目”工作流是本流程的核心。
• unity-package-management — 使用 Pipeline package 命令安装包（以 C# 脚本作为备用方案），以及按游戏类型／平台／盈利模式选择包。
• urp-postprocessing、ui、2d-pixel-perfect — 视觉基线（步骤 6）：后处理 Volume 设置、HUD 框架选择、2D 像素完美效果。
• implement-in-app-purchases、levelplay-unity-integration、build-live-game — 盈利模式／后端集成（在最后调用）。

一次只进行一个步骤。 只询问当前步骤的问题，并等待用户回答后再继续——平台和盈利模式的答案会影响安装内容，因此不要一开始就收集所有信息，也不要在这些问题确定前搭建项目骨架。

步骤 1 前：检查委托技能是否已加载

在客户端列出的技能中查找 unity-cli、unity-package-management、urp-postprocessing 和 ui。前两个技能包含本流程委托的命令。步骤 6 将后两个技能标记为必需技能。只获得本技能的客户端不会拥有其他技能。

如果缺少任何技能，请告知用户缺少哪些技能，以及它们能做什么。提出在开始前安装 Unity 技能，但未经用户同意不要安装，因为这会更改其 Agent 配置：

• **Claude Code，四个技能均未安装时：**运行 unity setup claude --format json 会安装包含所有这些技能的 Unity 插件。这可能会重复安装你已有的技能。旧版 CLI 不支持 unity setup，因此请改用下一种方式。全新安装的技能会在下一个会话中加载，或在运行 /reload-plugins 后加载。在此之前，请从它报告的 skillsPath 读取技能。
• **其他任何情况，包括只安装了部分技能时：**请用户在自己的终端运行 npx skills add Unity-Technologies/skills -g，这需要 Node.js。用户可在命令提示过程中选择缺少的技能和客户端。不要自行运行，因为命令提示会决定技能的安装位置。如果客户端读取的技能文件夹不是该命令的写入位置，请告知用户将每个缺少的技能文件夹从 github.com/Unity-Technologies/skills（skills 目录下）复制到该文件夹中。

新安装的技能可能要等客户端重启后才会加载。如果重启后仍未列出，请询问安装程序将其放在何处，并从那里读取其 SKILL.md。

不要因为两个必需技能而停滞。如果用户希望不安装它们也继续，请按照步骤 6 中对此项的指引操作。请在最终报告中指出缺少的技能，让用户知道本次跳过了更深入的指引。另外两个技能包含你不应自行编造的命令。unity skill show 无需安装即可显示 unity-cli。缺少 unity-package-management 时，步骤 5 无法执行，因此要在步骤 2 开始安装 Editor 前说明情况，并让用户决定。

流程——并行处理在哪里

1. 概念——他们要开发什么。
2. 平台和变现方式——确定平台后，立即在后台启动 Editor 安装（需要几分钟），同时继续沟通。
3. **（汇合）**Editor 和平台模块安装完成。
4. 项目和源代码管理——根据 2D/3D 选择匹配的 URP 模板创建项目；初始化 git。
5. 包——Editor 打开后，使用 package add 命令安装；否则使用 C# 脚本。
6. 视觉基线——后期处理、摄像机、质量等级、UI 栈、符合渲染管线要求的着色器，确保第一帧看起来不像未经修改的模板。
7. 保存并首次提交。
8. 移交变现 / 后端工作。

引导式流程优于照搬配方的关键在于：用户回答概念问题所花的几分钟，恰好与 Editor 的多分钟安装过程重叠，让设置感觉即刻完成。

步骤 1——概念

如果客户端有多选问题工具，就用它提问（Claude Code 中的 AskUserQuestion、Copilot CLI 中的 ask_user、VS Code 中的 askQuestions），方便用户快速选择，同时也允许他们自由回答。没有这类工具时，就用纯文本提问。涵盖以下内容：

• 类型 / 核心循环——平台游戏、俯视角射击、解谜、放置、RPG、竞速、卡牌、塔防、模拟、超休闲、第一人称等。
• 维度和视觉风格——2D 或 3D；美术风格（像素、低多边形、风格化、写实、仅 UI）。
• 玩法——用一句话描述“玩家每时每刻都在做什么”。
• 范围——单屏原型还是多场景游戏；单人还是多人。

还要确定一个项目名称。撰写 2–4 行的项目简介，读给用户听并确认。简介将决定模板选择（步骤 4）、包（步骤 5）和视觉基线（步骤 6）：记下用户提到的配色 / 氛围词，以及视觉风格是否为像素艺术。

步骤 2——平台和变现方式，然后开始安装

需要做出两个决定，因为它们都会影响安装内容：

• 目标平台（可多选）：桌面端（Win/macOS/Linux）、移动端（iOS/Android）、WebGL、主机。这些决定 Editor 模块（步骤 3），也意味着移动端 / WebGL 项目应使用更精简的包。
• 变现方式：无 / 付费 / 应用内购买 / 广告 / 混合。这只决定步骤 8 中要调用哪个移交技能——现在不要集成。

确认要使用的 Editor 版本（默认：最新 LTS——关于 LTS、Tech 和 beta 之间的取舍，请参阅 unity-cli）。现在就询问，开始安装之前确认，以免安装错误的版本。

然后确认前置条件，并将 Editor 安装作为后台任务启动，这样安装就能在你继续沟通时运行。准确的语法、各平台对应的模块名称，以及身份验证 / 许可证设置，请参阅 unity-cli 技能：

unity --version
unity auth status --format json      # if signed out:  unity auth login
unity license status --format json   # if none active: unity license activate

# Start in the BACKGROUND, then go straight back to the conversation. Module names per platform
# (android / ios / webgl / …) are in the unity-cli skill.
unity install lts --module <platform-modules> --yes --accept-eula

将安装作为后台任务运行（不要阻塞等待）。如果没有其他问题要问，直接等待也可以——只有在有对话可与安装并行进行时，并行处理才有帮助。

步骤 3——汇合：Editor 就绪

创建项目之前，确认后台安装已完成：

unity editors --installed --format json

如果失败，显示错误（请参阅 unity-cli 故障排除），然后停止——没有 Editor，后续操作都无法进行。

步骤 4 — 创建项目并设置源代码管理

严格遵循 unity-cli 中的“从头开始引导新项目”工作流：

• 列出 Editor 提供的实际模板 ID（unity templates list --type core），并根据渲染管线选择，而不只是看 2D/3D——不要猜测 ID。默认使用 URP： 3D 项目使用 com.unity.template.urp-blank（“Universal 3D”），2D 项目使用 com.unity.template.universal-2d （“Universal 2D”）。com.unity.template.3d / com.unity.template.2d 是 Built-in Render Pipeline 模板——自 Unity 6.5 起弃用，并将在 6.7 中移除——因此只有在用户明确要求使用 Built-in 时才选择它们。通过 JSON 中的 renderPipeline 字段确认选择（当前版本中 universal-2d 的值为空，因此该模板需根据 ID 匹配）。
• 使用 unity projects create "<Name>" --path <dir> --editor-version <v> --template <id> 创建项目。
• 设置源代码管理——询问用户的选择，不要自行假设：Git（GitHub / GitLab； 对资源繁多的游戏添加 --git-lfs），或 Unity Version Control（--vcs uvcs，可原生处理大型二进制资源——无需 LFS），或纯本地的 git init + Unity .gitignore。 使用 unity projects create --vcs … --git-token-from-stdin --no-initial-commit 一步发布（通过 stdin 输入令牌）。传入 --no-initial-commit，以免 CLI 在软件包和 .meta 文件尚不存在时就提交空项目——在步骤 7 中进行真正的首次提交/检入。 具体标志请参阅 unity-cli 工作流。

步骤 5 — 软件包

将需求映射为具体的软件包列表，并通过 unity-package-management 技能安装（切勿手动编辑 manifest.json）。Editor 打开并就绪，且已有 com.unity.pipeline （步骤 6 会安装它）后，使用该技能的 package add 命令。如果软件包必须在首次打开 Editor 前安装，由于步骤 6 会打开 Editor，应改用该技能提供的 C# 安装脚本（注意其中的 -quit 陷阱）。阅读该技能，了解类型/平台/变现方式与软件包之间的对应关系。 模板已提供渲染管线——切勿将 com.unity.render-pipelines.universal 添加到 Built-in 模板项目中（没有任何资源会分配 URP 资源；材质会变成粉色），反之亦然。安装前向用户复述最终列表；安装后验证 manifest.json。

步骤 6 — 视觉基线

全新模板能正确渲染，但外观仍是默认样式：没有色调映射，质量等级未经调整，颜色平淡。若不做处理，Agent 就会转而使用 OnGUI 并猜测着色器名称，这正是导致材质褪色或呈洋红色的原因。开始任何游戏玩法开发前，先应用这套基础配置。

首先，在打开 Editor 之前运行 unity pipeline install --project-path "<project-path>"。 在 Editor 中运行 C#，以及运行下方的 unity command capture screenshot，都需要项目中的 com.unity.pipeline 软件包。较早版本的 CLI 创建项目时不会默认添加该软件包，因此项目中会缺少它（较新版本已添加，执行此安装不会有任何变化）。步骤 5 不会添加它：该步骤通过使用 -batchmode -executeMethod 启动 Editor 二进制文件来安装软件包，不会触及该软件包。支持的顺序是在打开项目前安装——安装操作会更新 Packages/manifest.json，Unity 会在项目加载时读取该文件。如果对已打开的项目运行此命令，写入可能会因 PIPELINE_MANIFEST_WRITE_FAILED 而失败（请让用户关闭 Editor 并重新运行），也可能成功，但已打开的 Editor 要等到窗口重新获得焦点后才会加载该软件包。后一种情况下，unity status 会报告 STATUS_PIPELINE_LOAD_PENDING；请让用户切换到 Editor 窗口。没有该软件包，以下所有操作都会无法连接，看起来像 unity-cli 所述的 Safe Mode 故障，但原因不同。 然后，执行 unity open "<project-path>"（第 7 步也需要执行此命令），等待 unity status 报告 Editor 已就绪，然后在其中运行 C#，逐项应用以下内容。这些命令及其语法均由 unity-cli 负责——不要在此处重新推导。

Editor 就绪后，在你的技能中查找 unity-pipeline。这是 Pipeline 包自带的指南，任何客户端都不会从包文件夹加载它。如果找不到，现在就读取其 SKILL.md。它位于包中的 .claude/skills/unity-pipeline/ 下：如果项目嵌入了该包，路径为 Packages/com.unity.pipeline/；否则位于 Library/PackageCache/com.unity.pipeline@* 文件夹中。请列出 Library/PackageCache，查找确切名称，因为后缀通常是哈希值，而不是版本号。

若要让客户端在后续会话中加载它，可以运行 unity skill install <client> --local 镜像安装，但仅适用于支持项目作用域的客户端（unity skill install --list 会显示支持的客户端，Claude Desktop 则不支持）。此命令还会在它旁边写入一份项目级的 unity-cli 副本。unity-cli 技能建议运行一次，但在这里请等用户提出要求后，再于打开项目后从项目文件夹中运行。在安装了 Unity 插件的 Claude Code 中，该命令会提前停止，因为插件已自带 unity-cli。在这种情况下，得到用户同意后，将 unity-pipeline 文件夹复制到项目的 .claude/skills/ 即可。如果无法镜像安装，则在每个会话中重新读取包内的副本。

第 1、2、5 和 6 项假设使用 URP 模板，这是第 4 步的默认选项。如果用户明确选择了 Built-in，请勿按原样执行这些项目：UniversalAdditionalCameraData、Light2D、urp-postprocessing 体积框架以及所有 Universal Render Pipeline/* 着色器都是 Built-in 中不存在的 URP 类型，因此生成的 C# 将无法编译。在 Built-in 中，第 3 和第 4 项仍可按原样使用，后处理指的是旧版 Post Processing Stack，着色器名称则为 Standard / Unlit/Color。不要使用 migrate-birp-to-urp——用户要的是 Built-in。

1. 后处理。 使用带色调映射（ACES）的全局 Volume、较低的 Bloom（强度 0.5–1， 阈值 0.9）和轻微的暗角效果（≈ 0.25）；在主摄像机的 UniversalAdditionalCameraData 上设置 renderPostProcessing = true。必需的子技能： urp-postprocessing——其代码模板会创建 Volume， 并检查 HDR 和 Volume 层遮罩。如果未加载，请根据这些值自行构建 Volume，并检查 HDR 和层遮罩。
2. 摄像机和光照。 2D → 正交投影，使用来自需求说明调色板的纯色背景；如果模板场景中没有 Light2D，则添加一个类型为 Global 的 Light2D（没有它时 Sprite-Lit 着色器会渲染为黑色）。 3D → 透视投影；保留模板中的方向光和天空盒，并启用主光阴影。
3. 质量等级。 先读取 QualitySettings.names——不同模板的等级名称各不相同——然后调用 QualitySettings.SetQualityLevel，选择与主要目标平台匹配的等级：桌面端选最高等级，移动端/WebGL 选最低等级。保留模板设置的 Linear 色彩空间和 Input System。
4. UI 栈。 HUD 和菜单使用 uGUI Canvas + TextMeshPro 或 UI Toolkit——绝不使用 OnGUI。 必需的子技能： ui 会为项目选择其中一种。如果未加载，请根据需求说明进行选择，并在最终报告中 说明选择了哪一种以及原因。
5. 材质和着色器。 在 URP 下使用 Universal Render Pipeline/Lit、…/Unlit、 …/2D/Sprite-Lit-Default 或 …/2D/Sprite-Unlit-Default。在 URP 下，Standard 和 Unlit/Color 会渲染成粉色或褪色。优先使用 GraphicsSettings.currentRenderPipeline.defaultMaterial / .default2DMaterial，而不是 Shader.Find，并将 Shader.Find 返回 null 视为错误。使用 currentRenderPipeline， 而非 defaultRenderPipeline：质量等级可能带有自己的管线资源，而上面的第 3 项刚刚设置了等级。
6. 仅限像素美术。 为精灵设置 Point 过滤模式，并使用 Pixel Perfect Camera——参见 2d-pixel-perfect。如果未加载，请自行完成这两项，并在最终报告中附上“步骤 1 前”中的安装途径。

保存场景，然后确认以下两点。不要使用 unity logs——它读取的是 CLI 自身的日志，而不是 Editor 的日志，因此无论场景实际效果如何，它都会报告干净：

• Editor 侧没有渲染管线或着色器错误。通过 unity-cli 读取 Editor 控制台，或直接读取 Editor.log——该技能的“从安全模式恢复”部分列出了各平台的路径。
• unity command capture screenshot --output baseline.png 的截图看起来经过了照明和色调映射，而不是一片灰。

步骤 7 — 保存并首次提交

项目已在步骤 6 中打开，因此 .meta 文件已经存在。使用你在步骤 4 中设置的任一版本控制系统进行首次提交：

unity open "<project-path>"     # only if not already open; for headless/CI use the
                                # "Import & save headlessly" method in unity-package-management

• Git（GitHub / GitLab / 本地）：

  cd "<project-path>"
  git add -A
  git status                    # Library/ Temp/ obj/ Build/ must NOT be staged
  git commit -m "Initial Unity project: <Name>"
  

  每个 .cs/资源都必须与其 .meta 一起提交。
• Unity Version Control（UVCS）： 通过 UVCS 客户端/工作区（在步骤 4 中创建）检入——无需执行 git 步骤。生成的文件夹仍会按照忽略规则排除。

在任一提交之前，如果步骤 6 将技能镜像到了项目中（Claude Code 使用 .claude/skills/），请询问用户是将其纳入提交还是排除。

如果你在步骤 4 中通过 --vcs 发布，且未使用 --no-initial-commit，CLI 已经为这个空项目创建了初始提交——请在此处追加一次提交，不要重复提交。

步骤 8 — 交接

根据步骤 2 中确定的变现方式，调用相应技能完成实际集成：

• IAP → implement-in-app-purchases
• 广告 → levelplay-unity-integration
• 账户 / 云存档 / 经济系统 / 远程配置 / 排行榜 → build-live-game

如果尚未加载相应技能，请在后续步骤中提供“步骤 1 之前”中的安装方式，而不要凭记忆进行集成。

报告项目路径、Editor 版本、渲染管线和模板、已安装的软件包、已应用的视觉基线、缺失的技能以及后续步骤。

范围 — 此技能不负责的事项

• 不搭建游戏玩法框架。 此技能会帮你创建一个已运行、配置完成且具备视觉基础的项目；实际游戏的构建（场景、控制器、美术资源）将在下一次对话中进行——使用 unity-cli MCP 服务和 Package Manager，通过 Editor 迭代开发。通用的游戏类型框架往往会生成用完即弃的模拟基础图元，因此此技能会有意止步于干净的起点。视觉基线（步骤 6）涉及的是设置，而非内容。
• 不提供命令参考。 命令语法请参阅 unity-cli / unity-package-management。

检查清单

• 步骤 1 之前已检查委派技能（unity-cli、unity-package-management、 urp-postprocessing、ui）：缺少的技能已提供安装方式，或已在最终报告中注明
• 已记录并确认概念简报（类型、外观、玩法、范围、名称）
• 已记录平台和变现方式；已选择 Editor 版本
• 已安装 Editor 和平台模块（步骤 2 期间已在后台启动安装）
• 除非明确要求使用 Built-in，否则已从 URP 模板（urp-blank / universal-2d）创建项目；已使用 Unity .gitignore 初始化 git
• 已通过 package add 安装软件包（或在首次打开前运行技能提供的 C# 脚本）；已验证 manifest.json；未在模板基础上额外添加渲染管线软件包
• Editor 就绪后，已从软件包文件夹读取 unity-pipeline，或已征得用户同意后将其复制到项目中
• 已应用视觉基线：全局 Volume（色调映射、泛光、暗角）+ 已启用摄像机后处理、已为目标平台设置质量等级、已选择 UI 技术栈（不使用 OnGUI）、URP 着色器名称正确、已检查截图
• 已打开并保存项目，以生成 .meta 文件；已创建首个提交；已排除 Library/
• 如适用，已交接给变现 / 后端技能

常见错误

• 等待 Editor 安装完成后才继续，而不是让它在后台安装，同时向用户提问。
• 安装了错误的 Editor，因为后台安装前没有确认版本。
• 一次性问完所有问题——平台和变现方式的答案会影响模块和软件包。
• 手动编辑 manifest.json，而不是使用软件包命令或技能提供的脚本（参见 unity-package-management）。
• 相应子技能尚未加载时，凭记忆代做其工作，却不告知用户或提供安装方式。
• 提交 Library/、Temp/、obj/、Build/，或提交缺少对应 .meta 文件的脚本。
• 遗漏 Editor 模块——移动端目标需要 android / ios；WebGL 需要 webgl。
• 因为名称相符就选择 com.unity.template.2d / .3d——这些是 Built-in 管线模板。请使用 universal-2d / urp-blank。
• 跳过视觉基线，直接沿用模板的纯色默认设置，之后却使用 OnGUI 构建 HUD，并在 URP 下使用 Shader.Find("Standard") 创建材质。