From 28cebac3cd6add45353ef21dd12e68ca78a4903b Mon Sep 17 00:00:00 2001 From: unity-hub-bot Date: Tue, 22 Sep 2026 19:11:15 +0000 Subject: [PATCH] sync: align skills catalog with Unity-Technologies/skills Mirrors the approved skills/ catalog from Unity-Technologies/skills@main into this plugin. --- skills/audio-setup-mixers/SKILL.md | 2 +- skills/audio-setup-mixers/references/api.md | 2 +- .../references/open-search-window.md | 2 +- skills/implement-in-app-purchases/README.md | 233 ++++++++++++++++++ .../levelplay-unity-integration/CHANGELOG.md | 69 ++++++ skills/levelplay-unity-integration/README.md | 78 ++++++ skills/migrate-birp-to-urp/SKILL.md | 2 +- skills/new-unity-project/SKILL.md | 124 ++++++++-- skills/optimize-audio/SKILL.md | 2 +- .../resources/audio-import-api.md | 2 +- skills/optimize-web/SKILL.md | 2 +- skills/sprite-editor/SKILL.md | 2 +- skills/unity-cli/CHANGELOG.md | 36 ++- skills/unity-cli/SECURITY.md | 3 + skills/unity-cli/SKILL.md | 52 ++-- .../references/auth-license-cloud.md | 4 + skills/unity-cli/references/build-run-test.md | 96 ++++++++ skills/unity-cli/references/config-hub.md | 80 ++++++ .../references/diagnostics-maintenance.md | 27 +- .../unity-cli/references/editors-install.md | 4 +- .../references/integration-advanced.md | 28 ++- .../references/projects-templates.md | 47 +++- .../references/select-packages.md | 44 ++-- skills/urp-postprocessing/SKILL.md | 2 +- 24 files changed, 861 insertions(+), 82 deletions(-) create mode 100644 skills/implement-in-app-purchases/README.md create mode 100644 skills/levelplay-unity-integration/CHANGELOG.md create mode 100644 skills/levelplay-unity-integration/README.md diff --git a/skills/audio-setup-mixers/SKILL.md b/skills/audio-setup-mixers/SKILL.md index 5bcc7fc..30c07f2 100644 --- a/skills/audio-setup-mixers/SKILL.md +++ b/skills/audio-setup-mixers/SKILL.md @@ -40,7 +40,7 @@ Once `eval` is available, that is how each C# step below runs. Run C# through the connected Editor with the `eval` command. Discover its parameter shape from `unity command --format json` rather than assuming one — the inline form is -`unity command eval --caller plugin --skill audio-setup-mixers --code ''`, and some Pipeline versions also register +`unity command eval --code ''`, and some Pipeline versions also register `eval_file` for running a snippet from a file. **Check the catalog before reaching for `eval_file`; it is frequently absent.** `unity command` defaults to a 30 second timeout. diff --git a/skills/audio-setup-mixers/references/api.md b/skills/audio-setup-mixers/references/api.md index df03989..5ae7f9c 100644 --- a/skills/audio-setup-mixers/references/api.md +++ b/skills/audio-setup-mixers/references/api.md @@ -27,7 +27,7 @@ to add any missing groups (two clicks in a window they already have open), and t routing itself. The tedious part — walking dozens of Audio Sources and classifying them — is the part that was worth automating anyway. -All snippets below are written for `unity command eval --caller plugin --skill audio-setup-mixers --code ''`: fully qualified, no +All snippets below are written for `unity command eval --code ''`: fully qualified, no `using` directives, returning their result rather than logging it. ## Inventory the project's mixers and their groups diff --git a/skills/generate-editor-search-query/references/open-search-window.md b/skills/generate-editor-search-query/references/open-search-window.md index 5733853..ba82d60 100644 --- a/skills/generate-editor-search-query/references/open-search-window.md +++ b/skills/generate-editor-search-query/references/open-search-window.md @@ -8,7 +8,7 @@ This is a read-only Editor UI action. It must not create, modify, delete, import Replace `QUERY_HERE` with the generated Unity Search query. If the query contains double quotes, double them inside the verbatim C# string. -Run it through the Editor with `unity command eval --caller plugin --skill generate-editor-search-query --code ''`. Fully qualified, with no +Run it through the Editor with `unity command eval --code ''`. Fully qualified, with no `using` directives, because `eval` compiles a statement block rather than a file. ```csharp diff --git a/skills/implement-in-app-purchases/README.md b/skills/implement-in-app-purchases/README.md new file mode 100644 index 0000000..f714fd4 --- /dev/null +++ b/skills/implement-in-app-purchases/README.md @@ -0,0 +1,233 @@ +# Unity In-App Purchases Skill + +This skill helps you implement, configure, debug, and migrate Unity In-App Purchases (IAP) using `com.unity.purchasing` v5. It covers standard Apple App Store / Google Play billing, IAP D2C Capabilities (Direct-to-Customer — Stripe/Coda via Unity Cloud), and conversion from a wide range of third-party and native billing implementations. + +--- + +## What This Skill Covers + +| Path | When to use | +|---|---| +| **Add IAP to a new project** | No existing IAP — start from scratch with Unity IAP 5 | +| **Migrate v4 → v5** | Project uses `IStoreListener`, `UnityPurchasing.Initialize`, or `ConfigurationBuilder` | +| **Convert native Google BillingClient** | Project calls Android BillingClient via `AndroidJavaObject` / JNI bridge | +| **Convert native iOS StoreKit** | Project uses a custom ObjC/Swift StoreKit plugin bridged via `DllImport("__Internal")` | +| **Convert Essential Kit billing** | Project uses VoxelBusters Essential Kit for in-app purchases (without losing other features) | +| **Assess/Convert UniPay (FLOBUK)** | Project uses UniPay — determines whether migration is needed or possible | +| **Assess/Convert RevenueCat** | Project uses RevenueCat — evaluate/implement observer mode to work with Unity IAP 5 | +| **Assess/Convert Adapty** | Project uses Adapty — evaluate/implement observer mode to work with Unity IAP 5 | +| **Implement IAP D2C Capabilities** | Add third-party payment provider (Stripe or Coda) via Unity Cloud | + +The skill always scans the project first and routes to the correct path automatically. You can also specify a path manually if you know exactly which one you need. + +--- + +## Example Prompts + +``` +Add in-app purchases code to my game. I have a 100-coin pack and a Remove Ads unlock. +``` +``` +Migrate my existing IAP code in the project from Unity IAP v4 to v5. +``` +``` +My project uses AndroidJavaObject to call Google Play BillingClient. Convert it to Unity IAP. +``` +``` +I have a custom ObjC StoreKit plugin with SKPaymentQueue. Replace it with Unity IAP. +``` +``` +Disable Essential Kit billing and replace with Unity IAP 5. Keep other Essential Kit features working as before. +``` +``` +Can my RevenueCat project implement app store purchases through Unity's IAP v5? +``` +``` +My project uses Adapty. What features will we lose if we use Unity IAP instead? Give me a detailed report and do not make any changes now. +``` +``` +Add Stripe payment support via Unity IAP D2C Capabilities. +``` +``` +Add a web checkout option for my players using Unity's IAP D2C Capabilities with Coda. +``` + +--- + +## Path Details, Limitations, and Best Practices + +### Add IAP to a New Project + +**What it does:** Installs Unity IAP 5, creates an `IAPManager`, wires up the two-step purchase flow (pending → confirm), integrates with your existing save system, and connects to your shop UI. + +**Limitations:** +- The skill cannot create App Store Connect or Google Play Console product entries — you must do that manually. +- If you use local Google Play receipt validation, you must run the Receipt Validation Obfuscator manually in the Unity Editor (**Services > In-App Purchasing > Receipt Validation Obfuscator**). +- Apple local receipt validation is a no-op under StoreKit 2. Use server-side JWS validation for Apple. + +**Best practices:** +- Define all products in one authoritative catalog (a `ScriptableObject` or constants class) — not scattered across button click handlers. +- Always call `ConfirmPurchase` **after** saving the granted reward. An unconfirmed purchase re-delivers safely; a confirmed-but-unsaved one loses the reward permanently. +- Subscribe to all events **before** calling `Connect()` — pending purchases from a previous session may fire immediately on reconnect. +- Add a "Restore Purchases" button for any project with NonConsumable or Subscription products — required on iOS. + +--- + +### Migrate v4 → v5 + +**What it does:** Replaces the listener-based `IStoreListener` / `UnityPurchasing.Initialize` / `ConfigurationBuilder` pattern with the event-driven `StoreController` pattern. + +**Limitations:** +- `product.receipt` and `product.hasReceipt` are removed. The skill migrates ownership checks to `store.CheckEntitlement(product)` — verify your entitlement logic after migration. +- Apple local validation via `CrossPlatformValidator` still compiles but is a no-op under StoreKit 2. If your project validates Apple receipts locally, this validation silently stops working after migration. +- Developer payload (the third `Purchase()` argument) is removed. If your backend uses it, a backend change is required. +- `SubscriptionManager` is replaced — subscription info is now on `order.Info.PurchasedProductInfo`, not on `CartItem`. + +**Best practices:** +- Migrate one system at a time: get initialization working first, then purchase flow, then restore. +- Run the migration in a branch. The skill uses `#if` guards where needed, but test thoroughly before removing the old code. +- After migration, recheck all `OnPurchaseConfirmed` handlers — the event now receives `Order` (base type) and you must pattern-match `ConfirmedOrder` vs `FailedOrder`. + +--- + +### Convert Native Google BillingClient + +**What it does:** Converts C# → JNI → BillingClient bridge code to Unity IAP 5, preserves the public billing API via a compatibility facade, and wraps old native code in `#if !USE_UNITY_IAP_V5` for easy rollback. + +**Limitations:** +- **Multiple subscription base plans / offer tokens** (`basePlanId`, `offerToken`, `offerId`) are a hard blocker — Unity IAP does not expose offer-level selection. You must either simplify your Play Console subscription setup to one base plan per product, or stay on native billing. +- **Personalized price disclosure** (`setIsPersonalizedPrice`) and **alternative billing / external offers** are hard blockers. +- **Multi-quantity purchases** (quantity > 1 per transaction) are not supported in Unity IAP. +- A mixed native BillingClient + Unity IAP architecture is not supported — both compete for the same `PurchasesUpdatedListener` slot. The skill will not generate a mixed setup. +- The receipt format changes: the backend receives `order.Info.Receipt` (a JSON object containing `purchaseToken`, `orderId`, and `signature`) instead of raw fields. If your backend parses these fields individually, a backend update is required. + +**Best practices:** +- Run the blocker scan and read the migration report before making any changes. Hard blockers require a decision before code is written. +- Keep the Gradle billing dependency in place until migration is validated — Unity IAP brings its own BillingClient, but removing the old dependency prematurely can break the build in unexpected ways. +- Use the `#if USE_UNITY_IAP_V5` / `#if !USE_UNITY_IAP_V5` guards throughout. The rollback path (remove the define) must work cleanly before you ship. +- Test on a physical Android device with a real sandbox account — the BillingClient behavior in the Unity Editor and on emulators is not representative of production. + +--- + +### Convert Native iOS StoreKit + +**What it does:** Converts a custom Objective-C or Swift StoreKit plugin (bridged via `DllImport("__Internal")` and `UnitySendMessage`) to Unity IAP 5, preserving the C# game-facing API via a compatibility facade. + +**Limitations:** +- **Receipt format is a breaking backend change.** Unity IAP uses per-transaction JWS (StoreKit 2 style) rather than the SK1 base64 app receipt bundle. If your backend validates the receipt bundle against Apple's `/verifyReceipt` endpoint, it must migrate to Apple's App Store Server API or JWS validation before you can ship. +- **Promotional offer signing** (`SKPaymentDiscount` / SK2 signed offers) is a hard blocker — Unity IAP has no equivalent for server-signed promotional offers. +- **Win-back offers** (StoreKit 2) are not supported in Unity IAP 5.4. +- **`SKStorefront`** (region detection via storefront change observer) is not exposed in Unity IAP. +- **`SKReceiptRefreshRequest`** has no direct equivalent — `store.FetchPurchases()` covers the purchase re-delivery use case but not manual receipt refresh. +- ObjC/Swift plugin files cannot use C# `#if` defines. The skill guards only the C# call sites — the native files remain in `Assets/Plugins/iOS/` and compile unconditionally. +- A mixed native StoreKit + Unity IAP architecture is not supported — both register as `SKPaymentQueue` observers and only one reliably receives callbacks. + +**Best practices:** +- Audit the backend receipt validation endpoint before starting. If it calls `/verifyReceipt`, plan the backend migration in parallel with the client migration. +- If the plugin intercepts App Store promotional purchases (`shouldAddStorePayment`), wire up `OnPromotionalPurchaseIntercepted` and `ContinuePromotionalPurchases()` before removing the native interceptor. +- Test Ask-to-Buy explicitly — the deferred → pending two-stage flow behaves differently than a native `PURCHASING` → `PURCHASED` transition. +- Validate the migration on TestFlight, not just in the Unity Editor or Simulator. StoreKit behavior differs between Editor sandbox, Simulator, and TestFlight builds. + +--- + +### Convert Essential Kit Billing + +**What it does:** Disables the Essential Kit Billing service flag in `EssentialKitSettings.asset`, removes the conflicting `com.android.billingclient` Gradle dependency, and implements Unity IAP 5 using the product catalog extracted from the Essential Kit settings. + +**Limitations:** +- Essential Kit C# source files are **not deleted**. The Billing service is disabled via the settings flag — all EK code remains and compiles. Do not expect a clean removal. +- Only the Billing service is affected. All other Essential Kit services (Notification, GameServices, etc.) are left completely untouched. +- **Product IDs must not change.** The same IDs used in Essential Kit must be carried over to Unity IAP to preserve store history. +- If your project uses **server-side receipt validation**, the receipt format changes from `transaction.RawData` (Android) and `transaction.Receipt` (iOS JWS) to `order.Info.Receipt` and `order.Info.Apple?.jwsRepresentation`. Document the backend change required. +- Subscriptions are fully supported, but the restore path changes — EK's `OnRestorePurchasesComplete` maps to both `store.OnPurchasesFetched` and the `RestoreTransactions` callback in Unity IAP. + +**Best practices:** +- Run `Assets > External Dependency Manager > Android Resolver > Force Resolve` after removing the Gradle billing dependency — do not skip this step. +- Verify the Essential Kit Billing service is visually disabled in **Window > Voxel Busters > Essential Kit > Open Settings → Services** after the settings file edit. +- Confirm all product IDs in App Store Connect and Play Console match the Unity IAP catalog exactly before testing. + +--- + +### Assess UniPay (FLOBUK) + +**What it does:** This path does **not** perform a conversion. It assesses whether migration is needed and routes to one of three outcomes: unsupported platform (stop), upgrade required (stop), or no action needed (UniPay already wraps Unity IAP 5). + +**Limitations:** +- UniPay's Steam, Meta Quest, PayPal, and Facebook Instant Games integrations have **no Unity IAP equivalent**. If your project targets any of these platforms, there is no migration path — keep UniPay. +- If `com.unity.purchasing` is below v5.4, IAP D2C Capabilities (Stripe/Coda) are not available — an upgrade to the latest stable v5.4+ is needed before adding D2C support. +- The skill does not perform a "remove UniPay" conversion — that is a manual refactor scoped to what features you are replacing. + +**Best practices:** +- If the assessment concludes "no action needed," there is no code to write. Work within UniPay's API for new products or purchase logic changes. +- If you want to remove UniPay entirely and use Unity IAP directly, ask the skill explicitly and describe which UniPay features you are replacing — it will assess feasibility and scope. + +--- + +### Assess/Convert RevenueCat + +**What it does:** Evaluates whether the project can switch to Unity IAP 5 for handling purchases. Produces one of three outcomes: already in observer mode (no action), blockers detected (report + two choices), or no blockers (two conversion paths: observer mode or full removal). + +**Limitations:** +- **Amazon Appstore** is a hard blocker — Unity IAP 5 has removed Amazon support. RevenueCat observer mode also does not work reliably on Amazon builds. If your project targets Amazon, conversion is not viable. +- **RevenueCat Offerings / remote paywalls** have no Unity IAP equivalent — all products must be defined in code or a local catalog. +- **RevenueCat A/B testing (Experiments)** has no Unity IAP equivalent. +- **Cross-platform entitlement sync** (a user who buys on iOS retains access on Android) has no Unity IAP equivalent without a custom backend. +- **RevenueCat webhook events** (subscription renewals, cancellations, billing issues) are not delivered by Unity IAP — you would need to build your own subscription event infrastructure. +- In **observer mode**, `SyncPurchases()` must be called after every Unity IAP confirmed purchase. Missing this call means RevenueCat does not validate the receipt and `CustomerInfo` is not updated. + +**Best practices:** +- Run the full feature check before deciding. RevenueCat's value often comes from features that are not obvious in the codebase (e.g., webhooks configured server-side). +- If the project has a marketing team managing paywall copy or pricing remotely via RevenueCat Offerings, a full removal will require significant UI work to replace that capability. +- Observer mode is the lower-risk path — it preserves RevenueCat's server-side validation and subscription lifecycle tracking while Unity IAP handles the native purchase flow. + +--- + +### Assess/Convert Adapty + +**What it does:** Evaluates whether the project can switch to Unity IAP 5 for app store purchase handling. Produces one of three outcomes: already in observer mode (no action), blockers detected (report + two choices), or no blockers (observer mode or full removal). + +**Limitations:** +- **Adapty Paywall Builder** has no Unity IAP equivalent — and it is also **unavailable in Adapty's own Observer Mode**. Switching to observer mode loses Paywall Builder regardless of whether Unity IAP is involved. +- **Adapty A/B testing** has no Unity IAP equivalent. In observer mode, A/B testing is possible but requires significant manual instrumentation. +- **Cross-platform entitlement sync** has no Unity IAP equivalent without a custom backend. +- In **observer mode**, `Adapty.ReportTransaction()` must be called after every Unity IAP confirmed purchase. Missing this call means Adapty does not validate the receipt server-side. + +**Best practices:** +- If your marketing team uses Adapty's Paywall Builder to update paywall layouts without app releases, note that this capability is lost in observer mode. Make sure all stakeholders understand this before proceeding. +- Full removal requires replacing any `AdaptyUI` / `PaywallView` shop UI with custom Unity UI before Adapty can be removed. Budget time for this work. +- Observer mode is the lower-risk path and preserves Adapty's webhook delivery and analytics integrations. + +--- + +### Implement IAP D2C Capabilities + +**What it does:** Adds Direct-to-Customer (D2C) third-party payment provider support (Stripe or Coda) via Unity Cloud, including remote catalog setup, deep link configuration, the built-in payment options picker UI, Apple/Google external purchase compliance tools, and entitlement delivery guidance. + +**Limitations:** +- Requires **Unity IAP v5.4+**, **Unity Editor 2022.3+**, `com.unity.services.authentication` **v3.7.1+**, and `com.unity.services.core` **v1.18.0+**. All must be satisfied before any code is written. +- **Subscriptions are not supported** by IAP D2C Capabilities in v5.4. Only Consumable and NonConsumable products can be used. +- Requires a **Stripe or Coda account** connected in the Unity Cloud IAP dashboard, and Unity must enable D2C for your organization — contact your Unity Client Partner if it is not yet enabled. +- **Routing rules** must be configured in the Unity Dashboard before any player is offered a D2C payment option. Without a routing rule, no provider is offered even if a provider account is connected. +- **External web payments via Stripe/Coda are permitted in select regions only.** Apple and Google have their own program eligibility requirements. The developer is responsible for determining eligibility and meeting disclosure requirements — the skill does not perform compliance on your behalf. +- **Anonymous sign-in** must not be used as the authentication method. If a player's session token is lost (reinstall, app data clear), purchase history tied to an anonymous identity becomes unrecoverable. +- The **receipt format is different from standard IAP 5** — D2C purchases go through Unity Cloud, not the device's native store, so `order.Info.Apple` and `order.Info.Receipt` behave differently for D2C orders. + +**Best practices:** +- Set up **routing rules** in the Unity Dashboard before testing. Without them, `GetEligiblePaymentProviders()` returns an empty list and the purchase UI never appears — this is a common "nothing happens" issue during initial integration. +- Use a **proxy HTML page** for the Success Redirect URL rather than a direct app-scheme URL. On some Android and iOS devices, direct app-scheme redirects from the payment provider domain are silently dropped. Host the proxy on a stable HTTPS domain you control. +- Use **`ShowPurchaseOption(catalogListingId)`** as the primary purchase entry point — it shows the built-in picker UI and handles provider selection automatically. Only fall back to `PurchaseProduct` directly when `GetEligiblePaymentProviders()` returns an empty `Providers` list. +- Configure a **Cancel Redirect URL** in the payment provider dashboard — without it, the checkout page has no "Back" button and players who change their mind are stuck in the browser. +- The SDK remembers the **last used payment provider per player per device** (provider memory). This is expected behavior, not a bug. Clear app data to reset it during testing. +- Deploy the **Deployment package** (`com.unity.services.deployment`) early — it is required to push `.ucat` product definitions to the Remote Catalog. Without it, the catalog cannot be deployed and `FetchRemoteCatalog()` returns no products. + +--- + +## General Best Practices + +- **Always let the skill scan first.** The pre-check (`pre-check.md`) detects third-party packages, native billing code, and existing Unity IAP versions before routing. Skipping it leads to incompatible changes. +- **Read the migration report before approving any code changes.** Every conversion path produces a report covering what will change, what blockers were found, and what manual steps remain. Review it before proceeding. +- **Never confirm a purchase before saving the reward.** An unconfirmed purchase re-delivers safely. A confirmed-but-unsaved one is gone permanently. +- **Subscribe to all failure events.** `OnProductsFetchFailed`, `OnPurchasesFetchFailed`, `OnStoreDisconnected` — not subscribing generates runtime warnings and leaves failures silently unhandled. +- **Subscribe to `OnPurchaseDeferred`.** Ask-to-Buy (iOS) and Google Play deferred purchases fire this event. Not subscribing silently drops them. +- **Use `#if USE_UNITY_IAP_V5` guards** for all migration work. The rollback path (remove the define from Player Settings) must work cleanly before shipping. +- **Test with real sandbox accounts on real devices.** Editor sandbox and emulators do not reproduce all edge cases — particularly pending purchases, deferred flows, and restore behavior. diff --git a/skills/levelplay-unity-integration/CHANGELOG.md b/skills/levelplay-unity-integration/CHANGELOG.md new file mode 100644 index 0000000..0950dc5 --- /dev/null +++ b/skills/levelplay-unity-integration/CHANGELOG.md @@ -0,0 +1,69 @@ +# Changelog + +## v0.10.0 — 2026-08-21 — Workflow spine, and a hard install gate + +Moves reference material out of `SKILL.md` and makes the SDK install a verified step rather than an assumed one. + +**Changed:** +- `SKILL.md` is now the workflow spine only, going from about 1,100 lines to 435. The dependency-resolution, testing-and-validation and troubleshooting material that was inlined in it moves into `references/`. Nothing was dropped; it is read on demand instead. `SKILL.md` is loaded in full on every invocation while a reference file is read only when a step links it, so this is a saving on every run that does not need the detail. +- The reference set grows from nine files to twelve: `dependency-resolution.md`, `testing-and-validation.md` and `troubleshooting.md` are now separate files. + +**Added:** +- **A hard install-verification gate at Step 3.** No LevelPlay code is written until `com.unity.services.levelplay` is confirmed present in `Packages/packages-lock.json`, read from the project rather than taken from the Package Manager window or an earlier turn. The package is easy to believe is installed: its display name is **Ads Mediation** while the recorded id is `com.unity.services.levelplay`, two similarly named packages are the wrong ones, and the install prompts for a second package partway through. Code written before the id resolves fails with `CS0246` on every LevelPlay symbol, which reads as a code problem rather than an install problem. The gate also distinguishes "the install never happened" from "Unity has not resolved it yet", because the fix differs. +- The deprecated-APIs section now states explicitly that `SetGDPRConsents(Dictionary)` is **not** deprecated on SDK 9.4.x, where it is the correct call, and only becomes `[Obsolete]` on 9.5.0+. It is kept out of the deprecated list rather than listed with a caveat, so it cannot be read the wrong way round. + +## v0.9.0 — 2026-08-17 — SDK 9.x migration support + +Adds guided migration to the LevelPlay 9.x SDK and the current Ad Unit (MADU) APIs. + +**New:** +- "New Integration or Migration?" routing step at the start of the workflow +- Migration reference guide covering five scenarios: SDK upgrade (.unitypackage or UPM, including switching from .unitypackage to UPM), init API migration (IronSource.Agent to LevelPlay.Init), ad unit API migration (rewarded, interstitial, banner, and the ILRD handler), Maven Central dependency build failures, and Unity Ads (Advertisement Legacy) migration +- Upgrade safety flow: Developer Settings values and installed adapters are inventoried, and the user confirms, before any folder deletion; post-upgrade steps cover adapter reinstall, settings re-entry, and removal of the stale LEVELPLAY_DEPENDENCIES_INSTALLED scripting define when switching from .unitypackage to UPM +- Migration completeness checklist covering requirements that a line-by-line translation misses: placement capping checks when dashboard placements are used, an explicit rewarded load trigger, the version API mappings, correct ILRD event names, preserved logging, HideAd vs DestroyAd intent for legacy destroyBanner calls, and removal of onApplicationPause +- Compilation check after migration edits, with errors fixed before presenting results +- Skill description now also triggers on SDK upgrades, deprecated IronSource.Agent APIs, and Unity Ads migration + +**Fixed:** +- Banner adaptive-size example used a constructor form that does not compile on any 9.x version; now configured through Config.Builder (verified against 9.0.0, 9.4.0, and 9.5.0 source) +- API mapping corrections: validateIntegration maps to LevelPlay.ValidateIntegration (not LaunchTestSuite); pluginVersion maps to LevelPlay.PluginVersion (distinct from UnityVersion); onApplicationPause is removed in 9.x with no replacement; the legacy ILRD subscription maps to LevelPlay.OnImpressionDataReady on SDK 9.4.x and earlier or per-instance OnAdImpressionDataReady on 9.5.0+ +- Unity Ads migration now surfaces that LevelPlay.Init has no test-mode parameter (Test Suite or dashboard test mode are the equivalents) instead of dropping the flag silently +- Package edits during upgrades touch only manifest.json; packages-lock.json is never hand-edited +- Maven Central migration is mentioned only when the project actually needs it +- Corrected a consent-callback name mismatch in the privacy reference, and a banner troubleshooting example that called a method banners do not have + +## v0.8.0 — 2026-08-05 — Version-aware ILRD (SDK 9.5.0), rewarded load lifecycle, and improved activation + +Accuracy and activation updates reflecting current LevelPlay SDK behavior. + +**Impression-level revenue (ILRD) — SDK 9.5.0 API change** +- ILRD now documents both delivery mechanisms: the single global `LevelPlay.OnImpressionDataReady` event (SDK 9.4.x and earlier) and the per-ad-instance `OnAdImpressionDataReady` events on each ad object (SDK 9.5.0+), which replace the global event. +- The global event still exists but is deprecated on SDK 9.5.0+ and generates a compiler warning. +- Updated the initialization step and the rewarded/interstitial/banner references to direct SDK 9.5.0+ users to the per-instance approach. + +**Rewarded ad load lifecycle** +- Clarified that `LoadAd()` must be called explicitly; the SDK does not auto-manage rewarded loading (unlike the legacy IronSource API). +- Reframed the guidance so explicit, publisher-triggered loading is the default, with eager preloading documented as an optional pattern. Applies to `references/rewarded-api.md` and the loading-strategy guidance in `SKILL.md`. + +**Description and activation** +- Reworked the skill description to increase activation on general ad and monetization requests, not only when a developer names LevelPlay. +- Added guidance at the top of the skill directing the agent to run it as an interactive, step-by-step workflow and use the reference files, rather than answering from general knowledge. + +## v0.7.0 — 2026-06-12 — Initial public beta release + +First release of the LevelPlay Unity integration skill, released as public beta. + +**Features:** +- Step-by-step installation of the LevelPlay SDK using the Ads Mediation package in Unity Package Manager +- Native dependency resolution for Android and iOS +- SDK initialization with three code organization options +- Ad unit strategy recommendations based on business goals (revenue-focused, UX-focused, or balanced) +- Implementation guides for rewarded ads, interstitials, and banner ads +- Privacy compliance support (GDPR, CCPA, COPPA) +- iOS setup (App Tracking Transparency, SKAdNetwork) +- Impression-level revenue tracking (ILRD) +- Testing guidance using mock ads and the LevelPlay Test Suite + +## Feedback + +This skill is currently in beta. [Share your feedback here](https://docs.google.com/forms/d/e/1FAIpQLSe7WvWozJ67KjgOLglSBvLug8JdgEYk895nn_BHZs0HS_bWJA/viewform). diff --git a/skills/levelplay-unity-integration/README.md b/skills/levelplay-unity-integration/README.md new file mode 100644 index 0000000..fe4b205 --- /dev/null +++ b/skills/levelplay-unity-integration/README.md @@ -0,0 +1,78 @@ +# LevelPlay Unity Integration Skill + +![Beta](https://img.shields.io/badge/status-beta-orange) ![Version](https://img.shields.io/badge/version-0.7.0-blue) ![License](https://img.shields.io/badge/license-Unity%20Companion-blue) + +> 🧪 **Note:** This skill is in beta and will be shaped by your feedback. Try it out and [let us know what you think](https://docs.google.com/forms/d/e/1FAIpQLSe7WvWozJ67KjgOLglSBvLug8JdgEYk895nn_BHZs0HS_bWJA/viewform)! + +A skill that guides Unity developers through integrating the LevelPlay SDK using the Ads Mediation package in Unity Package Manager: from installation to fully working rewarded ads, interstitials, and banners. + +Compatible with Claude Code, GitHub Copilot, Cursor, Cline, and [50+ other agents](https://skills.sh). + +## What it does + +When you activate this skill, your agent walks you step by step through the complete LevelPlay integration: + +1. **Installing the SDK** via the Ads Mediation package in Unity Package Manager +2. **Resolving native dependencies** for Android and iOS builds +3. **Collecting credentials** from the LevelPlay dashboard +4. **Configuring privacy compliance** (GDPR, CCPA, COPPA) if needed +5. **Initializing the SDK** in your project, with three code organization options to fit your existing setup +6. **Recommending an ad unit strategy** based on your goals (revenue-focused, UX-focused, or balanced) +7. **Implementing ad formats** — rewarded ads, interstitials, and banners — with production-ready C# code +8. **Testing and validating** using mock ads in the Unity Editor and the LevelPlay Test Suite on device + +The skill also covers iOS-specific setup (App Tracking Transparency, SKAdNetwork), impression-level revenue tracking (ILRD) for analytics platforms, bid floors, and common troubleshooting. + +## Requirements + +- A Unity project using an LTS or actively developed version of the Unity Editor +- LevelPlay Unity package and SDK version 9.4.0+ +- A LevelPlay account: [get started here](https://platform.ironsrc.com/) + +Documentation for setting up the LevelPlay Unity package: see the [Unity Package Integration guide](https://docs.unity.com/en-us/grow/levelplay/sdk/unity/package-integration). + +## Installation + +```bash +npx skills add Unity-Technologies/skills +``` + +Then activate the `levelplay-unity-integration` skill in your agent. + +## Using the skill + +Type `/levelplay-unity-integration` to activate the skill, then describe what you want to do: + +- *"I want to add rewarded ads to my Unity game"* +- *"Help me integrate LevelPlay into my project"* +- *"I need to add interstitial ads between levels"* +- *"I have LevelPlay installed, help me implement banner ads"* + +You can jump in at any step. If the Unity package and SDK are already installed, your agent will pick up from where you are. + +## Privacy & Legal + +> **Note:** This skill provides technical integration guidance, including for LevelPlay's privacy APIs. It is not legal advice, and it does not determine which laws apply to your app — that depends on your users, your data practices, and your distribution. Consult your own legal counsel, and refer to [Regulation Advanced Settings for Unity](https://docs.unity.com/en-us/grow/levelplay/sdk/unity/regulation-advanced-settings) for the authoritative LevelPlay documentation. + +## What's in this folder + +``` +levelplay-unity-integration/ +├── SKILL.md # The workflow spine: decisions, checkpoints, questions +├── references/ # Detail read on demand, linked from the step that needs it +│ ├── initialization-api.md +│ ├── rewarded-api.md +│ ├── interstitial-api.md +│ ├── banner-api.md +│ ├── ilrd-api.md +│ ├── privacy-settings.md +│ ├── ios-setup.md +│ ├── dependency-resolution.md +│ ├── testing-and-validation.md +│ ├── troubleshooting.md +│ ├── migration-sdk-9.md +│ └── best-practices.md +├── CHANGELOG.md +└── README.md +``` + diff --git a/skills/migrate-birp-to-urp/SKILL.md b/skills/migrate-birp-to-urp/SKILL.md index 8d9ef3e..9b643ef 100644 --- a/skills/migrate-birp-to-urp/SKILL.md +++ b/skills/migrate-birp-to-urp/SKILL.md @@ -111,7 +111,7 @@ Two things it can't know for you: materials, and rebaking lighting all need a live Editor. An unreachable Editor is a stop, not a cue to hand-edit `ProjectSettings/GraphicsSettings.asset`. -Run C# with `unity command eval --caller plugin --skill migrate-birp-to-urp --code ''`. `unity command` defaults to a 30 second +Run C# with `unity command eval --code ''`. `unity command` defaults to a 30 second timeout, which matters here: installing URP triggers a package refresh and domain reload that will outlast it. Treat that as a phase boundary rather than raising the timeout. diff --git a/skills/new-unity-project/SKILL.md b/skills/new-unity-project/SKILL.md index 2ae0959..72c8faf 100644 --- a/skills/new-unity-project/SKILL.md +++ b/skills/new-unity-project/SKILL.md @@ -21,6 +21,8 @@ to other skills. 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. +- **`urp-postprocessing`**, **`ui`**, **`2d-pixel-perfect`** — the visual baseline (Step 6): + post-processing volume setup, HUD framework choice, pixel-perfect 2D. - **`implement-in-app-purchases`**, **`levelplay-unity-integration`**, **`build-live-game`** — monetization / backend *integration* (invoked at the end). @@ -34,10 +36,12 @@ up front or scaffold before they're settled. 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. +4. **Project + source control** — create from a **URP** template matching 2D/3D; init git. 5. **Packages** — install via the C# Client API. -6. **Save & first commit.** -7. **Hand off** monetization / backend. +6. **Visual baseline** — post-processing, camera, quality tier, UI stack, pipeline-correct + shaders, so the first frame doesn't look like an untouched template. +7. **Save & first commit.** +8. **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. @@ -53,7 +57,8 @@ Use `AskUserQuestion` so the user can pick fast, but let them answer freely too. - **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). +The brief drives template choice (Step 4), packages (Step 5) and the visual baseline (Step 6): +note the palette / mood words the user gives, and whether the look is pixel art. ## Step 2 — Platforms & monetization, then start installing @@ -62,7 +67,7 @@ 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. + handoff skill you invoke in Step 8 — 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 @@ -100,15 +105,20 @@ works without an Editor. 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. +- List the **real** template ids the Editor offers (`unity templates list --type core`) and pick by + **render pipeline**, not just 2D/3D — don't guess ids. **Default to URP:** + `com.unity.template.urp-blank` ("Universal 3D") for 3D, `com.unity.template.universal-2d` + ("Universal 2D") for 2D. `com.unity.template.3d` / `com.unity.template.2d` are the **Built-in + Render Pipeline** templates — deprecated from Unity 6.5, removed in 6.7 — so choose them only + when the user explicitly asks for Built-in. Confirm the pick against the JSON `renderPipeline` + field (blank for universal-2d on current releases, so match that one by id). - 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. + before packages and `.meta` files exist — you make the real first commit/check-in in Step 7. See the `unity-cli` workflow for exact flags. ## Step 5 — Packages @@ -116,15 +126,78 @@ Follow the **`unity-cli`** "Bootstrap a new project from scratch" workflow verba 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. +The template already provides the render pipeline — never add `com.unity.render-pipelines.universal` +to a Built-in template project (nothing assigns a URP asset; materials go pink) or vice versa. 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**: +## Step 6 — Visual baseline + +A fresh template renders correctly but looks like a default: no tonemapping, untouched quality +tier, flat colors. Left there, agents reach for `OnGUI` and guess shader names, which is where +washed-out or magenta materials come from. Apply this floor **before** any gameplay work. + +**First, `unity pipeline install --project-path ""`, before opening the +Editor.** Running C# in the Editor, and `unity command screenshot` below, both need the +project's `com.unity.pipeline` package. A project created in Step 4 does not have it, and Step 5 +does not add it: that step installs packages by launching the Editor binary with +`-batchmode -executeMethod`, which never touches the package. Installing before the open is the +supported order — the install updates `Packages/manifest.json`, which Unity reads at project +load. Run it against an already-open project and the CLI reports +`PIPELINE_MANIFEST_WRITE_FAILED`; ask the user to close the Editor and re-run. Without the +package, everything below fails to connect, which looks like the Safe Mode failure `unity-cli` +describes but has a different cause. + +**Then** `unity open ""` (also what Step 7 needs), wait until `unity status` +reports the Editor ready, and apply each item below by running C# in it. **`unity-cli` owns +those commands and their syntax** — don't re-derive them here. + +**Items 1, 2, 5 and 6 assume a URP template**, which is the Step 4 default. If the user +explicitly chose Built-in, don't run them as written: `UniversalAdditionalCameraData`, `Light2D`, +the `urp-postprocessing` volume framework and every `Universal Render Pipeline/*` shader are URP +types that do not exist there, so the generated C# won't compile. On Built-in, items 3 and 4 +still apply as written, post-processing means the legacy Post Processing Stack, and the shader +names are `Standard` / `Unlit/Color`. Don't reach for `migrate-birp-to-urp` — the user asked for +Built-in. + +1. **Post-processing.** Global Volume with Tonemapping (ACES), low Bloom (intensity 0.5–1, + threshold 0.9) and a subtle Vignette (≈ 0.25); set `renderPostProcessing = true` on the main + camera's `UniversalAdditionalCameraData`. **REQUIRED SUB-SKILL:** `urp-postprocessing` — its + code templates create the volume and check HDR and the Volume layer mask. +2. **Camera and light.** 2D → orthographic, solid background color from the brief's palette, and + a `Light2D` of type Global in the scene if the template scene has none (the Sprite-Lit shaders + render black without one). 3D → perspective; keep the template's directional light and skybox, + main-light shadows on. +3. **Quality tier.** Read `QualitySettings.names` first — tier names differ per template — then + `QualitySettings.SetQualityLevel` to the one matching the primary target: the highest tier for + desktop, the lowest for mobile/WebGL. Leave color space Linear and the Input System as the + template set them. +4. **UI stack.** HUD and menus use a uGUI Canvas + TextMeshPro or UI Toolkit — **never `OnGUI`**. + **REQUIRED SUB-SKILL:** `ui` picks between them for the project. +5. **Materials and shaders.** Under URP use `Universal Render Pipeline/Lit`, `…/Unlit`, + `…/2D/Sprite-Lit-Default` or `…/2D/Sprite-Unlit-Default`. `Standard` and `Unlit/Color` render + pink or washed out under URP. Prefer `GraphicsSettings.currentRenderPipeline.defaultMaterial` + / `.default2DMaterial` over `Shader.Find`, and treat a `null` from `Shader.Find` as an error. + `currentRenderPipeline`, not `defaultRenderPipeline`: a quality tier can carry its own pipeline + asset, and item 3 above just set the tier. +6. **Pixel art only.** Point filter mode on sprites and a Pixel Perfect Camera — see + `2d-pixel-perfect`. + +Save the scene, then confirm both of these. **Not with `unity logs`** — that reads the CLI's own +log, never the Editor's, so it reports clean whatever the scene looks like: + +- No render-pipeline or shader errors Editor-side. Read the Editor console through `unity-cli`, + or read `Editor.log` directly — that skill's "Recovering from Safe Mode" section has the + per-platform paths. +- `unity command screenshot --output baseline.png` looks lit and tonemapped rather than flat + gray. + +## Step 7 — Save & first commit + +The project is already open from Step 6, so `.meta` files exist. Make the first commit **with +whichever VCS you set up in Step 4**: ```bash -unity open "" # imports + generates .meta; for headless/CI use the +unity open "" # only if not already open; for headless/CI use the # "Import & save headlessly" method in unity-package-management ``` @@ -142,21 +215,23 @@ unity open "" # imports + generates .meta; for headless/CI use 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 +## Step 8 — 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. +Report the project path, Editor version, render pipeline and template, installed packages, the +visual baseline applied, 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 gameplay scaffolding.** It gets you to a running, wired project with a visual floor; + 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. The visual baseline (Step 6) is settings, not content. - **No command reference.** Syntax lives in `unity-cli` / `unity-package-management`. ## Checklist @@ -164,8 +239,11 @@ Report the project path, Editor version, installed packages, and next steps. - [ ] 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 created from a **URP** template (`urp-blank` / `universal-2d`) unless Built-in was + explicitly requested; git initialized with a Unity `.gitignore` +- [ ] Packages installed via the C# Client API; `manifest.json` verified; no render-pipeline package added on top of the template +- [ ] Visual baseline applied: global Volume (tonemapping, bloom, vignette) + camera post-processing on, + quality tier set for the target, UI stack chosen (no `OnGUI`), URP shader names, screenshot checked - [ ] Project opened/saved so `.meta` files exist; first commit made; `Library/` excluded - [ ] Handed off to the monetization/backend skill if applicable @@ -177,3 +255,7 @@ Report the project path, Editor version, installed packages, and next steps. - **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`. +- **Picking `com.unity.template.2d` / `.3d` because the name matches** — those are the Built-in + pipeline templates. Use `universal-2d` / `urp-blank`. +- **Skipping the visual baseline** and shipping the template's flat defaults, then building the + HUD with `OnGUI` and materials with `Shader.Find("Standard")` under URP. diff --git a/skills/optimize-audio/SKILL.md b/skills/optimize-audio/SKILL.md index 16c14c7..8c6a5a0 100644 --- a/skills/optimize-audio/SKILL.md +++ b/skills/optimize-audio/SKILL.md @@ -26,7 +26,7 @@ Two things it can't know for you: through `SaveAndReimport()` in a live Editor, so an unreachable Editor is a stop, not a cue to edit metadata directly. -Run C# with `unity command eval --caller plugin --skill optimize-audio --code ''`. Discover the parameter shape from +Run C# with `unity command eval --code ''`. Discover the parameter shape from `unity command --format json` rather than assuming one. `unity command` defaults to a 30 second timeout. diff --git a/skills/optimize-audio/resources/audio-import-api.md b/skills/optimize-audio/resources/audio-import-api.md index e6fc5bb..08b0fae 100644 --- a/skills/optimize-audio/resources/audio-import-api.md +++ b/skills/optimize-audio/resources/audio-import-api.md @@ -1,6 +1,6 @@ # Audio Import API Recipes -C# code recipes for `unity command eval --caller plugin --skill optimize-audio --code ''`. All examples target the Unity 6 +C# code recipes for `unity command eval --code ''`. All examples target the Unity 6 AudioImporter API. `eval` compiles a statement block, so there are no `using` directives and every type is written diff --git a/skills/optimize-web/SKILL.md b/skills/optimize-web/SKILL.md index c88f2cf..f727a03 100644 --- a/skills/optimize-web/SKILL.md +++ b/skills/optimize-web/SKILL.md @@ -24,7 +24,7 @@ Two things it can't know for you: are per-build-target, and a hand-edited value silently disagrees with what the build actually uses. An unreachable Editor is a stop for the write steps. -Run C# with `unity command eval --caller plugin --skill optimize-web --code ''`. `unity command` defaults to a 30 second +Run C# with `unity command eval --code ''`. `unity command` defaults to a 30 second timeout. ### Passing C# to `eval` diff --git a/skills/sprite-editor/SKILL.md b/skills/sprite-editor/SKILL.md index ceb4398..1e5980d 100644 --- a/skills/sprite-editor/SKILL.md +++ b/skills/sprite-editor/SKILL.md @@ -24,7 +24,7 @@ Two things it can't know for you: Run C# through the connected Editor with the `eval` command. Discover its parameter shape from `unity command --format json` rather than assuming one — the inline form is -`unity command eval --caller plugin --skill sprite-editor --code ''`, and some Pipeline versions also register +`unity command eval --code ''`, and some Pipeline versions also register `eval_file` for running a snippet from a file. **Check the catalog before reaching for `eval_file`; it is frequently absent.** `unity command` defaults to a 30 second timeout. diff --git a/skills/unity-cli/CHANGELOG.md b/skills/unity-cli/CHANGELOG.md index f5f2bcf..528c239 100644 --- a/skills/unity-cli/CHANGELOG.md +++ b/skills/unity-cli/CHANGELOG.md @@ -10,6 +10,31 @@ documentation for a CLI version that has not shipped publicly is not recorded he release is out — so this file never names unreleased surface. Pending skill work is tracked alongside the CLI change itself, not here. +## CLI `1.0.0-beta.10` (2026-09-14) + +Aligned to the CLI's `1.0.0-beta.10` release. Much of this release's surface was already documented ahead of it shipping — `unity context`, `unity watch test`, `unity commands`, `unity vcs blame`, `unity skill refresh`, and the Unity Accelerator settings (`unity config accelerator` / `--accelerator` / `unity diagnose accelerator`, listed under Deferred in the `1.0.0-beta.9` entry) — so this entry records what was still missing. + +### Added + +- **`unity assets inspect `** — new command family. A new Assets section in `projects-templates.md` covers the offline listing (asset path, GUID, payload size, preview flag), the machine formats, and the constant-memory streaming. +- **`unity build --list-targets` / `--list-profiles` / `--create-profile `** and **`unity build run`** — the build discovery and Build Profile creation options, plus launching the most recent recorded build (`--path` for another). A new subsection under Build in `build-run-test.md`, rows in the Build options table, and the `BUILD_INVALID_TARGET` pointer at `--profile`. +- **`unity open --wait`** (also `projects open` / `projects upgrade`) — documented under Projects in `projects-templates.md`: blocks until the Editor exits, exit `0` / `6`, macOS and Linux only, refused with exit `2` on Windows; plus the signal-killed-Editor reporting (inside the 150 ms startup watch without `--wait`, for the whole run with it). +- **`ProjectSettings/UnityCliConfig.json` and `unity config resolve [project]`** — the committed per-project build/test defaults layer (nine keys), the global `config set build.target …` layer beneath it, the precedence order, and the command that names which layer a value came from — in `config-hub.md`, with a pointer from Build. +- **`unity command --result-only`** — the envelope-free JSON result mode, in `integration-advanced.md`, alongside the readable rendering of `recompile` / `recompile_status` / `test_status` / `run_tests` results. +- **`unity license status`'s `floatingServer` / `machineId` fields** — in `auth-license-cloud.md`. +- **`UNITY_NO_AUTH_BROKER`, `UNITY_PEER_AUTH_MODE` / `UNITY_PEER_AUTH_LINUX_ALLOWED_HASHES`, `UNITY_CLI_HOME`, `UNITY_NO_EDITOR_IDENTITY_SERVER`** — added to the environment-variables table in SKILL.md, with a short paragraph under Auth explaining the on-demand resident auth broker, the hardware-sealed token store, and the peer code-signature check. + +### Changed + +- `unity mcp configure` — `continue` now prints `config.yaml` instructions instead of writing a file, `--dry-run` previews only the entry being changed, `codex` also relaxes the Codex sandbox network policy and refuses an unsafe `config.toml` edit, and every client config write is atomic; the MCP section also notes the desktop-screenshot fallback of `capture_game_view` / `capture_scene_view` and the `tools/list_changed` notification. +- `unity status` — the `starting` state (Editor still booting) noted alongside `unreachable`. +- `unity self-update` — noted that an interrupted download resumes on the next run and that a Brotli-compressed artifact is preferred when published. +- `unity install` — noted the bounded retry on transient download failures and that `--resume` also recovers an interrupted module download. +- Command index (SKILL.md) refreshed: `assets` added; `config` gains `resolve`; `build` gains `run`. +- Refreshed the latest-version note to `1.0.0-beta.10`. +- The `unity commands` note no longer links to the hub-only `apps/cli/docs/json-output.md`; it was the skill’s only relative link outside its own tree, so the standalone copy published to Unity-Technologies/skills is now self-contained. +- **Template selection defaults to URP.** The bootstrap workflow in `SKILL.md` and the Templates section of `projects-templates.md` now name `com.unity.template.urp-blank` (Universal 3D) and `com.unity.template.universal-2d` (Universal 2D) as the defaults, mark `com.unity.template.3d` / `com.unity.template.2d` as the Built-in Render Pipeline templates (deprecated from 6.5, removed in 6.7), and note that `renderPipeline` is blank for `universal-2d` in `templates list` output. Every `projects create` / `projects new` / `templates info` example now uses `urp-blank`. Previously the skill's examples all used the Built-in `com.unity.template.3d` and said the URP id "varies by version". + ## CLI `1.0.0-beta.9` (2026-09-08) Aligned to the CLI's `1.0.0-beta.9` release. Several pieces of this release's surface were already documented ahead of it landing in the shipped binary — `unity version`, `unity test --affected`, and the `--child-modules`/`--list-modules` spellings — and needed no change here. This pass documents the rest of the shipped surface for the first time. @@ -20,15 +45,14 @@ Aligned to the CLI's `1.0.0-beta.9` release. Several pieces of this release's su - **A `unity plugin` reference section**, new — this command family (`install`/`remove`/`upgrade`/`list`/`changelog`) shipped across earlier releases (`install`/`remove`/`upgrade` in `1.0.0-beta.7`) but had never had a dedicated write-up beyond a passing mention of `plugin install plastic`. Added now because `plugin upgrade`'s real version-comparison behavior and the new `plugin changelog ` needed somewhere to live, and documenting them in isolation without the surrounding command family would have been more confusing than useful. - **`--color ` / `--no-color`** — the new global flag, added to the global-flags table. - **`unity auth consumers`** / **`unity auth revoke `** — list and manage the applications using this machine's Unity sign-in through the auth broker. -- **`unity config get|set|list|unset `** — the generic key-value interface over the existing `proxy` / `proxy.bypass` / `update-check` settings, documented in `config-hub.md` alongside the purpose-built subcommands it shares storage with. +- **`unity config get|set|list|unset `** — the generic key-value interface over the existing `proxy` / `proxy.bypass` / `accelerator` / `update-check` settings, documented in `config-hub.md` alongside the purpose-built subcommands it shares storage with. - **`unity doctor`'s bundled third-party components section** — noted as a one-paragraph addition to the existing Doctor writeup; it's informational, not a check, so it didn't need more than that. - The always-on `cli telemetry` usage ping, the sign-in token store's machine-sealing, and the self-installed-vs-Homebrew PATH-conflict warning — each is a background/security behavior with no new command surface, so each got a sentence in the relevant existing section (Analytics, SKILL.md's Notes, and Self-update respectively) rather than a section of its own. - -- **A `unity vcs` reference section**, new (`version-control.md`) — the whole command family (`setup`/`status`/`sync`/`switch`/`doctor`/`providers`/`merge-setup`/`conflicts`/`explain`/`resolve`/`diff`/`blame`/`summarize`/`affected`/`hooks`, `vcs git` `migrate-lfs`/`worktree`, `vcs uvcs` `locks`/`changesets`/`review`) has shipped since `1.0.0-beta.7` but had no dedicated write-up until now. `SKILL.md`'s UVCS day-to-day section is reworded to point at it and to name `review` alongside the other wrapped reads. -- **"Sandboxed agent tooling can hide a running Editor"**, a new `integration-advanced.md` section under `status`, plus a matching callout in `SKILL.md` and in the `unity status`-first scene/GameObject/asset editing workflow. Interim guidance: a restrictive sandbox around an agent's own shell commands can make `unity status`/`command`/`list` report no reachable Editor even when one is genuinely running, on Windows (a separate restricted account can't read the Editor's discovery file) and macOS (a network sandbox can block the loopback connection to it). Says plainly not to conclude the Editor is down from that alone, not to quietly substitute an undisclosed workaround (e.g. a separate headless Editor invocation) for a disclosed file edit, and never to suggest disabling the sandbox. Superseded once the CLI itself reports this case with its own distinct message — this section says so and should shrink to match at that point. +- **"Sandboxed agent tooling can hide a running Editor"**, a new `integration-advanced.md` section under `status`, plus a matching callout in SKILL.md. Interim guidance: a restrictive sandbox around an agent's own shell commands can make `unity status`/`command`/`list` report no reachable Editor even when one is genuinely running, on Windows (a separate restricted account can't read the Editor's discovery file) and macOS (a network sandbox can block the loopback connection to it). Says plainly not to conclude the Editor is down from that alone, and never to suggest disabling the sandbox. Superseded once the CLI itself reports this case with its own distinct message — this section says so and should shrink to match at that point. ### Changed +- **Extended the sandboxed-agent guidance into the scene/GameObject/asset editing workflow.** The "Sandboxed agent tooling can hide a running Editor" note (added above) was previously reachable only from the top-of-skill "Drive a running Editor" quickstart. The `unity status`-first Common workflow — the section that actually fires before any scene/GameObject/prefab/asset edit — had no mention of it, so a sandboxed agent hitting a false "no Editor" there had nothing telling it to doubt that result. Observed in the wild: a Codex-sandboxed agent took a `unity status` false negative at face value and improvised an undocumented headless-Editor workaround instead of saying so and falling back to a disclosed file edit, producing an asset that wasn't actually materialized until a later build ran. The workflow now rules out Safe Mode and sandbox interference side by side before permitting the file-edit fallback, and `integration-advanced.md`'s own guidance now names the improvised-workaround failure mode explicitly, not just silent file-editing. - Command index (SKILL.md) and global-flags/environment tables refreshed for the above. - `unity install`/`install-modules`'s child-modules flag examples now lead with `--child-modules`/`--no-child-modules` (matching `unity editors module add`), noting the old `--cm`/`--no-cm` shorts still work. - `unity modules list`'s column table now names the last column `Aliases` (renamed from `downloaderName` in `--format json`). @@ -36,9 +60,7 @@ Aligned to the CLI's `1.0.0-beta.9` release. Several pieces of this release's su ### Deferred -- The Unity Accelerator feature (`unity config accelerator`, `--accelerator`/`--no-accelerator`, `unity diagnose accelerator`, the `accelerator` config key, `unity doctor`'s Accelerator section) is withheld from this publish — it is still `[Unreleased]` in the CLI's own changelog as of this release, so nothing about it appears here. -- One paragraph distinguishing `unity vcs uvcs review`'s four auth-shaped error codes is withheld from this publish for the same reason: it describes behavior a still-unreleased fix introduces (pre-fix, every failure surfaces as one generic error). The rest of that section — the commands themselves, released since `1.0.0-beta.7` — is unaffected. -- Three more pieces of hub-ahead content are withheld for the same reason, having landed in the hub's own docs after this alignment pass began: `unity context` (`save`/`use`/`list`/`current`/`delete`), `unity commands` (the plural, machine-readable command-tree introspection), and `unity watch test`/`unity watch build`. None has a published `cli-v` release yet per the CLI's own changelog. +- The `unity config accelerator` / `--accelerator` / `unity diagnose accelerator` feature itself is still `[Unreleased]` in the CLI's own changelog as of this release — despite the skill already documenting it from an earlier ahead-of-release pass. Left as-is (documenting a subset of the shipped surface is safe); this stamp does not newly assert that feature shipped. - Auth broker client libraries (the .NET/TypeScript SDKs for other products to use Unity sign-in) are not `unity` CLI commands, so nothing in this skill changes for them. ## CLI `1.0.0-beta.8` (2026-09-01) diff --git a/skills/unity-cli/SECURITY.md b/skills/unity-cli/SECURITY.md index cfbe3eb..802a315 100644 --- a/skills/unity-cli/SECURITY.md +++ b/skills/unity-cli/SECURITY.md @@ -33,6 +33,9 @@ So before acting on one, compare it against what actually changed. If the change Machine/agent mode (`unity shell --protocol ndjson`) runs the exact commands the caller sends. It validates framing (malformed or unknown requests return an error frame rather than crashing or ending the session), runs every command non-interactively, and returns structured JSON response frames (JSON-serialized, so control characters are escaped for the consuming parser). Callers must feed it **trusted input only** — commands they construct themselves — and never commands assembled from untrusted third-party content, exactly as they would guard any shell. +### Launching the project’s own build + +`unity build run` launches a player the CLI itself recorded from a previous `unity build` on the same machine — or the output the user names with `--path` — without rebuilding. It downloads nothing and runs nothing it did not just build or was not explicitly pointed at: a desktop player is started as the current user, and a WebGL build is served from a loopback-only local HTTP server that the default browser opens. Automated scanners flag documented executable paths (`./Build/…`) as local code execution; here the executable is the user’s own build artifact, on the user’s own machine, and the command refuses (exit 6) when no build has been recorded, when the recorded build’s platform cannot run on the current OS, or when its output is gone. ### Install via the official CDN The documented install downloads and runs an install script from Unity's official CDN, `public-cdn.cloud.unity3d.com`, **over HTTPS (TLS)**. This pipe-to-shell pattern is a deliberate, industry-standard install convenience for a first-party tool. Beyond TLS, the script verifies the downloaded binary against the SHA-256 published in the channel's release manifest and aborts on mismatch — or when no SHA-256 tool is available — so a corrupted, truncated, or substituted download fails instead of executing. The manifest is fetched from the same CDN origin as the binary, so this is an integrity check against a bad or altered *download*, not a defense against a compromise of the origin itself; trust in the install ultimately rests on TLS and on Unity's control of that CDN. diff --git a/skills/unity-cli/SKILL.md b/skills/unity-cli/SKILL.md index 8c708ac..a2716f0 100644 --- a/skills/unity-cli/SKILL.md +++ b/skills/unity-cli/SKILL.md @@ -16,13 +16,9 @@ unity status # confirm a connected Editor (look for state "re unity command # list the commands the Editor exposes unity command editor_play # run one — e.g. enter Play mode # Run arbitrary C# — e.g. add a GameObject named "Joe" — when the Editor exposes eval: -unity command eval --caller plugin --skill unity-cli 'new UnityEngine.GameObject("Joe");' +unity command eval 'new UnityEngine.GameObject("Joe");' ``` -**Pass `--caller plugin --skill ` on every `unity command` invocation.** `--skill` is the -skill whose instructions produced the call, so a task skill that sends you here passes its own name -rather than `unity-cli`. The flags are inert to the command itself; they only label the invocation. - ### More than one Editor open? Pass `--project-path` Every Editor-driving command takes `--project-path `. **Pass it whenever more than one Editor may be running** — without it the CLI targets the Editor whose project contains the current directory, so the target follows the shell's cwd: @@ -87,6 +83,8 @@ These work on every command: **Always use `--format json` when you need to parse output programmatically.** +`--accelerator ` and `--no-accelerator` are **not** root globals — they are accepted only on `run`, `test` and `build`, and only after the command name. See [build-run-test.md](references/build-run-test.md). + **`unity projects list` is the only command that pages IN-PROCESS.** It shows 10 projects per screen and waits for a keypress between screens, and only when stdout is a terminal. Paging is off for redirected stdout, under `--format json` and `--format ndjson`, and under `--all`, `--watch`, or `--no-pager` / `UNITY_NO_PAGER`. **Not every machine format bypasses that one.** Only `json` and `ndjson` get their own non-interactive rendering; on a terminal, `--format tsv` and `--format github` fall through to the human table and page like `human` does — so `--format tsv` on a TTY yields neither TSV nor unpaged output. Redirect stdout (the usual case for a machine format) or pass `--no-pager`. Note this is the **opposite** of the external pager below, which is `human`-only: the two mechanisms differ here, and `projects list` is the surprising one. @@ -123,8 +121,13 @@ All CLI env vars use the `UNITY_` prefix. A CLI flag always overrides the corres | `UNITY_NO_CONSENT_PROMPT` | — | Suppress the one-time first-run analytics consent prompt *without* recording a choice — for wrapper scripts on an interactive terminal that must never absorb the prompt. Analytics stay off until you run `unity analytics opt-in`. Unlike `UNITY_NON_INTERACTIVE`, it changes nothing else about command behavior. | | `UNITY_NO_CRASH_REPORT` | — | Disable anonymous crash/error reporting (Sentry) entirely. | | `UNITY_LOG_PROXY` | `--log-proxy` | Log one redacted entry per outbound request to `proxy-request.json`. Truthy values: `1`, `true`. | +| `UNITY_ACCELERATOR` | `--accelerator` | Unity Accelerator endpoint (`host:port`). Outranks the persisted `accelerator.json`; `--accelerator` outranks it. | | `UNITY_NO_ELEVATE` | `--no-elevate` | Windows: skip the elevated (UAC) install helper for `install` / `install-modules`, so the install service runs unelevated. The Editor's NSIS installer still asks for elevation on demand if Windows requires it for your account — an administrator token always does; a standard user never does. | -| `UNITY_INSTALL_RETRIES` | `--retries` | Number of times `install-modules` retries a module whose download/validation fails. `0` disables retries. | +| `UNITY_INSTALL_RETRIES` | `--retries` (`install-modules` only) | Number of times `install` and `install-modules` retry an editor or module download whose transfer or validation fails. `0` disables retries; `unity install` has no `--retries` flag, so set the variable there. | +| `UNITY_NO_AUTH_BROKER` | — | Skip the resident auth broker and read credentials directly from the OS keyring. By default every command that needs a token goes through a broker that starts on demand and exits after two idle minutes (see [auth-license-cloud.md](references/auth-license-cloud.md)). | +| `UNITY_PEER_AUTH_MODE` | — | How the auth broker and the Editor identity helper verify a connecting process’s code signature. `enforce` is the default on macOS and Windows: an unsigned or non-Unity-signed peer is refused. `identify-only` logs without refusing — use it for an Editor you built from source. Linux logs only unless set to `enforce` together with `UNITY_PEER_AUTH_LINUX_ALLOWED_HASHES` (comma-separated SHA-256 hashes of trusted executables). | +| `UNITY_CLI_HOME` | — | Install root for the install script and `unity self-install`, on every platform including Windows: the binary lands in `/bin` instead of the default location. | +| `UNITY_NO_EDITOR_IDENTITY_SERVER` | — | Disable the background identity helper that `unity open` starts to answer the Editor’s sign-in lookups when no Hub is running (see [projects-templates.md](references/projects-templates.md)). Presence-based. | **CI service account auth:** Set both `UNITY_SERVICE_ACCOUNT_ID` and `UNITY_SERVICE_ACCOUNT_SECRET` to skip the browser OAuth flow — this keeps the secret out of the process argument list and shell history. These map to the `--client-id` / `--secret-from-stdin` inputs of `unity auth login`, but reading the credentials from the environment isn't a full login: it doesn't run the interactive flow or persist credentials to the keyring. @@ -161,11 +164,11 @@ flags, environment variables, and exit codes above apply throughout. Every comma |---|---| | `auth` (login / logout / status / list / switch / default / consumers / revoke), `license` (activate / return / server), `cloud` (org / project) | [auth-license-cloud.md](references/auth-license-cloud.md) | | `editors` (list / running / add / default / path / install-path / info / upgrade / prune / verify / 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 / size / clean / exec), `releases`, `templates` (list / info / create / pack / delete) | [projects-templates.md](references/projects-templates.md) | -| `config` (proxy / update-check / get / set / list / unset), `hub install` | [config-hub.md](references/config-hub.md) | -| `run`, `test`, `build` | [build-run-test.md](references/build-run-test.md) | -| `logs`, `doctor`, `env`, `version`, `cache`, `ci init`, `analytics`, `changelog`, `language`, `completion`, `bug`, `self-update`, `self-uninstall`, `diagnose proxy` | [diagnostics-maintenance.md](references/diagnostics-maintenance.md) | -| `mcp` (+ `configure`), `skill` (install / refresh / show), `plugin` (install / remove / upgrade / list / changelog), connected editors (`pipeline` / `command` / `status` / `list`), `shell` | [integration-advanced.md](references/integration-advanced.md) | +| `projects` (list / create / new / clone / open / link / require / upgrade / export / import / pin / size / clean / exec), `releases`, `templates` (list / info / create / pack / delete), `assets` (`inspect`) | [projects-templates.md](references/projects-templates.md) | +| `config` (proxy / update-check / accelerator / get / set / list / unset / resolve), `context` (save / use / list / current / delete), `hub install` | [config-hub.md](references/config-hub.md) | +| `run`, `test`, `build` (+ `build run`), `watch` (`test`) | [build-run-test.md](references/build-run-test.md) | +| `logs`, `doctor`, `env`, `version`, `cache`, `ci init`, `analytics`, `changelog`, `language`, `completion`, `bug`, `self-update`, `self-uninstall`, `diagnose proxy`, `diagnose accelerator` | [diagnostics-maintenance.md](references/diagnostics-maintenance.md) | +| `mcp` (+ `configure`), `skill` (install / refresh / show), `plugin` (install / remove / upgrade / list / changelog), connected editors (`pipeline` / `command` / `commands` / `status` / `list`), `shell` | [integration-advanced.md](references/integration-advanced.md) | | `vcs` — `setup` / `status` / `sync` / `switch` / `doctor` / `providers` / `merge-setup` / `conflicts` / `explain` / `resolve` / `diff` / `blame` / `summarize` / `affected` / `hooks`, `vcs git` (`migrate-lfs` / `worktree`), `vcs uvcs` (`locks` / `changesets` / `review`) | [version-control.md](references/version-control.md) | | `collaboration` (alias `collab`) — `annotations` / `attachments` / `thumbnail` / `reactions` / `read` / `subscribe` / `jira` | [collaboration.md](references/collaboration.md) | @@ -219,19 +222,30 @@ unity license status --format json # if none active: unity license activa # 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.) +# (lts / latest aliases work almost everywhere a version is accepted — `templates` is the +# exception; see step 3.) 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). +# 3. List the real template ids this Editor offers — don't guess them — and pick by RENDER +# PIPELINE, not just by 2D/3D. Default to the URP templates: +# 3D → com.unity.template.urp-blank ("Universal 3D") +# 2D → com.unity.template.universal-2d ("Universal 2D": URP + the 2D packages) +# com.unity.template.3d and com.unity.template.2d are the Built-in Render Pipeline templates +# (displayName "… (Built-In Render Pipeline)"): deprecated from Unity 6.5, gone in 6.7. Use +# them only when the user explicitly asks for Built-in. Confirm the pick with the JSON +# `renderPipeline` field — it is blank for universal-2d on current releases, so match that +# one by id. +# NOTE: `templates` does NOT resolve the lts / latest aliases — unlike `install` and +# `projects create`, it passes --editor straight through and rejects anything that is not a +# concrete 6000.x.y. Use the version you just installed (read it from `editors --installed`). +unity templates list --editor <6000.x.y> --type core --format json # 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 + --editor-version lts --template com.unity.template.urp-blank ``` **Source control — let the user choose.** The CLI publishes the new project to a fresh remote in @@ -249,13 +263,13 @@ land in shell history or the process list. Pick based on the project — don't d # 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 \ + --editor-version lts --template com.unity.template.urp-blank \ --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 \ + --editor-version lts --template com.unity.template.urp-blank \ --vcs uvcs --git-namespace my-org --git-repo my-game --vcs-region ``` @@ -444,6 +458,6 @@ unity logs --follow --level info - The CLI supports kubectl-style plugins: any `unity-` binary on PATH is callable as `unity `. - Terminal output is hardened against control-character / escape-sequence injection from server-provided values (project titles, editor versions, module names) — C0 controls and non-SGR escape sequences are stripped from table/list/tree output, and now also from Commander usage errors, the `unity bug` log-archive warning, and `unity projects add`/`remove` machine (tsv) output, while SGR color/style codes are preserved. - The CLI reports anonymous crashes and errors via Sentry to help fix bugs (no IP address or hostname; home-directory paths and token-like values scrubbed before send), aligned with the Unity Hub. Opting in to analytics additionally attaches an anonymized machine id; opted-out users stay fully anonymous. Set `UNITY_NO_CRASH_REPORT` to disable reporting entirely. Separately again, every run sends one anonymous `cli telemetry` usage ping regardless of analytics/consent state — see [diagnostics-maintenance.md](references/diagnostics-maintenance.md#analytics--usagetelemetry-consent). -- The CLI is currently in **beta** (latest: `1.0.0-beta.9`). It moved to 1.0 versioning at `1.0.0-beta.1`; it's still a beta, so keep `UNITY_CLI_CHANNEL=beta` in the install command until GA ships, after which that part can be dropped. +- The CLI is currently in **beta** (latest: `1.0.0-beta.10`). It moved to 1.0 versioning at `1.0.0-beta.1`; it's still a beta, so keep `UNITY_CLI_CHANNEL=beta` in the install command until GA ships, after which that part can be dropped. - As of `0.1.0-beta.8` the CLI checks in the background for a newer version and prints an unobtrusive "update available" notice (interactive sessions only; never delays a command). Turn it off with `unity config update-check off` or the `UNITY_NO_UPDATE_CHECK` env var. - Outbound HTTP from every CLI command honors the resolved proxy (see `unity config proxy`). An invalid `--proxy` value (malformed URL or unsupported scheme) fails with a usage error (exit 2) instead of being silently ignored. Inspect what the CLI actually resolved with `unity env --format json` or `unity doctor --format json` — both surface the active proxy URL, its source, and auth source. diff --git a/skills/unity-cli/references/auth-license-cloud.md b/skills/unity-cli/references/auth-license-cloud.md index ca9ffb0..6672026 100644 --- a/skills/unity-cli/references/auth-license-cloud.md +++ b/skills/unity-cli/references/auth-license-cloud.md @@ -37,6 +37,8 @@ unity auth logout user@example.com unity auth logout --yes ``` +**How sign-in is served.** Every command’s OAuth token read goes through a resident auth broker — a background `unity` process started on demand by the first command that needs a token, exiting on its own after two idle minutes. It seals the token store to the machine’s hardware where available (a non-exportable TPM key on Windows, TPM2 via `systemd-creds` on Linux, then DPAPI, the Secret Service, the Keychain and a local key file, in that order), and `unity doctor` reports the active tier. On macOS and Windows it verifies a connecting process’s code signature and refuses an unsigned or non-Unity-signed peer; set `UNITY_PEER_AUTH_MODE=identify-only` to log without refusing (for an Editor you built from source), and `UNITY_NO_AUTH_BROKER=1` to bypass the broker and read the OS keyring directly. `unity auth consumers` (below) lists the applications that have used this machine’s sign-in through it. + #### Multiple accounts The CLI stores more than one signed-in account and keeps one of them *active*. `unity auth login` adds an account; these three manage the set. @@ -131,6 +133,8 @@ 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. +`unity license status` also reports `floatingServer` (the licensing server this machine is configured against) and `machineId` (the identity the licensing client reports to it) — the two values to match against a lease record when a floating seat looks stuck. Both are always present in `--format json` / `ndjson`; human and `tsv` output shows them only when a floating server is configured. + `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). **Service accounts.** The `license` commands recognize service-account sessions (`UNITY_SERVICE_ACCOUNT_ID` / `UNITY_SERVICE_ACCOUNT_SECRET`, or `unity auth login --client-id`): `unity license status` reports `Signed in: yes (service account)` and includes the auth mode in JSON. Unity's licensing backend does **not** accept service-account tokens for license activation, so with a service-account session the default entitlement mode and `--personal` fail up front — before contacting the licensing client — with guidance toward the unattended options (`--floating`, `--file`, `--generate-request`, or a perpetual `--serial`). `unity license return` lists and returns serial-activated licenses too (not just assigned/subscription seats) — important for CI machines that activate per run — and returns each license individually, so when only some can be freed it reports what succeeded (in text and in the JSON `returned` / `failed` fields) instead of an all-or-nothing failure. diff --git a/skills/unity-cli/references/build-run-test.md b/skills/unity-cli/references/build-run-test.md index 9f2fe59..7f97bef 100644 --- a/skills/unity-cli/references/build-run-test.md +++ b/skills/unity-cli/references/build-run-test.md @@ -287,6 +287,32 @@ Options: `--mode EditMode|PlayMode`, `--filter `, `--output `, `- --- +### Watch — re-run affected tests on file change + +`unity watch test` is a thin loop around `unity test --affected`: it runs once immediately, then re-runs on every project file change, so the inner dev loop no longer means re-typing `unity test --affected` by hand after each edit. + +```bash +unity watch test /path/to/MyProject +unity watch test . --filter "MyNamespace.MyTests" +unity watch test . --ignore "*.log" --ignore Recordings +``` + +**One run at a time, always.** A run in flight is always allowed to finish; changes that arrive while it is running only mark the next run pending, and a burst of them (a multi-file save, a branch switch) coalesces into exactly one follow-up run rather than one per file. Two Editor invocations against the same project can never overlap. + +**Ignored by default:** `Library/`, `Temp/`, `Logs/`, `Build/`, `obj/` — matched case-insensitively wherever they appear in the project tree, and no file watcher is even attached to a top-level directory that matches, so Unity's own import churn under `Library/` never reaches the CLI. `--ignore ` (repeatable) adds more file/directory glob patterns on top of that default set; there is no flag to remove a default entry. + +**Ctrl-C** while idle (between runs, waiting for the next change) exits cleanly with no Editor running. Ctrl-C while a run is in flight terminates the CLI and the spawned Editor together, the same as a plain `unity test` — never an orphaned Editor process either way. + +**Refuses to start** under `--non-interactive`, or when a `CI` environment variable is detected, since the loop has no exit condition of its own and would otherwise hang a job indefinitely. + +`unity watch test` deliberately exposes a narrower flag set than `unity test` itself — no `--shard`, `--coverage`, `--retries`, `--rerun-failed`, `--affected-compare`, or `--output`/`--report-format` (the report path is fixed internally, which is also what keeps a run's own report write from re-triggering itself). Reach for `unity test --affected` directly when you need those. + +Options: `--mode EditMode|PlayMode`, `--filter `, `--editor-version ` (env `UNITY_EDITOR_VERSION`), `-e, --editor-path `, `-a, --architecture `, `--allow-install`, `--timeout `, `--ignore ` (repeatable). + +`unity watch build` (re-running `unity build` on change) is a documented follow-up, not yet implemented. + +--- + ### Build The first-class build workflow. Rule of thumb vs `unity run`: building a player → `unity build`; anything else headless → `unity run`. @@ -315,6 +341,9 @@ unity build /path/to/MyProject --profile "Windows Release" --output-path ./Build | `--target ` | Build target (required unless `--profile` is used). | | `--execute-method ` | Static C# method to invoke, e.g. `Builder.PerformBuild`. Optional: without it, the CLI uses Unity's built-in build. | | `--profile ` | Build profile: a `.asset` path or a profile name in `Assets/Settings/Build Profiles` (Unity 6+; the profile defines the target). | +| `--list-targets` | List every valid `--target` value — flagged zero-code (the built-in build works) or needing `--execute-method` / `--profile` — then exit. | +| `--list-profiles` | List the project’s Build Profile assets (Unity 6+), then exit. | +| `--create-profile ` | Create a Build Profile for a target and exit without building (Unity 6+); build with it afterwards via `--profile`. | | `--build-target-group ` | Forwarded to Unity as `-buildTargetGroup`. | | `-o, --output-path ` | Output path. With `--execute-method`, passed as `-buildOutput` (your method must honor it); otherwise the built-in build's destination (required). | | `-l, --log-file ` | Log file path. Default: `/Logs/build--.log`. Streamed to stdout by default (see `--no-tail`). | @@ -365,4 +394,71 @@ unity build /path/to/MyProject --target StandaloneOSX --execute-method Builder.B # { "success": true, "command": "build", "data": { "target": "...", "logFile": "..." } } ``` +#### Discover targets, create profiles, launch the last build + +```bash +# Every valid --target value, flagged zero-code (built-in build works) or needing --execute-method / --profile +unity build /path/to/MyProject --list-targets --format json + +# The project’s Build Profile assets (Unity 6+) — the supported way to build partner or +# package-provided platforms, such as Meta Quest, that are not in --target’s list +unity build /path/to/MyProject --list-profiles --format json + +# Create a Build Profile for a target and exit without building (Unity 6000.0+), then build with it +unity build /path/to/MyProject --create-profile WebGL +unity build /path/to/MyProject --profile WebGL --output-path ./Build/web + +# Launch the project’s most recent recorded build without rebuilding (recorded = built with a known --output-path) +unity build run /path/to/MyProject +unity build run /path/to/MyProject --path ./Build/other/MyGame.exe # a different recorded build +``` + +`--list-targets`, `--list-profiles` and `--create-profile` each do their job and exit — no build happens. A `--target` outside the classic catalog fails with `BUILD_INVALID_TARGET` and points at `--profile`. A successful `unity build` with a known output path — a built-in build (`--output-path` is required there) or a `--profile` / `--execute-method` build that passed `--output-path` — records that path together with the target, architecture and Editor version, and `build run` launches that recording: a desktop player natively, a WebGL build from a loopback-only local HTTP server that opens in the default browser. An `--execute-method` build without `--output-path` chooses its own destination inside the method, so it records nothing and leaves any earlier record in place; launch such a build with `build run --path ` instead. `build run` fails cleanly (exit 6) when no build has been recorded yet, when the recorded build’s platform cannot run on this OS, or when its output is gone. + +**Per-project defaults.** A committed `ProjectSettings/UnityCliConfig.json` declares `unity build` / `unity test` defaults (`build.target`, `build.outputPath`, `build.profile`, `build.timeout`, `test.mode`, `test.reportFormat`, `test.coverage`, `test.coverageOptions`, `test.timeout`) so they need not be repeated on every invocation; `unity config resolve [project]` shows the resolved value and which layer supplied it. See [config-hub.md](config-hub.md). + --- + +### Unity Accelerator — shared asset-import cache + +The [Unity Accelerator](https://docs.unity3d.com/Manual/UnityAccelerator.html) is Unity's asset-import cache server: on import the Editor downloads a prebuilt artifact on a hash hit instead of re-importing. It pays off exactly where the CLI is used most — clean CI checkouts, ephemeral containers, branch switches, parallel agent worktrees. + +**Persist the endpoint once** with `unity config accelerator ` (see [config-hub.md](config-hub.md)), and `run`, `test` and `build` inject it automatically. Per-invocation control: + +| Flag | Description | +|---|---| +| `--accelerator ` | Endpoint for this invocation. Also via `UNITY_ACCELERATOR`. A bare host defaults to port `10080`. | +| `--no-accelerator` | Ignore any configured Accelerator for this invocation. | + +**Both are scoped to `run`, `test` and `build`, and go after the command name.** They are deliberately not root globals: every other command would accept an endpoint it can never act on, then still fail as a usage error on a malformed value. `unity --accelerator … build` is an `unknown option` error (exit 2) — put the flag after the command instead. + +```bash +# Uses the persisted endpoint automatically +unity test /path/to/MyProject + +# One-shot override / opt-out +unity build /path/to/MyProject --target StandaloneLinux64 --accelerator cache.example.com:10080 +unity test /path/to/MyProject --no-accelerator +``` + +When an endpoint resolves, the CLI appends `-EnableCacheServer -cacheServerEndpoint ` to the Editor argv and says so (`Using Unity Accelerator at … (source: settings).`). When nothing resolves, the argv is byte-identical to a CLI without this feature. `--no-accelerator` reports that it suppressed a configured endpoint, which is deliberately distinct from the silence of a machine that has none. + +**`unity run`, `unity test` and `unity build` inject. `unity open` does not** — interactive opens have their own argv builder and are a known follow-up; configure the Accelerator in Editor Preferences for interactive work in the meantime. + +**Reserved:** `-EnableCacheServer` and `-cacheServerEndpoint` are rejected if you forward them yourself (exit 6) — the CLI manages that pair. Matching is case-insensitive and covers the `--flag` and `-flag=value` spellings. + +**Everything else in the family stays forwardable**, and the injected pair is placed *before* your tail so Unity's last-wins parser lets your values win: `-cacheServerEnableImportResultCaching`, `-cacheServerNamespacePrefix`, `-cacheServerEnableDownload true|false`, `-cacheServerEnableUpload true|false`, `-cacheServerWaitForConnection `, `-cacheServerDownloadBatchSize `, `-cacheServerUploadExistingImports`, `-cacheServerUploadAllRevisions`, `-cacheServerUploadExistingShaderCache`, and the `-disableShaderCacheRemote*` / `-disableTextureCacheRemote*` families (each with `…Download` / `…Upload` sub-variants). + +```bash +unity test /path/to/MyProject -- \ + -cacheServerEnableImportResultCaching \ + -cacheServerNamespacePrefix "ci-6000.0" \ + -cacheServerWaitForConnection 10000 +``` + +**Import result caching is disabled by default from Unity 6.5 in new projects.** On a new 6.5+ project, connecting to an Accelerator is not by itself enough to get import-result reuse — pass `-cacheServerEnableImportResultCaching` or enable it in the project. + +**A configured endpoint can still be ignored.** Every `-cacheServer*` argument overrides *Editor Preferences*, not Project Settings; `ProjectSettings/EditorSettings.asset`'s `m_CacheServerMode` decides whether preferences are consulted at all (`0` = Use global settings, `1` = Enabled, `2` = Disabled). A project on mode `2` ignores the injected flags, and the CLI emits a warning (never a failure — the run proceeds). Mode `1` is not warned about: whether a project-pinned endpoint beats an injected one is unmeasured, and a false warning would be worse than none. Diagnose with `unity diagnose accelerator` (see [diagnostics-maintenance.md](diagnostics-maintenance.md)); full explanation in `apps/cli/docs/accelerator.md`. + +--- + diff --git a/skills/unity-cli/references/config-hub.md b/skills/unity-cli/references/config-hub.md index 0255228..cc31267 100644 --- a/skills/unity-cli/references/config-hub.md +++ b/skills/unity-cli/references/config-hub.md @@ -60,6 +60,39 @@ unity config update-check on # enable unity config update-check --json ``` +#### config accelerator + +View or change the [Unity Accelerator](https://docs.unity3d.com/Manual/UnityAccelerator.html) (asset-import cache server) endpoint. Once persisted, `unity run`, `unity test` and `unity build` inject it into the Editor automatically — see [build-run-test.md](build-run-test.md). + +```bash +# Show the resolved endpoint and its source +unity config accelerator +unity config accelerator --json + +# Persist an endpoint +unity config accelerator cache.example.com:10080 + +# A bare host defaults to port 10080 (the Accelerator default) +unity config accelerator cache.example.com + +# Clear the persisted endpoint (reports whether there was anything to clear) +unity config accelerator --unset +``` + +**The value is `host:port`, not a URL.** A scheme is rejected rather than stripped (`http://cache.example.com:10080` fails with exit 6), because `-cacheServerEndpoint` takes a host and a port — persisting a URL would produce a silent non-connection later. IPv6 literals are bracketed: `[::1]:10080`. + +**Resolution priority** (highest → lowest): +1. `--accelerator ` — accepted only on `run` / `test` / `build`, after the command name (one-shot override for that invocation) +2. `UNITY_ACCELERATOR` env var +3. Persisted `accelerator.json` (`unity config accelerator `) +4. None + +The reported source is one of `flag`, `env`, `settings`, `none`. The env var and the persisted file are resolved on **every** command, which is why `unity diagnose accelerator` can report them; only the flag is scoped to the three commands that inject. A malformed higher-priority candidate is skipped rather than fatal — except an explicit `--accelerator`, which fails as a usage error (exit 2) instead of silently falling through. + +`unity config accelerator` with no argument reports the `env` → `settings` → `none` view of persistent configuration. Use `unity diagnose accelerator` (see [diagnostics-maintenance.md](diagnostics-maintenance.md)) for the same resolution plus project settings and reachability. Neither command accepts `--accelerator`, so to see what a one-shot override resolves to, pass it to the `run` / `test` / `build` invocation that uses it. + +**A configured endpoint is not always enough.** Every `-cacheServer*` argument overrides *Editor Preferences*, not Project Settings, and `ProjectSettings/EditorSettings.asset`'s `m_CacheServerMode` decides whether preferences are consulted at all. A project set to `Disabled` (mode `2`) ignores the injected flags; the CLI warns when it sees that. Full explanation: `apps/cli/docs/accelerator.md`. + --- ### config get / set / list / unset — read or write any setting by key @@ -75,6 +108,7 @@ unity config list --format json unity config get proxy # Write one key (validated the same way its dedicated command would validate it) +unity config set accelerator cache.example.com:10080 unity config set update-check off # Clear one back to its default @@ -87,10 +121,56 @@ Recognized keys, and what they back onto: |---|---|---| | `proxy` | `unity config proxy ` | Secret-shaped values are redacted on read/echo (`http://***:***@host`) — the real value is still stored and used. | | `proxy.bypass` | `unity config proxy --bypass ` | Comma-separated hosts; writing/clearing it leaves the sibling `proxy` key untouched. | +| `accelerator` | `unity config accelerator ` | Normalized to `host:port` on write. | | `update-check` | `unity config update-check on\|off` | Value is `on`/`off`. | An unknown key, a read-only key (none exist yet — the mechanism exists for a future resolved-only value), or an invalid value for a writable key is rejected with exit **2** and a message pointing at `unity config list`. `--format json` returns `{key, value}` for `get`/`set`, `{key, cleared}` for `unset`, and `{entries: [{key, value, writable}, …]}` for `list`. +#### config resolve — build/test defaults and the per-project `UnityCliConfig.json` + +A committed `ProjectSettings/UnityCliConfig.json` declares `unity build` / `unity test` defaults for a project so a team stops repeating them on every invocation and in every CI workflow. The CLI finds it by walking up from the working directory (or the explicit project path) to the project root, and reads nine keys: `build.target`, `build.outputPath`, `build.profile`, `build.timeout`, `test.mode`, `test.reportFormat`, `test.coverage`, `test.coverageOptions`, `test.timeout`. The same keys can be set globally with `unity config set build.target …`. + +Precedence, highest first: command-line flag, environment variable (only `build.timeout` / `test.timeout` have one), the project file, the global config layer, then the CLI’s built-in default. A flag exists only on the `unity build` / `unity test` invocation itself, so `config resolve` never reports `flag`: its `source` is one of `env`, `project`, `global` or `default`. + +```bash +# Which value applies, and which layer supplied it: env, project, global, or default +unity config resolve build.target /path/to/MyProject +unity config resolve test.mode --format json # {key, value, source} +``` + +--- + +### Context — named sets of the five defaults + +The CLI keeps five defaults, each normally set by its own command: the active account (`auth switch`), the default organization (`cloud org set-default`), the default cloud project (`cloud project set-default`), the default editor (`editors default`) and the install path (`install-path`). A **context** is a name for one combination of all five, so moving between two setups is one command instead of five in the right order. + +```bash +# Record the current five settings under a name +unity context save work + +# Apply them again later — all five, or none +unity context use work + +# What exists, and which one is currently in effect +unity context list +unity context current + +# Forget one (the settings it named are left as they are) +unity context delete work +``` + +Names may use letters, digits, dots, dashes and underscores, up to 64 characters, and are matched case-insensitively — re-saving an existing name overwrites it in place. + +**Applying is all-or-nothing.** The account, editor and install path are validated before anything is written; the organization and project are then checked against Unity Cloud under the account the context selects. Any failure names the missing item, exits **6**, and leaves every setting exactly as it was — a context pinning an editor you have since uninstalled fails with that editor's version rather than half-switching. + +**A context clears what it does not pin.** Switching to a context that names no organization clears the organization rather than leaving the previous one's behind. The one exception is the account: there is no "signed in as nobody", so a context naming no account leaves the active one alone (and `unity context current` will still match such a context whoever is signed in). + +**Offline and signed-out still work.** When Unity Cloud cannot be reached the stored organization and project are applied as-is and a warning says they were not verified, rather than the switch being refused. + +`unity context use` reports every setting with a `*` against the ones that changed. The `setting` values are stable machine tokens — `account`, `organization`, `project`, `editor`, `install-path` — in every format, human included, so a script can key on them. Only `unity context list`'s column *headers* are translated. + +Two name collisions worth knowing: this is unrelated to `unity build --profile`, which names a Unity Build Profile asset; and inside `unity shell`, bare `context` still prints that session's own ephemeral project/org selection, while `context ` reaches this group. + --- ### Hub — install the Unity Hub application diff --git a/skills/unity-cli/references/diagnostics-maintenance.md b/skills/unity-cli/references/diagnostics-maintenance.md index e29e1fc..224cd12 100644 --- a/skills/unity-cli/references/diagnostics-maintenance.md +++ b/skills/unity-cli/references/diagnostics-maintenance.md @@ -44,7 +44,7 @@ unity doctor --format json 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. It also runs environment health checks and reports pass/warn per check (in every output format): whether the `unity` binary's directory is actually on `PATH` (the top post-install pitfall on Windows, where a new terminal is needed), whether multiple `unity` binaries shadow each other on `PATH`, whether Windows long-path support is enabled, and whether a git credential helper is configured (`git-credential-helper`: advisory for the git-token flows in `projects clone`/`create`/`link vcs`; the row is omitted on machines without git). +`unity doctor` reports real session state (matching `unity auth status`) and surfaces the resolved proxy URL, its source, and auth source. It carries an **Accelerator** section alongside the Proxy one, reporting the resolved endpoint and its source and — when a project is in scope — that project's cache-server mode and pinned endpoint. Three states, mirroring Proxy: a table, a plain `No Unity Accelerator configured.` (the common case, not a fault), or `Accelerator state unknown` when the configuration could not be read. Nothing there is a *check*: whether the endpoint answers is `doctor --ci`'s question, because the default collector is synchronous and cannot make a network call. It also runs environment health checks and reports pass/warn per check (in every output format): whether the `unity` binary's directory is actually on `PATH` (the top post-install pitfall on Windows, where a new terminal is needed), whether multiple `unity` binaries shadow each other on `PATH`, whether Windows long-path support is enabled, and whether a git credential helper is configured (`git-credential-helper`: advisory for the git-token flows in `projects clone`/`create`/`link vcs`; the row is omitted on machines without git). A **"Third-party components"** section lists every open-source runtime dependency the binary bundles — the .NET runtime plus each direct NuGet package — with its version and SPDX license identifier, and points at `https://spdx.org/licenses/` for the full texts (not embedded, to keep the binary small). It's generated from the CLI's own build configuration, so it can never drift from what actually shipped, and it's informational only — never a pass/fail check. @@ -126,6 +126,8 @@ Exit codes distinguish the two kinds of bad news, so a workflow can retry only w A `6` outranks a `7` when both occur, so a real blocker is never reported as retryable. +`--ci` also probes the configured Unity Accelerator, so a CI agent learns the cache server is down in seconds instead of discovering it as an unexplained twenty-minute import. **This check never blocks, in any arm** — an Accelerator is an accelerator, so an unreachable one is a `warn` (`ACCELERATOR_UNREACHABLE`, classified retryable) and a machine with none configured is an `info` row (`ACCELERATOR_NOT_CONFIGURED`). A project that does not use an Accelerator can never have its preflight failed by it. The probe targets the endpoint the CLI would hand to the Editor (the resolver's answer), not the project's own pinned endpoint. + Every check carries a machine-readable `code` (`LICENSE_NONE`, `EDITOR_NOT_INSTALLED`, `DISK_SPACE_LOW`, `NETWORK_UNREACHABLE`, …) plus a remediation `hint`. In `--format json` the per-check results stay in `data` even on failure, with one coded entry per failure in `errors`. Output is redacted and carries no tokens and no absolute user paths, so it is safe to paste into a public CI log. `--ci` is always explicit — it is never inferred from `CI=true`, because a report that silently changed shape and exit code on a runner would be a trap. Note that the CLI already defaults to `--format tsv` whenever stdout is redirected, which in CI it usually is; that output leads with a `verdict` row. @@ -146,6 +148,27 @@ Reports the resolved proxy and where it came from, PAC configuration, CA bundle, --- +### Diagnose accelerator — Unity Accelerator diagnostic report + +```bash +# Resolved endpoint, project cache-server settings, and whether the endpoint answers +unity diagnose accelerator + +# Machine-readable +unity diagnose accelerator --json +``` + +A working Accelerator and a broken one produce identical output apart from wall-clock time. This is the command that tells them apart. It reports four sections: + +- **Resolved configuration** — the endpoint and its source (`env` / `settings` / `none`), and whether the Accelerator was disabled. This command does not accept `--accelerator` or `--no-accelerator` (both are scoped to `run` / `test` / `build`), so it reports what the env var and the persisted setting resolve to — the endpoint any command would start from, before a one-shot override. +- **Environment variables** — `UNITY_ACCELERATOR` by **presence only**, never by value (a host and port is infrastructure detail a support paste should not carry). The character length is included, enough to tell "set" from "set to empty". +- **Project cache server** — the project's `m_CacheServerMode` (as Unity's own inspector labels it) and `m_CacheServerEndpoint`, and whether they agree with the resolved endpoint. There is no "void case": a project's cache-server mode never makes an injected endpoint moot — command-line flags always win — so the report states a mismatch as a fact without claiming which side the Editor uses. +- **Reachability** — a raw TCP connect with a 5-second timeout, reporting elapsed time and a familiar error code on failure (`ENOTFOUND`, `ECONNREFUSED`, `ETIMEDOUT`, …). A successful connect proves the port is reachable, **not** that an import will get a cache hit, and the report says so. + +**An unreachable endpoint is a reported row, not a command failure** — the command exits `0` having successfully diagnosed a broken endpoint. `--format json` emits the standard envelope; every other format writes the plaintext report raw to stdout so it survives a pipe or a CI log. `--quiet` is honoured. Full explanation of the mechanism: `apps/cli/docs/accelerator.md`. + +--- + ### Environment ```bash @@ -374,6 +397,8 @@ unity self-update --rollback - **Linux AppImage** — updates in place: downloads the new `.AppImage` artifact, verifies its checksum against the release manifest, and atomically replaces the AppImage you launched (`--rollback` restores the previous one). The embedded zsync update info is preserved, so external updaters (AppImageUpdate, Gear Lever) keep working. - **Package-manager install** — points you at the owning manager instead of replacing the binary. The `.deb` and `.rpm` packages are published to Unity's apt and rpm repositories on every beta and GA release (rpm packages are GPG-signed), so a package-managed install stays current through the system package manager: `sudo apt update && sudo apt upgrade unity-cli` on Debian/Ubuntu, `sudo dnf upgrade unity-cli` on Fedora/RHEL. +Downloads go through the CLI’s regular download engine: an interrupted download (a dropped connection, a closed lid, a Ctrl-C) resumes from where it left off on the next `unity self-update`, and a Brotli-compressed artifact is preferred when the release publishes one — verified against its own checksum and again after decompression. A release with no compressed artifact for your platform falls back to the raw download. + `--check`, `--changelog`, and `--dry-run` work everywhere. The background "update available" notice is package-manager-aware: when the release manifest says your install's package manager already carries the new version, the notice suggests that manager's exact upgrade command instead of `unity self-update`; installs whose manager doesn't carry the release yet stay quiet. The same background check also warns when a self-installed `unity` and a Homebrew-managed one are **both** on `PATH` — a state where `which unity` keeps resolving to the self-installed copy while `brew upgrade` updates the other, so the two silently drift apart. The notice points at `unity self-uninstall -y` to remove the self-installed copy so Homebrew is the only one managing updates going forward. diff --git a/skills/unity-cli/references/editors-install.md b/skills/unity-cli/references/editors-install.md index 40f3807..d6eb121 100644 --- a/skills/unity-cli/references/editors-install.md +++ b/skills/unity-cli/references/editors-install.md @@ -225,7 +225,7 @@ 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) +# Resume an interrupted download — editor installer or module — (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 @@ -248,7 +248,7 @@ unity install 6000.0.47f1 -m android -m ios # repeated flag (same effect) unity install 6000.0.47f1 --no-elevate --yes --accept-eula ``` -When installing an editor with several modules, a failed module no longer aborts the whole batch — `unity install` (and `unity install-modules`) continue with the remaining items and exit non-zero if any failed. Each editor and module is listed as installed (✓), failed (✗), or pending (·); the NDJSON `result` frame carries the same breakdown as an `items` array (each entry has `uid`, `name`, `kind`, `status`), so scripts can tell exactly which modules succeeded even on a non-zero exit. +A transient editor or module download failure (a dropped connection, a truncated transfer) is retried with the same bounded policy `install-modules` already uses (two attempts by default; `UNITY_INSTALL_RETRIES` sets the count for both commands, and the `--retries` flag exists on `install-modules` only — `unity install` has no such flag) before the install fails. When installing an editor with several modules, a failed module no longer aborts the whole batch — `unity install` (and `unity install-modules`) continue with the remaining items and exit non-zero if any failed. Each editor and module is listed as installed (✓), failed (✗), or pending (·); the NDJSON `result` frame carries the same breakdown as an `items` array (each entry has `uid`, `name`, `kind`, `status`), so scripts can tell exactly which modules succeeded even on a non-zero exit. **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. diff --git a/skills/unity-cli/references/integration-advanced.md b/skills/unity-cli/references/integration-advanced.md index f64ad89..31a93c7 100644 --- a/skills/unity-cli/references/integration-advanced.md +++ b/skills/unity-cli/references/integration-advanced.md @@ -61,6 +61,8 @@ unity mcp --project-path /path/to/MyProject `unity mcp` no longer accepts `--instance `: talking to an Editor requires that Editor's per-instance auth token, which a bare host and port can't carry, so the CLI always discovers running Editors itself — run from the project directory or pass `--project-path` to target one. Editors launched to create a new project (`-createproject`) are discovered too. +The `capture_game_view` / `capture_scene_view` tools fall back to an OS-level screenshot of the whole desktop when the Editor’s main thread does not respond in time (a modal dialog, for example); the result says so in a note, since it captures the screen rather than the specific view. The server also declares support for `tools/list_changed` and notifies the client when the tool catalog changes, so a session started before any Editor was running picks up the Editor’s tools without a restart. + #### 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`. @@ -82,6 +84,8 @@ unity mcp configure vscode --yes unity mcp configure vscode --dry-run ``` +`--dry-run` prints only the entry that would be added or changed, not the whole config file. `continue` no longer writes a file — Continue reads `config.yaml`, not the deprecated `config.json` — and prints setup instructions instead. `codex` also relaxes Codex’s sandbox network policy so `unity mcp` and a direct `unity command` can reach the Editor over localhost, and refuses any edit to `config.toml` it cannot prove safe rather than corrupting the file. Every client config write is atomic, and a `--local` write refuses to follow a symlinked path component. + --- ### Skill — install this skill into an AI client @@ -310,8 +314,14 @@ unity command --runtime-path /path/to/port-file # Set a timeout (default: 30 seconds) unity command editor_play --timeout 60 + +# Only the Editor’s own result value, as JSON — no command/parameters/target envelope +# (implies --format json; cannot be combined with --detach) +unity command recompile_status --result-only ``` +In the human table, `recompile`, `recompile_status`, `test_status` and `run_tests` results render as short readable text in the Result column instead of a JSON blob; `--format json` / `ndjson` output is unchanged. + #### Querying the command list A mature project's Pipeline catalog gets long, so the **listing** form of `unity command` (no command name) accepts query flags that filter, group, sort, and page it — the fastest way for an agent to find the right command without pulling the whole catalog: @@ -353,9 +363,23 @@ Two traps worth knowing: - **`--group_by` is spelled with an underscore**, unlike every other flag on the CLI. That is deliberate and load-bearing, so don't "correct" it to `--group-by`. - **These flags only mean "listing" when no command name is given.** With a command name they are forwarded to that Pipeline command as ordinary parameters — `unity command my_cmd --query foo` passes `query: foo` to `my_cmd`. That is why each takes an *optional* value: a bare `--query` forwards boolean `true` to the command, while the listing path rejects a bare flag with a clear error rather than guessing. +#### commands — the CLI's own command tree, as JSON + +**Not to be confused with `unity command` above** — `unity command` (singular) lists the *connected Editor's* Pipeline commands; `unity commands` (plural) lists *this CLI binary's own* commands, subcommands, arguments, and flags. Use it instead of parsing `--help` output when you need to introspect what the `unity` binary itself can do: + +```bash +# The full command tree, machine-readable +unity commands --format json + +# A compact human listing (name + description, one indented line of subcommand names) +unity commands +``` + +Each node in `data.commands` carries `name`, `aliases`, `description`, `arguments` (positional, with `required`/`variadic`), `options` (this command's own flags: `long`/`short`/`valuePlaceholder`/`default`/`description`), `globalOptions` (same shape — flags inherited from every ancestor, so `--format`/`--json`/etc. show up on every node without repeating a root-level dump, and a mid-tree umbrella's own options show up on its descendants too), and `subcommands` (the same shape, recursively). Hidden and dev-only surfaces are excluded — the same visibility rule `--help` uses — so what you see is exactly what the current build actually exposes. + #### Available in production — the common live commands -Everything reached through **`unity command `** is part of the project's `com.unity.pipeline` package and works against a normal, **production** Editor (or a Player runtime via `--runtime`) — it is *not* development-gated. Don't refuse a live-Editor task on the assumption that driving the Editor requires a development build — it doesn't. +Everything reached through **`unity command `** is part of the project's `com.unity.pipeline` package and works against a normal, **production** Editor (or a Player runtime via `--runtime`) — it is *not* development-gated. A live-Editor task never needs a development build: a production Editor exposes this command surface, so treat the Editor as drivable whenever `unity status` reports one. The Pipeline package ships a set of built-in scene/GameObject commands. The common ones (names and parameters come from the Editor, so confirm the exact set with `unity command` / `unity list`): @@ -404,7 +428,7 @@ 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. +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. An Editor that is still starting up is reported as `starting` rather than `ready` — the CLI probes the Editor’s main thread directly — so a script that polls `status` does not treat a booting Editor as ready. Read the error code, not the exit code: `starting` yields `STATUS_NOT_READY`, and all three failure codes below exit 6. With `--format json`/`ndjson`, emits a `success: false` envelope (`STATUS_NO_INSTANCES` / `STATUS_NOT_READY` / `STATUS_ALL_UNREACHABLE`) and a non-zero exit when no Editor is reachable, so CI scripts can gate on Editor availability. #### Sandboxed agent tooling can hide a running Editor diff --git a/skills/unity-cli/references/projects-templates.md b/skills/unity-cli/references/projects-templates.md index 6f1676e..4fa2c6e 100644 --- a/skills/unity-cli/references/projects-templates.md +++ b/skills/unity-cli/references/projects-templates.md @@ -24,6 +24,9 @@ unity projects info /path/to/MyProject --format json # Open a project in the editor unity open /path/to/MyProject +# Block until the Editor exits and report its real outcome — macOS/Linux only (exit 0 clean, 6 failed) +unity open /path/to/MyProject --wait + # Open with a specific editor version unity open /path/to/MyProject --editor-version 6000.0.47f1 @@ -42,6 +45,8 @@ The project argument is matched against the Hub registry first (exact name or pa **Signed-in Editor, no Hub required.** `unity open` starts a small background identity helper that answers the Editor's account lookup with the session `unity auth login` stored — your account, organization list (so Package Manager entitlements resolve), and the service addresses for your resolved `--cloudEnvironment` — so a Hub-less machine gets a signed-in Editor instead of an anonymous one. It steps aside whenever a real Hub is running or starting, exits on its own a few minutes after the Editor stops using it, and can be disabled with `UNITY_NO_EDITOR_IDENTITY_SERVER`. Signed out, the Editor just starts anonymous, as before. +**`--wait` — a real exit code from an interactive open.** By default `unity open`, `unity projects open` and `unity projects upgrade` return once the hand-off to the Editor completes, watching it only briefly for an instant failure. `--wait` blocks for as long as the Editor runs and exits `0` when it exits cleanly or `6` (`OPEN_EDITOR_EXITED`, or the licensing diagnosis for a 198) when it fails. The Editor runs in its own process group: Ctrl-C is absorbed, the wait always runs to completion, and the Editor is never touched. macOS and Linux only for now — Windows refuses `--wait` with exit `2` rather than falling back to the bounded watch. Without `--wait`, the CLI watches the Editor for only about 150 ms after launch, so an Editor killed by a signal is reported as a failure only when that happens inside the startup window; once the command has returned, nothing further can be reported. `--wait` is what covers the Editor’s whole lifetime, and it reports a signal death as a failure too. `projects create --open` / `projects new --open` do not take `--wait`. + **Reserved flags — do NOT pass these via `--args`.** `-projectPath` is managed by the command (Unity's parser is last-wins, so forwarding it would silently redirect the open to a different project), and `-useHub`/`-hubIPC` are deliberately never passed — they tell the Editor a Unity Hub manages its session, which the CLI is not. Passing any of them fails fast, before launch, with exit code 6: ``` @@ -55,7 +60,7 @@ All three spellings Unity accepts are rejected (`-useHub`, `--useHub`, `-useHub= Create a project. On a TTY, prompts for any missing options (parent directory, editor version, template) and then asks whether to link the project to a Unity Cloud project — that last question defaults to **No**, so pressing Enter creates an unlinked project. 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 +unity projects create MyGame --editor-version 6000.0.47f1 --template com.unity.template.urp-blank # Place the project in a specific directory unity projects create MyGame --path /path/to/projects --editor-version 6000.0.47f1 @@ -125,7 +130,7 @@ Create a project without any interactive prompts — resolves missing options fr 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 +unity projects new MyGame --path /path/to/projects --editor-version 6000.0.47f1 --template com.unity.template.urp-blank # Open the project immediately after creation unity projects new MyGame --open @@ -227,6 +232,14 @@ to 50 and caps at 500, and the envelope's `truncated` tells you when there was m self-hosted workspace has no reviews API — those commands refuse with `VCS_UVCS_REVIEW_SELF_HOSTED` and point at the GUI rather than failing obscurely. +**They need a signed-in session, and the three auth-shaped failures mean different things.** +`unity auth login` is all you have to do; the short-lived gateway token these commands +authenticate with is obtained for you. `NOT_SIGNED_IN` and `SESSION_EXPIRED` (both exit 3) mean +sign in again. `UVCS_TOKEN_UNAVAILABLE` (exit 6) means that token could not be obtained at all — +a connectivity or service problem, not a credential one, so re-running sign-in will not help. +`VCS_UVCS_REVIEW_REQUIRE_AUTH` (exit 3) is the reviews service itself refusing a credential the +CLI did obtain. Do not treat them as one condition: only the first two are worth a login retry. + **`line` is one-based, and may be absent.** The service anchors a comment with a zero-based line in a string field whose `-1` means "not anchored to a line". The CLI does that arithmetic once: `line` in the envelope matches what the dashboard shows, and is `null` — never `0` — for a comment that @@ -484,6 +497,16 @@ unity projects unlink vcs /path/to/MyProject --unlink-workspace The `[url]` second operand attaches to a remote that already exists, instead of creating one — the one thing the flag form of `link vcs` cannot do. It is mutually exclusive with `--vcs`, `--git-namespace`, `--git-repo`, `--git-visibility`, `--git-default-branch`, `--git-remote-protocol`, `--git-description`, `--cloud-org`, and `--cloud-project` (all meaningless without a repository to create — the URL's own scheme already says which transport to use). `--git-token[-stdin]`, `--no-initial-commit`, and `--git-lfs` still apply, and the same ambient-auth / Tier A rules as `projects clone [url]` govern whether the push uses a supplied token or the machine's own git auth. +### Assets — inspect a `.unitypackage` without importing it + +```bash +# List a package’s contents: asset path, GUID, payload size, and whether a preview image is bundled +unity assets inspect ./MyPackage.unitypackage +unity assets inspect ./MyPackage.unitypackage --format json +``` + +Works offline, with no Editor installed and no open project. The archive is streamed rather than read into memory, so a multi-gigabyte package is inspected in constant memory. `--format json` / `tsv` / `ndjson` carry the raw byte size and a boolean preview flag for scripts; the human table shows readable sizes and ends with a summary of entry count and total size. A missing file fails with `ASSET_PACKAGE_NOT_FOUND` (exit 6). + --- ### Releases — browse Unity versions @@ -511,6 +534,24 @@ unity releases --limit 10 --skip 20 --format json ### Templates +**Choosing a core template.** Pick by render pipeline, not just by 2D/3D. Default to the URP +templates; the Built-in Render Pipeline templates are deprecated from Unity 6.5 and removed in +6.7, so use them only when the user explicitly asks for Built-in. Verify with `templates list` +for the target Editor — ids below are as of Unity 6000.3 to 6000.7: + +| Brief | Template id | Display name | Pipeline | +|---|---|---|---| +| 3D (default) | `com.unity.template.urp-blank` | Universal 3D | URP | +| 2D (default) | `com.unity.template.universal-2d` | Universal 2D | URP + `com.unity.2d.*` packages (the JSON `renderPipeline` field is blank for this one — match by id) | +| High-fidelity PC/console 3D | `com.unity.template.hdrp-blank` | High Definition 3D | HDRP | +| VR / MR / AR | `com.unity.template.vr` / `.mixed-reality` / `.ar-mobile` | VR, Mixed Reality (MR), AR Mobile | URP | +| Built-in, only on request | `com.unity.template.3d` / `com.unity.template.2d` | 3D / 2D (Built-In Render Pipeline) | Built-in; absent from 6.7+ | + +`--editor` here takes a **concrete** version. Unlike `install` and `projects create`, the +`templates` commands do not resolve the `lts` / `latest` aliases — the value is passed straight +through and anything that is not a `6000.x.y` fails with `UnityVersion: version argument is not a +valid unity version`. Resolve the version first (`editors --installed`, `releases`). + ```bash # List templates for an editor version (uses default editor if --editor is omitted) unity templates list --editor 6000.0.47f1 --format json @@ -533,7 +574,7 @@ 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 +unity templates info com.unity.template.urp-blank --editor 6000.0.47f1 --format json # Create a custom template from an existing Unity project # --name and --display-name are REQUIRED diff --git a/skills/unity-package-management/references/select-packages.md b/skills/unity-package-management/references/select-packages.md index 09326aa..96c1a6a 100644 --- a/skills/unity-package-management/references/select-packages.md +++ b/skills/unity-package-management/references/select-packages.md @@ -5,9 +5,10 @@ list, then install it via the C# PackageManager Client API (see the main `SKILL. **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. +chosen template (the URP templates `com.unity.template.urp-blank` / `universal-2d` already +include the render pipeline, Input System, uGUI/TextMeshPro, 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 @@ -48,18 +49,25 @@ HTTP (the npm `-/v1/search` endpoint is not available — it 404s). For keyword | 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. | +| Text / UI | `com.unity.ugui` | uGUI + TextMeshPro (bundled). UI Toolkit ships with the Editor. Use one of these for HUDs and menus — never `OnGUI`. | | 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) +## Render pipeline (set by the template — do not add or swap it here) -| Choice | Package | Use when | +The pipeline is decided by the template chosen in the **`unity-cli`** bootstrap step (default: +`com.unity.template.urp-blank` for 3D, `com.unity.template.universal-2d` for 2D — both URP). +Installing `com.unity.render-pipelines.universal` into a Built-in template project does **not** +switch pipelines: no URP asset gets assigned, and materials render pink. To change pipeline after +creation use the **`migrate-birp-to-urp`** skill instead. The rows below are for reading a +`manifest.json`, not for adding packages: + +| Choice | Package | Notes | |---|---|---| -| **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. | +| **URP** (Universal) | `com.unity.render-pipelines.universal` | Default for all 2D/3D, mobile, and WebGL. Ships in the URP templates. | +| **HDRP** (High-Definition) | `com.unity.render-pipelines.high-definition` | High-fidelity PC/console only; `com.unity.template.hdrp-blank`. Not for mobile/WebGL. | +| **Built-in** | (none) | Legacy. Its templates are deprecated from Unity 6.5 and removed in 6.7; use only when the user explicitly asks. | ## By dimension & look @@ -75,12 +83,12 @@ HTTP (the npm `-/v1/search` endpoint is not available — it 404s). For keyword | 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) | +| Platformer / action | Input System, Cinemachine, 2D feature (if 2D), AI Navigation (if 3D) | +| Puzzle / match / card | Input System, uGUI/TextMeshPro, 2D feature (if 2D), Timeline (juice) | +| Top-down / twin-stick | Input System, Cinemachine, 2D feature (if 2D), AI Navigation (if 3D) | +| RPG / adventure | Input System, Cinemachine, AI Navigation, Addressables, Timeline | +| Racing / physics | Input System, Cinemachine; Physics is built in | +| Idle / hyper-casual | Input System, uGUI/TextMeshPro, 2D feature (if 2D) — keep it lean | | Multiplayer (any) | `com.unity.netcode.gameobjects` + Multiplayer Services → see **build-live-game** | ## By target platform @@ -90,9 +98,9 @@ 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 | +| Mobile (iOS/Android) | Keep dependencies lean; a URP template, never HDRP; Addressables for download size; monetization below | +| WebGL | A URP template (not HDRP); small footprint; avoid heavy packages | +| Desktop / Console | URP template by default; `hdrp-blank` only for a high-fidelity target | ## By monetization — install now, integrate via the dedicated skill diff --git a/skills/urp-postprocessing/SKILL.md b/skills/urp-postprocessing/SKILL.md index 12523e0..3ca6cf7 100644 --- a/skills/urp-postprocessing/SKILL.md +++ b/skills/urp-postprocessing/SKILL.md @@ -23,7 +23,7 @@ missing, say so and stop. Run C# through the connected Editor with the `eval` command. Discover its parameter shape from `unity command --format json` rather than assuming one — the inline form is -`unity command eval --caller plugin --skill urp-postprocessing --code ''`, and some Pipeline versions also register +`unity command eval --code ''`, and some Pipeline versions also register `eval_file` for running a snippet from a file. **Check the catalog before reaching for `eval_file`; it is frequently absent.** `unity command` defaults to a 30 second timeout.