iwsdk-native-xr-test
Skill1 starsChanged 32 days agoMITView on GitHub
Test an IWSDK app in a real Quest immersive session while controlling headset and controller poses through the IWSDK CLI. Use when the user asks to run, automate, or debug an app on a connected Quest rather than in desktop IWER emulation.
In this repository58 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- cf-cliSkill
- durable-objectsSkill
- game-gdd-authorSkill
- game-playtestSkill
- pmndrs-handleSkill
- pmndrs-pointer-eventsSkill
- pmndrs-uikitSkill
- prototype-fastSkill
- pwa-offlineSkill
- review-game-trailerSkill
- scenario-blender-expertSkill
- scenario-blender-retopologySkill
- scenario-blender-uv-bakingSkill
- threejs-perf-loadingSkill
- webapp-testingSkill
- workers-best-practicesSkill
- wranglerSkill
- xr-perceptual-constraints-displays-and-trackingSkill
- xr-platforms-audio-and-comfortSkill
- xr-referenceSkill
- xr-rendering-input-and-spatial-understandingSkill
- xr-ux-design-and-performance-budgetingSkill
- horizon-launch-roadmapSkill
- horizon-store-listing-assetsSkill
- horizon-web-store-publishSkill
- horizon-web-vrc-checklistSkill
- iwsdk-asset-pipelineSkill
- iwsdk-dev-workflowSkill
- iwsdk-performanceSkill
- iwsdk-project-setupSkill
- iwsdk-quest-device-testingSkill
- iwsdk-testingSkill
- iwsdk-vr-glassesSkill
- quest-browser-webxrSkill
- iwsdk-build-modelSkill
- iwsdk-compose-sceneSkill
- iwsdk-debugSkill
- iwsdk-depth-occlusionSkill
- iwsdk-devSkill
- iwsdk-grabSkill
- iwsdk-hostingSkill
- iwsdk-migrate-0-5Skill
- iwsdk-physicsSkill
- iwsdk-pwa-packagingSkill
- iwsdk-raySkill
- iwsdk-uiSkill
- hz-immersive-designerSkill
- hz-iwsdk-webxrSkill
- hz-new-project-creationSkill
- hz-perfetto-debugSkill
- hz-quest-verify-firstSkill
- hz-simpleperf-debugSkill
- hz-store-pwaSkill
- hz-store-submitSkill
- hz-vr-debugSkill
- metavr-cliSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. About 0 are common, 8 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Run the app through an ADB-reversed localhost connection, enter the browser's real immersive session, and use the ordinary IWSDK XR, ECS, …
- Distinctive: line 19
Use only public Android platform tools and IWSDK commands.
- Very specific: line 21
Always work with an explicit device serial.
- Very specific: line 27
Keep the command bridge on loopback.
- Distinctive: line 35
Ask the user to approve it physically, then relaunch.
- Distinctive: line 37
Always remove the ADB reverse and stop the dev session during cleanup, including after a failed test.
- Very specific: line 58
Put it under the top-level runtimeTarget key of every headset command's --input-json, next to that command's own parameters.
- Very specific: line 61
Never select a headset page with expectedTab alone.
- Very specific: line 63
Never guess between candidates.
- Very specific: line 87
Run npm run --if-present typecheck and fix type errors before device testing.
- Very specific: line 89
Run adb devices and settle the explicit serial as described above.
- Very specific: line 135
Before each launch, run npx @iwsdk/cli runtime targets --raw and record the pageId and tabGeneration of every physical target whose …
- Very specific: line 150
Keep the nested URL encoded so ?, &, and fragment characters cannot be interpreted as parameters of the outer deep link.
- Distinctive: line 168
If no target appears, check in the headset that the page loaded from the pairing URL and did not redirect to a network hostname.
- Very specific: line 184
Do not use iwsdk xr enter for this step: that command accepts an emulated offer, while this workflow must preserve the browser's native …
- Very specific: line 197
Add the recorded runtimeTarget to each command's --input-json, next to the command's own parameters.
- Distinctive: line 208
Use the same commands as desktop automation.
- Distinctive: line 224
Run these cleanup actions individually even if an earlier assertion failed:
- Very specific: line 232
Use the most recently discovered runtimeTarget for xr exit.
- Distinctive: line 244
before/after evidence for the requested behavior.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Test on a physical Quest
Run the app through an ADB-reversed localhost connection, enter the browser's
real immersive session, and use the ordinary IWSDK XR, ECS, scene, and browser
commands to observe and control it. The native browser continues to own
XRSession, frame scheduling, rendering, and tracking; IWSDK/IWER selectively
override poses and input for the test.
The requested scenario is in $ARGUMENTS.
Safety and scope
- Use only public Android platform tools and IWSDK commands. Do not depend on a device-rental service, XRPilot, or internal Meta tooling.
- Always work with an explicit device serial. With exactly one authorized
device in
adb devices, use its serial. With several connected devices, require the user to name the serial to test; never choose one yourself. Pass-s <serial>to every ADB command and use the same serial as the IWSDKheadsetId. - Support Quest Browser only. Do not broaden the browser user-agent check.
- Keep the command bridge on loopback. Use
adb reverse; never expose or forward the bridge over a LAN. - Native control replaces the headset's native controller input sources with synthetic controllers for the duration of the test. Physical controller and hand-action playback are unavailable while the override is installed.
xr set-transformapplies absolute test poses, not offsets from live tracking.- A first run may show an immersive-WebXR permission prompt in the headset. Ask the user to approve it physically, then relaunch. Do not automate that permission dialog.
- Always remove the ADB reverse and stop the dev session during cleanup, including after a failed test.
Target the headset explicitly
A command without runtimeTarget always routes to the managed host browser,
never to a headset, even when a paired headset page is the only connected page.
This workflow starts with --no-open, so such a command fails with
browser_not_launched. Do not restart with --open to fix a headset command;
the managed browser never forwards commands to the Quest.
- Discover connected targets with
npx @iwsdk/cli runtime targets --raw. Each entry intargetscarries a nestedruntimeTargetobject and themethodsthat page supports. - A headset page qualifies only when its entry has
deviceClass: "physical",role: "app",commandReady: true, and aheadsetIdequal to the explicit serial. - Copy the qualifying entry's complete
runtimeTargetunchanged:deviceClass,headsetId,pageId,tabGeneration, and any returnedsessionIdorbrowserEpoch. Never rebuild it from separate fields, drop or edit a field, or pass the surrounding entry instead. - Put it under the top-level
runtimeTargetkey of every headset command's--input-json, next to that command's own parameters. It is unrelated to the position-vectortargetparameter of commands such asxr look-at. - Never select a headset page with
expectedTabalone. It carries nodeviceClassorheadsetId, so the command stays on the managed browser. - Never guess between candidates. If these rules do not identify exactly one
page, or a command returns
ambiguous_target, ask the user to close the extra app tabs in the headset, then rediscover. Do not fall back to list order, the newest entry, another headset, or an untargeted command. - A reload or relaunch advances the page generation. After one, or after a
stale_browser_tabortarget_unavailableerror, runruntime targetsagain and reselect with these rules. An oldruntimeTargetstays fenced to its generation. outcome_unknownmeans the command may have executed. Never replay it. Rediscover the target, inspect state with read-only commands such asxr status,ecs query, orscene transform, and only then decide whether a new command is needed.- Headset pages accept runtime commands only. Host-only browser tools, such as
screenshots, snapshots, interaction, profiling, and console capture, return
unsupported_on_target; check the entry'smethodsfirst.
To test several headsets in one dev session, set up each serial separately: one
adb -s <serial> reverse route and one runtime pair-headset call per device,
discovery by each device's own headsetId, and one recorded runtimeTarget per
headset. Send each command with the runtimeTarget of the headset it is meant
for; never reuse one headset's runtimeTarget for another.
1. Verify the app and device
Run npm run --if-present typecheck and fix type errors before device testing.
Run adb devices and settle the explicit serial as described above. Continue
only when that serial is in the device state. A pending, offline, or
unauthorized device is not ready.
This workflow expects a manifest-first app that imports
virtual:iwsdk-project and passes it to World.create(). For a hand-built
WorldOptions object, opt in explicitly with:
xr: {
// existing XR options
launchOnSessionGranted: true,
}2. Start the native-control dev session
From the application root, run:
npx @iwsdk/cli dev up --native-xr-control --no-openInspect npx @iwsdk/cli dev status and record the numeric port from the
active runtime. Native-control sessions default to HTTP when the application
does not explicitly configure Vite HTTPS. The app is loaded from
headset-localhost through ADB reverse, so the default remains a trustworthy
WebXR origin. --no-open leaves the managed host browser unlaunched, so only
commands that carry the headset's runtimeTarget can run.
3. Install the ADB route and pair the headset
Replace <serial> and <port> with the values verified above:
adb -s <serial> reverse tcp:<port> tcp:<port>
npx @iwsdk/cli runtime pair-headset --input-json '{"headsetId":"<serial>"}' --rawRecord the returned url. It carries this headset's pairing token for the
current dev session; an unpaired headset page is refused and never becomes a
target. Continue only if the URL points at localhost or 127.0.0.1 on
<port>. Pair again after any dev-session restart.
4. Enter the real immersive session
Before each launch, run npx @iwsdk/cli runtime targets --raw and record the
pageId and tabGeneration of every physical target whose headsetId is
<serial>.
URL-encode the returned pairing URL without changing its host or dropping its query, then launch:
adb -s <serial> shell am broadcast \
-n com.oculus.vrshell/.ShellControlBroadcastReceiver \
-a com.oculus.vrshell.intent.action.LAUNCH \
-d apk://com.oculus.browser \
-e uri "ovrweb://vr?uri=<encoded-pairing-url>"Keep the nested URL encoded so ?, &, and fragment characters cannot be
interpreted as parameters of the outer deep link.
Poll npx @iwsdk/cli runtime targets --raw. Select the qualifying target that
this launch created: its pageId was not recorded, or its tabGeneration is
higher than recorded. If exactly one target matches, record its complete
runtimeTarget. A physical target has this shape:
{
"deviceClass": "physical",
"headsetId": "<serial>",
"pageId": "<pageId>",
"tabGeneration": 1,
"sessionId": "<sessionId>"
}If no target appears, check in the headset that the page loaded from the pairing URL and did not redirect to a network hostname. If more than one matches, ask the user to close the extra tabs and relaunch.
Replace <runtimeTarget> below with the recorded object, verbatim:
npx @iwsdk/cli xr status --input-json '{"runtimeTarget":<runtimeTarget>}' --rawXR status must show an active immersive-vr or immersive-ar session. Its
browserConnected and browserCommandReady fields describe the managed host
browser, not the headset. If the session stays inactive, ask the user to accept
the one-time browser permission in the headset, then repeat this step from the
pre-launch record.
Do not use iwsdk xr enter for this step: that command accepts an emulated
offer, while this workflow must preserve the browser's native session.
5. Run the scenario
Discover the available command shapes before improvising:
npx @iwsdk/cli xr --help
npx @iwsdk/cli ecs --help
npx @iwsdk/cli scene --helpAdd the recorded runtimeTarget to each command's --input-json, next to the
command's own parameters. Here target is the world position to aim at:
npx @iwsdk/cli xr look-at --input-json \
'{"device":"controller-right","target":{"x":0,"y":1.2,"z":-1},"runtimeTarget":<runtimeTarget>}' --rawThe exact runtimeTarget both selects the intended headset page and rejects
stale commands after a page reload.
Use the same commands as desktop automation. Typical controls are:
xr set-transformfor headset or controller position/orientation.xr look-atto aim a controller ray at a world position.xr set-select-valueorxr selectfor trigger/pinch interaction.xr set-gamepad-statefor squeeze and controller buttons.ecs query,ecs snapshot, andecs difffor authoritative state.scene runtime-hierarchyandscene transformto locate and measure rendered objects.
Prove behavior with state, not only screenshots. For an interaction test, record the target transform or component state before the action, perform the pose/input sequence, and show the corresponding state change afterward.
6. Exit and clean up
Run these cleanup actions individually even if an earlier assertion failed:
npx @iwsdk/cli xr exit --input-json '{"runtimeTarget":<runtimeTarget>}' --raw
adb -s <serial> reverse --remove tcp:<port>
npx @iwsdk/cli dev downUse the most recently discovered runtimeTarget for xr exit. If it returns
stale_browser_tab or target_unavailable, rediscover and exit with the fresh
object; if it returns outcome_unknown, check xr status instead of repeating
the exit. Remove the reverse route from every device you configured.
Report:
- device serial (
headsetId) and app URL used; - the exact
runtimeTargetof the final command; - native session mode and enabled features;
- the selected target's command-ready state;
- pose/input actions performed;
- before/after evidence for the requested behavior;
- console errors or capability notes;
- confirmation that the reverse route and dev session were removed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

