From cfbb096b9f5275fde710d265ec053de94a626101 Mon Sep 17 00:00:00 2001 From: "pre-shared-workflows-auth[bot]" <168739156+pre-shared-workflows-auth[bot]@users.noreply.github.com> Date: Fri, 13 Nov 2026 17:03:37 +0000 Subject: [PATCH] chore: publish 1 skill (create-xr) --- skills/create-xr/SECURITY.md | 15 + skills/create-xr/SKILL.md | 119 +++++++ skills/create-xr/references/eval-guide.md | 30 ++ .../references/meta-graphics-setup.md | 40 +++ skills/create-xr/references/rig-pitfalls.md | 48 +++ skills/create-xr/references/rig-recipes.md | 238 ++++++++++++++ skills/create-xr/references/rig-structure.md | 88 ++++++ skills/create-xr/references/rig.md | 128 ++++++++ skills/create-xr/references/setup-manual.md | 61 ++++ skills/create-xr/references/setup.md | 40 +++ skills/create-xr/scripts/_eval.sh | 292 ++++++++++++++++++ .../dependency/com.unity.pipeline/0.10.sh | 68 ++++ .../dependency/com.unity.pipeline/0.9.sh | 68 ++++ .../dependency/com.unity.pipeline/1.0.sh | 74 +++++ .../dependency/com.unity.pipeline/FALLBACK | 1 + .../com.unity.xr.androidxr-openxr/1.0.sh | 6 + .../dependency/com.unity.xr.hands/1.9.sh | 7 + .../dependency/com.unity.xr.management/4.7.sh | 47 +++ .../dependency/com.unity.xr.openxr/1.19.sh | 81 +++++ .../dependency/unity-cli/1.0.0-beta.14.sh | 36 +++ .../dependency/unity-cli/1.0.0-beta.8.sh | 34 ++ .../scripts/dependency/unity/6000.0.sh | 181 +++++++++++ .../create-xr/scripts/meta-graphics/check.sh | 15 + .../meta-graphics/meta-graphics-setup.sh | 32 ++ skills/create-xr/scripts/pipeline_check.sh | 51 +++ skills/create-xr/scripts/setup/1_modules.sh | 6 + skills/create-xr/scripts/setup/2_packages.sh | 18 ++ .../scripts/setup/3_build_profile.sh | 109 +++++++ skills/create-xr/scripts/setup/4_openxr.sh | 23 ++ .../scripts/setup/5_player_settings.sh | 13 + skills/create-xr/scripts/setup/6_validate.sh | 16 + skills/create-xr/scripts/setup/_lib.sh | 87 ++++++ skills/create-xr/scripts/setup/check.sh | 36 +++ skills/create-xr/scripts/setup/setup.sh | 18 ++ skills/create-xr/scripts/status.sh | 72 +++++ 35 files changed, 2198 insertions(+) create mode 100644 skills/create-xr/SECURITY.md create mode 100644 skills/create-xr/SKILL.md create mode 100644 skills/create-xr/references/eval-guide.md create mode 100644 skills/create-xr/references/meta-graphics-setup.md create mode 100644 skills/create-xr/references/rig-pitfalls.md create mode 100644 skills/create-xr/references/rig-recipes.md create mode 100644 skills/create-xr/references/rig-structure.md create mode 100644 skills/create-xr/references/rig.md create mode 100644 skills/create-xr/references/setup-manual.md create mode 100644 skills/create-xr/references/setup.md create mode 100644 skills/create-xr/scripts/_eval.sh create mode 100644 skills/create-xr/scripts/dependency/com.unity.pipeline/0.10.sh create mode 100644 skills/create-xr/scripts/dependency/com.unity.pipeline/0.9.sh create mode 100644 skills/create-xr/scripts/dependency/com.unity.pipeline/1.0.sh create mode 100644 skills/create-xr/scripts/dependency/com.unity.pipeline/FALLBACK create mode 100644 skills/create-xr/scripts/dependency/com.unity.xr.androidxr-openxr/1.0.sh create mode 100644 skills/create-xr/scripts/dependency/com.unity.xr.hands/1.9.sh create mode 100644 skills/create-xr/scripts/dependency/com.unity.xr.management/4.7.sh create mode 100644 skills/create-xr/scripts/dependency/com.unity.xr.openxr/1.19.sh create mode 100644 skills/create-xr/scripts/dependency/unity-cli/1.0.0-beta.14.sh create mode 100644 skills/create-xr/scripts/dependency/unity-cli/1.0.0-beta.8.sh create mode 100644 skills/create-xr/scripts/dependency/unity/6000.0.sh create mode 100644 skills/create-xr/scripts/meta-graphics/check.sh create mode 100644 skills/create-xr/scripts/meta-graphics/meta-graphics-setup.sh create mode 100644 skills/create-xr/scripts/pipeline_check.sh create mode 100644 skills/create-xr/scripts/setup/1_modules.sh create mode 100644 skills/create-xr/scripts/setup/2_packages.sh create mode 100644 skills/create-xr/scripts/setup/3_build_profile.sh create mode 100644 skills/create-xr/scripts/setup/4_openxr.sh create mode 100644 skills/create-xr/scripts/setup/5_player_settings.sh create mode 100644 skills/create-xr/scripts/setup/6_validate.sh create mode 100644 skills/create-xr/scripts/setup/_lib.sh create mode 100644 skills/create-xr/scripts/setup/check.sh create mode 100644 skills/create-xr/scripts/setup/setup.sh create mode 100644 skills/create-xr/scripts/status.sh diff --git a/skills/create-xr/SECURITY.md b/skills/create-xr/SECURITY.md new file mode 100644 index 0000000..9a4f022 --- /dev/null +++ b/skills/create-xr/SECURITY.md @@ -0,0 +1,15 @@ +# Security notes: create-xr skill + +This skill has the agent run C# inside the user's open Unity Editor through `unity command eval`. 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 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. `eval` sits behind the Pipeline capability gate. No code fetched from a remote source is run. Where a named `unity command` covers a step, the skill uses that instead of `eval`. | + +## Mitigations + +- **Only the user's own Editor.** `unity command eval` talks to the Editor open on this machine. It can't reach another machine or another user's Editor. +- **No remote code.** The agent runs C# it writes from this skill's own recipes. Nothing downloaded from outside is executed. +- **Named commands first.** When a dedicated `unity command` covers a step, the skill uses it instead of `eval`. diff --git a/skills/create-xr/SKILL.md b/skills/create-xr/SKILL.md new file mode 100644 index 0000000..4e87c06 --- /dev/null +++ b/skills/create-xr/SKILL.md @@ -0,0 +1,119 @@ +--- +name: create-xr +description: >- + Sets up a Unity project for XR. Use when user asks for XR, OpenXR, Quest + graphics or XR rig. +required_editor_version: ">=6000.1" +--- + +Set up a Unity project for XR: configure it for the target devices, optimize graphics for Quest, then add a configured XR rig. + +**Goal: the project builds for the target device(s) with XR enabled, and the user can enter the scene on their headset with working controllers (or hands) and the movement they chose — without building it.** + +**``** = the "Base directory for this skill" shown at the top of this document. +**``** = absolute path to the Unity project on disk. + +## Critical Rules + +- Do only what's asked. Don't change unrelated assets or files. Avoid long explanations. Unrequested changes are hard for the user to spot and undo. +- Create a restore point you can roll back to if your changes fail: check the project's version control has no uncommitted changes, or otherwise copy `Packages/` and `ProjectSettings/` to a folder outside the project. +- Don't add verification code or logging to the project; read state back through the scripts or `eval`. Anything you add stays in the user's project and console. +- Do NOT specify package version numbers — let the Package Manager resolve the latest compatible version, because a pinned version may not support the project's Unity version. +- Do NOT edit `Packages/manifest.json`, `.unity`, `.prefab`, `.asset`, or `.meta` files directly, because the open Editor doesn't validate hand edits and can overwrite them or break on a malformed file. +- Do NOT write C# files into the project — C# runs only through `eval`, because a script file forces a recompile and stays in the user's project. +- Do NOT dismiss Editor dialogs with UI automation, simulated clicks, or key presses, because a dialog asks for a decision that belongs to the user (such as restarting the Editor). If the Editor is blocked by a dialog, tell the user what it says and ask them to answer it. +- Do NOT write your own package-install or wait-for-Editor loops — use the skill's scripts and the `install_package` / `wait_ready` helpers in `scripts/_eval.sh`, because they already handle reloads, timeouts, and blocking dialogs. +- Do NOT use reflection or non-public APIs, because they change between Unity versions without notice. If no public API or Pipeline command covers a step, ask the user to do it in the Editor. +- Use a Pipeline command when one covers the step; `eval` only when none does, because commands are validated and don't compile C# on every call. +- Read back the result of every change before the next step, because a call can report success while the Editor is reloading and the value didn't change. + +## Docs + +Before you start a procedure or diagnose a failure: + +1. Open and read the doc pages listed in that procedure's file. +2. Name the files you read in your response. + +This is because your training knowledge about Unity and its XR packages may be outdated, incorrect, or for the wrong version. + +The pages are markdown files in `/Library/PackageCache/@*/Documentation~/` (installed packages only). Read only the `.md` files in that single subfolder. Don't open non-.md files or other Library or PackageCache folders, because that takes too long. If a page is missing, find it in that folder's `TableOfContents.md`; if the folder has no `.md` files, use the online docs. The decisions in this skill still apply. + +Prefer `WebFetch` over `WebSearch`, because it's faster and lands on the exact page. Replace `` before fetching: + +- **Packages on docs.unity3d.com** (`https://docs.unity3d.com/Packages/@/manual/`): the installed package version, major.minor (e.g. `@1.19`). Read it from `Packages/packages-lock.json`, because `manifest.json` can hold a range. +- **Unity Manual on docs.unity.com** (`https://docs.unity.com/en-us/engine//manual/.md`): the project's Unity version, major.minor (e.g. `6000.3`). + +## 0. Connect + +Connect to the project's Editor before anything else, in this order (the `unity-cli` skill has the command details): + +1. **Pipeline package first.** If `Packages/manifest.json` has no `com.unity.pipeline`, run `unity pipeline install` before opening the Editor, because Unity reads the manifest when it loads the project. Against an already-open Editor: + + | Message | Cause | Fix | + |---|---|---| + | `PIPELINE_MANIFEST_WRITE_FAILED` | The open Editor holds the manifest | Ask the user to close the Editor, then run the install again | + | `STATUS_PIPELINE_LOAD_PENDING` (from `unity status`) | Installed, but loads only when the Editor window regains focus | Ask the user to switch to the Editor window | + +2. **Then the Editor.** `unity status` only lists Editors that already have the Pipeline package, so before opening one, check for `Temp/UnityLockfile` in the project: if it exists, an Editor probably has the project open already. Don't run `unity open` (a second Editor would replace it, and the user could lose unsaved work); ask the user to switch to the Editor window instead. If they say Unity isn't open, the file is left over and you can open it. If no Editor is open on the project, run `unity open ""`, then `unity status --until-ready`. The first open imports the project and can take several minutes: if the wait ends before the Editor is ready, run it again. +3. **Then check that the Pipeline version works with this skill.** From ``, run `bash "/scripts/pipeline_check.sh"`, with `--switch` if you installed the package in step 1. If the version doesn't work with the skill's scripts, `--switch` changes it to one that does: tell the user in the final report. Without `--switch` it prints `ASK` instead: the package was already in the project, so ask the user before changing it, re-run with `--switch` if they agree, and stop if they don't. If it prints `FAILED`, report the line and stop. + +Don't run the skill's scripts until the Editor is connected. Do not check the Pipeline commands by hand: `status.sh` (step 2) checks every command the skill needs and stops with exit code 4 naming any that is missing — then follow its message. + +Run the skill's scripts from ``, because with several Editors open the CLI picks the project from the current folder; the scripts stop if it isn't a Unity project. Run them as the procedures say; do not read their source, because their output tells you everything you need. Read [eval-guide.md](references/eval-guide.md) only before writing an `eval` or Pipeline command that is not one of the scripts. + +## 1. Questions + +Ask about anything the user has not already specified, **in one message**: + +1. **Target device(s)** — Meta Quest (Quest 2, 3, 3S, Pro), PC VR (SteamVR), Android XR (Samsung Galaxy XR, etc.). More than one allowed. **Apple Vision Pro:** this skill doesn't cover it. If the user asks for it, say so and continue the skill with any other devices they named. +2. **Input:** controllers only / controllers and hand tracking / hand tracking only — setup configures hand tracking from this answer, so ask it even when no rig is wanted. +3. **Rig:** + - **Interactions:** near (grab up close) / far (point at distant objects) / poke (press buttons) — any combination; UI interaction is always included + - **Movement:** teleport / continuous / both / stationary + - **Turning:** snap / continuous / none + +Skip question 3 for narrow requests that don't involve a rig (e.g., "optimize my project for XR", "just install the XR packages", "configure OpenXR"); otherwise ask it, because the rig answers decide every rig override. For hand tracking only, skip movement and turning — this skill does not configure hand-based locomotion. + +If the user leaves the rig choices to you ("set it all up", "just do it", "use the defaults"), use the default rig: the controller rig, or the hands rig if they said hands, with its default settings — near, far and poke, teleport and continuous movement, snap turn. For hand tracking only, the default rig has no movement or turning: say so in the report instead of listing teleport, continuous movement and snap turn. Don't change or turn off anything beyond what the input choice needs, and say in the final report that you used the default rig. If the request is a concrete task that spells out what to build (e.g., "add a rig with hands and controllers and a cube I can grab"), do the same for the rig questions it leaves open, and list those defaults in the final report. A vague or short request ("make it run on Quest") is not a hand-over: ask the missing rig questions in one message before changing anything. Don't turn the user's goals into rig choices ("look around" doesn't mean stationary, "pick things up" doesn't mean near only): if the request doesn't name the rig pieces and doesn't hand the choices over, ask. + +If the user asks for mixed reality, passthrough, or other environment features, tell them this skill does not yet configure MR, passthrough, or any environment-related features, and continue with the rest of the setup. + +Tell the user what this skill will change, in the same message as your questions, or at the top of the final report if you asked nothing: it installs XR packages and samples, switches the build platform, and changes project, XR and graphics settings. If it adds a rig, it also changes the scene. If the project isn't under version control, suggest the user commit or back it up first if they want to be able to undo this. + +Map variations: "AVP" / "Vision Pro" → Apple Vision Pro (not covered by this skill), "Galaxy XR" → Android XR, "Quest 3" / "Meta Quest" → Meta Quest, "Index" / "Vive" → PC VR. If the user asks how devices differ, explain and return to the question. Explain XR terms in plain language if the user seems unfamiliar with them. + +## 2. Check + +Run `bash "/scripts/status.sh" ` with the same arguments the setup script takes (devices, plus `--hands`) (read-only, one call). It prints one line per procedure: `setup`, `quest-graphics` (Quest only): `done` / `todo`; `rig`: `present` / `not present`; then `console`: `compile ok` / `compile failed`. Run only the procedures that are not done, because each one takes minutes even when it skips everything. If every procedure the user asked for is done, report the status lines and stop. Do not inspect the project any other way first, because `status.sh` already reads what the procedures need. + +## 3. Run the procedures + +Run them in this order, because each one depends on the one before it. Read each procedure only when you reach it, so you load only what you use, and finish one — including its done check — before starting the next. + +Procedures 1–2 are the **base setup**: packages (including the XR Interaction Toolkit), build profile, OpenXR, and — for Meta Quest — Quest graphics. Procedure 3 adds the rig. + +| # | Procedure | Run when | Skip when | Done when | +|---|---|---|---|---| +| 1 | [setup.md](references/setup.md) | Always: check, then do what's missing | Never | Target devices confirmed; base packages, profile, OpenXR, player settings set | +| 2 | [meta-graphics-setup.md](references/meta-graphics-setup.md) | Quest is a target, and the request is a full setup or mentions graphics | No Quest target, or a narrow request that doesn't mention graphics* | Quest URP asset assigned, single-pass, foveated on | +| 3 | [rig.md](references/rig.md) | Always, unless skipped | Narrow request that doesn't mention a rig* | XRI installed; linked rig; read-back matches answers | + +\* E.g., "just install the XR packages", "configure OpenXR". + +Setup always runs all its steps (packages, build profile, OpenXR, player settings), because each needs the one before. For a narrow request, tell the user that before running it. + +The procedures point to their supporting files when they need them; do not read these ahead of that point: [setup-manual.md](references/setup-manual.md) (when the setup script can't be used), [rig-pitfalls.md](references/rig-pitfalls.md), [rig-recipes.md](references/rig-recipes.md), [rig-structure.md](references/rig-structure.md). + +- If graphics can't finish (e.g., the project isn't on URP), tell the user and continue to the rig, because the rig doesn't depend on it. +- If everything is already done, report the current state to the user — do not re-run any steps. + +## 4. Final step + +The done checks confirm each setting was saved, but a saved setting can still break the project, so finish with these checks. If one fails, reread the pages in [Docs](#docs) for that procedure, fix the cause, and run the checks again. + +1. Re-run `status.sh` with the same arguments, then run `unity command console status --format json` and confirm `groundTruth.consoleErrors` is 0 and `compilationFailed` is false. If there are errors, list them in the report; investigate them only if compilation failed or a script printed `FAILED`. Stop here unless the user asked for proof that the result works or you suspect a fault. +2. Only to chase a suspected fault, enter Play mode once and read the state tied to that fault through `eval`. Without a headset connected the XR loader doesn't start in Play mode; that is expected, not a fault. Add no logging and take no screenshots, because they take too long. Exit Play mode and check the console again. + +## 5. Report + +End with a short report: what each procedure did and any defaults you chose; side effects the user didn't ask for (a Pipeline version switch, build platform switch, Editor restart needed for input, Android used because Android XR is disabled); every rig override, revertible in the Inspector with **Overrides → Revert**; and what's left for the user. Offer to save the configured rig as a prefab variant. diff --git a/skills/create-xr/references/eval-guide.md b/skills/create-xr/references/eval-guide.md new file mode 100644 index 0000000..e633c27 --- /dev/null +++ b/skills/create-xr/references/eval-guide.md @@ -0,0 +1,30 @@ +# Writing `eval` and Pipeline commands by hand + +Read this before running any `eval` or Pipeline command that is not one of the skill's scripts. + +## Find the command name first + +Pipeline command names change between versions — do not guess one. `unity command` lists the groups; `unity command --tag --detail full --format json` lists a group's commands and parameters. Tags are not group names (package commands: `packages`; build profiles: `build/settings`). If a tag returns nothing, use `unity command --query `. Subgroups are typed with a dot: `unity command build.target list` (the space form fails with "command not found"). + +## Domain reloads + +Package installs, build target switches, Build Profile activation, and sample imports trigger a reload or recompile. During it the Pipeline server is unreachable and commands fail or time out — expected; do not troubleshoot it. + +- Wait until the Editor responds again (`source "/scripts/_eval.sh" && wait_ready`) before the next step. +- If an `eval` times out, wait 10–15 s and retry the same command unchanged. +- Keep each `eval` to one change. +- Poll long operations instead of `--wait true`. +- The first Android switch or profile activation reimports for minutes. + +## `eval` code + +`eval` compiles a **statement block, not a file**: + +- **No `using` directives** — `using UnityEngine;` is read as a disposal statement (`CS0210`). +- **Fully qualify every type** — bare `AssetDatabase` fails (`CS0246` / `CS0103`). + +The recipes in this skill are already fully qualified. + +## Type names + +Look up type names and namespaces at `https://docs.unity3d.com/Packages/@/api/` (``: the installed package version, major.minor). Don't rely on names you remember, because XR types have moved between namespaces across versions. diff --git a/skills/create-xr/references/meta-graphics-setup.md b/skills/create-xr/references/meta-graphics-setup.md new file mode 100644 index 0000000..3f159ca --- /dev/null +++ b/skills/create-xr/references/meta-graphics-setup.md @@ -0,0 +1,40 @@ +# Meta Graphics Setup — Quest URP & OpenXR + +Relative paths in this file resolve to the skill directory. + +Single-pass instanced stereo, foveated rendering, and the Quest URP asset. Requires the setup procedure first (OpenXR on the Android tab, Vulkan); the script checks and stops if either is missing. + +## Docs + +- `com.unity.xr.openxr`: `features/foveatedrendering.md`, `features/performance-settings.md`. +- `com.unity.xr.meta-openxr`: `get-started/graphics-settings.md` (Quest graphics settings). +- `https://docs.unity.com/en-us/engine//manual/xr/graphics/untethered-device-optimization.md` (6000.3+; skip on older versions). + +## Step 1 — Configure Quest graphics (script, no reload) + +``` +bash "/scripts/meta-graphics/meta-graphics-setup.sh" +``` + +Runs five steps, each sent to the Editor with `unity command eval`: single-pass instanced stereo → foveated rendering and performance settings → new Quest URP asset and renderer (no SSAO) → Quest URP settings (incl. GPU Resident Drawer off) → Quest URP asset on the `Meta Quest (Build Profile)` quality level (other levels unchanged; they can be shared with PC). + +Ends with `=== Quest graphics setup complete ===`. The script waits for the Editor itself. + +### If a step prints `FAILED` + +The script stops at the failed step. Every step is idempotent: fix the cause, then re-run the same script. Do not rewrite the script. + +| Message contains | Cause | What to do | +|---|---|---| +| `Run the setup procedure (OpenXR) first` | OpenXR not configured for Android | Re-run `references/setup.md`, then re-run this script | +| `Vulkan is not the Android graphics API` | Player settings not applied | Re-run `references/setup.md`, then re-run this script | +| `no active UniversalRenderPipelineAsset` | Not a URP project | Stop this procedure — tell the user URP is required, and continue to the rig | +| `FoveatedRenderingFeature not found` | OpenXR package version without the feature | Stop and report the `FAILED` line to the user | +| `(URP version changed?)` | This URP version stores the renderer list differently | Stop and report the `FAILED` line to the user | +| `EVAL_FAILED` with compiler diagnostics (`CS....`) | A step doesn't compile against this Unity or package version | Stop and report the `FAILED` line to the user | +| `EVAL_NOT_FINISHED` | Editor still busy | Wait ~10 s, then re-run the same script | +| `no Pipeline command for` (exit 4) | This Pipeline version renamed or removed a command | Run the `unity command --query` the message names; if it exists under a new name, re-run with the `PIPELINE_CMD_` override it names, otherwise report the line | + +## Step 2 — Done check + +The script's last step (`verify`) is the done check: `OK [verify]: done: renderMode=SinglePassInstanced, foveated=True, Meta Quest (Build Profile) on Quest_RPAsset=True, URP settings=ok, SSAO=none`. If it reports `SSAO=present`, the user added SSAO to `Quest_Renderer`: don't change it; flag it in the final report: SSAO is not recommended on Quest (performance cost). diff --git a/skills/create-xr/references/rig-pitfalls.md b/skills/create-xr/references/rig-pitfalls.md new file mode 100644 index 0000000..5afa3dc --- /dev/null +++ b/skills/create-xr/references/rig-pitfalls.md @@ -0,0 +1,48 @@ +# Rig pitfalls + +Read before starting the rig procedure. Each one cost a wasted iteration before. + +## Correct vs wrong + +| Context | CORRECT | WRONG (do not use) | +|---|---|---| +| Rig creation | Place the Starter Assets `XR Origin (XR Rig)` prefab | Build a rig from individual components | +| Grab and point interaction | `NearFarInteractor` (near and far casting) | `XRDirectInteractor`, `XRRayInteractor` | +| Poke | `XRPokeInteractor` | `NearFarInteractor` | +| Teleport aiming | `XRRayInteractor` on the Teleport Interactor child | `NearFarInteractor` | +| Rig root component | `Unity.XR.CoreUtils.XROrigin` (com.unity.xr.core-utils) | `XRRig` (deprecated) | +| Sample import API | `UnityEditor.PackageManager.UI.Sample` | `UnityEditor.PackageManager.Sample` | +| Interaction manager | `UnityEngine.XR.Interaction.Toolkit.XRInteractionManager` | `...Toolkit.Interactions.XRInteractionManager` | +| Existing custom rig | Ask: replace, or use a new scene | Try to fix or complete it | + +## Rules + +1. **Match sample names exactly.** Use `displayName == "Starter Assets"`, never `.Contains()` — "AR Starter Assets" also contains it. + +2. **Two objects are named "Main Camera".** The scene template's camera is at the scene root; the rig has its own child "Main Camera". Target the template camera by hierarchy path `/Main Camera` or by checking it has no parent — a name-only lookup can return the rig's camera. + +3. **Disabling the Teleport Interactor alone does not turn teleport off.** `ControllerInputActionManager` re-activates it when the teleport input fires. Clear `m_TeleportMode` and `m_TeleportModeCancel` instead — see rig-structure.md. + +4. **A move stick cannot turn.** On a controller with `m_SmoothMotionEnabled` = true, the turn and snap-turn actions are disabled. Turning only works on controllers set to teleport + turn. + +5. **`ControllerInputActionManager` is a sample script, not a package type.** Do not reference its type in `eval` code — match it by `GetType().Name` and read or write its fields with `SerializedObject`. + +6. **Starter Assets requires TMP Essentials.** Without them a project validation error remains. Import them with `TMPro.TMP_PackageResourceImporter.ImportResources(true, false, false)` — the validation rule's own fix opens a window and does nothing from the CLI. + +7. **A freshly started Editor may have no scene open.** `SceneManager.GetActiveScene().path` is empty and scene queries return nothing. Open a scene before placing the rig. + +8. **Hand tracking only: `XRInputModalityManager` alone does not hide the controllers.** It still shows a controller the user picks up, and that controller's sticks still move the user. Clear its controller references, deactivate the controllers, and set the providers' controller inputs to Unused. In other setups, controllers are inactive in Play mode when no controller is tracked — that is expected. + +9. **In edit mode the Teleport Interactor is active.** `ControllerInputActionManager` deactivates it when Play mode starts. Do not treat it as an error in edit-mode checks. + +10. **Turning far casting off on a hand does not hold on its own.** In the hands rig, `PokeGestureDetector` events turn `enableFarCasting` off when a poke gesture starts and back on when it ends. Disable the hand's `PokeGestureDetector` too. + +11. **Deactivating a hand's Poke Interactor GameObject does not turn hand poke off.** `MetaSystemGestureDetector` on the hand calls `SetActive(true)` on it whenever the hand activates. Disable the `XRPokeInteractor` component instead. + +12. **Never modify an existing rig, even when the user asks you to change it.** Its structure and earlier overrides are unknown, so changing it can leave old settings behind (e.g., disabled turn providers that break turning). Ask replace (deactivate it, place a new rig) or new scene. A disabled component is not proof of the prefab default. + +13. **Don't activate the hand mesh objects in the hands rig.** `LeftHandQuestVisual` / `RightHandQuestVisual` (and the Android XR ones) are inactive in the prefab on purpose: the rig shows the right hand meshes for the platform at runtime. + +14. **Use the XR Interaction Simulator, never the XR Device Simulator.** XRI ships both samples; the Device Simulator is the old one. Do not turn on "Use Classic XR Device Simulator" either. + +*Add only rules where the error message alone does not point to the fix.* diff --git a/skills/create-xr/references/rig-recipes.md b/skills/create-xr/references/rig-recipes.md new file mode 100644 index 0000000..42dbba2 --- /dev/null +++ b/skills/create-xr/references/rig-recipes.md @@ -0,0 +1,238 @@ +# Rig Setup — Eval Recipes + +All recipes use fully qualified types (no `using` directives) so they can be passed to `unity command eval --code '...'` as-is. Replace `<...>` placeholders before running. + +## Table of Contents + +- [Read or set Active Input Handling](#read-or-set-active-input-handling) +- [Import a package sample](#import-a-package-sample) +- [Import TMP Essentials](#import-tmp-essentials) +- [Find the rig prefab](#find-the-rig-prefab) +- [Check the template Main Camera](#check-the-template-main-camera) +- [Set component fields (fallback)](#set-component-fields-fallback) +- [Name interaction layer 31 Teleport](#name-interaction-layer-31-teleport) +- [Turn on the XR Interaction Simulator](#turn-on-the-xr-interaction-simulator) +- [Add example content](#add-example-content) +- [Rig read-back](#rig-read-back) + +## Read or set Active Input Handling + +`activeInputHandler`: 0 = Input Manager (old), 1 = Input System, 2 = Both. A change takes effect after an Editor restart. To set, replace ``; to read only, remove the two lines that write. + +```csharp +var ps = UnityEditor.AssetDatabase.LoadAllAssetsAtPath("ProjectSettings/ProjectSettings.asset")[0]; +var so = new UnityEditor.SerializedObject(ps); +var p = so.FindProperty("activeInputHandler"); +if (p == null) return "activeInputHandler not found"; +var before = p.intValue; +p.intValue = ; so.ApplyModifiedProperties(); UnityEditor.AssetDatabase.SaveAssets(); +return "activeInputHandler " + before + " -> " + p.intValue; +``` + +## Import a package sample + +Replace `` (e.g., `com.unity.xr.interaction.toolkit`, `com.unity.xr.hands`) and `` with the exact display name (`Starter Assets`, `Hands Interaction Demo`, `HandVisualizer`). Import triggers a recompile — wait for the Editor to respond before continuing. + +```csharp +var info = UnityEditor.PackageManager.PackageInfo.FindForAssetPath("Packages/"); +if (info == null) return " is not installed"; +foreach (var s in UnityEditor.PackageManager.UI.Sample.FindByPackage(info.name, info.version)) { + if (s.displayName != "") continue; + if (s.isImported) return " already imported for " + info.version; + var ok = s.Import(UnityEditor.PackageManager.UI.Sample.ImportOptions.HideImportWindow | UnityEditor.PackageManager.UI.Sample.ImportOptions.OverridePreviousImports); + return " imported=" + ok + " (" + info.version + ")"; +} +return " not found in " + info.name + " " + info.version; +``` + +`isImported` is only true for the installed package version. If an older version's sample folder exists under `Assets/Samples//`, ask the user before importing — `OverridePreviousImports` replaces it. + +## Import TMP Essentials + +Starter Assets requires them. Non-interactive (no importer window): + +```csharp +if (UnityEditor.AssetDatabase.IsValidFolder("Assets/TextMesh Pro")) return "TMP Essentials already present"; +TMPro.TMP_PackageResourceImporter.ImportResources(true, false, false); +return "TMP Essentials import requested"; +``` + +The import finishes asynchronously; check that `Assets/TextMesh Pro` exists before continuing. + +## Find the rig prefab + +Replace `` with `XR Origin (XR Rig)` or `XR Origin Hands (XR Rig)`: + +```csharp +var r = ""; +foreach (var g in UnityEditor.AssetDatabase.FindAssets("t:Prefab \"\"", new[]{ "Assets/Samples" })) { + var path = UnityEditor.AssetDatabase.GUIDToAssetPath(g); + if (System.IO.Path.GetFileNameWithoutExtension(path) == "") r += path + "\n"; +} +return r == "" ? "not found" : r; +``` + +If more than one path is returned, use the one whose folder matches the installed package version. + +## Check the template Main Camera + +Targets the scene's root `Main Camera`, not the rig's child camera: + +```csharp +UnityEngine.GameObject cam = null; +foreach (var go in UnityEngine.SceneManagement.SceneManager.GetActiveScene().GetRootGameObjects()) + if (go.name == "Main Camera") cam = go; +if (cam == null) return "no root Main Camera"; +var names = ""; +foreach (var c in cam.GetComponents()) names += c.GetType().Name + ","; +var template = cam.transform.childCount == 0 && names == "Transform,Camera,AudioListener,UniversalAdditionalCameraData,"; +return "active=" + cam.activeSelf + " template=" + template + " components=" + names + " children=" + cam.transform.childCount; +``` + +## Set component fields (fallback) + +Use only if the Pipeline catalog has no command for setting component properties. Replace ``, ``, and the assignments. Records a prefab override, like editing in the Inspector. + +```csharp +var go = UnityEngine.GameObject.Find(""); +if (go == null) return "not found: "; +UnityEngine.Component comp = null; +foreach (var c in go.GetComponents()) if (c != null && c.GetType().Name == "") comp = c; +if (comp == null) return "no on "; +var so = new UnityEditor.SerializedObject(comp); +var p = so.FindProperty("m_SmoothMotionEnabled"); // example +if (p == null) return "field not found"; +p.boolValue = false; // example; use objectReferenceValue = null to clear a reference +so.ApplyModifiedProperties(); +return "set"; +``` + +`GameObject.Find` with a path only finds active objects. Save the scene afterwards. + +Use this recipe for nested fields too if the Pipeline command does not accept them: `FindProperty` takes a dotted path, e.g. `so.FindProperty("m_LeftHandMoveInput.m_InputSourceMode")` with `p.intValue = 0;` (Unused). + +## Name interaction layer 31 Teleport + +The Starter Assets teleport setup expects interaction layer 31 to be named `Teleport`. Only needed when teleport is on. Edits the XR Interaction Toolkit's interaction layer settings asset, as the Project Settings window does: + +```csharp +var guids = UnityEditor.AssetDatabase.FindAssets("t:InteractionLayerSettings"); +if (guids.Length == 0) return "InteractionLayerSettings asset not found"; +var asset = UnityEditor.AssetDatabase.LoadMainAssetAtPath(UnityEditor.AssetDatabase.GUIDToAssetPath(guids[0])); +var so = new UnityEditor.SerializedObject(asset); +var names = so.FindProperty("m_LayerNames"); +if (names == null || names.arraySize < 32) return "layer names not found"; +var layer = names.GetArrayElementAtIndex(31); +if (layer.stringValue == "Teleport") return "already Teleport"; +if (!string.IsNullOrEmpty(layer.stringValue)) return "layer 31 is already named '" + layer.stringValue + "' - ask the user"; +layer.stringValue = "Teleport"; +so.ApplyModifiedProperties(); +UnityEditor.AssetDatabase.SaveAssets(); +return "layer 31 named Teleport"; +``` + +## Turn on the XR Interaction Simulator + +Only when the user asks for the simulator, after importing the **XR Interaction Simulator** sample. Sets XRI's simulator settings (Project Settings > XR Plug-in Management > XR Interaction Toolkit). The settings class is internal, so this edits its asset: + +```csharp +var s = UnityEditor.AssetDatabase.LoadAssetAtPath("Assets/XRI/Settings/Resources/XRDeviceSimulatorSettings.asset"); +if (s == null) return "XRDeviceSimulatorSettings.asset not found (XRI settings not created yet)"; +string prefab = null; +foreach (var g in UnityEditor.AssetDatabase.FindAssets("t:Prefab \"XR Interaction Simulator\"", new[]{ "Assets/Samples" })) { + var p = UnityEditor.AssetDatabase.GUIDToAssetPath(g); + if (System.IO.Path.GetFileNameWithoutExtension(p) == "XR Interaction Simulator") prefab = p; +} +if (prefab == null) return "XR Interaction Simulator prefab not found: import the sample first"; +var so = new UnityEditor.SerializedObject(s); +var on = so.FindProperty("m_AutomaticallyInstantiateSimulatorPrefab"); +var editorOnly = so.FindProperty("m_AutomaticallyInstantiateInEditorOnly"); +var classic = so.FindProperty("m_UseClassic"); +var pf = so.FindProperty("m_SimulatorPrefab"); +if (on == null || editorOnly == null || classic == null || pf == null) return "simulator settings fields not found (XRI version changed?)"; +on.boolValue = true; editorOnly.boolValue = true; classic.boolValue = false; +pf.objectReferenceValue = UnityEditor.AssetDatabase.LoadAssetAtPath(prefab); +so.ApplyModifiedProperties(); UnityEditor.EditorUtility.SetDirty(s); UnityEditor.AssetDatabase.SaveAssets(); +return "simulator on in Editor Play mode only, prefab " + prefab; +``` + +If more than one prefab path exists, use the one whose folder matches the installed XRI version. + +## Add example content + +Only after placing a rig, and only if the user says yes. First check that the scene has nothing but the template objects and the rig: + +```csharp +var scene = UnityEngine.SceneManagement.SceneManager.GetActiveScene(); +var template = new[]{ "Main Camera", "Directional Light", "Global Volume", "EventSystem", "XR Interaction Manager" }; +var other = ""; +foreach (var g in scene.GetRootGameObjects()) + if (g.GetComponentInChildren(true) == null && System.Array.IndexOf(template, g.name) < 0) other += g.name + "; "; +return other == "" ? "empty" : "has content: " + other; +``` + +If it returns `empty` and the user agrees, add the Starter Assets demo pieces: a floor to teleport and move on, objects to grab, and a button to poke: + +```csharp +var inv = System.Globalization.CultureInfo.InvariantCulture; +var items = new[]{ "Teleport Area|0,-0.125,0|0,0,0|2,1,4", "Interactables Sample|0,0.25,-0.9|0,0,0|1,1,1", "Far Grab Samples|0,0,0|0,180,0|1,1,1", "Push Button|0.15,0.95,0.45|0,0,0|1,1,1" }; +var r = ""; +foreach (var it in items) { + var p = it.Split((char)124); string path = null; + foreach (var g in UnityEditor.AssetDatabase.FindAssets("t:Prefab \"" + p[0] + "\"", new[]{ "Assets/Samples" })) { + var a = UnityEditor.AssetDatabase.GUIDToAssetPath(g); + if (System.IO.Path.GetFileNameWithoutExtension(a) == p[0] && a.Contains("/Starter Assets/DemoAssets/")) path = a; + } + if (path == null) { r += "missing " + p[0] + "; "; continue; } + var o = (UnityEngine.GameObject)UnityEditor.PrefabUtility.InstantiatePrefab(UnityEditor.AssetDatabase.LoadAssetAtPath(path)); + var t = p[1].Split((char)44); var e = p[2].Split((char)44); var s = p[3].Split((char)44); + o.transform.position = new UnityEngine.Vector3(float.Parse(t[0], inv), float.Parse(t[1], inv), float.Parse(t[2], inv)); + o.transform.eulerAngles = new UnityEngine.Vector3(float.Parse(e[0], inv), float.Parse(e[1], inv), float.Parse(e[2], inv)); + o.transform.localScale = new UnityEngine.Vector3(float.Parse(s[0], inv), float.Parse(s[1], inv), float.Parse(s[2], inv)); + r += "added " + o.name + "; "; +} +var sc = UnityEngine.SceneManagement.SceneManager.GetActiveScene(); +UnityEditor.SceneManagement.EditorSceneManager.MarkSceneDirty(sc); UnityEditor.SceneManagement.EditorSceneManager.SaveScene(sc); +return r + "saved"; +``` + +`Teleport Area` is on the Teleport interaction layer (31), which the rig's teleport ray uses. Each piece is a linked prefab instance the user can delete. + +## Rig read-back + +Read-only. Compare the output against the user's answers. + +```csharp +Unity.XR.CoreUtils.XROrigin origin = null; int active = 0, inactive = 0; +foreach (var o in UnityEngine.Object.FindObjectsByType(UnityEngine.FindObjectsInactive.Include, UnityEngine.FindObjectsSortMode.None)) + if (o.gameObject.activeInHierarchy) { origin = o; active++; } else inactive++; +if (origin == null) return "No active XR Origin in the open scene" + (inactive > 0 ? " (" + inactive + " inactive)" : ""); +if (active > 1) return active + " active XR Origins in the scene; only one rig may be active"; +var r = "rig=" + origin.name + " link=" + UnityEditor.PrefabUtility.GetPrefabInstanceStatus(origin.gameObject) + (inactive > 0 ? " (+" + inactive + " inactive)" : "") + "\n"; +var cams = 0; foreach (var c in UnityEngine.Object.FindObjectsByType(UnityEngine.FindObjectsSortMode.None)) if (c.isActiveAndEnabled) cams++; +var ears = 0; foreach (var a in UnityEngine.Object.FindObjectsByType(UnityEngine.FindObjectsSortMode.None)) if (a.isActiveAndEnabled) ears++; +r += "activeCameras=" + cams + " activeListeners=" + ears + "\n"; +foreach (var c in origin.GetComponentsInChildren(true)) { + if (c == null) continue; + var t = c.GetType().Name; + if (t == "ControllerInputActionManager") { + var so = new UnityEditor.SerializedObject(c); + var sm = so.FindProperty("m_SmoothMotionEnabled"); var st = so.FindProperty("m_SmoothTurnEnabled"); + var tm = so.FindProperty("m_TeleportMode"); var tc = so.FindProperty("m_TeleportModeCancel"); + r += c.name + ": smoothMotion=" + (sm == null ? "?" : sm.boolValue.ToString()) + + " smoothTurn=" + (st == null ? "?" : st.boolValue.ToString()) + + " teleportMode=" + (tm == null ? "?" : (tm.objectReferenceValue != null ? "set" : "empty")) + + " teleportCancel=" + (tc == null ? "?" : (tc.objectReferenceValue != null ? "set" : "empty")) + "\n"; + } + else if (t == "NearFarInteractor") { + var so = new UnityEditor.SerializedObject(c); + var n = so.FindProperty("m_EnableNearCasting"); var f = so.FindProperty("m_EnableFarCasting"); + r += " NearFar @" + c.transform.parent.name + " active=" + c.gameObject.activeInHierarchy + " near=" + (n == null ? "?" : n.boolValue.ToString()) + " far=" + (f == null ? "?" : f.boolValue.ToString()) + "\n"; + } + else if (t == "XRPokeInteractor" || t.EndsWith("Provider") && !t.Contains("Affordance")) + r += " " + t + " @" + c.name + " " + (c.enabled && c.gameObject.activeInHierarchy ? "on" : "off") + "\n"; +} +return r; +``` + +A `?` means the field was not found — the XRI version may have renamed it; report it rather than guessing. diff --git a/skills/create-xr/references/rig-structure.md b/skills/create-xr/references/rig-structure.md new file mode 100644 index 0000000..6528854 --- /dev/null +++ b/skills/create-xr/references/rig-structure.md @@ -0,0 +1,88 @@ +# Starter Assets XR Origin Rig — Structure Reference + +## Table of Contents + +- [Hierarchy](#hierarchy) +- [Root Components](#root-components) +- [Controller Components](#controller-components) +- [Locomotion Providers](#locomotion-providers) +- [How ControllerInputActionManager Routes the Thumbsticks](#how-controllerinputactionmanager-routes-the-thumbsticks) +- [Turning Teleport Off](#turning-teleport-off) +- [Hand Tracking Rig](#hand-tracking-rig) + +## Hierarchy + +``` +XR Origin (XR Rig) +├── Camera Offset +│ ├── Main Camera +│ ├── Left Controller +│ │ ├── Poke Interactor +│ │ ├── Near-Far Interactor +│ │ └── Teleport Interactor +│ └── Right Controller +│ ├── Poke Interactor +│ ├── Near-Far Interactor +│ └── Teleport Interactor +└── Locomotion + ├── Turn (SnapTurnProvider, ContinuousTurnProvider) + ├── Move (DynamicMoveProvider) + ├── Grab Move (GrabMoveProvider, TwoHandedGrabMoveProvider) — inactive by default + ├── Teleportation (TeleportationProvider) + ├── Climb (ClimbProvider, ClimbTeleportInteractor) + ├── Gravity (GravityProvider) + └── Jump (JumpProvider) +``` + +## Root Components + +| Component | Role | +|---|---| +| XROrigin | Tracking origin; references the camera and Camera Offset | +| CharacterController | Collision for locomotion | +| InputActionManager | Enables the XRI default input actions | +| XRInputModalityManager | Switches between controllers and hands; deactivates controllers that are not tracked | + +## Controller Components + +| Component | Role | +|---|---| +| ControllerInputActionManager (sample script) | Routes the thumbstick to move, teleport, or turn; toggles the Teleport Interactor | +| XRInteractionGroup | Coordinates the Near-Far and Poke interactors | +| NearFarInteractor (child) | Near grab and far pointing, including UI by ray. Near and far casting can be turned off separately | +| XRPokeInteractor (child) | Poking buttons and UI | +| XRRayInteractor (child "Teleport Interactor") | Teleport aiming only | + +## Locomotion Providers + +All providers go through the LocomotionMediator and XRBodyTransformer on the Locomotion object. Keep those enabled even if every provider is disabled. + +## How ControllerInputActionManager Routes the Thumbsticks + +At runtime it enables input actions per controller: + +| Action | Enabled when | +|---|---| +| Move | `m_SmoothMotionEnabled` = true | +| Teleport mode / cancel | `m_SmoothMotionEnabled` = false | +| Continuous turn | `m_SmoothMotionEnabled` = false and `m_SmoothTurnEnabled` = true | +| Snap turn | `m_SmoothMotionEnabled` = false and `m_SmoothTurnEnabled` = false | + +So a controller is either a **move** stick (move and strafe, no turning) or a **teleport + turn** stick. Prefab default: left = move, right = teleport + snap turn. + +## Turning Teleport Off + +Disabling the Teleport Interactor or the TeleportationProvider is not enough on its own. When the teleport input fires, `ControllerInputActionManager` re-activates the Teleport Interactor and hides the Near-Far Interactor. + +To turn teleport off on a controller that is a teleport + turn stick: + +1. Clear `m_TeleportMode` and `m_TeleportModeCancel` on its `ControllerInputActionManager` (set them to `null`). The teleport input never fires; turning still works. +2. Disable the `TeleportationProvider`. Climb teleport (`ClimbTeleportInteractor`) also goes through it. + +A move stick (`m_SmoothMotionEnabled` = true) already has its teleport input disabled. + +## Hand Tracking Rig + +`XR Origin Hands (XR Rig)` (Hands Interaction Demo sample) contains the controller rig above plus a **Left Hand** and **Right Hand**, each with a Poke Interactor and a Near-Far Interactor, and a **Hands Smoothing Post Processor**. `XRInputModalityManager` switches between the controllers and hands automatically. + +On each hand, `PokeGestureDetector` events set the hand's `NearFarInteractor.enableFarCasting` off when a poke gesture starts and back on when it ends, and `MetaSystemGestureDetector` re-activates the hand's Poke Interactor GameObject whenever the hand activates. diff --git a/skills/create-xr/references/rig.md b/skills/create-xr/references/rig.md new file mode 100644 index 0000000..0482d13 --- /dev/null +++ b/skills/create-xr/references/rig.md @@ -0,0 +1,128 @@ +# Rig procedure + +Relative paths in this file resolve to the skill directory. + +## Table of Contents + +- [Docs](#docs) +- [1. Pre-flight](#1-pre-flight) +- [2. Prerequisites](#2-prerequisites) +- [3. Place the rig](#3-place-the-rig) +- [4. Configure](#4-configure) +- [5. Validate](#5-validate) +- [6. For the final report](#6-for-the-final-report) +- [Rule](#rule) + +Add a configured XR rig to the open scene: import the XR Interaction Toolkit Starter Assets rig prefab, place it as a linked prefab instance, and configure input, interactions, and locomotion from the user's answers. Requires the setup procedure first: if `status.sh` hasn't run in this session, run it now, and run setup if it reads todo. Read `references/rig-pitfalls.md` first. + +## Docs + +- `com.unity.xr.interaction.toolkit`: `samples-starter-assets.md` (the rig prefabs), `near-far-interactor.md`, `locomotion.md`, `teleportation.md`, `continuous-movement.md`, `snap-turning.md`, `interaction-layers.md` (the Teleport layer). +- `com.unity.xr.hands` (hand tracking): `project-setup/install-xrhands.md`, `openxr-features/metahandtrackingaim.md`; XR Interaction Toolkit `samples-hands-interaction-demo.md`. + +## 1. Pre-flight + +Only surface these to the user if something is wrong. + +1. **Open scene.** If no scene is open, open the project's first scene in the build list, or ask the user which scene to use. +2. **Existing rig.** If the scene already contains an XR Origin, do not modify it — even if it looks like an unmodified Starter Assets rig, and even if the user asks you to change their rig (e.g., "add teleport to my rig"). Don't offer to edit it. Ask: replace it (deactivate the existing rig and place a new one), or put the new rig in a new scene. Only deactivate the existing rig; don't rename or change it. If the names need to differ, rename the new rig. Replacing breaks any references the user's objects hold to the old rig — say so. +3. **Active Input Handling.** If it is set to the old Input Manager only, set it to Both (recipe in rig-recipes.md) and tell the user the Editor must restart before the rig receives input. +4. **XR Interaction Toolkit.** Setup installs it. If it is missing (e.g., the project was set up without this skill), install it with the shared helper (skips it if already installed, waits for the reload, stops on a blocking dialog): + + ``` + source "/scripts/_eval.sh" && install_package com.unity.xr.interaction.toolkit + ``` +5. **Versions.** Read the installed XR Interaction Toolkit version. Sample versions must match it. + +## 2. Prerequisites + +1. **If hand tracking was chosen:** setup has already installed XR Hands and enabled the OpenXR hand features (`setup.sh --hands`). If `com.unity.xr.hands` is not installed — e.g., setup ran earlier without `--hands` — re-run setup with the same devices plus `--hands`; it skips everything already done. +2. **TMP Essentials, before the samples.** Starter Assets requires them, and importing the samples first opens the TMP importer window. If `Assets/TextMesh Pro` does not exist, import them with the recipe and wait until the folder exists. +3. **Import samples** with the sample import recipe — only these, matched by exact display name: + - XR Interaction Toolkit **Starter Assets** (always) + - XR Hands **HandVisualizer** and XR Interaction Toolkit **Hands Interaction Demo** (hand tracking only) + + If a sample is already imported for a different package version, ask before updating it. +4. Wait for the recompile to finish before continuing. +5. **Simulator — only if the user asks for it.** Import the XRI **XR Interaction Simulator** sample (exact name) with the sample import recipe, then turn on XRI's "Use XR Interaction Simulator in scenes" setting with the simulator recipe. It then appears automatically in Editor Play mode only — tell the user. Never use the XR Device Simulator. + +## 3. Place the rig + +1. **Find the prefab** in the imported sample folder with the recipe — the folder path includes the version, so do not hardcode it: + - Controllers only → **XR Origin (XR Rig)** + - With hand tracking → **XR Origin Hands (XR Rig)** +2. **Place it** with the Pipeline's prefab-instantiate command. Confirm it is a linked prefab instance. +3. **The scene's own Main Camera.** Target it by hierarchy path `/Main Camera` — the rig has its own child named "Main Camera". Use the template camera recipe: + - **Untouched template camera** (only Transform, Camera, AudioListener, URP camera data; no children): disable it and tell the user. + - **Customized camera:** ask before disabling it. +4. Save the scene. + +## 4. Configure + +Every change is a prefab override. Use the Pipeline's command for setting component properties (it writes serialized fields by name and accepts `null` to clear a reference); fall back to the `eval` recipe if the catalog has none. Target components by hierarchy path, e.g. `--target '{"hierarchyPath":"/XR Origin (XR Rig)/Camera Offset/Right Controller"}' --type ControllerInputActionManager`; for the hands rig the root is `XR Origin Hands (XR Rig)`. See `references/rig-structure.md` for where each component lives and how locomotion works. + +### Interactions (each controller) + +| Not chosen | Change | +|---|---| +| Near | Near-Far Interactor: near casting off | +| Far | Near-Far Interactor: far casting off | +| Poke | Disable the Poke Interactor GameObject | + +**With hand tracking, apply the same choices to each hand** (`Camera Offset/Left Hand`, `Camera Offset/Right Hand`), with two differences: + +- **No poke on a hand:** disable the `XRPokeInteractor` component on the hand's Poke Interactor — not its GameObject, which the hand re-activates (rig-pitfalls.md). +- **Far or poke off on a hand:** also disable the hand's `PokeGestureDetector`, or far casting turns back on after a poke gesture. + +### Hand tracking only + +Hide the controllers and stop their input from moving the user: + +1. On the rig root's `XRInputModalityManager`, clear `m_LeftController` and `m_RightController` (`null`). +2. Deactivate the `Left Controller` and `Right Controller` GameObjects. +3. Set the controller inputs on the locomotion providers to Unused (`m_InputSourceMode` = 0) — with the controllers inactive, nothing else turns their stick actions off, so a picked-up controller would still move and turn the user: + - `Locomotion/Move` `DynamicMoveProvider`: `m_LeftHandMoveInput`, `m_RightHandMoveInput` + - `Locomotion/Turn` `SnapTurnProvider` and `ContinuousTurnProvider`: `m_LeftHandTurnInput`, `m_RightHandTurnInput` + - `Locomotion/Jump` `JumpProvider`: `m_JumpInput` + + These are nested fields: use the dotted path, e.g. `m_LeftHandMoveInput.m_InputSourceMode`. Keep the providers enabled. Skip the locomotion and turning tables below. + +### Locomotion (each controller's `ControllerInputActionManager`) + +`m_SmoothMotionEnabled` sets each thumbstick's job: `true` = move and strafe (no turning); `false` = teleport (push forward) and turn (left/right). + +| Movement | Left `m_SmoothMotionEnabled` | Right `m_SmoothMotionEnabled` | Also | +|---|---|---|---| +| Teleport | false | false | — | +| Continuous | true | false | Right: clear `m_TeleportMode` and `m_TeleportModeCancel`; disable `TeleportationProvider` | +| Both (prefab default) | true | false | — | +| Stationary | false | false | Both: clear `m_TeleportMode` and `m_TeleportModeCancel`; disable `TeleportationProvider` and the Move provider | + +Unless the user asks otherwise, Stationary keeps turning. + +**Continuous with no turning:** the right stick has no other job, so make it a move stick too — right `m_SmoothMotionEnabled` = true, in addition to the Continuous row's changes. + +### Turning (both controllers) + +Set the turn type on both controllers, even a move stick, so it holds if the user later switches a stick to teleport and turn. + +- **Snap:** `m_SmoothTurnEnabled` = false +- **Continuous:** `m_SmoothTurnEnabled` = true +- **None:** disable `SnapTurnProvider` and `ContinuousTurnProvider` + +Leave the Climb, Gravity, Jump, and Grab Move providers as the prefab has them. Save the scene. + +## 5. Validate + +1. **Rig read-back.** Run the rig read-back recipe and compare against the user's answers: the rig is linked, exactly one active camera and AudioListener, per-controller move/turn values and teleport input references, interactors and providers on or off as expected. In edit mode the Teleport Interactor shows as active — this is expected; it switches off when Play mode starts. +2. **Starter Assets project validation items.** TMP Essentials must be present (step 2). If teleport is on, interaction layer 31 must be named `Teleport` — set it with the recipe in rig-recipes.md if it is not. + +## 6. For the final report + +- **If far and poke are both off**, warn that world-space UI cannot be used without one of them. +- List every override this step made (the skill's final report covers how to revert them). +- **If the scene had nothing but the template objects and the rig**, offer example content to try the rig: a floor to teleport and move on, objects to grab, and a button to poke. For hand tracking only, describe the floor as just a floor: hands can't teleport or move on it. Add it only if the user says yes (recipe in rig-recipes.md). + +## Rule + +Start from the Starter Assets prefab and change it only by overrides: never build a rig from components, unpack the prefab, or remove components — disable or change them instead, so the user can revert every change. diff --git a/skills/create-xr/references/setup-manual.md b/skills/create-xr/references/setup-manual.md new file mode 100644 index 0000000..0fe208a --- /dev/null +++ b/skills/create-xr/references/setup-manual.md @@ -0,0 +1,61 @@ +# Setup by hand + +Relative paths in this file resolve to the skill directory. + +Only when the setup scripts cannot be used. Read `references/eval-guide.md` first. + +**Scripts:** step N below is `scripts/setup/N_*.sh` (e.g. step 4 = `4_openxr.sh`). For Quest, PC VR, and Android XR, run that script rather than doing the step by hand. Reuse the C# in the step's script where it applies. + +## 1. Platform modules + +Script: `1_modules.sh` + +Each target platform needs its build support module; the device package's get-started page names it. If one is missing, stop. Offer `unity install-modules --editor-version -m ` (IDs from `--list`; some include a version number) and ask first — it is a large download and the Editor may need a restart. + +## 2. Packages + +Script: `2_packages.sh` + +**First, Active Input Handling.** If it is Input Manager (old) only, set it to Both before installing anything — the Input System otherwise opens a dialog that blocks the Editor. Takes effect after an Editor restart; tell the user. + +Install one at a time with `source "/scripts/_eval.sh" && install_package ` (it skips installed packages). + +Always install `com.unity.xr.management`, `com.unity.xr.openxr`, and `com.unity.inputsystem`. Add the device package: `com.unity.xr.meta-openxr` for Quest; `com.unity.xr.androidxr-openxr` for Android XR (it brings AR Foundation as a dependency). + +Also install `com.unity.xr.interaction.toolkit`, and `com.unity.xr.hands` if the user wants hand tracking. The rig procedure imports the samples. + +## 3. Build profiles + +Script: `3_build_profile.sh` + +Use the device's own Build Profile platform if the Editor lists one (Meta Quest), otherwise its base platform (Android, Windows). See the Unity Manual's `building-and-publishing/build-settings/build-profiles.md`. + +1. **Create missing profiles** with the catalog's create-profile command (`--name --platform `), non-primary ones with `--activate false`. Never pass `--confirm true` — it overwrites a profile of the same name. No create command → ask the user to add it in **File > Build Profiles**. +2. **Activate the primary device's profile** (the first device named), unless already active: + - Switch the build target first (`--target --confirm true`), then poll its status command until `"status":"completed"` with `"success":true`. Pipeline refuses to activate a profile that needs a different target. + - New profile: create it with `--activate true`. Existing profile: there is no CLI command — activate it with `eval` (`BuildProfile.SetActiveBuildProfile`). Never recreate a profile to activate it. + - Confirm `"isActive":true` in the profile list, then set `EditorUserBuildSettings.selectedBuildTargetGroup` to the active target's group — activating from code leaves it out of sync. + +Quest-only needs no Windows profile — the Standalone OpenXR tab (Quest Link) works without one. + +## 4. OpenXR + +Script: `4_openxr.sh` + +Use OpenXR unless the user asks for another plug-in. Settings are per tab: Android (Quest on-device, Android XR) and Standalone (PC VR, Quest Link). Enable the loader on each tab, then the device's support feature and controller profiles. Read the OpenXR package's `project-configuration.md` and `features/metaquest.md`, and for Android XR its package's `get-started/project-setup.md`. If the user wants hand tracking, enable the hand-tracking features here too. + +## 5. Player settings + +Script: `5_player_settings.sh` + +Set them with `eval` naming the platform explicitly — never the Pipeline's player-settings command, which writes to the platform selected in the Build Profiles window, not the active one. Do this after step 3. + +Use the values in the Meta OpenXR package's `get-started/project-settings.md` (Quest) or the Android XR package's `get-started/project-setup.md`. + +After the last change, mark the active Build Profile dirty and call `AssetDatabase.SaveAssets()`: while a Build Profile is active, player settings live in the profile asset and are lost on restart unless it is saved. + +## 6. Validation + +Script: `6_validate.sh` + +Read back the active profile, the OpenXR loader and features per tab, and the installed packages. Note the results for the final report. diff --git a/skills/create-xr/references/setup.md b/skills/create-xr/references/setup.md new file mode 100644 index 0000000..4896593 --- /dev/null +++ b/skills/create-xr/references/setup.md @@ -0,0 +1,40 @@ +# Setup procedure + +Relative paths in this file resolve to the skill directory. + +Configure the project for the target devices: platform modules, packages, build profile, OpenXR, and player settings. + +## Docs + +- `com.unity.xr.management`: `EndUser.md` (XR Plug-in Management settings and loaders). +- `com.unity.xr.openxr`: `project-configuration.md` (OpenXR features and interaction profiles per platform), `features/metaquest.md`, `project-validation.md`. +- `com.unity.xr.meta-openxr` (Quest): `get-started/project-settings.md`. +- `com.unity.xr.androidxr-openxr` (Android XR): `get-started/project-setup.md`. + +## Run the setup script + +For Meta Quest, PC VR, and Android XR, one script does everything. List the devices the user named, primary first; add `--hands` if they want hand tracking (controllers and hands, or hands only) — it installs XR Hands and enables the OpenXR hand features, with or without a rig: + +``` +bash "/scripts/setup/setup.sh" quest +bash "/scripts/setup/setup.sh" quest pcvr +bash "/scripts/setup/setup.sh" --hands quest +``` + +Runs ~20× longer than `status.sh` and prints progress; set the timeout accordingly and don't pipe its output. + +It prints `OK` / `SKIP` / `WARN` / `FAILED` per step, waits for reloads itself, and ends with `=== XR base setup complete ===`. Every step is idempotent and already-done work is skipped, so after fixing a `FAILED` cause, re-run the same command. `FAILED [n/6 …]` names the step: step n is `scripts/setup/n_*.sh`, which takes the same arguments and can be re-run on its own. Do not rewrite the script or replace it with your own install or wait loops. + +| `FAILED` message contains | What to do | +|---|---| +| `is not installed for` (modules) | Ask the user before installing the module with the `unity install-modules` command the message names — large download, may need an Editor restart | +| `blocked by a dialog` | Ask the user to answer the named dialog in the Editor — never click it for them — then re-run | +| `no Pipeline command for` (exit 4) | Run the `unity command --query` the message names. If the command exists under a new name, re-run with the `PIPELINE_CMD_=""` override it names; otherwise report the line to the user | +| `did not start` (package add) | A parameter changed: check the command's parameters with the `--query` the message names, report it to the user | +| `could not create the profile` | Ask the user to add the profile in **File > Build Profiles**, then re-run | +| `not found on the … tab` | A required OpenXR feature is missing (package version?) — report the line to the user | +| `EVAL_FAILED` with compiler diagnostics, or `EVAL_NOT_FINISHED` | Report the line; for a timeout, wait ~10 s and re-run once | + +If the script reports `Input Manager (old) -> Both`, tell the user the Editor must restart before input works. + +Apple Vision Pro isn't covered by this skill. diff --git a/skills/create-xr/scripts/_eval.sh b/skills/create-xr/scripts/_eval.sh new file mode 100644 index 0000000..53e4d72 --- /dev/null +++ b/skills/create-xr/scripts/_eval.sh @@ -0,0 +1,292 @@ +#!/usr/bin/env bash +# _eval.sh — shared helpers, sourced by the skill's scripts. Not meant to be run directly. +# require_cmds ... resolve Pipeline command names against the Editor's catalog (see below) +# eval_result print the eval's return value, or EVAL_FAILED:/EVAL_NOT_FINISHED: + details +# run_eval