new-unity-project

新建 Unity 项目

从构想到创建一个可运行、纳入版本控制的 Unity 项目的完整流程。此技能负责流程—— 模式、默认值、顺序、后台安装和交接。

委托给以下技能（实际命令请查看这些技能——不要重新发明）：

• unity-cli — 安装、身份验证/许可、Editor 安装、创建、源代码管理、打开。其 “从零开始引导新项目”工作流是此处的骨干。
• unity-package-management — 使用 Pipeline package 命令管理包（C# 脚本作为备用方案）。
• urp-postprocessing、ui、2d-pixel-perfect — 视觉基线机制（第 7 步）。
• craft-game-floors — 制作基础层（外观、手感、音频、外壳、在线基础层、完成门槛）， 在第 6 步加载，并贯穿整个构建过程。
• implement-in-app-purchases、levelplay-unity-integration、build-live-game — 变现/后端集成（在最后调用）。

模式：默认采用铺好路的流程，按需引导

除非用户用文字提出访谈式引导（“问我一些问题”“引导我”），或对清单提出异议，否则采用铺好路的流程；每个会话只决定一次模式。铺好路的流程约定： 先解析提示词 · 根据默认值表补齐空缺 · 启动创建前打印清单 · 继续执行，只在用户提出异议或遇到未规定的分支时提问 · 绝不替用户越过人工确认门槛——登录和发布始终需要询问。用户要求纯基础/最简项目时，使用 --bare，跳过基础层，并说明代价（身份、存档、排名均未接通）。

在引导模式下，只询问当前步骤的问题，然后等待。铺好路的流程中新增的内容（身份、 基础层、交接）会在相应步骤询问，绝不自行假定。

默认值表

每一行都可以根据用户一句话进行调整；只有运行中取得的凭据才能更改行内容。

决策	铺好路的流程默认值
Editor 版本	明确指定 --editor-version latest
模板	URP；除非提示词说明使用 2D，否则使用 3D（--template 3d 或 2d）
平台	仅桌面端；提示词暗示需要其他平台时添加相应模块（“手机游戏” → ios/android）
变现	创建时不启用；记录下来供后续处理
版本控制	本地 git + Unity .gitignore
玩家身份	匿名账户——如果创建结果中显示了账户，则使用创建时生成的账户；否则在第 6 步接通
制作基础层	始终启用，通过 craft-game-floors 技能实现：外观、摄像机、光照、反馈、音频、外壳、在线基础层、完成门槛

云端关联和诊断不属于表格中的决策项：创建过程会应用自身默认值——根据结果说明这些设置， 不要重新决定。

假设清单

在第 2 步结束时、启动创建前，准确打印一个区块。它会预测创建过程将执行的操作 （--template 3d|2d 对应 URP 模板，绝不猜测 ID）：

铺好路的流程假设： Unity · <URP 模板，2D/3D> · <平台> · <变现> · 匿名玩家账户（创建时生成，否则添加一个引导脚本）· <版本控制> · 已关联云端并启用诊断（创建过程的默认值，根据结果说明）· 基础层包 （Cinemachine；云端关联时接入身份 + 在线服务）· 通过 craft-game-floors 启用制作基础层 · 在项目的 CLAUDE.md 末尾附上一行交接说明。 如需更改其中任何一项，请直接说明；否则我将继续执行。

只打印一个区块，包含所有假设，每项都可调整，不得隐含任何内容；第 3 步会根据实际结果进行核对。

第 1 步之前：确认已加载委托技能

检查客户端的技能中是否包含 unity-cli、unity-package-management、urp-postprocessing、ui、build-live-game 和 craft-game-floors。如果缺少任何技能，说明缺少哪些技能及其用途，并提供 references/skill-setup.md 中的安装途径——未经用户同意，绝不安装。不要因此停滞： 用户拒绝安装时，在相应步骤采用备用方案，并在报告中指出缺失项。unity skill show 无需安装即可显示 unity-cli；缺少 unity-package-management 时，第 5 步无法执行——请在第 2 步之前说明。

流程——以及并行执行的位置

1. 概念（已铺设：从提示词中解析）。2. 平台与变现——打印清单（已铺设），然后在后台启动创建：projects create --install-editor 安装 Editor 和模块（需要几分钟），然后创建项目；与此同时继续交流。
2. **（汇合）**根据清单核对结果。4. **源代码管理。**5. 包。
3. 玩家身份，然后是 craft 楼层——确认创建时的身份，或完成关联；加载 craft-game-floors。7. 根据 craft 技能的美术圣经确定视觉基线。8. 保存并首次提交。
4. 交接 + 后续接力信息。

