diff --git a/README.md b/README.md index 816d062..aeb1225 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,12 @@ npx skills add Unity-Technologies/skills | Skill | Description | |---|---| -| `unity-cli` | Interact with the Unity CLI — install editors, manage projects, run builds, check auth, and more | +| `new-unity-project` | Guided flow from an idea to a running, version-controlled project — gathers concept, platforms, and monetization, then delegates setup to the skills below | +| `unity-cli` | Interact with the Unity CLI — bootstrap a new project from scratch, install editors, manage projects, run builds, check auth, and more | +| `unity-package-management` | Add, remove, upgrade, or discover Unity (UPM) packages programmatically — headless/CI installs via the C# PackageManager Client API, and choosing packages by genre/platform/monetization | +| `build-live-game` | Build and operate a live game with Unity Gaming Services — auth, cloud save, cloud code, economy, remote config, leaderboards, and more | +| `implement-in-app-purchases` | Implement, configure, and debug Unity In-App Purchases (IAP) | +| `levelplay-unity-integration` | Integrate LevelPlay (IronSource) ad mediation — rewarded, interstitial, and banner ads | ## Usage diff --git a/skills/new-unity-project/SKILL.md b/skills/new-unity-project/SKILL.md new file mode 100644 index 0000000..f1c221a --- /dev/null +++ b/skills/new-unity-project/SKILL.md @@ -0,0 +1,179 @@ +--- +name: new-unity-project +description: Use when starting a brand-new Unity game or project from scratch — "make/start/create a new game", "bootstrap a Unity project", "I want to build a game", "scaffold/prototype a game", game jam, greenfield, blank project, project setup. A guided flow that gathers the concept, target platforms, and monetization, installs the Editor in the background while it asks, then creates the project and source control and installs packages — delegating the mechanics to the unity-cli and unity-package-management skills and handing off monetization to the dedicated skills. Does not scaffold gameplay code. +allowed-tools: + - Bash + - Read + - Write + - Edit + - AskUserQuestion +--- + +# New Unity Project + +A guided flow from an idea to a running, version-controlled Unity project. This skill owns the +**flow** — the questions, their ordering, running slow installs in the background while you ask, +and the handoffs. It deliberately does **not** re-document commands; it delegates the mechanics +to other skills. + +**Delegates to (read these for the actual commands — don't reinvent them):** +- **`unity-cli`** — CLI install, auth/license, Editor install, project creation, source control, + opening the project. Its "Bootstrap a new project from scratch" workflow is the backbone here. +- **`unity-package-management`** — installing packages via the C# PackageManager Client API, and + choosing packages by genre / platform / monetization. +- **`implement-in-app-purchases`**, **`levelplay-unity-integration`**, **`build-live-game`** — + monetization / backend *integration* (invoked at the end). + +**Work one step at a time.** Ask only the current step's questions and wait for the user before +moving on — platform and monetization answers change what you install, so don't gather everything +up front or scaffold before they're settled. + +## The flow — and where the parallelism is + +1. **Concept** — what they're building. +2. **Platforms & monetization** — then, as soon as platforms are known, **kick off the Editor + install in the background** (it takes minutes) and keep talking. +3. **(joins)** Editor + platform modules finish installing. +4. **Project + source control** — create from a matching template; init git. +5. **Packages** — install via the C# Client API. +6. **Save & first commit.** +7. **Hand off** monetization / backend. + +The whole point of a guided flow over a raw recipe: the multi-minute Editor install overlaps the +minutes the user spends answering concept questions, so setup feels instant. + +## Step 1 — Concept + +Use `AskUserQuestion` so the user can pick fast, but let them answer freely too. Cover: + +- **Genre / core loop** — platformer, top-down shooter, puzzle, idle, RPG, racing, card, tower + defense, sim, hyper-casual, first-person, etc. +- **Dimension & look** — 2D or 3D; art style (pixel, low-poly, stylized, realistic, UI-only). +- **Gameplay** — the one-sentence "what the player does moment to moment." +- **Scope** — single-screen prototype vs. multi-scene game; single-player or multiplayer. + +Also settle on a **project name**. Write a 2–4 line **project brief**, read it back to confirm. +The brief drives template choice (Step 4) and packages (Step 5). + +## Step 2 — Platforms & monetization, then start installing + +Two decisions, because both change what you install: + +- **Target platforms** (multi-select): Desktop (Win/macOS/Linux), Mobile (iOS/Android), WebGL, + Console. These map to Editor **modules** (Step 3) and argue for leaner packages on mobile/WebGL. +- **Monetization**: none / premium / in-app purchases / ads / mix. This only decides which + handoff skill you invoke in Step 7 — don't integrate it now. + +Confirm the Editor version to use (**default: latest LTS** — see `unity-cli` for the LTS vs. Tech +vs. beta trade-off). Ask this *now*, before kicking off the install, so you don't install the +wrong one. + +Then confirm prerequisites and **launch the Editor install as a background task** so it runs while +you continue. See the `unity-cli` skill for exact syntax, module names per platform, and auth / +license setup: + +```bash +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 --yes --accept-eula +``` + +Run that install as a **background task** (don't block on it). If you have nothing left to ask, +it's fine to just wait — the parallelism only helps when there's a conversation to overlap. + +## Step 3 — Join: Editor ready + +Before creating the project, confirm the background install finished: + +```bash +unity editors --installed --format json +``` + +If it failed, surface the error (see `unity-cli` troubleshooting) and stop — nothing downstream +works without an Editor. + +## Step 4 — Create the project + source control + +Follow the **`unity-cli`** "Bootstrap a new project from scratch" workflow verbatim: + +- List the **real** template ids the Editor offers (`unity templates list`) and pick one matching + 2D/3D and render pipeline from the brief — don't guess ids. +- Create with `unity projects create "" --path --editor-version --template `. +- Set up source control — **ask the user which they want**, don't assume: Git (GitHub / GitLab; + add `--git-lfs` for asset-heavy games) or **Unity Version Control** (`--vcs uvcs`, which handles + large binary assets natively — no LFS), or a purely local `git init` + Unity `.gitignore`. + Publish in one step with `unity projects create --vcs … --git-token-stdin --no-initial-commit` + (tokens on stdin). Pass **`--no-initial-commit`** so the CLI doesn't commit the bare project + before packages and `.meta` files exist — you make the real first commit/check-in in Step 6. + See the `unity-cli` workflow for exact flags. + +## Step 5 — Packages + +Map the brief to a concrete package list and install it via the **`unity-package-management`** +skill (C# PackageManager Client API — **never** hand-edit `manifest.json`). Read that skill for +the genre/platform/monetization → package mapping, the installer script, and the `-quit` gotcha. +Read the final list back to the user before installing; verify `manifest.json` afterward. + +## Step 6 — Save & first commit + +Open the project once so Unity imports the assets and generates every `.meta` file, then make +the first commit **with whichever VCS you set up in Step 4**: + +```bash +unity open "" # imports + generates .meta; for headless/CI use the + # "Import & save headlessly" method in unity-package-management +``` + +- **Git (GitHub / GitLab / local):** + ```bash + cd "" + git add -A + git status # Library/ Temp/ obj/ Build/ must NOT be staged + git commit -m "Initial Unity project: " + ``` + Every `.cs`/asset must be committed together with its `.meta`. +- **Unity Version Control (UVCS):** check in through your UVCS client/workspace (created during + Step 4) — there's no `git` step. Generated folders are still excluded by the ignore rules. + +If you published via `--vcs` in Step 4 **without** `--no-initial-commit`, the CLI already made an +initial commit of the bare project — add a follow-up commit here rather than double-committing. + +## Step 7 — Hand off + +Based on Step 2 monetization, invoke the matching skill for the actual integration: +- IAP → **implement-in-app-purchases** +- Ads → **levelplay-unity-integration** +- Accounts / cloud save / economy / remote config / leaderboards → **build-live-game** + +Report the project path, Editor version, installed packages, and next steps. + +## Scope — what this skill does NOT do + +- **No gameplay scaffolding.** It gets you to a running, empty-but-wired project; building the + actual game (scenes, controllers, art) is the next conversation — iterate there with the Editor + via the `unity-cli` MCP server and the Package Manager. Generic genre skeletons tend to produce + throwaway mocked primitives, so this skill intentionally stops at a clean starting point. +- **No command reference.** Syntax lives in `unity-cli` / `unity-package-management`. + +## Checklist + +- [ ] Concept brief captured and confirmed (genre, look, gameplay, scope, name) +- [ ] Platforms + monetization recorded; Editor version chosen +- [ ] Editor + platform modules installed (started in the background during Step 2) +- [ ] Project created from a matching template; git initialized with a Unity `.gitignore` +- [ ] Packages installed via the C# Client API; `manifest.json` verified +- [ ] Project opened/saved so `.meta` files exist; first commit made; `Library/` excluded +- [ ] Handed off to the monetization/backend skill if applicable + +## Common mistakes + +- **Blocking on the Editor install** instead of backgrounding it while you ask questions. +- **Installing the wrong Editor** because the version wasn't confirmed before the background install. +- **Gathering all questions up front** — platform/monetization answers change the modules and packages. +- **Hand-editing `manifest.json`** instead of using the Client API (see `unity-package-management`). +- **Committing `Library/`/`Temp/`/`obj/`/`Build/`**, or scripts without their `.meta` files. +- **Missing Editor modules** — a mobile target needs `android`/`ios`; WebGL needs `webgl`. diff --git a/skills/unity-cli/SKILL.md b/skills/unity-cli/SKILL.md index fc37dd8..c463fff 100644 --- a/skills/unity-cli/SKILL.md +++ b/skills/unity-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: unity-cli -description: Use when interacting with Unity CLI from the terminal — install, upgrade or uninstall editors, list or open projects, manage modules, manage licenses, check auth status, read logs, browse Unity releases, build/test projects, configure the Unity MCP server for AI agents, or run any other Unity CLI operation. +description: Use when interacting with Unity CLI from the terminal — install, upgrade or uninstall editors, create, list or open projects, manage modules, manage licenses, check auth status, read logs, browse Unity releases, build/test projects, configure the Unity MCP server for AI agents, or run any other Unity CLI operation. For a guided idea-to-running-project flow for a brand-new game, use the new-unity-project skill instead. allowed-tools: - Bash --- @@ -116,1204 +116,116 @@ This works at every level of the command hierarchy. ## Commands -### Auth +The full per-command reference — syntax, flags, and examples — lives in grouped files under +[`references/`](references/). **Read the file for the command group you need**; all the global +flags, environment variables, and exit codes above apply throughout. Every command also supports +`-h` / `--help` (see [Getting help](#getting-help)). -```bash -# Check login status -unity auth status --format json - -# Login (opens browser for OAuth) -unity auth login - -# Login with service account credentials (CI — skips browser) -# Preferred: read secret from stdin to avoid shell-history and process-list exposure -unity auth login --client-id --secret-from-stdin - -# A --client-secret flag also exists, but passing a secret as a -# command-line argument exposes it in shell history and the process list. -# Avoid it — use --secret-from-stdin (above) or the -# UNITY_SERVICE_ACCOUNT_ID / UNITY_SERVICE_ACCOUNT_SECRET env vars instead. - -# Login without persisting credentials to the keyring (ephemeral CI) -unity auth login --client-id --secret-from-stdin --no-store - -# Logout (clears both service-account and OAuth credential slots) -unity auth logout - -# Skip the confirmation prompt -unity auth logout --yes -``` - -**Separate sign-in from Hub.** As of `0.1.0-beta.8`, the CLI and the GUI Hub store their sign-in credentials **separately** — signing in to one no longer signs you out of (or overwrites the account of) the other, so each can stay signed in as a different account. (In earlier betas they shared a single keyring session.) - -**Service-account credentials via env vars** (`UNITY_SERVICE_ACCOUNT_ID` + `UNITY_SERVICE_ACCOUNT_SECRET`) mint bearer tokens automatically for the duration of the process — no browser round-trip, no keyring write. If only one of the two is set, the CLI prints a warning on stderr instead of silently falling back to the keyring/OAuth identity. - -The interactive `unity auth login` flow prints the sign-in URL to the terminal **before** attempting to launch the browser, which unblocks remote/headless sessions (SSH, containers, dev VMs) where `xdg-open` / `open` has no graphical session to attach to. With `--format json`, an `auth_url=…` progress frame is emitted so machine consumers can capture the URL without parsing human text. - -`unity auth status` reflects real session state (including an explicit "session expired" message), not optimistic local assumptions. `unity doctor` and `unity cloud status` report the same real session state. - ---- - -### License — list, activate, return - -```bash -# List the Unity licenses active on this machine -unity license -unity license list # explicit form, identical output -unity license --format json # machine-readable - -# Summary: active license(s) + sign-in state -unity license status - -# Activate a license — choose exactly one mode (default = signed-in subscription) -unity license activate # signed-in user's subscription (entitlement) licenses -unity license activate --serial SC-… # serial-based (ULF) activation, no sign-in needed -unity license activate --personal --accept-eula # free Unity Personal license (must accept the EULA) -unity license activate --floating # lease a seat from the configured floating server -unity license activate --file ./Unity_lic.ulf # offline activation from a .ulf / .xml file -unity license activate --generate-request ./req.alf # write an offline activation request (air-gapped) - -# Return the active assigned/subscription licenses (prompts to confirm; --yes skips) -unity license return -unity license return --yes - -# Floating (network) license server -unity license server list # the configured floating license server(s) -unity license server status # reachability + available seats -``` - -`list` columns: product, license type (`Floating` / `Assigned` / `ULF`), organization, and expiry. `status` prints a one-glance summary — the active license(s) and whether you're signed in — and exits non-zero (`4`) when no license is active, so it works as a scriptable health check. The first licensing command downloads the Unity licensing client on demand; as of `0.1.0-beta.8`, if the client is unavailable `list` reports a clear error and exits non-zero (matching `status`), rather than printing an empty list. - -`activate` takes a single mode flag (combining them is a usage error). The default (no flag) and `--personal` activate the signed-in user's entitlements — sign in first with `unity auth login`. `--personal` also requires `--accept-eula` to acknowledge the Unity Personal license terms. `--serial` / `--file` work offline without sign-in. `--floating` requires a configured floating license server (exit `4` if none is set). `--generate-request` writes a `.alf` request for air-gapped activation instead of activating. `return` returns the active licenses, prompting for confirmation first — pass `--yes` to skip (required in non-interactive shells and with `--json`). All honor `--json` / `--format` and exit non-zero on failure (`2` bad usage, `3` sign-in required, `4` floating not configured, `6` licensing-client error). - -`unity license server list` shows the configured floating license server (from the `licensingServiceBaseUrl` machine setting; a pure settings read, no client download). `unity license server status` contacts that server and reports reachability plus available seats — exit `4` when no server is configured, `6` when configured but unreachable. - ---- - -### Cloud — Unity Cloud organizations and projects - -Requires being signed in (`unity auth login`). - -```bash -# Show cloud sign-in state and active organization -unity cloud status --format json - -# Organizations -unity cloud org list --format json -unity cloud org current # print the active default org id -unity cloud org set-default # set active default org -unity cloud org clear-default # revert to "All Organizations" - -# Projects in the active organization -unity cloud project list --format json - -# Override the active organization for a single call -unity cloud project list --cloud-org # also via UNITY_CLOUD_ORG env var -``` - ---- - -### Editors — list, install, uninstall - -```bash -# List all editors (installed + available releases) -# Short alias: unity e. The bare `unity editors` is shorthand for the explicit `unity editors list` (matches projects/templates/modules) -unity editors list --format json - -# List only installed editors -# As of beta.8 the --installed table includes an "Upgrade to" column flagging editors with a newer patch in their line -unity editors --installed --format json - -# List only available releases -unity editors --releases --format json - -# Filter by architecture -unity editors --installed --architecture arm64 --format json - -# Show detailed module info -unity editors --verbose - -# Watch mode — live-updates as editors are installed or removed -unity editors --watch -unity editors --installed --watch -``` - -`unity editors` honors `--format tsv` and `--format ndjson` for its default listing. Identifier columns keep their natural width even if the table exceeds the terminal — they are no longer silently truncated. - -#### editors add - -Register one or more existing editor installations by path: - -```bash -unity editors add /path/to/Unity/Editor - -# Register multiple at once -unity editors add /path/one /path/two - -# Skip macOS code-signature check (useful for unsigned or side-loaded builds) -unity editors add /path/to/Unity/Editor --skip-signature-check -``` - -#### editors default - -```bash -# Show current default editor -unity editors default --format json - -# Set default by version, alias, or keyword -unity editors default 6000.0.47f1 -unity editors default latest -unity editors default lts - -# Clear the default -unity editors default --unset -``` - -On a TTY with no arguments, shows an interactive selection prompt. - -#### editors path - -```bash -# Print the install directory of an installed editor (local, offline — no release-feed fetch) -unity editors path 6000.0.47f1 -unity editors path 6000.0.47f1 --architecture arm64 --json -``` - -Honors `--architecture` and `--format` / `--json`, and reports ambiguous matches so you can narrow by version or architecture. - -#### editors install-path - -```bash -# Show the directory where editors are installed -unity editors install-path - -# Set a new install path -unity editors install-path --set /path/to/editors -``` - -Also available as the top-level `unity install-path` (with an additional `--get` flag). Distinct from `editors path`: `install-path` gets/sets the *root* install directory; `editors path` prints the install directory of *one* editor version. - -#### editors info - -```bash -# Show release details for a specific version -unity editors info 6000.0.47f1 --format json -``` - -#### editors upgrade - -New in `0.1.0-beta.8`. Upgrade an installed editor to the newest official (f-channel) patch in the same `major.minor` line (e.g. `2022.3.10f1` → `2022.3.62f1`), carrying the installed modules over. The `[editor]` argument accepts an exact version, a `major.minor` line, or the `latest` / `lts` / `default` aliases. Editors install side by side — the old version is kept unless `--replace` (alias `--remove-old`) is passed. - -```bash -# Upgrade a specific editor (or the default / lts / latest) to the newest patch in its line -unity editors upgrade 2022.3.10f1 -unity editors upgrade lts - -# Upgrade every installed editor that has a newer patch -unity editors upgrade --all --yes --accept-eula - -# Report current → target without installing (--check is an alias for --dry-run) -unity editors upgrade --all --dry-run --format json - -# Remove the old editor after a successful upgrade; skip carrying modules; add extra modules -unity editors upgrade 2022.3.10f1 --replace --yes -unity editors upgrade 2022.3.10f1 --no-modules -unity editors upgrade 2022.3.10f1 --module android --module ios -``` - -#### editors module / editor module - -Module management is exposed under **both** `editors module` and the `editor` (singular) command group. Both share the same subcommands: - -```bash -# List modules for an installed editor -unity editors module list 6000.0.47f1 --format json -unity editor module list 6000.0.47f1 --architecture arm64 --format json - -# Add modules to an installed editor -unity editors module add 6000.0.47f1 --module android --module ios -unity editors module add 6000.0.47f1 --all # Install every available module -unity editors module add 6000.0.47f1 --module android --child-modules # Include child modules -unity editors module add 6000.0.47f1 --module android --accept-eula # Accept EULAs automatically - -# Refresh module list for a manually located editor -unity editors module refresh 6000.0.47f1 -``` - -#### editor add (single path, with module-fetch control) - -The `editor add` subcommand is similar to `editors add` but targets a single path and supports skipping the module-fetch step: - -```bash -unity editor add /path/to/Unity/Editor - -# Skip fetching module metadata (faster, but modules won't be listed until refreshed) -unity editor add /path/to/Unity/Editor --no-fetch-modules -``` - ---- - -### Install - -```bash -# Install an editor (interactive version selection if omitted) -unity install 6000.0.47f1 - -# Install with specific modules -unity install 6000.0.47f1 --module windows-mono --module android - -# Install a specific changeset by hash -unity install 6000.0.47f1 --changeset abc123def456 - -# Include child modules -unity install 6000.0.47f1 --cm - -# Exclude child modules -unity install 6000.0.47f1 --no-cm - -# Install and accept EULAs automatically (CI) -unity install 6000.0.47f1 --yes --accept-eula - -# Force reinstall even if already present -unity install 6000.0.47f1 --force - -# Resume an interrupted download (also recovers orphaned partials left by a crash or kill) -unity install 6000.0.47f1 --resume - -# Dry-run: show what would be installed without doing it -unity install 6000.0.47f1 --dry-run --format json - -# Space-separated module values after a single -m are equivalent to repeating -m -unity install 6000.0.47f1 -m android ios # space-separated -unity install 6000.0.47f1 -m android -m ios # repeated flag (same effect) -``` - -**NDJSON progress frames** for `unity install` and `unity install-modules` include a `phase: 'download' | 'install'` field so scripts can switch to an indeterminate spinner during the install phase (which is genuinely indeterminate — NSIS on Windows only reports success/failure). During the install phase, `pct` is locked at 50 and only jumps to 100 on completion. Module download/install progress is nested under the parent editor via `parentItemUid`, so consumers see one editor group with its modules rather than one group per module. - -Module installers honor the per-module install command from the release manifest (e.g. Visual Studio on Windows uses `--passive`, not `/S`); the resolved command is surfaced in `unity modules list --json`. `unity install` self-heals a corrupted partial download by discarding the bad partial and re-downloading; a cross-process install lock prevents two concurrent installs of the same version from corrupting the unpack. - -### Uninstall - -```bash -# Uninstall an editor version -unity uninstall 6000.0.47f1 --yes - -# Uninstall a specific architecture -unity uninstall 6000.0.47f1 --architecture arm64 --yes -``` - ---- - -### Modules — add/list per editor - -```bash -# List modules for an installed editor -unity modules list 6000.0.47f1 --format json - -# Filter by architecture -unity modules list 6000.0.47f1 --architecture arm64 --format json -``` - -`unity modules list` honors `--format ndjson` (empty results emit a clean, empty NDJSON stream). - -### install-modules - -```bash -# List available modules without installing -unity install-modules --editor-version 6000.0.47f1 --list - -# Install specific modules -unity install-modules --editor-version 6000.0.47f1 --module android --module ios - -# Install all available modules -unity install-modules --editor-version 6000.0.47f1 --all --yes - -# Include child modules (default behaviour) -unity install-modules --editor-version 6000.0.47f1 --module android --cm - -# Exclude child modules -unity install-modules --editor-version 6000.0.47f1 --module android --no-cm - -# Accept EULAs and dry-run -unity install-modules --editor-version 6000.0.47f1 --all --accept-eula --dry-run -``` - -`--list` and `--all` are mutually exclusive. `--list` is also mutually exclusive with `--module`. - -`--module android ios` (space-separated values after a single `--module`) and `--module android --module ios` (repeated flag) are equivalent — both install all listed modules. - -Module discovery works for editors registered via `unity editors add ` (located editors), not just editors installed by the Hub. - ---- - -### Projects — list, open, create, register, clone, link - -```bash -# List registered projects -unity projects list --format json - -# Register an existing project -unity projects add /path/to/MyProject - -# Remove from registry (does not delete files) -unity projects remove /path/to/MyProject - -# Show project details -unity projects info /path/to/MyProject --format json - -# Open a project in the editor -unity open /path/to/MyProject - -# Open with a specific editor version -unity open /path/to/MyProject --editor-version 6000.0.47f1 - -# Pass extra Unity arguments -unity open /path/to/MyProject --args "-logFile output.log" - -# Pass a build target (forwarded to Unity as -buildTarget / -buildTargetGroup) -unity open /path/to/MyProject --build-target StandaloneOSX -unity open /path/to/MyProject --build-target-group Standalone - -# Version shorthand (equivalent to open with --editor-version) -unity 6000.0.47f1 /path/to/MyProject -``` - -The project argument is matched against the Hub registry first (exact name or path opens immediately; a glob like `"My Game*"` prompts when multiple match); with no registry match it falls back to treating the argument as a filesystem path. `unity open` forwards `--args` to the Editor correctly on all platforms (including Windows). - -#### projects create - -Create a project. On a TTY, prompts for any missing options (parent directory, editor version, template). In CI, pass `--non-interactive` or pipe stdin to suppress prompts and rely on stored defaults. The first positional argument is the project **name**; `--path` sets the parent directory: - -```bash -unity projects create MyGame --editor-version 6000.0.47f1 --template com.unity.template.3d - -# Place the project in a specific directory -unity projects create MyGame --path /path/to/projects --editor-version 6000.0.47f1 - -# --template also accepts a .tgz file path or a directory, not just a registered template id -unity projects create MyGame --template /path/to/template.tgz -``` - -**Cloud linking during creation:** - -```bash -# Create and link a NEW Unity Cloud project as part of creation -unity projects create MyGame --cloud --cloud-org - -# Link an EXISTING cloud project instead -unity projects create MyGame --cloud-project -``` - -**Source-control during creation** — publish the new project to a fresh repository: - -```bash -unity projects create MyGame \ - --vcs github \ - --git-namespace my-org \ - --git-repo my-game \ - --git-visibility private \ - --git-default-branch main \ - --git-token-stdin -``` - -Source-control flags (shared with `projects link vcs`): `--vcs github|gitlab|uvcs`, `--git-namespace `, `--git-repo `, `--git-visibility private|public|internal` (default private), `--git-default-branch `, `--git-token ` / `--git-token-stdin`, `--no-initial-commit`, `--git-lfs`, and `--vcs-region ` for Unity Version Control. - -#### projects new - -Create a project without any interactive prompts — resolves missing options from stored defaults, never asks the user. The first positional argument is the project **name**; `--path` sets the parent directory: - -```bash -# All omitted options resolve from stored defaults -unity projects new MyGame - -# Override stored defaults with explicit values -unity projects new MyGame --path /path/to/projects --editor-version 6000.0.47f1 --template com.unity.template.3d - -# Open the project immediately after creation -unity projects new MyGame --open -``` - -#### projects clone - -Clone a remote repository and register the Unity project it contains. Works across providers: - -```bash -# Clone by full repo URL / shorthand -unity projects clone --vcs github --vcs-namespace my-org --vcs-repo my-game --path ./MyGame - -# Check out a specific ref (branch, sha, or UVCS changeset) -unity projects clone --vcs uvcs --vcs-namespace my-org --vcs-repo my-game --ref main - -# Authenticate with a personal access token (prefer stdin) -unity projects clone --vcs gitlab --vcs-namespace my-org --vcs-repo my-game --git-token-stdin - -# Project lives in a subdirectory of the repo -unity projects clone --vcs github --vcs-namespace my-org --vcs-repo monorepo \ - --path ./repo --project-path packages/MyGame -``` - -Options: `--vcs github|gitlab|uvcs`, `--vcs-namespace `, `--vcs-repo `, `--ref ` (an all-digit ref is treated as a Unity Version Control changeset, anything else as a branch), `--path ` (clone destination), `--project-path ` (project subdirectory), `--git-token ` / `--git-token-stdin`, `--json`. Git LFS assets are fetched as pointer files only. - -#### projects pin / unpin - -```bash -# Pin a project to the top of the list -unity projects pin /path/to/MyProject - -# Unpin -unity projects unpin /path/to/MyProject -``` - -#### projects require - -Ensure the editor version required by a project is installed, installing it if needed: - -```bash -unity projects require /path/to/MyProject --yes -``` - -On a TTY with no path, prompts interactively. - -#### projects upgrade - -Upgrade a project to a different Unity editor version. `--to` is required: - -```bash -unity projects upgrade --to 6000.0.47f1 -unity projects upgrade /path/to/MyProject --to 6000.0.47f1 --yes -``` - -#### projects export / import - -```bash -# Export the project registry to a file (or stdout if -o is omitted) -unity projects export -o projects.json - -# Import a previously exported registry -unity projects import projects.json -unity projects import --input projects.json -``` - -#### projects open / link / unlink - -```bash -# Open a registered project by name, fuzzy title match, or path -unity projects open MyProject -# (the top-level `unity open` is the same thing) - -# --- Cloud links --- -# Connect an existing local project to a Unity Cloud project -unity projects link cloud /path/to/MyProject --cloud-org -# Disconnect from its Unity Cloud project -unity projects unlink cloud /path/to/MyProject - -# --- Version-control links --- -# Publish a local project to a NEW GitHub / GitLab / Unity Version Control repository -unity projects link vcs /path/to/MyProject \ - --vcs github --git-namespace my-org --git-repo my-game --git-token-stdin -# Remove a project's git remotes (the remote repositories are NOT deleted) -unity projects unlink vcs /path/to/MyProject -# Also detach the Unity Version Control workspace -unity projects unlink vcs /path/to/MyProject --unlink-workspace -``` - -`link vcs` shares the source-control flag set documented under `projects create`. `link cloud` / `link vcs` accept `--cloud-org ` (env `UNITY_CLOUD_ORG`). - ---- - -### Releases — browse Unity versions - -```bash -# List recent releases -unity releases --format json - -# Filter by stream (alpha, beta, lts, tech) -unity releases --stream lts --format json -unity releases --stream tech --format json -unity releases --stream beta --format json - -# LTS only shorthand -unity releases --lts --format json - -# Filter from a year onward -unity releases --since 2023 --format json - -# Paginate -unity releases --limit 10 --skip 20 --format json -``` - ---- - -### Templates - -```bash -# List templates for an editor version (uses default editor if --editor is omitted) -unity templates list --editor 6000.0.47f1 --format json - -# List only locally installed templates -unity templates list --editor 6000.0.47f1 --installed --format json - -# Filter by type (core, learning, sample, custom, new, all) — case-insensitive -unity templates list --editor 6000.0.47f1 --type core --format json -unity templates list --editor 6000.0.47f1 --type learning --format json -unity templates list --editor 6000.0.47f1 --type sample --format json -unity templates list --editor 6000.0.47f1 --type new --format json -unity templates list --editor 6000.0.47f1 --type all --format json # no-op, returns everything - -# List only user-generated (custom) templates -unity templates list --editor 6000.0.47f1 --custom --format json -# --type custom is an alias for --custom -unity templates list --editor 6000.0.47f1 --type custom --format json - -# --custom and --type are mutually exclusive — using both is an error (exit 1) - -# Show template details -unity templates info com.unity.template.3d --editor 6000.0.47f1 --format json - -# Create a custom template from an existing Unity project -# --name and --display-name are REQUIRED -unity templates create /path/to/MyProject \ - --name com.myorg.template.mytemplate \ - --display-name "My Template" - -# With all optional options -unity templates create /path/to/MyProject \ - --name com.myorg.template.mytemplate \ - --display-name "My Template" \ - --description "A starting point for our projects" \ - --template-version 1.0.0 \ - --output /path/to/templates/dir \ - --keep-embedded-packages \ - --keep-project-settings \ - --overwrite - -# JSON output (includes path to created .tgz archive) -unity templates create /path/to/MyProject \ - --name com.myorg.template.mytemplate \ - --display-name "My Template" \ - --json - -# NDJSON streaming — emits progress frames then a result frame -unity templates create /path/to/MyProject \ - --name com.myorg.template.mytemplate \ - --display-name "My Template" \ - --format ndjson -``` - -**`templates create` key notes:** -- `--name` must be a valid npm package name (e.g. `com.myorg.template.mytemplate`) -- `--output` overrides the Hub-configured user templates directory -- `--overwrite` replaces an existing archive of the same name without error -- On success, prints the path to the created `.tgz` archive -- Created templates appear in `unity templates list --editor --custom` - -```bash -# Delete a user-generated custom template (prompts for confirmation) -unity templates delete com.myorg.template.mytemplate --editor 6000.0.47f1 - -# Skip the confirmation prompt (CI-friendly) -unity templates delete com.myorg.template.mytemplate --editor 6000.0.47f1 --yes - -# JSON output -unity templates delete com.myorg.template.mytemplate --editor 6000.0.47f1 --yes --json -``` - -**`templates delete` key notes:** -- Only user-generated templates (created via Hub UI or `templates create`) can be deleted -- Attempting to delete a built-in Unity template exits with a descriptive error (exit 6) -- Attempting to delete a template that doesn't exist exits with a descriptive error (exit 6) -- In interactive mode, prompts for confirmation before deleting; use `--yes` to skip -- On success, the template no longer appears in `unity templates list --editor --custom` - -```bash -# Get/set/reset the default storage path for custom templates -# Print current configured templates location -unity templates location - -# Set a new default templates directory (must exist as a directory) -unity templates location --set /path/to/templates - -# Reset templates location to the Hub default -unity templates location --reset - -# JSON output for any variant -unity templates location --json -unity templates location --set /path/to/templates --json -unity templates location --reset --json -``` - -**`templates location` key notes:** -- `--set` and `--reset` are mutually exclusive (using both is an error) -- `--set` validates that the path exists and is a directory (exits 2 if not) -- `--reset` restores the Hub default templates path -- JSON output: `{ "path": "..." }` inside the standard envelope - -```bash -# Edit a user-generated (custom) template's metadata -# At least one of --display-name, --description, --template-version, -# --preview-image, --remove-preview-image is required -unity templates edit com.myorg.template.mytemplate --editor 6000.0.47f1 --display-name "My Updated Template" - -# Update multiple fields at once -unity templates edit com.myorg.template.mytemplate \ - --editor 6000.0.47f1 \ - --display-name "My Updated Template" \ - --description "A new description for the template" \ - --template-version 1.1.0 - -# Replace / remove preview image -unity templates edit com.myorg.template.mytemplate --editor 6000.0.47f1 --preview-image /path/to/image.png -unity templates edit com.myorg.template.mytemplate --editor 6000.0.47f1 --remove-preview-image - -# JSON / NDJSON output (--yes required because these are non-interactive) -unity templates edit com.myorg.template.mytemplate --editor 6000.0.47f1 --display-name "Updated" --yes --json -``` - -**`templates edit` key notes:** -- Only works on user-generated (custom) templates; built-in templates cannot be edited -- Use `--editor` to specify which editor version's template list to search, or omit to use the stored default -- `--preview-image ` resolves to an absolute path before passing to the service -- `--remove-preview-image` is only applied when no valid `--preview-image` path is given; if both are passed with a valid image path, the new image wins and `--remove-preview-image` is ignored -- On success (human format), prints the updated template's display name - ---- - -### Config — persisted CLI configuration - -The `config` command group manages settings that persist across invocations. - -#### config proxy - -View or change the configured HTTP/HTTPS/SOCKS/PAC proxy. The persisted value is read by every CLI command that issues outbound HTTP (releases, install, auth, telemetry, etc.). - -```bash -# Show the effective proxy configuration (resolution source + auth source) -unity config proxy -unity config proxy --json - -# Persist a proxy URL -unity config proxy http://proxy.example.com:8080 - -# Embedded userinfo (user:password@host) is supported and redacted in echo -# output, but prefer leaving credentials out of the URL — the CLI looks them -# up in the OS keyring instead (see Resolution priority below). - -# Persist with bypass list (hosts that should NOT go through the proxy) -unity config proxy http://proxy.example.com:8080 --bypass "localhost,127.0.0.1,*.internal" - -# SOCKS / PAC variants -unity config proxy socks5://proxy.example.com:1080 -unity config proxy pac+http://wpad.example.com/proxy.pac -unity config proxy pac+file:///etc/proxy.pac - -# Clear the persisted proxy -unity config proxy --unset -``` - -**Supported schemes:** `http://`, `https://`, `socks://`, `socks4://`, `socks4a://`, `socks5://`, `socks5h://`, `pac+http://`, `pac+https://`, `pac+file://`. - -**Resolution priority** (highest → lowest): -1. `--proxy ` global flag (one-shot override for the current invocation) -2. `UNITY_PROXY` env var -3. Standard env vars: `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, `NO_PROXY` -4. Persisted `proxy.json` (`unity config proxy `) -5. System proxy settings (where supported) - -Credentials missing from the URL are looked up in the OS keyring (shared with the GUI Hub); Kerberos/SPNEGO-authenticated proxies are supported. `--proxy-disable` short-circuits all of the above for the current invocation, which is the recommended way to diagnose a misconfigured proxy without clearing it. - -#### config update-check - -New in `0.1.0-beta.8`. Enable or disable the background check for a newer CLI version (the unobtrusive "update available" notice; interactive sessions only, never delays a command). Equivalent to the `UNITY_NO_UPDATE_CHECK` env var. - -```bash -unity config update-check # show the current setting -unity config update-check off # disable -unity config update-check on # enable -unity config update-check --json -``` - ---- - -### Hub — install the Unity Hub application - -Bootstrap Unity Hub on a clean machine from the command line. - -```bash -# Install the latest stable Hub for the current OS + architecture -unity hub install - -# Install a specific Hub version -unity hub install --hub-version 3.17.0 - -# Force reinstall even when Hub is already detected -unity hub install --force - -# Run the installer silently (Windows only) -unity hub install --headless - -# Override architecture (e.g. x64 Hub on Apple Silicon via Rosetta) -unity hub install --architecture x64 - -# Skip the installer code-signature check (unsigned/local builds — not recommended) -unity hub install --skip-signature-check -``` - -Options: `-f` / `--force`, `--headless` (silent installer, Windows only), `-a` / `--architecture x64|arm64` (env `UNITY_ARCHITECTURE`), `--hub-version ` (default latest), `--skip-signature-check`. - -**Integrity & signature verification** — every download is checked against the SHA-512 from the HTTPS manifest, then the installer's **code signature** is verified before it runs with elevation: on macOS via `codesign` (signer `Developer ID Application: Unity Technologies`), on Windows via Authenticode (signer subject `Unity Technologies`), checked *before* the UAC prompt. Verification is **fail-closed** — if it fails or the verifier is unavailable, the command aborts with exit 6 and does not run the installer. Linux `.AppImage` has no standard verifier, so it is SHA-512-only. Pass `--skip-signature-check` to bypass (prints a warning; not recommended). - -**`--hub-version` behaviour** — fetches the version-specific manifest from the CDN; if that version does not exist, the command exits with code 6 (no fallback to latest). - -```bash -# JSON output -unity hub install --format json -``` - -Emits `{ "success": true, "command": "hub install", "data": { "version": "3.x.x", "installed": true } }` on success, or an `{ "alreadyInstalled": true, "installedPath": "…" }` payload when Hub was already present. - ---- - -### Run — batch/headless execution - -```bash -# Run a Unity project headless (batch mode is automatic — do NOT pass -batchmode/-quit) -unity run /path/to/MyProject -- -executeMethod Builder.Build - -# Override editor version -unity run /path/to/MyProject --editor-version 6000.0.47f1 -- -nographics -logFile out.log - -# Install editor automatically if missing -unity run /path/to/MyProject --allow-install -- -executeMethod Builder.Build - -# Kill the Unity process after 300 seconds (useful in CI to prevent hangs) -unity run /path/to/MyProject --timeout 300 -- -executeMethod Builder.Build -# Equivalent via env var: -UNITY_RUN_TIMEOUT=300 unity run /path/to/MyProject -- -executeMethod Builder.Build -``` - -`unity run` always launches the editor in batch mode and forwards the args after `--` to the Unity executable, then returns the editor's exit code. - -**Reserved flags — do NOT pass these after `--`.** The command adds them itself: `-batchmode`, `-quit`, `-projectPath`, `-useHub`, `-hubIPC`. Passing any of them fails fast (before launch) with exit code 6: - -``` -Error: Forwarded argument '-batchmode' conflicts with a reserved Unity flag managed by this command. Remove it from the args after `--`. -``` - -Flags like `-nographics`, `-logFile `, and `-executeMethod ` are not reserved and are forwarded normally. - -When `--timeout ` is set, the process receives SIGTERM at the deadline; if still alive after 2 s it receives SIGKILL. The command exits with code 6 (EXIT_COMMAND_FAILURE) on timeout. - ---- - -### Test — run EditMode/PlayMode tests - -```bash -# Run tests and write an NUnit XML report (omitting --mode runs the editor's default platform) -unity test /path/to/MyProject - -# Run a specific platform (--mode is case-insensitive: EditMode/editmode both work) -unity test /path/to/MyProject --mode EditMode -unity test /path/to/MyProject --mode PlayMode --output ./results/play.xml - -# Run only tests whose names match a filter -unity test /path/to/MyProject --filter "MyNamespace.MyTests" - -# Pin the editor version, installing it if missing; cap the run at 600 s -unity test /path/to/MyProject --editor-version 6000.0.47f1 --allow-install --timeout 600 -# Equivalent via env var: -UNITY_TEST_TIMEOUT=600 unity test /path/to/MyProject - -# Forward extra editor args after -- (reserved test flags are rejected) -unity test /path/to/MyProject -- -nographics -``` - -`unity test` launches the editor's built-in test runner in batch mode (`-runTests -testPlatform -testResults -testFilter `), waits for it to finish, and writes the report to `--output` (default `test-results.xml`). It exits 0 when the run succeeds and 6 (EXIT_COMMAND_FAILURE) when the editor exits non-zero — i.e. reports test failures or fails to run. It runs the tests **directly via the editor command line** — no pipeline package or server is involved. `--mode` is optional; when omitted, `-testPlatform` is not passed and the editor runs its default platform. - -It deliberately does **not** pass `-quit`: `-runTests` quits the editor itself once results are written, so forcing `-quit` would terminate it before the report exists. Anything after `--` is forwarded to the editor verbatim, except reserved flags managed by the command (`-projectPath`, `-batchmode`, `-runTests`, `-testPlatform`, `-testResults`, `-testFilter`, `-quit`, `-useHub`, `-hubIPC`), which are rejected. - -Options: `--mode EditMode|PlayMode`, `--filter `, `--output `, `--editor-version ` (env `UNITY_EDITOR_VERSION`), `-e, --editor-path `, `-a, --architecture `, `--allow-install`, `--timeout ` (env `UNITY_TEST_TIMEOUT`). - ---- - -### Build - -`--target` and `--execute-method` are both **required** — Unity has no built-in command-line build, so your `executeMethod` is responsible for the actual build (including honoring `--output-path`). - -```bash -# Build a project (requires --target and --execute-method) -unity build /path/to/MyProject \ - --target StandaloneOSX \ - --execute-method Builder.PerformBuild \ - --output-path ./build/output - -# Common build targets: StandaloneOSX, StandaloneWindows64, StandaloneLinux64, Android, iOS, WebGL -``` - -**Options:** - -| Flag | Description | -|---|---| -| `--target ` | Build target (required). | -| `--execute-method ` | Static C# method to invoke, e.g. `Builder.PerformBuild` (required). | -| `--build-target-group ` | Forwarded to Unity as `-buildTargetGroup`. | -| `-o, --output-path ` | Passed as `-buildOutput` (your method must honor it). | -| `-l, --log-file ` | Log file path. Default: `/Logs/build--.log`. | -| `--editor-version ` | Override editor version (default: from `ProjectVersion.txt`). | -| `-e, --editor-path ` | Use a specific editor binary. | -| `-a, --architecture ` | Editor architecture (`x86_64` or `arm64`). | -| `--args ` | Extra arguments passed to Unity (shell-split). | -| `--no-tail` | Do not stream the log to stdout in real time. | -| `--allow-install` | Install the project's editor version if missing. | -| `--versioning-strategy ` | `semantic`, `tag`, `custom`, or `none` (default: `none`). | -| `--build-version ` | Explicit version string; only used with `--versioning-strategy custom`. | -| `--allow-dirty-build` | Skip the uncommitted-changes guard (default: false). | - -**Android signing & export** (applied to Android targets only): - -| Flag | Description | +| Commands | Reference file | |---|---| -| `--android-export-type ` | `apk`, `aab`, or `android-studio-project`. | -| `--android-keystore-base64 ` | Keystore file, base64-encoded. | -| `--android-keystore-password ` | Keystore password. | -| `--android-key-alias ` | Key alias within the keystore. | -| `--android-key-alias-password ` | Key alias password. | -| `--android-target-sdk-version ` | Target SDK version. | -| `--android-symbol-type ` | `none`, `public`, or `debugging`. | -| `--android-version-code ` | Android version code. | - -Keystore flags are validated together. Secrets passed as command-line flags surface in the process list and can be echoed into CI logs. Supply `--android-keystore-base64`, `--android-keystore-password`, and `--android-key-alias-password` from CI secret environment variables (e.g. `--android-keystore-password "$KEYSTORE_PASSWORD"`), never as inline literals, and source those variables from a dedicated CI secret store. Note that sourcing from an env var only avoids hard-coding the literal — the expanded value still appears in `argv`, so also mask it in CI log output. - -**Versioning** — `semantic` and `tag` derive the version from git tags/history; `custom` requires an explicit `--build-version`; a dirty working tree is rejected unless `--allow-dirty-build` is passed. - -```bash -# With --format json, stdout includes newline-delimited JSON progress frames before the final envelope: -unity build /path/to/MyProject --target StandaloneOSX --execute-method Builder.Build --format json -# Output (each line is a JSON object): -# {"type":"progress","command":"build","message":"Resolving project..."} -# {"type":"progress","command":"build","message":"Resolving editor..."} -# {"type":"progress","command":"build","message":"Starting Unity..."} -# {"type":"progress","command":"build","message":"Unity exited (code 0)"} -# { "success": true, "command": "build", "data": { "target": "...", "logFile": "..." } } -``` - ---- - -### Logs — application logs - -```bash -# Show last 20 log lines (default) -unity logs - -# Show last 50 lines -unity logs --tail 50 - -# Follow in real-time (like tail -f) -unity logs --follow - -# Filter by level -unity logs --level error -unity logs --level warn - -# Available levels: trace, debug, info, warn, error, fatal -``` - -The CLI writes its own `cli-log.json` (separate from the Hub's `info-log.json`) and records its version on every start. `unity logs`, `unity bug`, and `unity doctor` read the CLI's own log. - ---- - -### Doctor — system diagnostics - -```bash -# Full system report -unity doctor --format json - -# Includes: platform info, auth status, installed editors, recent log lines, resolved proxy -unity doctor --tail 50 -``` - -`unity doctor` reports real session state (matching `unity auth status`) and surfaces the resolved proxy URL, its source, and auth source. - ---- - -### Environment - -```bash -# Show environment paths -unity env --format json - -# Returns: user data path, editor install path, download cache path, config path, CLI version, resolved proxy -``` - ---- - -### Cache - -```bash -# Show cache location and size -unity cache info --format json - -# Clear download cache -unity cache clean --yes -``` - ---- - -### Analytics — usage/telemetry consent - -The CLI defaults to **opt-out**. On the first interactive run a y/N prompt is shown once before any data is collected; non-interactive, CI, piped, and `--quiet` contexts silently keep the opt-out default. - -```bash -# Show current consent status -unity analytics status -unity analytics status --format json - -# Opt in to anonymous usage data collection -unity analytics opt-in - -# Opt out (the default) -unity analytics opt-out -``` - -Consent is stored in the shared Hub privacy preferences, so opting out in the CLI also opts out in Hub, and vice versa. - ---- - -### Changelog - -Show the embedded release notes for the currently installed CLI version: - -```bash -unity changelog -unity changelog --format json -``` - ---- - -### Language - -```bash -# Show current language and available options -unity language - -# Set language by code -unity language --set en -unity language --set ja -unity language --set zh-hans - -# Alias -unity lang --set ko -``` - -On a TTY with no flags, shows an interactive selection prompt. - ---- - -### Completion — shell tab completion - -Generate and install shell completion scripts: - -```bash -# Supported shells: bash, zsh, fish, powershell -unity completion bash -unity completion zsh -unity completion fish -unity completion powershell -``` - ---- - -### Bug — report a bug - -Interactive bug reporter that collects system info and recent logs, then submits to Unity: - -```bash -unity bug -``` - -Prompts for title, description, email, and reproducibility level. As of beta.8 it collects the same diagnostic system information as the Unity Hub bug reporter (including GPU details). - ---- - -### Upgrade — update the CLI itself - -```bash -# Check for available updates -unity upgrade --check --format json - -# Show changelog for the new version -unity upgrade --changelog - -# Upgrade (interactive confirmation) -unity upgrade - -# Upgrade without prompts -unity upgrade --yes - -# Install a specific version -unity upgrade --target 0.2.0 - -# Select update channel (stable or beta) -unity upgrade --channel beta - -# Dry-run: show what would change -unity upgrade --dry-run - -# Rollback to previous version -unity upgrade --rollback -``` - ---- - -### Self-uninstall — remove the CLI - -```bash -# Uninstall the CLI (interactive confirmation) -unity self-uninstall - -# Uninstall without prompts -unity self-uninstall --yes - -# Also remove config and data files -unity self-uninstall --purge --yes - -# Dry-run: show what would be removed -unity self-uninstall --dry-run -``` +| `auth` (login / logout / status), `license` (activate / return / server), `cloud` (org / project) | [auth-license-cloud.md](references/auth-license-cloud.md) | +| `editors` (list / add / default / path / install-path / info / upgrade / module), `install`, `uninstall`, `modules`, `install-modules` | [editors-install.md](references/editors-install.md) | +| `projects` (list / create / new / clone / open / link / require / upgrade / export / import / pin), `releases`, `templates` | [projects-templates.md](references/projects-templates.md) | +| `config` (proxy / update-check), `hub install` | [config-hub.md](references/config-hub.md) | +| `run`, `test`, `build` | [build-run-test.md](references/build-run-test.md) | +| `logs`, `doctor`, `env`, `cache`, `analytics`, `changelog`, `language`, `completion`, `bug`, `upgrade`, `self-uninstall` | [diagnostics-maintenance.md](references/diagnostics-maintenance.md) | +| `mcp` (+ `configure`), connected editors (`pipeline` / `command` / `status`), development-only (`eval` / `cloud-pipeline` / `collab`) | [integration-advanced.md](references/integration-advanced.md) | -> **`unity implode` was removed** in `0.1.0-beta.8` (it was previously a deprecated alias). Use `unity self-uninstall`. - ---- - -### MCP — Model Context Protocol server (AI agent integration) - -New in `0.1.0-beta.8`. `unity mcp` starts a Model Context Protocol server, built into the `unity` binary, that exposes the commands of a connected Unity Editor as MCP tools. AI agent clients connect over stdio, list those tools, and run them. The server starts even when no Editor is running and reports that it isn't connected; commands that a connected Editor adds show up as tools automatically. - -```bash -# Start the MCP stdio server (usually launched by the AI client, not by hand) -unity mcp - -# Pin the server to a specific Unity project / Editor instance -unity mcp --project-path /path/to/MyProject -unity mcp --instance localhost:55000 -``` - -#### mcp configure — register the server in an AI client - -Writes the Unity MCP server entry into an AI client's config in one step, preserving every other key in the file. 16 clients are supported: `claude`, `claude-code`, `cursor`, `vscode`, `vscode-insiders`, `copilot-cli`, `windsurf`, `cline`, `codex`, `kiro`, `trae`, `openclaw`, `antigravity`, `zed`, `continue`, `inspect`. - -```bash -# List all supported clients and their config paths -unity mcp configure --list - -# Configure a client -unity mcp configure claude -unity mcp configure claude-code - -# Project-local config for clients that support it (e.g. cursor, windsurf) -unity mcp configure cursor --local - -# Pin to a project; skip the "already exists, update?" prompt; preview without writing -unity mcp configure claude --project-path /path/to/MyProject -unity mcp configure vscode --yes -unity mcp configure vscode --dry-run -``` - ---- - -### Connected Editors — pipeline / command / status - -> **Promoted to production in `0.1.0-beta.8`.** In earlier betas these were development-only (and the Pipeline package was Unity-internal). They now talk to any running Unity Editor over its Pipeline server, and the supporting Editor-side package (`com.unity.pipeline`) is resolved from the **Unity (UPM) registry** and added to the project's `Packages/manifest.json` — no internal access or manual setup required. The Editor defines each command's parameters, help, and error messages, so the commands a connected Editor exposes are usable without a CLI update. - -#### pipeline (alias: pipe) — manage the Unity Pipeline package - -```bash -# List the Editors the CLI can reach and the Pipeline package status of each -unity pipeline list --format json - -# Install / update the Pipeline package into a project (auto-detects project if omitted) -unity pipeline install -unity pipeline install --project-path /path/to/MyProject -unity pipeline install --force # re-resolve to the latest version even if present -``` - -`pipeline install` options: `--project-path `, `--force`. The package is resolved from the Unity registry and written to `Packages/manifest.json`. - -#### command (aliases: cmd, request) — send commands to a running Unity Editor - -Forwards a command to a connected Editor. Run it with no arguments to list the commands the connected Editor exposes. - -```bash -# List all commands available on the connected Unity Editor -unity command -unity command --format json - -# Execute a specific command (names/params come from the Editor) -unity command editor_play -unity command log_editor "Hello from CLI" -unity command editor_status --includeMemory true - -# Capture a Scene/Game view screenshot (forwarded to the Editor's screenshot command, new in beta.8) -unity command screenshot --output ./shot.png --width 1920 --height 1080 - -# Target a specific project / instance / Player runtime -unity command editor_play --project-path /path/to/MyProject -unity command editor_play --instance localhost:8765 -unity command --runtime "MyGame" -unity command --runtime-path /path/to/port-file - -# Set a timeout (default: 30 seconds) -unity command editor_play --timeout 60 -``` - -If no editor with a reachable Pipeline server is found, the command errors with guidance (make sure the editor is running and its Pipeline server is up). - -#### status — live state of connected editors - -```bash -# Show port, state, project, version, PID for every connected Unity Editor -unity status --format json - -# Filter to one instance -unity status --port 8765 -unity status --project megacity -``` - -Reads the lockfile the Pipeline package writes per running Editor (faster and more CI-friendly than `pipeline list`). Stale-heartbeat instances are reported as `unreachable` without an HTTP probe. With `--format json`/`ndjson`, emits a `success: false` envelope (`STATUS_NO_INSTANCES` / `STATUS_ALL_UNREACHABLE`) and a non-zero exit when no Editor is reachable, so CI scripts can gate on Editor availability. - ---- - -## Development-only commands (hidden in production builds) +## Common workflows -The commands below are **absent from the published production CLI** — they only register when `HUB_ENV=development`, so they won't appear in `unity --help` for a normal install. Documented here for completeness; if you don't see them, they're not available in your build. +### Bootstrap a new project from scratch -### eval — evaluate a C# expression in a running editor +> For a **guided** end-to-end experience — concept questions, installing the Editor in the +> background while you plan, package selection, and monetization handoff — use the +> **`new-unity-project`** skill. This section is the raw CLI recipe that skill builds on; use it +> directly when you just want the commands. -Requires a connected Editor with the Pipeline package (see *Connected Editors* above). +Take an idea to a running, version-controlled project using only the CLI. Decide the **target +platforms first** — they determine which Editor modules you install in step 2. You can add +modules later (`unity install-modules`), but a project can't build for a platform until that +platform's module is installed, so it's simplest to decide up front. ```bash -unity eval 'Application.version' -unity eval '1 + 2' -unity eval 'Application.version' --json -unity eval 'Time.realtimeSinceStartup' --timeout 10 # server-side timeout (default: 5s) - -# Bare expressions are auto-wrapped as 'return ;'. Include a ';' to run a statement body: -unity eval 'Debug.Log("hello");' -unity eval 'var s = Application.dataPath; return s.Length;' -``` - -Compile failures surface the Roslyn diagnostics and exit non-zero. Targeting options match `command`: `--project-path`, `--instance `, `--runtime `, `--runtime-path `. - -### cloud-pipeline — Unity Cloud Pipeline - -Manage Unity Cloud Pipeline resources. Subcommand groups: `status`, `onboard`, `assets` (`list`/`status`/`url`), `branches` (`list`/`show`/`create`/`url`/`enable`/`edit`/`disable`), `pending-changes list`, `files` (`create`/`update`/`delete`/`move`), `pull-request create`. Use `unity cloud-pipeline --help` (development build) for the full flag set. - -### collab — Unity collaboration (annotations & attachments) - -Manage review annotations and attachments. Subcommand groups: `annotations` (`count`/`create`/`delete`/`get`/`update`/`replies`/`resolve`/`status`/`unresolve`) and `attachments` (`list`/`delete`/`update`). Use `unity collab --help` (development build) for the full flag set. - ---- - -## Common workflows +# 1. Confirm the CLI works and you're signed in and licensed (see references/auth-license-cloud.md). +unity --version +unity auth status --format json # if signed out: unity auth login +unity license status --format json # if none active: unity license activate + +# 2. Pick and install an Editor with the modules your target platforms need. +# Default to the latest LTS (most stable, ~2 years of patches). Reach for a Tech-stream +# release (--stream tech) only for a feature not yet in LTS; treat --stream beta/alpha as +# evaluation-only, never for a project you intend to ship. A deadline argues for LTS. +# (lts / latest aliases work wherever a version is accepted.) +unity releases --stream lts --limit 5 --format json +unity install lts --module android --module ios --yes --accept-eula # add --module webgl, etc. +unity editors --installed --format json # confirm it landed + +# 3. List the real template ids this Editor offers — don't guess them. +unity templates list --editor lts --format json +# Common ids: com.unity.template.3d, com.unity.template.2d, and a URP template (id varies by version). + +# 4. Create the project. The first positional arg is the NAME; --path sets the parent directory. +# All options supplied, so it won't prompt; add --non-interactive in CI. +unity projects create "MyGame" --path ~/UnityProjects \ + --editor-version lts --template com.unity.template.3d +``` + +**Source control — let the user choose.** The CLI publishes the new project to a fresh remote in +one step for any provider. **Always pass tokens on stdin** (`--git-token-stdin`) so secrets never +land in shell history or the process list. Pick based on the project — don't default to one: + +- **Git — GitHub / GitLab** (`--vcs github` / `--vcs gitlab`). Ubiquitous. For asset-heavy games + add **Git LFS** (`--git-lfs`) so large binaries don't bloat history. +- **Unity Version Control — UVCS** (`--vcs uvcs`). Unity's own VCS, built for large binary game + assets: it handles them natively (**no LFS needed**) and supports file locking — often the + better fit for art-heavy projects or larger teams. Auth uses your Unity sign-in; `--vcs-region` + selects the region. + +```bash +# Git (GitHub) — drop --git-lfs if the game isn't asset-heavy. Add --no-initial-commit if you +# want to add packages/assets BEFORE the first commit (see the new-unity-project flow). +unity projects create "MyGame" --path ~/UnityProjects \ + --editor-version lts --template com.unity.template.3d \ + --vcs github --git-namespace my-org --git-repo my-game \ + --git-visibility private --git-default-branch main --git-token-stdin --git-lfs + +# Unity Version Control (UVCS) — handles binaries natively, so no LFS: +unity projects create "MyGame" --path ~/UnityProjects \ + --editor-version lts --template com.unity.template.3d \ + --vcs uvcs --git-namespace my-org --git-repo my-game --vcs-region +``` + +Feed the token to `--git-token-stdin` from a secret store, never a literal — e.g. +`… --git-token-stdin <<<"$GIT_TOKEN"` where `$GIT_TOKEN` comes from your CI/secret manager +(UVCS uses your Unity sign-in, so no token is needed). See +[references/projects-templates.md](references/projects-templates.md) for the full +source-control flag set. For a purely local Git repository instead, initialize git with a +Unity-appropriate ignore so the multi-GB `Library/` and other generated folders are never committed: + +```bash +cd ~/UnityProjects/MyGame +git init -b main +# Download (do not pipe to a shell) a maintained Unity .gitignore: +curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Unity.gitignore -o .gitignore + +# Asset-heavy game? Keep large binaries out of git history with Git LFS: +git lfs install +git lfs track "*.psd" "*.fbx" "*.wav" "*.mp3" "*.png" # adjust to your asset types +git add .gitattributes + +git add -A +git status # sanity-check: Library/ Temp/ obj/ Build/ must NOT be staged +git commit -m "Initial Unity project: MyGame" +git ls-files | grep -c '^Library/' # must print 0 +``` + +**What the CLI does and doesn't cover.** The CLI handles editor, project, and source control. +It does **not** manage UPM (Unity Package Manager) packages — to add packages beyond the +template headlessly, use the **`unity-package-management`** skill (C# PackageManager Client +API). For monetization/backend, hand off to the dedicated skills: `implement-in-app-purchases` +(IAP), `levelplay-unity-integration` (ads), or `build-live-game` (accounts, cloud save, +economy, remote config, leaderboards). Open the project to start working: +`unity open ~/UnityProjects/MyGame`. ### Find and install a missing editor diff --git a/skills/unity-cli/references/auth-license-cloud.md b/skills/unity-cli/references/auth-license-cloud.md new file mode 100644 index 0000000..7f7888e --- /dev/null +++ b/skills/unity-cli/references/auth-license-cloud.md @@ -0,0 +1,105 @@ +# Auth, license & cloud — unity-cli command reference + +Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +environment variables, exit codes, and common workflows. All global flags (`--format json`, +`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. + +--- + +### Auth + +```bash +# Check login status +unity auth status --format json + +# Login (opens browser for OAuth) +unity auth login + +# Login with service account credentials (CI — skips browser) +# Preferred: read secret from stdin to avoid shell-history and process-list exposure +unity auth login --client-id --secret-from-stdin + +# A --client-secret flag also exists, but passing a secret as a +# command-line argument exposes it in shell history and the process list. +# Avoid it — use --secret-from-stdin (above) or the +# UNITY_SERVICE_ACCOUNT_ID / UNITY_SERVICE_ACCOUNT_SECRET env vars instead. + +# Login without persisting credentials to the keyring (ephemeral CI) +unity auth login --client-id --secret-from-stdin --no-store + +# Logout (clears both service-account and OAuth credential slots) +unity auth logout + +# Skip the confirmation prompt +unity auth logout --yes +``` + +**Separate sign-in from Hub.** As of `0.1.0-beta.8`, the CLI and the GUI Hub store their sign-in credentials **separately** — signing in to one no longer signs you out of (or overwrites the account of) the other, so each can stay signed in as a different account. (In earlier betas they shared a single keyring session.) + +**Service-account credentials via env vars** (`UNITY_SERVICE_ACCOUNT_ID` + `UNITY_SERVICE_ACCOUNT_SECRET`) mint bearer tokens automatically for the duration of the process — no browser round-trip, no keyring write. If only one of the two is set, the CLI prints a warning on stderr instead of silently falling back to the keyring/OAuth identity. + +The interactive `unity auth login` flow prints the sign-in URL to the terminal **before** attempting to launch the browser, which unblocks remote/headless sessions (SSH, containers, dev VMs) where `xdg-open` / `open` has no graphical session to attach to. With `--format json`, an `auth_url=…` progress frame is emitted so machine consumers can capture the URL without parsing human text. + +`unity auth status` reflects real session state (including an explicit "session expired" message), not optimistic local assumptions. `unity doctor` and `unity cloud status` report the same real session state. + +--- + +### License — list, activate, return + +```bash +# List the Unity licenses active on this machine +unity license +unity license list # explicit form, identical output +unity license --format json # machine-readable + +# Summary: active license(s) + sign-in state +unity license status + +# Activate a license — choose exactly one mode (default = signed-in subscription) +unity license activate # signed-in user's subscription (entitlement) licenses +unity license activate --serial SC-… # serial-based (ULF) activation, no sign-in needed +unity license activate --personal --accept-eula # free Unity Personal license (must accept the EULA) +unity license activate --floating # lease a seat from the configured floating server +unity license activate --file ./Unity_lic.ulf # offline activation from a .ulf / .xml file +unity license activate --generate-request ./req.alf # write an offline activation request (air-gapped) + +# Return the active assigned/subscription licenses (prompts to confirm; --yes skips) +unity license return +unity license return --yes + +# Floating (network) license server +unity license server list # the configured floating license server(s) +unity license server status # reachability + available seats +``` + +`list` columns: product, license type (`Floating` / `Assigned` / `ULF`), organization, and expiry. `status` prints a one-glance summary — the active license(s) and whether you're signed in — and exits non-zero (`4`) when no license is active, so it works as a scriptable health check. The first licensing command downloads the Unity licensing client on demand; as of `0.1.0-beta.8`, if the client is unavailable `list` reports a clear error and exits non-zero (matching `status`), rather than printing an empty list. + +`activate` takes a single mode flag (combining them is a usage error). The default (no flag) and `--personal` activate the signed-in user's entitlements — sign in first with `unity auth login`. `--personal` also requires `--accept-eula` to acknowledge the Unity Personal license terms. `--serial` / `--file` work offline without sign-in. `--floating` requires a configured floating license server (exit `4` if none is set). `--generate-request` writes a `.alf` request for air-gapped activation instead of activating. `return` returns the active licenses, prompting for confirmation first — pass `--yes` to skip (required in non-interactive shells and with `--json`). All honor `--json` / `--format` and exit non-zero on failure (`2` bad usage, `3` sign-in required, `4` floating not configured, `6` licensing-client error). + +`unity license server list` shows the configured floating license server (from the `licensingServiceBaseUrl` machine setting; a pure settings read, no client download). `unity license server status` contacts that server and reports reachability plus available seats — exit `4` when no server is configured, `6` when configured but unreachable. + +--- + +### Cloud — Unity Cloud organizations and projects + +Requires being signed in (`unity auth login`). + +```bash +# Show cloud sign-in state and active organization +unity cloud status --format json + +# Organizations +unity cloud org list --format json +unity cloud org current # print the active default org id +unity cloud org set-default # set active default org +unity cloud org clear-default # revert to "All Organizations" + +# Projects in the active organization +unity cloud project list --format json + +# Override the active organization for a single call +unity cloud project list --cloud-org # also via UNITY_CLOUD_ORG env var +``` + +--- + diff --git a/skills/unity-cli/references/build-run-test.md b/skills/unity-cli/references/build-run-test.md new file mode 100644 index 0000000..e13ad8a --- /dev/null +++ b/skills/unity-cli/references/build-run-test.md @@ -0,0 +1,133 @@ +# Run, test & build — unity-cli command reference + +Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +environment variables, exit codes, and common workflows. All global flags (`--format json`, +`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. + +--- + +### Run — batch/headless execution + +```bash +# Run a Unity project headless (batch mode is automatic — do NOT pass -batchmode/-quit) +unity run /path/to/MyProject -- -executeMethod Builder.Build + +# Override editor version +unity run /path/to/MyProject --editor-version 6000.0.47f1 -- -nographics -logFile out.log + +# Install editor automatically if missing +unity run /path/to/MyProject --allow-install -- -executeMethod Builder.Build + +# Kill the Unity process after 300 seconds (useful in CI to prevent hangs) +unity run /path/to/MyProject --timeout 300 -- -executeMethod Builder.Build +# Equivalent via env var: +UNITY_RUN_TIMEOUT=300 unity run /path/to/MyProject -- -executeMethod Builder.Build +``` + +`unity run` always launches the editor in batch mode and forwards the args after `--` to the Unity executable, then returns the editor's exit code. + +**Reserved flags — do NOT pass these after `--`.** The command adds them itself: `-batchmode`, `-quit`, `-projectPath`, `-useHub`, `-hubIPC`. Passing any of them fails fast (before launch) with exit code 6: + +``` +Error: Forwarded argument '-batchmode' conflicts with a reserved Unity flag managed by this command. Remove it from the args after `--`. +``` + +Flags like `-nographics`, `-logFile `, and `-executeMethod ` are not reserved and are forwarded normally. + +When `--timeout ` is set, the process receives SIGTERM at the deadline; if still alive after 2 s it receives SIGKILL. The command exits with code 6 (EXIT_COMMAND_FAILURE) on timeout. + +--- + +### Test — run EditMode/PlayMode tests + +```bash +# Run tests and write an NUnit XML report (omitting --mode runs the editor's default platform) +unity test /path/to/MyProject + +# Run a specific platform (--mode is case-insensitive: EditMode/editmode both work) +unity test /path/to/MyProject --mode EditMode +unity test /path/to/MyProject --mode PlayMode --output ./results/play.xml + +# Run only tests whose names match a filter +unity test /path/to/MyProject --filter "MyNamespace.MyTests" + +# Pin the editor version, installing it if missing; cap the run at 600 s +unity test /path/to/MyProject --editor-version 6000.0.47f1 --allow-install --timeout 600 +# Equivalent via env var: +UNITY_TEST_TIMEOUT=600 unity test /path/to/MyProject + +# Forward extra editor args after -- (reserved test flags are rejected) +unity test /path/to/MyProject -- -nographics +``` + +`unity test` launches the editor's built-in test runner in batch mode (`-runTests -testPlatform -testResults -testFilter `), waits for it to finish, and writes the report to `--output` (default `test-results.xml`). It exits 0 when the run succeeds and 6 (EXIT_COMMAND_FAILURE) when the editor exits non-zero — i.e. reports test failures or fails to run. It runs the tests **directly via the editor command line** — no pipeline package or server is involved. `--mode` is optional; when omitted, `-testPlatform` is not passed and the editor runs its default platform. + +It deliberately does **not** pass `-quit`: `-runTests` quits the editor itself once results are written, so forcing `-quit` would terminate it before the report exists. Anything after `--` is forwarded to the editor verbatim, except reserved flags managed by the command (`-projectPath`, `-batchmode`, `-runTests`, `-testPlatform`, `-testResults`, `-testFilter`, `-quit`, `-useHub`, `-hubIPC`), which are rejected. + +Options: `--mode EditMode|PlayMode`, `--filter `, `--output `, `--editor-version ` (env `UNITY_EDITOR_VERSION`), `-e, --editor-path `, `-a, --architecture `, `--allow-install`, `--timeout ` (env `UNITY_TEST_TIMEOUT`). + +--- + +### Build + +`--target` and `--execute-method` are both **required** — Unity has no built-in command-line build, so your `executeMethod` is responsible for the actual build (including honoring `--output-path`). + +```bash +# Build a project (requires --target and --execute-method) +unity build /path/to/MyProject \ + --target StandaloneOSX \ + --execute-method Builder.PerformBuild \ + --output-path ./build/output + +# Common build targets: StandaloneOSX, StandaloneWindows64, StandaloneLinux64, Android, iOS, WebGL +``` + +**Options:** + +| Flag | Description | +|---|---| +| `--target ` | Build target (required). | +| `--execute-method ` | Static C# method to invoke, e.g. `Builder.PerformBuild` (required). | +| `--build-target-group ` | Forwarded to Unity as `-buildTargetGroup`. | +| `-o, --output-path ` | Passed as `-buildOutput` (your method must honor it). | +| `-l, --log-file ` | Log file path. Default: `/Logs/build--.log`. | +| `--editor-version ` | Override editor version (default: from `ProjectVersion.txt`). | +| `-e, --editor-path ` | Use a specific editor binary. | +| `-a, --architecture ` | Editor architecture (`x86_64` or `arm64`). | +| `--args ` | Extra arguments passed to Unity (shell-split). | +| `--no-tail` | Do not stream the log to stdout in real time. | +| `--allow-install` | Install the project's editor version if missing. | +| `--versioning-strategy ` | `semantic`, `tag`, `custom`, or `none` (default: `none`). | +| `--build-version ` | Explicit version string; only used with `--versioning-strategy custom`. | +| `--allow-dirty-build` | Skip the uncommitted-changes guard (default: false). | + +**Android signing & export** (applied to Android targets only): + +| Flag | Description | +|---|---| +| `--android-export-type ` | `apk`, `aab`, or `android-studio-project`. | +| `--android-keystore-base64 ` | Keystore file, base64-encoded. | +| `--android-keystore-password ` | Keystore password. | +| `--android-key-alias ` | Key alias within the keystore. | +| `--android-key-alias-password ` | Key alias password. | +| `--android-target-sdk-version ` | Target SDK version. | +| `--android-symbol-type ` | `none`, `public`, or `debugging`. | +| `--android-version-code ` | Android version code. | + +Keystore flags are validated together. Secrets passed as command-line flags surface in the process list and can be echoed into CI logs. Supply `--android-keystore-base64`, `--android-keystore-password`, and `--android-key-alias-password` from CI secret environment variables (e.g. `--android-keystore-password "$KEYSTORE_PASSWORD"`), never as inline literals, and source those variables from a dedicated CI secret store. Note that sourcing from an env var only avoids hard-coding the literal — the expanded value still appears in `argv`, so also mask it in CI log output. + +**Versioning** — `semantic` and `tag` derive the version from git tags/history; `custom` requires an explicit `--build-version`; a dirty working tree is rejected unless `--allow-dirty-build` is passed. + +```bash +# With --format json, stdout includes newline-delimited JSON progress frames before the final envelope: +unity build /path/to/MyProject --target StandaloneOSX --execute-method Builder.Build --format json +# Output (each line is a JSON object): +# {"type":"progress","command":"build","message":"Resolving project..."} +# {"type":"progress","command":"build","message":"Resolving editor..."} +# {"type":"progress","command":"build","message":"Starting Unity..."} +# {"type":"progress","command":"build","message":"Unity exited (code 0)"} +# { "success": true, "command": "build", "data": { "target": "...", "logFile": "..." } } +``` + +--- + diff --git a/skills/unity-cli/references/config-hub.md b/skills/unity-cli/references/config-hub.md new file mode 100644 index 0000000..eafccec --- /dev/null +++ b/skills/unity-cli/references/config-hub.md @@ -0,0 +1,103 @@ +# Config & Hub — unity-cli command reference + +Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +environment variables, exit codes, and common workflows. All global flags (`--format json`, +`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. + +--- + +### Config — persisted CLI configuration + +The `config` command group manages settings that persist across invocations. + +#### config proxy + +View or change the configured HTTP/HTTPS/SOCKS/PAC proxy. The persisted value is read by every CLI command that issues outbound HTTP (releases, install, auth, telemetry, etc.). + +```bash +# Show the effective proxy configuration (resolution source + auth source) +unity config proxy +unity config proxy --json + +# Persist a proxy URL +unity config proxy http://proxy.example.com:8080 + +# Embedded userinfo (user:password@host) is supported and redacted in echo +# output, but prefer leaving credentials out of the URL — the CLI looks them +# up in the OS keyring instead (see Resolution priority below). + +# Persist with bypass list (hosts that should NOT go through the proxy) +unity config proxy http://proxy.example.com:8080 --bypass "localhost,127.0.0.1,*.internal" + +# SOCKS / PAC variants +unity config proxy socks5://proxy.example.com:1080 +unity config proxy pac+http://wpad.example.com/proxy.pac +unity config proxy pac+file:///etc/proxy.pac + +# Clear the persisted proxy +unity config proxy --unset +``` + +**Supported schemes:** `http://`, `https://`, `socks://`, `socks4://`, `socks4a://`, `socks5://`, `socks5h://`, `pac+http://`, `pac+https://`, `pac+file://`. + +**Resolution priority** (highest → lowest): +1. `--proxy ` global flag (one-shot override for the current invocation) +2. `UNITY_PROXY` env var +3. Standard env vars: `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, `NO_PROXY` +4. Persisted `proxy.json` (`unity config proxy `) +5. System proxy settings (where supported) + +Credentials missing from the URL are looked up in the OS keyring (shared with the GUI Hub); Kerberos/SPNEGO-authenticated proxies are supported. `--proxy-disable` short-circuits all of the above for the current invocation, which is the recommended way to diagnose a misconfigured proxy without clearing it. + +#### config update-check + +New in `0.1.0-beta.8`. Enable or disable the background check for a newer CLI version (the unobtrusive "update available" notice; interactive sessions only, never delays a command). Equivalent to the `UNITY_NO_UPDATE_CHECK` env var. + +```bash +unity config update-check # show the current setting +unity config update-check off # disable +unity config update-check on # enable +unity config update-check --json +``` + +--- + +### Hub — install the Unity Hub application + +Bootstrap Unity Hub on a clean machine from the command line. + +```bash +# Install the latest stable Hub for the current OS + architecture +unity hub install + +# Install a specific Hub version +unity hub install --hub-version 3.17.0 + +# Force reinstall even when Hub is already detected +unity hub install --force + +# Run the installer silently (Windows only) +unity hub install --headless + +# Override architecture (e.g. x64 Hub on Apple Silicon via Rosetta) +unity hub install --architecture x64 + +# Skip the installer code-signature check (unsigned/local builds — not recommended) +unity hub install --skip-signature-check +``` + +Options: `-f` / `--force`, `--headless` (silent installer, Windows only), `-a` / `--architecture x64|arm64` (env `UNITY_ARCHITECTURE`), `--hub-version ` (default latest), `--skip-signature-check`. + +**Integrity & signature verification** — every download is checked against the SHA-512 from the HTTPS manifest, then the installer's **code signature** is verified before it runs with elevation: on macOS via `codesign` (signer `Developer ID Application: Unity Technologies`), on Windows via Authenticode (signer subject `Unity Technologies`), checked *before* the UAC prompt. Verification is **fail-closed** — if it fails or the verifier is unavailable, the command aborts with exit 6 and does not run the installer. Linux `.AppImage` has no standard verifier, so it is SHA-512-only. Pass `--skip-signature-check` to bypass (prints a warning; not recommended). + +**`--hub-version` behaviour** — fetches the version-specific manifest from the CDN; if that version does not exist, the command exits with code 6 (no fallback to latest). + +```bash +# JSON output +unity hub install --format json +``` + +Emits `{ "success": true, "command": "hub install", "data": { "version": "3.x.x", "installed": true } }` on success, or an `{ "alreadyInstalled": true, "installedPath": "…" }` payload when Hub was already present. + +--- + diff --git a/skills/unity-cli/references/diagnostics-maintenance.md b/skills/unity-cli/references/diagnostics-maintenance.md new file mode 100644 index 0000000..5e73e9e --- /dev/null +++ b/skills/unity-cli/references/diagnostics-maintenance.md @@ -0,0 +1,194 @@ +# Diagnostics & maintenance — unity-cli command reference + +Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +environment variables, exit codes, and common workflows. All global flags (`--format json`, +`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. + +--- + +### Logs — application logs + +```bash +# Show last 20 log lines (default) +unity logs + +# Show last 50 lines +unity logs --tail 50 + +# Follow in real-time (like tail -f) +unity logs --follow + +# Filter by level +unity logs --level error +unity logs --level warn + +# Available levels: trace, debug, info, warn, error, fatal +``` + +The CLI writes its own `cli-log.json` (separate from the Hub's `info-log.json`) and records its version on every start. `unity logs`, `unity bug`, and `unity doctor` read the CLI's own log. + +--- + +### Doctor — system diagnostics + +```bash +# Full system report +unity doctor --format json + +# Includes: platform info, auth status, installed editors, recent log lines, resolved proxy +unity doctor --tail 50 +``` + +`unity doctor` reports real session state (matching `unity auth status`) and surfaces the resolved proxy URL, its source, and auth source. + +--- + +### Environment + +```bash +# Show environment paths +unity env --format json + +# Returns: user data path, editor install path, download cache path, config path, CLI version, resolved proxy +``` + +--- + +### Cache + +```bash +# Show cache location and size +unity cache info --format json + +# Clear download cache +unity cache clean --yes +``` + +--- + +### Analytics — usage/telemetry consent + +The CLI defaults to **opt-out**. On the first interactive run a y/N prompt is shown once before any data is collected; non-interactive, CI, piped, and `--quiet` contexts silently keep the opt-out default. + +```bash +# Show current consent status +unity analytics status +unity analytics status --format json + +# Opt in to anonymous usage data collection +unity analytics opt-in + +# Opt out (the default) +unity analytics opt-out +``` + +Consent is stored in the shared Hub privacy preferences, so opting out in the CLI also opts out in Hub, and vice versa. + +--- + +### Changelog + +Show the embedded release notes for the currently installed CLI version: + +```bash +unity changelog +unity changelog --format json +``` + +--- + +### Language + +```bash +# Show current language and available options +unity language + +# Set language by code +unity language --set en +unity language --set ja +unity language --set zh-hans + +# Alias +unity lang --set ko +``` + +On a TTY with no flags, shows an interactive selection prompt. + +--- + +### Completion — shell tab completion + +Generate and install shell completion scripts: + +```bash +# Supported shells: bash, zsh, fish, powershell +unity completion bash +unity completion zsh +unity completion fish +unity completion powershell +``` + +--- + +### Bug — report a bug + +Interactive bug reporter that collects system info and recent logs, then submits to Unity: + +```bash +unity bug +``` + +Prompts for title, description, email, and reproducibility level. As of beta.8 it collects the same diagnostic system information as the Unity Hub bug reporter (including GPU details). + +--- + +### Upgrade — update the CLI itself + +```bash +# Check for available updates +unity upgrade --check --format json + +# Show changelog for the new version +unity upgrade --changelog + +# Upgrade (interactive confirmation) +unity upgrade + +# Upgrade without prompts +unity upgrade --yes + +# Install a specific version +unity upgrade --target 0.2.0 + +# Select update channel (stable or beta) +unity upgrade --channel beta + +# Dry-run: show what would change +unity upgrade --dry-run + +# Rollback to previous version +unity upgrade --rollback +``` + +--- + +### Self-uninstall — remove the CLI + +```bash +# Uninstall the CLI (interactive confirmation) +unity self-uninstall + +# Uninstall without prompts +unity self-uninstall --yes + +# Also remove config and data files +unity self-uninstall --purge --yes + +# Dry-run: show what would be removed +unity self-uninstall --dry-run +``` + +> **`unity implode` was removed** in `0.1.0-beta.8` (it was previously a deprecated alias). Use `unity self-uninstall`. + +--- + diff --git a/skills/unity-cli/references/editors-install.md b/skills/unity-cli/references/editors-install.md new file mode 100644 index 0000000..5c16ab6 --- /dev/null +++ b/skills/unity-cli/references/editors-install.md @@ -0,0 +1,241 @@ +# Editors, install & modules — unity-cli command reference + +Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +environment variables, exit codes, and common workflows. All global flags (`--format json`, +`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. + +--- + +### Editors — list, install, uninstall + +```bash +# List all editors (installed + available releases) +# Short alias: unity e. The bare `unity editors` is shorthand for the explicit `unity editors list` (matches projects/templates/modules) +unity editors list --format json + +# List only installed editors +# As of beta.8 the --installed table includes an "Upgrade to" column flagging editors with a newer patch in their line +unity editors --installed --format json + +# List only available releases +unity editors --releases --format json + +# Filter by architecture +unity editors --installed --architecture arm64 --format json + +# Show detailed module info +unity editors --verbose + +# Watch mode — live-updates as editors are installed or removed +unity editors --watch +unity editors --installed --watch +``` + +`unity editors` honors `--format tsv` and `--format ndjson` for its default listing. Identifier columns keep their natural width even if the table exceeds the terminal — they are no longer silently truncated. + +#### editors add + +Register one or more existing editor installations by path: + +```bash +unity editors add /path/to/Unity/Editor + +# Register multiple at once +unity editors add /path/one /path/two + +# Skip macOS code-signature check (useful for unsigned or side-loaded builds) +unity editors add /path/to/Unity/Editor --skip-signature-check +``` + +#### editors default + +```bash +# Show current default editor +unity editors default --format json + +# Set default by version, alias, or keyword +unity editors default 6000.0.47f1 +unity editors default latest +unity editors default lts + +# Clear the default +unity editors default --unset +``` + +On a TTY with no arguments, shows an interactive selection prompt. + +#### editors path + +```bash +# Print the install directory of an installed editor (local, offline — no release-feed fetch) +unity editors path 6000.0.47f1 +unity editors path 6000.0.47f1 --architecture arm64 --json +``` + +Honors `--architecture` and `--format` / `--json`, and reports ambiguous matches so you can narrow by version or architecture. + +#### editors install-path + +```bash +# Show the directory where editors are installed +unity editors install-path + +# Set a new install path +unity editors install-path --set /path/to/editors +``` + +Also available as the top-level `unity install-path` (with an additional `--get` flag). Distinct from `editors path`: `install-path` gets/sets the *root* install directory; `editors path` prints the install directory of *one* editor version. + +#### editors info + +```bash +# Show release details for a specific version +unity editors info 6000.0.47f1 --format json +``` + +#### editors upgrade + +New in `0.1.0-beta.8`. Upgrade an installed editor to the newest official (f-channel) patch in the same `major.minor` line (e.g. `2022.3.10f1` → `2022.3.62f1`), carrying the installed modules over. The `[editor]` argument accepts an exact version, a `major.minor` line, or the `latest` / `lts` / `default` aliases. Editors install side by side — the old version is kept unless `--replace` (alias `--remove-old`) is passed. + +```bash +# Upgrade a specific editor (or the default / lts / latest) to the newest patch in its line +unity editors upgrade 2022.3.10f1 +unity editors upgrade lts + +# Upgrade every installed editor that has a newer patch +unity editors upgrade --all --yes --accept-eula + +# Report current → target without installing (--check is an alias for --dry-run) +unity editors upgrade --all --dry-run --format json + +# Remove the old editor after a successful upgrade; skip carrying modules; add extra modules +unity editors upgrade 2022.3.10f1 --replace --yes +unity editors upgrade 2022.3.10f1 --no-modules +unity editors upgrade 2022.3.10f1 --module android --module ios +``` + +#### editors module / editor module + +Module management is exposed under **both** `editors module` and the `editor` (singular) command group. Both share the same subcommands: + +```bash +# List modules for an installed editor +unity editors module list 6000.0.47f1 --format json +unity editor module list 6000.0.47f1 --architecture arm64 --format json + +# Add modules to an installed editor +unity editors module add 6000.0.47f1 --module android --module ios +unity editors module add 6000.0.47f1 --all # Install every available module +unity editors module add 6000.0.47f1 --module android --child-modules # Include child modules +unity editors module add 6000.0.47f1 --module android --accept-eula # Accept EULAs automatically + +# Refresh module list for a manually located editor +unity editors module refresh 6000.0.47f1 +``` + +#### editor add (single path, with module-fetch control) + +The `editor add` subcommand is similar to `editors add` but targets a single path and supports skipping the module-fetch step: + +```bash +unity editor add /path/to/Unity/Editor + +# Skip fetching module metadata (faster, but modules won't be listed until refreshed) +unity editor add /path/to/Unity/Editor --no-fetch-modules +``` + +--- + +### Install + +```bash +# Install an editor (interactive version selection if omitted) +unity install 6000.0.47f1 + +# Install with specific modules +unity install 6000.0.47f1 --module windows-mono --module android + +# Install a specific changeset by hash +unity install 6000.0.47f1 --changeset abc123def456 + +# Include child modules +unity install 6000.0.47f1 --cm + +# Exclude child modules +unity install 6000.0.47f1 --no-cm + +# Install and accept EULAs automatically (CI) +unity install 6000.0.47f1 --yes --accept-eula + +# Force reinstall even if already present +unity install 6000.0.47f1 --force + +# Resume an interrupted download (also recovers orphaned partials left by a crash or kill) +unity install 6000.0.47f1 --resume + +# Dry-run: show what would be installed without doing it +unity install 6000.0.47f1 --dry-run --format json + +# Space-separated module values after a single -m are equivalent to repeating -m +unity install 6000.0.47f1 -m android ios # space-separated +unity install 6000.0.47f1 -m android -m ios # repeated flag (same effect) +``` + +**NDJSON progress frames** for `unity install` and `unity install-modules` include a `phase: 'download' | 'install'` field so scripts can switch to an indeterminate spinner during the install phase (which is genuinely indeterminate — NSIS on Windows only reports success/failure). During the install phase, `pct` is locked at 50 and only jumps to 100 on completion. Module download/install progress is nested under the parent editor via `parentItemUid`, so consumers see one editor group with its modules rather than one group per module. + +Module installers honor the per-module install command from the release manifest (e.g. Visual Studio on Windows uses `--passive`, not `/S`); the resolved command is surfaced in `unity modules list --json`. `unity install` self-heals a corrupted partial download by discarding the bad partial and re-downloading; a cross-process install lock prevents two concurrent installs of the same version from corrupting the unpack. + +### Uninstall + +```bash +# Uninstall an editor version +unity uninstall 6000.0.47f1 --yes + +# Uninstall a specific architecture +unity uninstall 6000.0.47f1 --architecture arm64 --yes +``` + +--- + +### Modules — add/list per editor + +```bash +# List modules for an installed editor +unity modules list 6000.0.47f1 --format json + +# Filter by architecture +unity modules list 6000.0.47f1 --architecture arm64 --format json +``` + +`unity modules list` honors `--format ndjson` (empty results emit a clean, empty NDJSON stream). + +### install-modules + +```bash +# List available modules without installing +unity install-modules --editor-version 6000.0.47f1 --list + +# Install specific modules +unity install-modules --editor-version 6000.0.47f1 --module android --module ios + +# Install all available modules +unity install-modules --editor-version 6000.0.47f1 --all --yes + +# Include child modules (default behaviour) +unity install-modules --editor-version 6000.0.47f1 --module android --cm + +# Exclude child modules +unity install-modules --editor-version 6000.0.47f1 --module android --no-cm + +# Accept EULAs and dry-run +unity install-modules --editor-version 6000.0.47f1 --all --accept-eula --dry-run +``` + +`--list` and `--all` are mutually exclusive. `--list` is also mutually exclusive with `--module`. + +`--module android ios` (space-separated values after a single `--module`) and `--module android --module ios` (repeated flag) are equivalent — both install all listed modules. + +Module discovery works for editors registered via `unity editors add ` (located editors), not just editors installed by the Hub. + +--- + diff --git a/skills/unity-cli/references/integration-advanced.md b/skills/unity-cli/references/integration-advanced.md new file mode 100644 index 0000000..69a613e --- /dev/null +++ b/skills/unity-cli/references/integration-advanced.md @@ -0,0 +1,137 @@ +# Integration & advanced — unity-cli command reference + +Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +environment variables, exit codes, and common workflows. All global flags (`--format json`, +`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. + +--- + +### MCP — Model Context Protocol server (AI agent integration) + +New in `0.1.0-beta.8`. `unity mcp` starts a Model Context Protocol server, built into the `unity` binary, that exposes the commands of a connected Unity Editor as MCP tools. AI agent clients connect over stdio, list those tools, and run them. The server starts even when no Editor is running and reports that it isn't connected; commands that a connected Editor adds show up as tools automatically. + +```bash +# Start the MCP stdio server (usually launched by the AI client, not by hand) +unity mcp + +# Pin the server to a specific Unity project / Editor instance +unity mcp --project-path /path/to/MyProject +unity mcp --instance localhost:55000 +``` + +#### mcp configure — register the server in an AI client + +Writes the Unity MCP server entry into an AI client's config in one step, preserving every other key in the file. 16 clients are supported: `claude`, `claude-code`, `cursor`, `vscode`, `vscode-insiders`, `copilot-cli`, `windsurf`, `cline`, `codex`, `kiro`, `trae`, `openclaw`, `antigravity`, `zed`, `continue`, `inspect`. + +```bash +# List all supported clients and their config paths +unity mcp configure --list + +# Configure a client +unity mcp configure claude +unity mcp configure claude-code + +# Project-local config for clients that support it (e.g. cursor, windsurf) +unity mcp configure cursor --local + +# Pin to a project; skip the "already exists, update?" prompt; preview without writing +unity mcp configure claude --project-path /path/to/MyProject +unity mcp configure vscode --yes +unity mcp configure vscode --dry-run +``` + +--- + +### Connected Editors — pipeline / command / status + +> **Promoted to production in `0.1.0-beta.8`.** In earlier betas these were development-only (and the Pipeline package was Unity-internal). They now talk to any running Unity Editor over its Pipeline server, and the supporting Editor-side package (`com.unity.pipeline`) is resolved from the **Unity (UPM) registry** and added to the project's `Packages/manifest.json` — no internal access or manual setup required. The Editor defines each command's parameters, help, and error messages, so the commands a connected Editor exposes are usable without a CLI update. + +#### pipeline (alias: pipe) — manage the Unity Pipeline package + +```bash +# List the Editors the CLI can reach and the Pipeline package status of each +unity pipeline list --format json + +# Install / update the Pipeline package into a project (auto-detects project if omitted) +unity pipeline install +unity pipeline install --project-path /path/to/MyProject +unity pipeline install --force # re-resolve to the latest version even if present +``` + +`pipeline install` options: `--project-path `, `--force`. The package is resolved from the Unity registry and written to `Packages/manifest.json`. + +#### command (aliases: cmd, request) — send commands to a running Unity Editor + +Forwards a command to a connected Editor. Run it with no arguments to list the commands the connected Editor exposes. + +```bash +# List all commands available on the connected Unity Editor +unity command +unity command --format json + +# Execute a specific command (names/params come from the Editor) +unity command editor_play +unity command log_editor "Hello from CLI" +unity command editor_status --includeMemory true + +# Capture a Scene/Game view screenshot (forwarded to the Editor's screenshot command, new in beta.8) +unity command screenshot --output ./shot.png --width 1920 --height 1080 + +# Target a specific project / instance / Player runtime +unity command editor_play --project-path /path/to/MyProject +unity command editor_play --instance localhost:8765 +unity command --runtime "MyGame" +unity command --runtime-path /path/to/port-file + +# Set a timeout (default: 30 seconds) +unity command editor_play --timeout 60 +``` + +If no editor with a reachable Pipeline server is found, the command errors with guidance (make sure the editor is running and its Pipeline server is up). + +#### status — live state of connected editors + +```bash +# Show port, state, project, version, PID for every connected Unity Editor +unity status --format json + +# Filter to one instance +unity status --port 8765 +unity status --project megacity +``` + +Reads the lockfile the Pipeline package writes per running Editor (faster and more CI-friendly than `pipeline list`). Stale-heartbeat instances are reported as `unreachable` without an HTTP probe. With `--format json`/`ndjson`, emits a `success: false` envelope (`STATUS_NO_INSTANCES` / `STATUS_ALL_UNREACHABLE`) and a non-zero exit when no Editor is reachable, so CI scripts can gate on Editor availability. + +--- + +## Development-only commands (hidden in production builds) + +The commands below are **absent from the published production CLI** — they only register when `HUB_ENV=development`, so they won't appear in `unity --help` for a normal install. Documented here for completeness; if you don't see them, they're not available in your build. + +### eval — evaluate a C# expression in a running editor + +Requires a connected Editor with the Pipeline package (see *Connected Editors* above). + +```bash +unity eval 'Application.version' +unity eval '1 + 2' +unity eval 'Application.version' --json +unity eval 'Time.realtimeSinceStartup' --timeout 10 # server-side timeout (default: 5s) + +# Bare expressions are auto-wrapped as 'return ;'. Include a ';' to run a statement body: +unity eval 'Debug.Log("hello");' +unity eval 'var s = Application.dataPath; return s.Length;' +``` + +Compile failures surface the Roslyn diagnostics and exit non-zero. Targeting options match `command`: `--project-path`, `--instance `, `--runtime `, `--runtime-path `. + +### cloud-pipeline — Unity Cloud Pipeline + +Manage Unity Cloud Pipeline resources. Subcommand groups: `status`, `onboard`, `assets` (`list`/`status`/`url`), `branches` (`list`/`show`/`create`/`url`/`enable`/`edit`/`disable`), `pending-changes list`, `files` (`create`/`update`/`delete`/`move`), `pull-request create`. Use `unity cloud-pipeline --help` (development build) for the full flag set. + +### collab — Unity collaboration (annotations & attachments) + +Manage review annotations and attachments. Subcommand groups: `annotations` (`count`/`create`/`delete`/`get`/`update`/`replies`/`resolve`/`status`/`unresolve`) and `attachments` (`list`/`delete`/`update`). Use `unity collab --help` (development build) for the full flag set. + +--- + diff --git a/skills/unity-cli/references/projects-templates.md b/skills/unity-cli/references/projects-templates.md new file mode 100644 index 0000000..ac6c500 --- /dev/null +++ b/skills/unity-cli/references/projects-templates.md @@ -0,0 +1,342 @@ +# Projects, releases & templates — unity-cli command reference + +Part of the **`unity-cli`** skill. See that skill's `SKILL.md` for CLI install, global flags, +environment variables, exit codes, and common workflows. All global flags (`--format json`, +`--non-interactive`, `--yes`, `--proxy`, …) apply to every command below. + +--- + +### Projects — list, open, create, register, clone, link + +```bash +# List registered projects +unity projects list --format json + +# Register an existing project +unity projects add /path/to/MyProject + +# Remove from registry (does not delete files) +unity projects remove /path/to/MyProject + +# Show project details +unity projects info /path/to/MyProject --format json + +# Open a project in the editor +unity open /path/to/MyProject + +# Open with a specific editor version +unity open /path/to/MyProject --editor-version 6000.0.47f1 + +# Pass extra Unity arguments +unity open /path/to/MyProject --args "-logFile output.log" + +# Pass a build target (forwarded to Unity as -buildTarget / -buildTargetGroup) +unity open /path/to/MyProject --build-target StandaloneOSX +unity open /path/to/MyProject --build-target-group Standalone + +# Version shorthand (equivalent to open with --editor-version) +unity 6000.0.47f1 /path/to/MyProject +``` + +The project argument is matched against the Hub registry first (exact name or path opens immediately; a glob like `"My Game*"` prompts when multiple match); with no registry match it falls back to treating the argument as a filesystem path. `unity open` forwards `--args` to the Editor correctly on all platforms (including Windows). + +#### projects create + +Create a project. On a TTY, prompts for any missing options (parent directory, editor version, template). In CI, pass `--non-interactive` or pipe stdin to suppress prompts and rely on stored defaults. The first positional argument is the project **name**; `--path` sets the parent directory: + +```bash +unity projects create MyGame --editor-version 6000.0.47f1 --template com.unity.template.3d + +# Place the project in a specific directory +unity projects create MyGame --path /path/to/projects --editor-version 6000.0.47f1 + +# --template also accepts a .tgz file path or a directory, not just a registered template id +unity projects create MyGame --template /path/to/template.tgz +``` + +**Cloud linking during creation:** + +```bash +# Create and link a NEW Unity Cloud project as part of creation +unity projects create MyGame --cloud --cloud-org + +# Link an EXISTING cloud project instead +unity projects create MyGame --cloud-project +``` + +**Source-control during creation** — publish the new project to a fresh repository: + +```bash +unity projects create MyGame \ + --vcs github \ + --git-namespace my-org \ + --git-repo my-game \ + --git-visibility private \ + --git-default-branch main \ + --git-token-stdin +``` + +Source-control flags (shared with `projects link vcs`): `--vcs github|gitlab|uvcs`, `--git-namespace `, `--git-repo `, `--git-visibility private|public|internal` (default private), `--git-default-branch `, `--git-token ` / `--git-token-stdin`, `--no-initial-commit`, `--git-lfs`, and `--vcs-region ` for Unity Version Control. + +**Flag names differ by subcommand:** `projects create` and `projects link vcs` use `--git-namespace` / `--git-repo`, while `projects clone` (below) uses `--vcs-namespace` / `--vcs-repo`. Copy the names for the exact command you're running, and confirm with `--help` if unsure. + +#### projects new + +Create a project without any interactive prompts — resolves missing options from stored defaults, never asks the user. The first positional argument is the project **name**; `--path` sets the parent directory: + +```bash +# All omitted options resolve from stored defaults +unity projects new MyGame + +# Override stored defaults with explicit values +unity projects new MyGame --path /path/to/projects --editor-version 6000.0.47f1 --template com.unity.template.3d + +# Open the project immediately after creation +unity projects new MyGame --open +``` + +#### projects clone + +Clone a remote repository and register the Unity project it contains. Works across providers: + +```bash +# Clone by full repo URL / shorthand +unity projects clone --vcs github --vcs-namespace my-org --vcs-repo my-game --path ./MyGame + +# Check out a specific ref (branch, sha, or UVCS changeset) +unity projects clone --vcs uvcs --vcs-namespace my-org --vcs-repo my-game --ref main + +# Authenticate with a personal access token (prefer stdin) +unity projects clone --vcs gitlab --vcs-namespace my-org --vcs-repo my-game --git-token-stdin + +# Project lives in a subdirectory of the repo +unity projects clone --vcs github --vcs-namespace my-org --vcs-repo monorepo \ + --path ./repo --project-path packages/MyGame +``` + +Options: `--vcs github|gitlab|uvcs`, `--vcs-namespace `, `--vcs-repo `, `--ref ` (an all-digit ref is treated as a Unity Version Control changeset, anything else as a branch), `--path ` (clone destination), `--project-path ` (project subdirectory), `--git-token ` / `--git-token-stdin`, `--json`. Git LFS assets are fetched as pointer files only. + +#### projects pin / unpin + +```bash +# Pin a project to the top of the list +unity projects pin /path/to/MyProject + +# Unpin +unity projects unpin /path/to/MyProject +``` + +#### projects require + +Ensure the editor version required by a project is installed, installing it if needed: + +```bash +unity projects require /path/to/MyProject --yes +``` + +On a TTY with no path, prompts interactively. + +#### projects upgrade + +Upgrade a project to a different Unity editor version. `--to` is required: + +```bash +unity projects upgrade --to 6000.0.47f1 +unity projects upgrade /path/to/MyProject --to 6000.0.47f1 --yes +``` + +#### projects export / import + +```bash +# Export the project registry to a file (or stdout if -o is omitted) +unity projects export -o projects.json + +# Import a previously exported registry +unity projects import projects.json +unity projects import --input projects.json +``` + +#### projects open / link / unlink + +```bash +# Open a registered project by name, fuzzy title match, or path +unity projects open MyProject +# (the top-level `unity open` is the same thing) + +# --- Cloud links --- +# Connect an existing local project to a Unity Cloud project +unity projects link cloud /path/to/MyProject --cloud-org +# Disconnect from its Unity Cloud project +unity projects unlink cloud /path/to/MyProject + +# --- Version-control links --- +# Publish a local project to a NEW GitHub / GitLab / Unity Version Control repository +unity projects link vcs /path/to/MyProject \ + --vcs github --git-namespace my-org --git-repo my-game --git-token-stdin +# Remove a project's git remotes (the remote repositories are NOT deleted) +unity projects unlink vcs /path/to/MyProject +# Also detach the Unity Version Control workspace +unity projects unlink vcs /path/to/MyProject --unlink-workspace +``` + +`link vcs` shares the source-control flag set documented under `projects create`. `link cloud` / `link vcs` accept `--cloud-org ` (env `UNITY_CLOUD_ORG`). + +--- + +### Releases — browse Unity versions + +```bash +# List recent releases +unity releases --format json + +# Filter by stream (alpha, beta, lts, tech) +unity releases --stream lts --format json +unity releases --stream tech --format json +unity releases --stream beta --format json + +# LTS only shorthand +unity releases --lts --format json + +# Filter from a year onward +unity releases --since 2023 --format json + +# Paginate +unity releases --limit 10 --skip 20 --format json +``` + +--- + +### Templates + +```bash +# List templates for an editor version (uses default editor if --editor is omitted) +unity templates list --editor 6000.0.47f1 --format json + +# List only locally installed templates +unity templates list --editor 6000.0.47f1 --installed --format json + +# Filter by type (core, learning, sample, custom, new, all) — case-insensitive +unity templates list --editor 6000.0.47f1 --type core --format json +unity templates list --editor 6000.0.47f1 --type learning --format json +unity templates list --editor 6000.0.47f1 --type sample --format json +unity templates list --editor 6000.0.47f1 --type new --format json +unity templates list --editor 6000.0.47f1 --type all --format json # no-op, returns everything + +# List only user-generated (custom) templates +unity templates list --editor 6000.0.47f1 --custom --format json +# --type custom is an alias for --custom +unity templates list --editor 6000.0.47f1 --type custom --format json + +# --custom and --type are mutually exclusive — using both is an error (exit 1) + +# Show template details +unity templates info com.unity.template.3d --editor 6000.0.47f1 --format json + +# Create a custom template from an existing Unity project +# --name and --display-name are REQUIRED +unity templates create /path/to/MyProject \ + --name com.myorg.template.mytemplate \ + --display-name "My Template" + +# With all optional options +unity templates create /path/to/MyProject \ + --name com.myorg.template.mytemplate \ + --display-name "My Template" \ + --description "A starting point for our projects" \ + --template-version 1.0.0 \ + --output /path/to/templates/dir \ + --keep-embedded-packages \ + --keep-project-settings \ + --overwrite + +# JSON output (includes path to created .tgz archive) +unity templates create /path/to/MyProject \ + --name com.myorg.template.mytemplate \ + --display-name "My Template" \ + --json + +# NDJSON streaming — emits progress frames then a result frame +unity templates create /path/to/MyProject \ + --name com.myorg.template.mytemplate \ + --display-name "My Template" \ + --format ndjson +``` + +**`templates create` key notes:** +- `--name` must be a valid npm package name (e.g. `com.myorg.template.mytemplate`) +- `--output` overrides the Hub-configured user templates directory +- `--overwrite` replaces an existing archive of the same name without error +- On success, prints the path to the created `.tgz` archive +- Created templates appear in `unity templates list --editor --custom` + +```bash +# Delete a user-generated custom template (prompts for confirmation) +unity templates delete com.myorg.template.mytemplate --editor 6000.0.47f1 + +# Skip the confirmation prompt (CI-friendly) +unity templates delete com.myorg.template.mytemplate --editor 6000.0.47f1 --yes + +# JSON output +unity templates delete com.myorg.template.mytemplate --editor 6000.0.47f1 --yes --json +``` + +**`templates delete` key notes:** +- Only user-generated templates (created via Hub UI or `templates create`) can be deleted +- Attempting to delete a built-in Unity template exits with a descriptive error (exit 6) +- Attempting to delete a template that doesn't exist exits with a descriptive error (exit 6) +- In interactive mode, prompts for confirmation before deleting; use `--yes` to skip +- On success, the template no longer appears in `unity templates list --editor --custom` + +```bash +# Get/set/reset the default storage path for custom templates +# Print current configured templates location +unity templates location + +# Set a new default templates directory (must exist as a directory) +unity templates location --set /path/to/templates + +# Reset templates location to the Hub default +unity templates location --reset + +# JSON output for any variant +unity templates location --json +unity templates location --set /path/to/templates --json +unity templates location --reset --json +``` + +**`templates location` key notes:** +- `--set` and `--reset` are mutually exclusive (using both is an error) +- `--set` validates that the path exists and is a directory (exits 2 if not) +- `--reset` restores the Hub default templates path +- JSON output: `{ "path": "..." }` inside the standard envelope + +```bash +# Edit a user-generated (custom) template's metadata +# At least one of --display-name, --description, --template-version, +# --preview-image, --remove-preview-image is required +unity templates edit com.myorg.template.mytemplate --editor 6000.0.47f1 --display-name "My Updated Template" + +# Update multiple fields at once +unity templates edit com.myorg.template.mytemplate \ + --editor 6000.0.47f1 \ + --display-name "My Updated Template" \ + --description "A new description for the template" \ + --template-version 1.1.0 + +# Replace / remove preview image +unity templates edit com.myorg.template.mytemplate --editor 6000.0.47f1 --preview-image /path/to/image.png +unity templates edit com.myorg.template.mytemplate --editor 6000.0.47f1 --remove-preview-image + +# JSON / NDJSON output (--yes required because these are non-interactive) +unity templates edit com.myorg.template.mytemplate --editor 6000.0.47f1 --display-name "Updated" --yes --json +``` + +**`templates edit` key notes:** +- Only works on user-generated (custom) templates; built-in templates cannot be edited +- Use `--editor` to specify which editor version's template list to search, or omit to use the stored default +- `--preview-image ` resolves to an absolute path before passing to the service +- `--remove-preview-image` is only applied when no valid `--preview-image` path is given; if both are passed with a valid image path, the new image wins and `--remove-preview-image` is ignored +- On success (human format), prints the updated template's display name + +--- + diff --git a/skills/unity-package-management/SKILL.md b/skills/unity-package-management/SKILL.md new file mode 100644 index 0000000..268ed5c --- /dev/null +++ b/skills/unity-package-management/SKILL.md @@ -0,0 +1,304 @@ +--- +name: unity-package-management +description: Use when adding, removing, upgrading, or discovering Unity (UPM) packages programmatically from outside the Editor — headless or CI package installs via the C# UnityEditor.PackageManager.Client API, verifying package ids/versions against the Unity registry, or choosing which packages a game needs by genre, platform, and monetization. The Unity CLI does not manage UPM packages, so this skill covers that gap. Triggers on "install a Unity package", "add com.unity.*", "set up packages headless/CI", "which packages for a game". +allowed-tools: + - Bash + - Read + - Write + - Edit +--- + +# Unity Package Management (headless, via the C# Client API) + +Add, remove, upgrade, and discover UPM (Unity Package Manager) packages programmatically with +`UnityEditor.PackageManager.Client`, driven headless from the terminal or CI. Do **not** +hand-edit `Packages/manifest.json` — the Client API resolves dependencies and compatible +versions correctly, whereas manual edits routinely break resolution. + +This complements the **`unity-cli`** skill (editor install, project creation, build/test): the +CLI has **no** package-management command, so all package work goes through the Editor's C# API. + +## When to use + +- Add / remove / upgrade one or more packages in an existing or freshly-created project. +- Set up a project's packages non-interactively in CI. +- Verify a package id exists, or find its available versions, before depending on it. +- Decide which packages a game actually needs — see + [references/select-packages.md](references/select-packages.md). + +## Choosing what to install + +Install what the project actually needs, not everything; prefer packages the chosen template +already provides (URP templates already include the render pipeline, Input System, etc.). The +genre / look / platform / monetization → package mapping, plus how to search the registry, is +in [references/select-packages.md](references/select-packages.md). Produce a **deduplicated +list of package ids** and read it back to the user before installing. + +## The `-quit` problem — why NOT `unity run` for installs + +`Client.Add` / `Client.AddAndRemove` are **asynchronous**: they return a `Request` that only +completes on later `EditorApplication.update` ticks (the UPM child process marshals its result +back on the Editor's main-loop pump, so a blocking `while (!req.IsCompleted)` busy-wait +deadlocks it). The Editor must **stay alive** after `-executeMethod` returns, until the request +finishes. + +`unity run` **cannot** be used for the installer: it always injects `-quit` (see the reserved +flags in the **`unity-cli`** skill). With `-quit`, the Editor quits the instant the method +returns — before UPM resolves — so packages never install and the callback never runs. + +**Solution:** launch the **Editor binary directly** in `-batchmode` **without** `-quit`. The +Editor stays alive, `EditorApplication.update` keeps ticking, the poll callback runs, and it +calls `EditorApplication.Exit(code)` itself when done — which both quits and sets the process +exit code. + +## The installer script + +Write this to `Assets/Editor/ProjectBootstrap/PackageInstaller.cs`. It must live under an +`Editor/` folder (or an Editor-only assembly) because it uses `UnityEditor`. + +```csharp +using System.Linq; +using UnityEditor; +using UnityEditor.PackageManager; +using UnityEditor.PackageManager.Requests; +using UnityEngine; + +namespace ProjectBootstrap +{ + // Installs (and optionally removes) a fixed set of packages via the PackageManager + // Client API, headless-safe. + public static class PackageInstaller + { + // EDIT this list to match the package selection (see references/select-packages.md). + static readonly string[] PackagesToAdd = + { + "com.unity.inputsystem", + "com.unity.cinemachine", + "com.unity.render-pipelines.universal", + // "com.unity.package@1.2.3" // pin a version with @ when a minimum is required + }; + + // Optionally drop packages in the same resolution pass (e.g. a template default you don't want). + static readonly string[] PackagesToRemove = { }; + + const double TimeoutSeconds = 600; // UPM resolution + downloads can be slow + + static AddAndRemoveRequest _request; + static double _deadline; + + // Invoke with: -executeMethod ProjectBootstrap.PackageInstaller.Install (NO -quit) + public static void Install() + { + if (PackagesToAdd.Length == 0 && PackagesToRemove.Length == 0) + { + Debug.Log("[PackageInstaller] Nothing to do."); + EditorApplication.Exit(0); + return; + } + + Debug.Log($"[PackageInstaller] Adding: {string.Join(", ", PackagesToAdd)}"); + _request = Client.AddAndRemove(packagesToAdd: PackagesToAdd, packagesToRemove: PackagesToRemove); + _deadline = EditorApplication.timeSinceStartup + TimeoutSeconds; + EditorApplication.update += Poll; + } + + static void Poll() + { + if (_request == null) return; + + if (!_request.IsCompleted) + { + if (EditorApplication.timeSinceStartup > _deadline) + { + EditorApplication.update -= Poll; + Debug.LogError("[PackageInstaller] Timed out waiting for UPM."); + EditorApplication.Exit(2); + } + return; + } + + EditorApplication.update -= Poll; + + if (_request.Status == StatusCode.Success) + { + var names = _request.Result.Select(p => $"{p.name}@{p.version}"); + Debug.Log($"[PackageInstaller] Resolved: {string.Join(", ", names)}"); + EditorApplication.Exit(0); + } + else + { + Debug.LogError($"[PackageInstaller] Failed: {_request.Error?.message}"); + EditorApplication.Exit(1); + } + } + } +} +``` + +`AddAndRemove` installs the whole set in a single UPM resolution pass — faster and less +error-prone than one `Client.Add` per package. + +**Add / remove / upgrade with one script:** +- **Add**: list the id in `PackagesToAdd`. +- **Remove**: list the id in `PackagesToRemove`. +- **Upgrade / pin**: add the id with `@` (e.g. `com.unity.cinemachine@2.9.7`). Without + a version, resolution picks the latest compatible release. + +## Discovering / verifying packages + +To confirm an id exists or list its versions before adding it, search the registry. The +in-Editor `Client.SearchAll()` / `Client.Search("")` calls are also async, so they use the +**same poll-and-`Exit` pattern and the same headless run** as the installer. Write +`Assets/Editor/ProjectBootstrap/PackageSearch.cs`: + +```csharp +using System.Linq; +using UnityEditor; +using UnityEditor.PackageManager; +using UnityEditor.PackageManager.Requests; +using UnityEngine; + +namespace ProjectBootstrap +{ + public static class PackageSearch + { + const double TimeoutSeconds = 120; + static SearchRequest _request; + static double _deadline; + + // Invoke with: -executeMethod ProjectBootstrap.PackageSearch.SearchAll (NO -quit) + public static void SearchAll() + { + _request = Client.SearchAll(); // or Client.Search("com.unity.cinemachine") + _deadline = EditorApplication.timeSinceStartup + TimeoutSeconds; + EditorApplication.update += Poll; + } + + static void Poll() + { + if (_request == null) return; + if (!_request.IsCompleted) + { + if (EditorApplication.timeSinceStartup > _deadline) + { + EditorApplication.update -= Poll; + Debug.LogError("[PackageSearch] Timed out."); + EditorApplication.Exit(2); + } + return; + } + EditorApplication.update -= Poll; + + if (_request.Status == StatusCode.Success) + { + foreach (var p in _request.Result.OrderBy(p => p.name)) + Debug.Log($"[PackageSearch] {p.name}@{p.versions.latestCompatible} {p.displayName}"); + Debug.Log($"[PackageSearch] {_request.Result.Length} packages found."); + EditorApplication.Exit(0); + } + else + { + Debug.LogError($"[PackageSearch] Failed: {_request.Error?.message}"); + EditorApplication.Exit(1); + } + } + } +} +``` + +`_request.Result` is a `PackageInfo[]`; each entry exposes `name`, `displayName`, `description`, +and `versions` (`.latest`, `.latestCompatible`, `.all`). For a terminal-only check without the +Editor (a **known** id, not free-text search), query the registry directly — see +[references/select-packages.md](references/select-packages.md#discovering-and-verifying-packages). + +## Run it headless (direct Editor invocation, no `-quit`) + +Resolve the Editor binary from the version, then run it in batch mode. The script owns quitting +via `EditorApplication.Exit`, so do **not** pass `-quit`: + +```bash +VERSION="" # e.g. 6000.0.47f1 (or an installed version) +PROJECT="" +METHOD="ProjectBootstrap.PackageInstaller.Install" # or ...PackageSearch.SearchAll + +# Install directory of that editor (Hub layout), via the unity CLI +ED=$(unity editors path "$VERSION" --format json | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['path'])") + +# Resolve the executable per-OS (handles both "dir containing Unity.app" and the ".app" itself) +case "$(uname)" in + Darwin) if [ -d "$ED/Unity.app" ]; then UNITY_BIN="$ED/Unity.app/Contents/MacOS/Unity"; + elif [[ "$ED" == *.app ]]; then UNITY_BIN="$ED/Contents/MacOS/Unity"; + else UNITY_BIN="$ED/Unity"; fi ;; + Linux) UNITY_BIN="$ED/Unity" ;; + *) UNITY_BIN="$ED/Unity.exe" ;; # Windows (Git Bash / MSYS); use Unity.exe in PowerShell +esac + +"$UNITY_BIN" -batchmode -projectPath "$PROJECT" -executeMethod "$METHOD" -logFile - +echo "Exit code: $?" # 0 = success, 1 = UPM error, 2 = timeout +``` + +`-logFile -` streams the Editor log (including the `[PackageInstaller]` / `[PackageSearch]` +lines) to stdout so you can watch resolution progress and read any UPM error. If +`unity editors path` output shape differs on your build, get the directory from +`unity editors --installed --format json` instead. + +## Verify + +```bash +# Every requested id should appear as a dependency +cat "/Packages/manifest.json" +``` + +Confirm the run exited `0` and each package from the list is present in `manifest.json`. If a +package fails to resolve, `_request.Error.message` is logged; read it and check the id/version +against the registry. The Editor's own log (including the `[PackageInstaller]` lines) is the +stdout you streamed with `-logFile -` above — read it there, not via `unity logs` (which shows +the CLI's own log, not the Editor's). + +## Import & save headlessly (generate `.meta` files) + +After a script or tool writes new `.cs`/asset files, Unity must **import** them so it generates +the `.meta` file each asset needs — and every `.cs`/asset MUST be committed together with its +`.meta`. Merely opening the project once (`unity open ""`) imports and generates +them; use this method when you need it **headless** (in a script or CI). + +Unlike the package installer, this is **synchronous** — it finishes before returning — so it's +safe to run via `unity run` (its injected `-quit` is harmless; the method also calls +`EditorApplication.Exit` for a clean exit code). Write +`Assets/Editor/ProjectBootstrap/ProjectSaver.cs`: + +```csharp +using UnityEditor; +using UnityEngine; + +namespace ProjectBootstrap +{ + public static class ProjectSaver + { + // Invoke with: -executeMethod ProjectBootstrap.ProjectSaver.SaveAll + public static void SaveAll() + { + AssetDatabase.Refresh(ImportAssetOptions.ForceUpdate); + AssetDatabase.SaveAssets(); + Debug.Log("[ProjectSaver] Assets imported and saved."); + EditorApplication.Exit(0); + } + } +} +``` + +```bash +unity run "" --editor-version \ + -- -executeMethod ProjectBootstrap.ProjectSaver.SaveAll +``` + +## Notes + +- These editor scripts are a bootstrap convenience. Leave them in + `Assets/Editor/ProjectBootstrap/` (they do nothing unless invoked) or delete them after + setup — your call; mention it to the user. +- All scripts live under `Editor/` because they use `UnityEditor`; they never ship in a build. +- Monetization / backend packages (`com.unity.purchasing`, `com.unity.services.levelplay`, the + UGS packages) install through this same mechanism, but do the actual **integration** via the + dedicated skills: **implement-in-app-purchases**, **levelplay-unity-integration**, + **build-live-game**. diff --git a/skills/unity-package-management/references/select-packages.md b/skills/unity-package-management/references/select-packages.md new file mode 100644 index 0000000..09326aa --- /dev/null +++ b/skills/unity-package-management/references/select-packages.md @@ -0,0 +1,108 @@ +# Selecting packages + +Turn a game concept — genre, look, target platforms, monetization — into a concrete package +list, then install it via the C# PackageManager Client API (see the main `SKILL.md`). + +**Principle:** install what the concept actually needs, not everything. A hyper-casual 2D +prototype needs far less than a 3D multiplayer RPG. Prefer packages already provided by the +chosen template (URP templates already include the render pipeline, Input System, etc.) — only +add what's missing. Don't pin exact versions unless a minimum is required; `Client.Add` without +a version resolves the latest compatible release. + +The tables below are a starting point, not the whole registry. **Search the registry** to +discover packages beyond this list, confirm an id exists, or check available versions before +installing — see [Discovering and verifying packages](#discovering-and-verifying-packages). + +## Discovering and verifying packages + +Two ways to search, depending on whether the Editor is involved: + +**In-Editor — the PackageManager Client API (preferred).** `Client.SearchAll()` returns every +package available in the project's configured registries (the Unity registry plus any scoped +registries), each with all its versions and metadata — this is what the Package Manager +window's search filters over. `Client.Search("")` inspects a single package. Use the +ready-to-run `PackageSearch` script in the main `SKILL.md` to discover candidates and verify +ids/versions before building the install list. + +**Terminal — query the npm-compatible registry directly** (no Editor needed) to confirm a +**known** id exists and list its versions: + +```bash +# Full metadata for one package: versions{}, dist-tags.latest, description, dependencies. +# -f makes curl fail (non-zero) on HTTP errors — e.g. a 404 for a bad id — instead of piping +# an error page into python; -L follows redirects. +curl -fsSL https://packages.unity.com/com.unity.cinemachine | python3 -m json.tool | head -40 + +# Just the latest published version +curl -fsSL https://packages.unity.com/com.unity.cinemachine \ + | python3 -c "import sys,json;print(json.load(sys.stdin)['dist-tags']['latest'])" +``` + +Note: the registry supports fetching a **known** package id, but **not** free-text search over +HTTP (the npm `-/v1/search` endpoint is not available — it 404s). For keyword discovery, use +`Client.SearchAll()` in-Editor, the Package Manager window, or the +[Unity package documentation](https://docs.unity3d.com/Manual/pack-keys.html). + +## Foundation (almost every project) + +| Need | Package | Notes | +|---|---|---| +| Modern input | `com.unity.inputsystem` | Preferred over the legacy Input Manager. | +| Text / UI | `com.unity.ugui` | uGUI + TextMeshPro (bundled). UI Toolkit ships with the Editor. | +| Camera framing | `com.unity.cinemachine` | Great for almost any 3D and many 2D games. | +| Testing | `com.unity.test-framework` | Enables `unity test`; usually already present. | +| Large/streamed assets | `com.unity.addressables` | Add when the game has many assets or needs content updates. | + +## Render pipeline (pick one; usually set by the template) + +| Choice | Package | Use when | +|---|---|---| +| **URP** (Universal) | `com.unity.render-pipelines.universal` | Default for most 2D/3D, mobile, and WebGL. Broadest platform reach. | +| **HDRP** (High-Definition) | `com.unity.render-pipelines.high-definition` | High-fidelity PC/console only. Not for mobile/WebGL. | +| **Built-in** | (none) | Simplest/legacy; fine for tiny prototypes. | + +## By dimension & look + +| Look | Packages | +|---|---| +| **2D** (any) | `com.unity.2d.feature` (sprites, tilemap, animation, pixel-perfect bundle) | +| **2D pixel-perfect** | `com.unity.2d.pixel-perfect` (included in the 2D feature set) | +| **3D navigation** | `com.unity.ai.navigation` (NavMesh for AI/pathfinding) | +| **Cutscenes / sequencing** | `com.unity.timeline` | +| **No-code logic** | `com.unity.visualscripting` | + +## By genre (starting points, combine with the above) + +| Genre | Typical additions | +|---|---| +| Platformer / action | URP, Input System, Cinemachine, 2D feature (if 2D), AI Navigation (if 3D) | +| Puzzle / match / card | URP or 2D feature, Input System, uGUI/TextMeshPro, Timeline (juice) | +| Top-down / twin-stick | URP, Input System, Cinemachine, AI Navigation | +| RPG / adventure | URP, Input System, Cinemachine, AI Navigation, Addressables, Timeline | +| Racing / physics | URP, Input System, Cinemachine; Physics is built in | +| Idle / hyper-casual | 2D feature or URP, Input System, uGUI/TextMeshPro (keep it lean) | +| Multiplayer (any) | `com.unity.netcode.gameobjects` + Multiplayer Services → see **build-live-game** | + +## By target platform + +Platform support is mostly Editor **modules** (installed with `unity install --module …`, see +the **`unity-cli`** skill), not packages. Package-wise: + +| Platform | Consider | +|---|---| +| Mobile (iOS/Android) | Keep dependencies lean; URP over HDRP; Addressables for download size; monetization below | +| WebGL | URP (not HDRP); small footprint; avoid heavy packages | +| Desktop / Console | URP or HDRP depending on fidelity target | + +## By monetization — install now, integrate via the dedicated skill + +| Goal | Package | Integration skill | +|---|---|---| +| In-app purchases | `com.unity.purchasing` | **implement-in-app-purchases** | +| Ads / mediation | `com.unity.services.levelplay` | **levelplay-unity-integration** | +| Accounts, cloud save, economy, remote config, leaderboards, analytics | see the UGS package table | **build-live-game** | + +Install the package(s) here so the manifest is complete, but do the actual wiring by invoking +the matching skill. For the full UGS package/version matrix (`com.unity.services.core`, +`authentication`, `cloudsave`, `cloudcode`, `economy`, `remote-config`, `analytics`, etc.), +read the **build-live-game** skill.