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.
6 changes: 3 additions & 3 deletions skills/manage-cloud-build/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ This is because your training knowledge about Unity Build Automation might be ou
Prefer fetching a page directly (for example `WebFetch`) over searching (for example `WebSearch`), because it lands on the exact page. Only fetch what you need, and only search if you don't have the exact URL. Replace `<VERSION>` with the following before fetching:

- **docs.unity.com (Build Automation)**: no version, because these pages carry none.
- **docs.unity3d.com**: the build's or the project's Unity version as major.minor, for example `6000.3` for a `unityVersion` of `6000_3_26f1`.
- **docs.unity3d.com**: the build's or the project's Unity version as major.minor, for example `6000.3` for a `unityVersion` of `6000_3_26f1`. For Unity 6 and later these pages redirect to `https://docs.unity.com/en-us/engine/<VERSION>/`, so follow the redirect.

The page index is in [references/topic-map.md](references/topic-map.md): Build Automation pages under `https://docs.unity.com/en-us/build-automation/`, and Unity Manual pages under `https://docs.unity3d.com/<VERSION>/Documentation/Manual/`.

Expand All @@ -65,15 +65,15 @@ The page index is in [references/topic-map.md](references/topic-map.md): Build A
1. Run the workflow's CLI check. If `unity` isn't found, tell the user to install the Unity CLI, and stop. If the check fails, tell the user to update the CLI with `unity self-update`, and stop, because older versions lack the workflow's commands.
2. Run `unity auth status`. If the user isn't signed in, ask them to run `unity auth login`, and stop.
3. Get the organization and project. If the user gave their IDs, or a Unity Cloud Dashboard link with them in the path segments after `organizations/` and `projects/`, use those. Otherwise use the IDs that `unity cloud org current` and `unity cloud project current` print. If they print none, ask the user. Below, `<scope>` stands for `--cloud-org <org> --cloud-project <project>`. Put it on every `unity pipeline cloud-build` command, because otherwise the CLI reads its default project, which can hold a same-named target and build. Write both options out in each command rather than in one shell variable, because zsh passes such a variable as a single argument.
4. Run `unity logs --console --level error` and note the errors it lists, so the final step can tell the project's own errors from new ones. If no Editor answers, skip this read and the final step's.
4. Run `unity command console status`. If `groundTruth.consoleErrors` is above 0, also save the errors that `unity logs --console --level error` lists, so the final step can tell the project's own errors from new ones. If no Editor answers, skip this read and the final step's.

## Step 4: Follow the workflow

Follow the workflow's steps in order, including its own checks.

## Final step

1. Run `unity logs --console --level error` again to check the project has zero console errors, because neither workflow may change the project's code or assets. An error that Step 3 already listed is the project's own. If a new one appeared, tell the user what you ran.
1. Run `unity command console status` again to check the project has zero console errors other than its own, because neither workflow may change the project's code or assets. If `groundTruth.consoleErrors` is above 0, list the errors with `unity logs --console --level error` and compare them with the ones Step 3 saved, because a count alone misses one error replacing another. If any is new, tell the user what you ran.
2. Stop there unless the user asked for more proof, because each workflow already checked its own result.

If a workflow's check fails, go back to the [topic map](#topic-map), reread the page that covers it, and check whether you missed something.
Expand Down
Loading
Loading