耗时数分钟的 Editor 安装与用户回答并行进行，因此设置感觉是即时完成的。

步骤 1——概念

**已铺设：**提示词就是规格——将类型、维度（2D/3D）、视觉风格、范围和名称解析为一份 2–4 行的简述；根据默认值表填补空缺；无需复述确认。

引导式：使用客户端的多选工具提问（Claude Code 中的 AskUserQuestion、 Copilot CLI 中的 ask_user、VS Code 中的 askQuestions）；没有此类工具时，使用纯文本。 涵盖类型 / 核心循环 · 维度与视觉风格（2D 或 3D；像素风、低多边形、风格化、 写实）· 玩法（用一句话描述“玩家时时刻刻在做什么”）· 范围 （原型还是多场景；单人还是多人）。确定项目名称，撰写简述并复述确认。简述将决定模板（步骤 2）、包（步骤 5）和基线（步骤 7）： 记下调色板 / 氛围词和像素美术风格。

步骤 2——平台与变现，然后开始安装

两项决策（已铺设：根据默认值表填入，然后打印清单）：

• 目标平台：Desktop、Mobile（iOS/Android）、WebGL、Console——它们对应 Editor 模块（--module），也决定了在 Mobile/WebGL 上采用更精简的包。
• 变现方式：无 / 付费 / IAP / 广告 / 混合——这只影响步骤 9 的交接。

默认明确指定 --editor-version latest，除非用户指定版本——不带此标志时，创建操作会优先使用已保存的默认版本或较旧的已安装 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. Module names per platform are in the unity-cli skill.
# --bare only on the user's ask (see Mode).
unity projects create "<Name>" --path <dir> --editor-version latest \
  --template <3d|2d> --install-editor --module <platform-modules> --accept-eula --format json

命令会等待安装完成，然后创建项目，因此一次运行的结果涵盖两者。如果没有其他问题要问，也可以直接等待。

模板：--template 3d / 2d 会解析为该版本的 URP 模板 （com.unity.template.urp-blank、com.unity.template.universal-2d），这是所有游戏的默认选项。 内置模板（完整 ID com.unity.template.3d/.2d）从 6.5 开始弃用，并将在 6.7 移除——仅在用户明确要求使用内置渲染管线时传入。

步骤 3——汇合：项目就绪，核对结果

等待后台创建任务完成并读取其 JSON 结果：data.path 是项目路径， data.version 是 Editor 版本，data.editorInstalled 表示本次运行是否安装了 Editor。

已铺设：根据清单核对结果，并说明差异——包括云端关联软失败（cloudLinked: false、警告信息，项目完整无损；步骤 6 会据此处理）。关联时报 403 通常是因为已保存的默认组织拒绝创建新项目——在得出无身份的结论前，先重试 unity projects link cloud <path> --cloud-org <用户拥有的组织>。如果结果包含 steps 字段，则逐步核对其中的内容。

只有本次运行安装 Editor 时，--module 才会生效：如果 data.editorInstalled: false，则使用 unity install-modules -e <version> -m <platform-modules> --accept-eula 添加平台模块 （会跳过已安装的模块）。如果创建失败，则展示错误（参阅 unity-cli 故障排除）并停止——安装失败不会创建项目，而没有 Editor，后续步骤都无法进行。

步骤 4 — 源代码管理

**预置：**本地 git + Unity .gitignore。引导式：询问 — Git（GitHub / GitLab；资源繁多的游戏使用 --git-lfs）、Unity Version Control（--vcs uvcs — 原生支持大型二进制文件，无需 LFS），或纯本地。使用 unity projects link vcs "<project-path>" --vcs … --git-token-from-stdin --no-initial-commit 关联（令牌通过 stdin 传入）——--no-initial-commit 可防止 CLI 在软件包和 .meta 文件创建之前提交空项目；真正的首次提交在步骤 8。准确标志请见 unity-cli 工作流。

步骤 5 — 软件包

根据需求简介确定软件包列表，并通过 unity-package-management 安装（绝不手动编辑 manifest.json）：等 Editor 打开后再使用 package add 安装 com.unity.pipeline（步骤 7）；必须在打开前安装软件包时，则使用其 C# 安装脚本（注意 -quit 的问题）。该技能提供了游戏类型／平台／变现方式 → 软件包的映射。预置内容会添加各层所需的软件包：所有游戏玩法摄像机（包括 2D Rig）都使用 Cinemachine；步骤 6 接入身份验证时使用 com.unity.services.authentication；云关联项目则添加实时层所需的服务（云存档、排行榜、远程配置）——在本轮中添加，而非在 Shell 阶段添加。模板已提供渲染管线——Built-in 模板绝不要添加 com.unity.render-pipelines.universal（材质会变成粉色），反之亦然。安装前先复述列表（预置流程：现在打印出来）；之后检查 manifest.json。

