Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions skills/build-live-game/SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Security notes: build-live-game

This skill has the agent read state from the user's open Unity Editor through `unity command script eval` to read the Cloud project ID after linking and the result of a feature it changed. Automated skill scanners flag that as a powerful capability. It is intentional, and it is limited by the safeguards below.

## Accepted risks

| Risk | Capability | Why it is accepted |
|---|---|---|
| `SEC_POWER_CAP` | Runs C# in the user's open Editor through `unity command script eval` | It only reaches the Editor the user already has open, on their own machine, as that user, so it grants nothing they couldn't do themselves. `script eval` sits behind the Pipeline capability gate. No code fetched from a remote source is run. The skill uses it only to read state, and uses `unity command console status` for the console check. |

## Mitigations

- **Only the user's own Editor.** `unity command script eval` talks to the Editor open on this machine. It can't reach another machine or another user's Editor.
- **Capability gate.** `script eval` is only available when the project's Pipeline package provides it.
- **No remote code.** The agent runs C# it writes itself to read Editor state. Nothing downloaded from outside is executed.
- **Reads, not logging.** `script eval` only reads state; the skill reads results with it instead of adding logging. The one write it makes for verification is a temporary client Cloud Save call that checks an Access Control policy rejects it, removed afterwards.
- **Play mode only when needed.** The skill enters Play mode for that Access Control check and, when the user asks for proof or a fault is suspected, once to run the feature.
- **One Editor.** Every `unity command` names the project with `--project-path`, so it can't drive another project's Editor.
18 changes: 12 additions & 6 deletions skills/build-live-game/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ description: Builds and operates a live game's backend with Unity Gaming Service
## Before You Start