步骤 6 — 玩家身份，然后是制作层

身份 — 创建结果决定是否接入（--bare 运行会跳过整个步骤：除非使用 --no-cloud，否则空项目仍会关联云服务；不接入的代价已在 Mode 阶段说明）：如果结果中已处理身份 → 在对账时确认并跳过，绝不重复接入身份验证。未设置身份且项目已关联云服务 → 接入：初始化服务，并在启动时启动匿名登录，放在一个小型启动脚本中，绝不阻塞（实现细节见 build-live-game 的身份验证部分——已在步骤 1 前检查；若缺失且用户拒绝 → 跳过接入，并指出这一缺口）；每项服务依赖都单独列为计划事项，用户拒绝时只移除对应事项。云关联失败或跳过 → 跳过并说明代价（存档和排名将保留在本地）——绝不对没有云 ID 的项目初始化服务。这对玩家不可见，之后可升级——这是实时层构建所依托的基础。

--bare 运行也会跳过制作层（Mode 部分已说明相关代价）。否则，加载 craft-game-floors 技能（已在步骤 1 前检查），并在整个构建过程中按其制作层流程执行——先制定美术规范，然后是摄像机、光照、反馈、音频、外壳、实时层及其完成门槛。只要这些技能提供了相应内容，其规范优先于下方的内联回退方案，包括版本差异。若缺失且用户拒绝 → 使用回退方案，并在报告中指出这一缺口。

步骤 7 — 视觉基线

全新模板可以正确渲染，但看起来像默认项目；若任其如此，Agent 就会改用 OnGUI 并猜测着色器名称。在任何游戏玩法工作开始前，应用此制作层。

**首先，在打开 Editor 之前运行 unity pipeline install --project-path "<project-path>"。**在 Editor 中运行 C# 以及下文的 unity command capture screenshot 都需要项目包含 com.unity.pipeline 软件包。较新的 CLI 会在创建项目时默认添加该软件包（因此此安装不会产生任何变化）；较旧的 CLI 则不会添加，而步骤 5 中的 -batchmode 安装脚本也不会处理它。受支持的顺序是在打开前安装；如果没有该软件包，下方所有操作都会因无法连接而失败（这与 unity-cli 的安全模式故障类似）。故障代码（PIPELINE_MANIFEST_WRITE_FAILED、卡在 STATUS_PIPELINE_LOAD_PENDING）以及卡死 Editor 的恢复方法见 references/skill-setup.md。

然后运行 unity open "<project-path>"，等待 unity status 报告 Editor 已就绪，再通过在 Editor 中运行 C# 来应用下方各项——这些命令由 unity-cli 管理；此处不要重新推导。 Editor 准备就绪后，如果技能列表中没有 unity-pipeline 指南，请阅读该指南—— 位置和镜像路由：references/skill-setup.md。

第 1、2、5 和 6 项假定使用 URP 模板（第 2 步的默认设置）。如果用户明确选择了 Built-in，请勿照此执行——那里不存在 UniversalAdditionalCameraData、Light2D、 urp-postprocessing 体积框架和 Universal Render Pipeline/* 着色器；后处理指的是旧版 Post Processing Stack，着色器名称为 Standard / Unlit/Color，第 3–4 项仍可照此执行。不要调用 migrate-birp-to-urp——用户要求使用 Built-in。

1. 后处理。 全局 Volume——加载时使用 craft-game-floors 的场景光照数值（会覆盖下列设置）；回退设置：色调映射（ACES）、Bloom 强度 0.5–1 @ 阈值 0.9、Vignette ≈ 0.25；在主摄像机的 UniversalAdditionalCameraData 上将 renderPostProcessing = true。 必需子技能： urp-postprocessing——其模板会创建 Volume 并检查 HDR 和 Layer Mask；如果未加载，请根据这些数值自行完成这两项设置。
2. 摄像机和灯光。 2D → 正交，背景使用项目说明中的配色，并在模板场景没有全局光时添加一个 Light2D（类型为 Global；没有它，Sprite-Lit 着色器会渲染为黑色）。 3D → 透视，开启主光源阴影；加载 craft-game-floors 后，其光照流程会替换模板默认的灯光配置；否则保留模板的方向光和天空盒。
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。如果该技能缺失，请自行完成这两项设置，并在报告中注明技能安装路线。

保存场景，然后确认以下两项——不要使用 unity logs，它读取的是 CLI 自身的日志，无论场景实际效果如何都会报告正常：

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

第 8 步 — 保存并首次提交

项目已在第 7 步中打开，因此 .meta 文件已存在（仅在文件不存在时才运行 unity open "<project-path>" ——无头模式／CI 使用 unity-package-management 中的“无头导入并保存”方法）。使用你在第 4 步中设置的版本控制系统进行提交：

• 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)：**通过第 4 步中的工作区检入——不需要执行 git 步骤； 生成的文件夹会根据忽略规则排除。

如果第 7 步将技能镜像到项目中，请询问是否要将它们纳入提交。如果第 4 步在链接时未使用 --no-initial-commit，CLI 已提交了空白项目——请追加一次提交，而不是重复提交。

第 9 步 — 交接

根据第 2 步中的变现方式，调用相应技能进行实际集成：

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

如果相应技能尚未加载，请将后续步骤指向 skill-setup 安装流程，而不是凭记忆进行集成。

写入后续接力说明（已在清单中声明）：在项目的 CLAUDE.md 或 AGENTS.md 中追加一行幂等内容——“构建游戏玩法、手感、音频、外壳或在线功能时，加载 craft-game-floors 技能；如果尚未安装，询问用户是否运行 unity skill install <client>（必须先询问；未经同意绝不运行）。”提交这条说明——若在第 8 步后追加，它不会同步到克隆副本。后续会话可通过它触达 floors，无需此技能再次触发。

报告项目路径、Editor 版本、渲染管线和模板、软件包、包含对账结果的清单、身份状态、已应用的基线、缺失的技能、craft-game-floors 的完成门槛（作为构建的完成标准）以及后续步骤。

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

• **不搭建游戏玩法框架。**提供一个可运行、已连线并带有视觉地面的项目；游戏将在下一次对话中构建（使用 craft-game-floors）。唯一例外：第 6 步中的单个引导脚本。
• **不提供命令参考。**语法见 unity-cli / unity-package-management。
• 不重新决定 create 的默认值——根据结果说明即可。默认值表是此文件唯一包含的主张；引导式访谈保持原样。

检查清单

• 第 1 步前检查了委派技能（包括 craft-game-floors）：缺少的技能已提供安装选项，或已在报告中注明
• 模式只决定一次；在 paved 模式下，启动 create 前已打印清单
• 已记录简要说明；已记录平台和变现方式
• 在后台创建项目，使用 --install-editor 和模块；使用 URP 模板（--template 3d／2d），除非用户要求 Built-in；仅在用户要求时使用 --bare；已核对结果
• 已配置源代码管理（第 4 步），或设置了本地 git + Unity .gitignore
• 通过 package add 添加软件包（或在打开项目之前运行 C# 脚本）；已验证 manifest.json；模板上未添加渲染管线软件包
• 已根据结果确认身份，或已在第 6 步接入（链接失败时说明费用）
• 已加载 craft-game-floors（或注明其缺失）；Editor 就绪后已阅读一次 unity-pipeline
• 已应用基线：Volume + 摄像机后期处理已开启、质量等级、UI 堆栈（无 OnGUI）、URP 着色器、已检查捕获
• .meta 文件已存在；已完成首次提交；已排除 Library/
• 已追加后续接力说明；如适用，已完成交接

常见错误

• 在 create 期间阻塞，而不是将其放到后台运行：使用 --install-editor 时，它会等待整个 Editor 安装完成。
• 在清单输出前就采取行动（已铺设），或把假设藏在清单之外——如果清单里没有，就不作假设。
• 重复配置身份验证——如果 create 的结果中显示了身份信息，就跳过步骤 6 的配置。
• 手动编辑 manifest.json，而不是使用包命令或该技能的脚本。
• 未加载必需的子技能时，凭记忆替它完成工作，却不告知用户或提供安装选项。
• 提交 Library/、Temp/、obj/、Build/，或提交缺少对应 .meta 文件的脚本。
• 遗漏 Editor 模块——移动端目标需要 android/ios；WebGL 需要 webgl。
• 按名称选择 com.unity.template.2d / .3d——这些是内置模板；请使用 --template 3d/2d。
• 跳过视觉基线——使用平淡的模板默认效果、OnGUI HUD，以及在 URP 下使用 Shader.Find("Standard")。