1. Read the Editor version from `ProjectSettings/ProjectVersion.txt` and the installed UGS package versions from `Packages/packages-lock.json`. Pick the steps below that match (for example `.ccmu` or `.ccmr` modules), because the right workflow depends on the Editor and package versions.
2. Check whether the project is linked to a Unity project ID and environment (**Edit > Project Settings > Services**), and ask the user to link it if it is not.
3. Create a restore point you can roll back to if your changes fail: commit the project in version control. If there is no version control, copy the project folder instead.
2. Create a restore point you can roll back to if your changes fail: commit the project in version control. If there is no version control, copy the project folder instead. Do this before linking or any other write.
3. If the project has no Unity Cloud link, see [Link the Project to Unity Cloud](#link-the-project-to-unity-cloud). Advice-only questions stay read-only: give the `unity projects link cloud` command.
4. Before you go forward with a workflow or diagnosis, open and read the documentation pages for the service you will use (see [Documentation Map](#documentation-map)) and the matching file under `references/`, and name the pages you read in your response. This is because your training knowledge about Unity Gaming Services might be out of date, incorrect, or for the wrong package version.
5. Do only what's asked. Don't change unrelated assets or files. Avoid long explanations.
6. When you change runtime behaviour, add `Debug.Log` lines at the points you need to verify (sign-in complete, module call returned, config fetched). You read them in Play mode during [Validation](#validation).
6. Never leave verification code in the user's script. Never build logging or detection they didn't ask for.

## Glossary

Expand All @@ -25,7 +25,7 @@ description: Builds and operates a live game's backend with Unity Gaming Service
| **Script** | Server-side JavaScript endpoint. Legacy: maintain existing ones, don't write new ones |
| **CloudBehaviour** | Experimental Cloud Code class that generates client bindings, synchronized state and push events |
| **Protected data** | Cloud Save player data that the player can read but only server code can write |
| **Custom data** | Cloud Save game-wide data, not tied to one player, written only by server code |
| **Custom data** | Cloud Save game-wide data, not tied to one player, server-written only |
| **Cloud resource file** | A deployable config file (`.rc`, `.ac`, `.ccmu`, `.ccmr`, `.lb`, `.ugo`) that the Deployment Window pushes to a UGS environment |

## Documentation Map
Expand Down Expand Up @@ -61,6 +61,7 @@ Pages to read before acting:
- [Before You Start](#before-you-start)
- [Glossary](#glossary)
- [Documentation Map](#documentation-map)
- [Link the Project to Unity Cloud](#link-the-project-to-unity-cloud)
- [Initialization Pattern](#initialization-pattern)
- [Architecture — How Packages Combine](#architecture--how-packages-combine)
- [Core Services — Quick Reference](#core-services--quick-reference)
Expand All @@ -69,6 +70,10 @@ Pages to read before acting:
- [Detailed References](#detailed-references)
- [Final Report](#final-report)

## Link the Project to Unity Cloud

Service calls need a linked Cloud project. Link only when the task needs service calls or asks to link, and only after the restore point. Follow every step in [references/link-cloud.md](references/link-cloud.md): choose backend and COPPA setting, check the Pipeline package, close the Editor, link, reopen, verify.

## Initialization Pattern

Every UGS game starts the same way. `com.unity.services.core` must initialize first, then the player signs in:
Expand Down Expand Up @@ -225,7 +230,8 @@ After writing code for a live game feature, run these checks in order. If one fa
3. Check that sensitive writes (XP, rewards, currency) go through Cloud Code: search the client code for Cloud Save `SaveAsync` calls on those keys and move any you find into a module. Also confirm each Cloud Save read uses the access class of the bucket that was written to, because a mismatched class returns no data.
4. Deploy the cloud resource files the feature uses (`.rc`, `.ac`, `.ccmu` or `.ccmr`, `.lb`; skip the types it does not use) to the active environment with the `Deploy.cs` script in `references/deployment.md`, and read its output: every file must report `Success`. A file reported as `not a deployable item`, or with an `Error` status, has failed. If the project does not have both packages the script needs, `com.unity.pipeline` and `com.unity.services.deployment.api`, ask the user to deploy from the Deployment Window and report each file's status.
5. Check Access Control by its effect: if the feature deploys an `.ac` policy that denies direct player writes, enter Play mode, run one direct client Cloud Save write to a key the policy covers (a temporary `SaveAsync` call), and confirm it fails with a `403`. Remove the temporary call afterwards. Skip this step when the feature has no `.ac` file.
6. Enter Play mode, run the feature once, and confirm the `Debug.Log` lines from [Before You Start](#before-you-start) appear in the order you expect and the console has zero errors.
6. Check for zero console errors with `unity command console status`. Pass `--project-path <path>` to every `unity command` here, so it drives this project's Editor. Older Editors name it `console_status`: check with `unity commands --grep console`.
7. Stop after step 6 unless the user asked for proof or you suspect a specific fault, and report that the feature was not run. To chase that fault, enter Play mode once (`unity command editor.playmode start`), run the feature, read the result (player ID, module return value, config) through `unity command script eval`, not added logging, then repeat step 6. Remove any temporary code afterwards. Take no screenshots.

## Detailed References

Expand All @@ -249,7 +255,7 @@ After writing code for a live game feature, run these checks in order. If one fa

When the work is done, end your response with a short report:

1. What you created or changed: files, packages added to `Packages/manifest.json`, and cloud resource files.
1. What you created or changed: files, packages added to `Packages/manifest.json`, cloud resource files, and the Unity Cloud project you linked (its ID, and whether the link created it).
2. The checks from [Validation](#validation) that you ran and their results, including any you could not run and why.
3. Follow-ups only the user can do, for example: deploy the cloud resources to the target environment, link the project to a Unity project ID and environment, complete a stubbed integration (such as battle pass `PurchasePremium`), or restore from the restore point you created if they reject the changes.
4. Which documentation pages you read.
11 changes: 11 additions & 0 deletions skills/build-live-game/references/link-cloud.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Link the Project to Unity Cloud

UGS calls need a linked Unity Cloud project ID. Linking writes `ProjectSettings/ProjectSettings.asset`: do it only when the task needs service calls or asks to link, after the restore point. Pass `--project-path <path>` to every `unity command` below, because without it the CLI drives the Editor of the shell's current folder, which may be another project.

1. A non-empty `cloudProjectId` in `ProjectSettings/ProjectSettings.asset` means it is linked: skip the rest.
2. Without `--cloud-project`, the CLI reuses `UNITY_CLOUD_PROJECT`, then the saved default (`defaultCloudProjectId` from `unity cloud project current --format json`), and creates a project only when both are empty. To reuse one, pass `--cloud-project <id>`. If either is set and the user wants a new one, ask first: `unity cloud project clear-default` clears only the saved default, and the user must unset `UNITY_CLOUD_PROJECT` in their own shell.
3. Check `Packages/manifest.json` for `com.unity.pipeline`: closing gracefully, `--until-ready` and `script eval` need it. If it is missing, add it with `unity pipeline install --project-path <path>` (Unity 6.0+) and say so in the report. If it can't be added, ask the user to save and close the Editor themselves, and in step 5 check only the asset.
4. `unity close <path>` exits without saving, so ask the user to save their work first, then run it: an open Editor keeps the old link and can save it back over the new one.
5. Run `unity projects link cloud <path> --format json`, plus `--cloud-project <id>` when reusing. When it will create a project, first ask whether the game is directed at children under 13 and add `--coppa compliant` if so: the default is `not_compliant`. Never pass `--coppa` with `--cloud-project` (error `COPPA_ARGS_CONFLICT`); change an existing project's COPPA setting in the Unity Cloud dashboard.
6. Verify: if `data.editor.restartRequired` is `true`, an Editor still had the project open: close it, then check the asset still holds the new ID, and if not rerun with `--cloud-project <id>`. Reopen with `unity open <path> --until-ready --format json` (a plain `unity open` returns before the Editor can answer commands) and check `cloudProjectId` in the asset and `CloudProjectSettings.projectId` (via `unity command script eval --project-path <path>`) equal `data.cloudProject`'s ID. On failure, stop and report the error code.
7. Never hand-edit the asset or write an Editor-side linker: a manual edit can mismatch project and organization IDs.
2 changes: 1 addition & 1 deletion skills/new-unity-project/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ of these as powerful capabilities. They are intentional, and limited by the safe
writes and the cloud-link narration included — prints in one block before the create launches,
and any line reverses on a word. Consent in the strict sense comes from guided mode's per-step
asks; paved mode's bar is that nothing runs unannounced and nothing is irreversible.
- **Human gates are never consumed.** Sign-in, license activation (including accepting the Unity Personal EULA) and publishing each run only after the user says yes to a question the agent asks and waits on.
- **Human gates are never consumed.** Sign-in, license activation (including accepting the Unity Personal EULA and the Unity Editor Software Terms, which `unity terms accept --yes` records only after that yes) and publishing each run only after the user says yes to a question the agent asks and waits on.
- **Only the user's own Editor and account.** Everything runs on this machine as this user.
- **No remote code.** All executed C# comes from this skill's text and its delegated skills.
- **Named commands first.** Where a dedicated `unity` command covers a step, the skill uses it.
37 changes: 31 additions & 6 deletions skills/new-unity-project/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,14 @@ with your client's multiple-choice question tool (plain text only without one),
answer. Send it together with the delegated-skills offer (below) and any Step 1 question, so the
user answers once. Offer the free
**Unity Personal** license as the default choice, with the other license types (a subscription the
account already has, a serial, a floating server) as alternatives. The Personal choice itself says
that picking it accepts the Unity Personal EULA
(https://unity.com/legal/editor-terms-of-service/software), so the user sees it before answering.
account already has, a serial, a floating server) as alternatives. The question says that a yes
also accepts the Unity Editor Software Terms
(https://unity.com/legal/editor-terms-of-service/software) for every Editor this run opens, installed now or already on the machine, and
the Personal choice says it accepts the Unity Personal EULA (the same page), so the user sees both
before answering. Every Editor stops on its own terms dialog the first time it opens until they are
accepted, and an agent can't see or click that dialog. When sign-in and license are already set
and no license question goes out, still ask about the terms with your first question; the create
can start before the answer, but `unity terms accept` and the first `unity open` wait for it.

- Never tell the user to sign in or activate a license themselves, and never hand them commands to
run. You run them, after they say yes.
Expand Down Expand Up @@ -141,6 +146,13 @@ Two decisions (paved: filled from the Defaults table, then **print the manifest*
Default to an explicit `--editor-version latest` unless the user names a version — without the
flag, create prefers a stored default or an older installed Editor.

For a cloud-linked create, pick the organization first: `unity cloud orgs --format json`. When
`data.activeOrganizationId` is null and `data.organizations` holds exactly one org, pass that org's `id` as
`--cloud-org <id>`; without it create links nothing (`CLOUD_LINK_FAILED`, no organization
configured) and skips player accounts, Remote Config and Cloud Save. With several orgs and no
default, ask the user which one before starting the create (the list needs sign-in, so this comes
after it).

Confirm prerequisites, then **start the create as a background task** (`unity-cli` has module
names and auth / license setup):

Expand All @@ -149,8 +161,9 @@ unity --version # sign-in and license: settled before your first question (see

# Start in the BACKGROUND. Module names per platform are in the unity-cli skill.
# --bare only on the user's ask (see Mode).
unity projects create "<Name>" --path <dir> --editor-version latest \
--template <3d|2d> --install-editor --module <platform-modules> --accept-eula --format json
unity projects create "<Name>" --output-dir <dir> --editor-version latest \
--template <3d|2d> --install-editor --module <platform-modules> --accept-eula \
[--cloud-org <id>] --format json
```

The command waits for the install, then creates the project, so its one result covers both. If you
Expand All @@ -177,6 +190,17 @@ the platform modules with `unity install-modules -e <version> -m <platform-modul
(skips what's already there). If create failed, surface the error (`unity-cli` troubleshooting)
and stop — a failed install creates no project, and nothing downstream works without an Editor.

**Once create succeeded, accept the Editor Software Terms before any open, and only after the
user's yes.** If the terms question is still unanswered, wait for the answer before running
anything. If the user declined, don't run `unity terms accept`: stop before the first open and say
the Editor won't start past its terms dialog. On a yes, run
`unity terms accept <data.version> --architecture <data.architecture> --yes` with no Editor running
(a running Editor can overwrite the answer). It reports `alreadyAccepted: true` and writes nothing
when they are already recorded. Do the same for any Editor the run moves to later, such as the
6000.5.3+ update in Step 7. If `unity status --until-ready` after an open reports
no instance while the Editor process is running, check `unity terms status <version> --architecture <architecture>`: a
`not-accepted` Editor is sitting on that dialog, which only the user can click.

## Step 4 — Source control

**Paved:** local git + Unity `.gitignore`. **Guided:** ask — Git (GitHub / GitLab; `--git-lfs` for
Expand Down Expand Up @@ -234,7 +258,8 @@ whole step (no Pipeline install, no baseline): go to Step 8, which opens the pro
Editors (create reports `PIPELINE_EDITOR_UNSUPPORTED`), so nothing below can connect, and reopening
won't help. Create also left the package out on those Editors. Ask the user to update to
6000.5.3f1 or later, then continue below with the project still closed: the Pipeline install comes
first, then the open names the updated Editor, `unity open "<project-path>" --editor-version
first, then `unity terms accept <updated-version> --architecture <architecture> --yes` (Step 3; the
architecture of the Editor you'll open), then the open names the updated Editor, `unity open "<project-path>" --editor-version
<updated-version>` — a plain `unity open` reopens with the project's saved 6000.5.x Editor. If the
update is 6000.7 or later, `unity open` refuses that move (`PROJECT_UPGRADE_REQUIRED`): run
`unity projects upgrade "<project-path>" --to <updated-version> --yes` instead. It asks
Expand Down
17 changes: 17 additions & 0 deletions skills/setup-multiplayer-services/SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Security notes: setup-multiplayer-services

This skill has the agent read state from the user's open Unity Editor through `unity command script eval` to read the Cloud project ID after linking and the session result of a feature it changed. Automated skill scanners flag that as a powerful capability. It is intentional, and it is limited by the safeguards below.

## Accepted risks

| Risk | Capability | Why it is accepted |
|---|---|---|
| `SEC_POWER_CAP` | Runs C# in the user's open Editor through `unity command script eval` | It only reaches the Editor the user already has open, on their own machine, as that user, so it grants nothing they couldn't do themselves. `script eval` sits behind the Pipeline capability gate. No code fetched from a remote source is run. The skill uses it only to read state, and uses `unity command console status` for the console check. |

## Mitigations

- **Only the user's own Editor.** `unity command script eval` talks to the Editor open on this machine. It can't reach another machine or another user's Editor.
- **Capability gate.** `script eval` is only available when the project's Pipeline package provides it.
- **No remote code.** The agent runs C# it writes itself to read Editor state. Nothing downloaded from outside is executed.
- **Read only, once.** The skill enters Play mode at most once per change and reads state instead of adding logging. Any temporary verification code is removed afterwards.
- **One Editor.** Every `unity command` names the project with `--project-path`, so it can't drive another project's Editor.
Loading
Loading