Made by Navid Mirzaaghazadeh · part of iwsdk-webxr-skills · MIT
Gets a machine and a project to the state the official iwsdk-* skills expect: an IWSDK 1.x
manifest-first project, dependencies installed, Claude Code connected to the project's MCP servers,
and npx @iwsdk/cli dev status reporting browserCommandReady: true.
Hand-offs: building features → iwsdk-dev; testing on a Quest → iwsdk-quest-device-testing;
0.4.x projects (GLXF, Meta Spatial Editor) → iwsdk-migrate-0-5 first.
Ground rules
- Ask before installing Node, Playwright browsers, Android platform tools, or anything global.
Never run
npm i -gor edit~/.claudewithout a yes. adapter syncwrites project config (.mcp.json,.claude/settings.json). Say so before running it in an existing repo.- Don't install duplicate skills. Every scaffold already contains the 12 official skills in
.claude/skills/(and a copy in.agents/skills/). Install only this library'scustom/and extra skills into such a project. - Always use the scoped name
npx @iwsdk/cli ...(never an unscopediwsdkpackage via npx). The scope is a security boundary: npx could fetch an unrelated package otherwise. - Check flags with
--helpbefore relying on them:npx @iwsdk/create@latest --help,npx @iwsdk/cli dev up --help. This skill was checked against 1.0.1 (npmlatest;1.1.0-rc.1sits onnextand movesthreetosuper-three@0.185.0: use it only if the user asks). - IWSDK's docs on Meta's site (https://developers.meta.com/vr/documentation/iwsdk/guides/overview/)
were generated from IWSDK 0.5.3. They show unscoped
npx iwsdk …, port 5173, 45 MCP tools and two VR Glasses config keys 1.0.1 rejects. Prefer the installed package and https://iwsdk.dev; differences:docs/meta-reference/web-iwsdk-docs-on-meta.md.
1. Check the machine
node --version # must satisfy >=20.19.0 <21 || >=22.12.0 <23 || >=24.0.0
npm --version
git --version
The engine range comes from every @iwsdk/* package.json; the scaffold's .nvmrc is
22.12.0. Node 18 and Node 21/23 are rejected by @iwsdk/cli. If Node is wrong, ask which
version manager the user has (nvm, fnm, Volta, Homebrew) and use it; don't pick one for them.
Optional now, needed for the headset: Android platform tools (adb version) and desktop Chrome
(for chrome://inspect). See iwsdk-quest-device-testing.
2. Turn the pitch into flags
| Pitch says | Flag |
|---|---|
| Fully virtual world | --target vr |
| Passthrough, content in the real room | --target ar (the session mode is immersive-ar) |
| Desktop browser 3D, no headset | --target browser |
| Gravity, collisions, throwing | --physics (Havok; adds a JS + WASM payload) |
| Walk/teleport through a big space | --locomotion (VR and browser only) |
| Pick up and move objects | --grabbing |
| Real walls, floors, tables, anchors | --scene-understanding (AR only) |
| Place things on real surfaces (hit test) | --environment-raycast (AR only) |
Every boolean also has a --no-… form. Defaults with --yes: TypeScript, git init, install.
Recommended baselines (create README): VR = locomotion on a worker + grabbing, no physics;
mixed reality = grabbing only; desktop = browser camera, input, locomotion, interactions.
If the pitch is ambiguous in a way that changes the target or a feature, ask.
3. Scaffold
# new folder (npm create needs `--` before flags)
npm create @iwsdk@latest my-game -- --yes --target vr --grabbing --physics --no-locomotion
# same thing via npx
npx @iwsdk/create@latest my-game --yes --target vr --grabbing --physics --no-locomotion
# inside an existing, non-empty repo: --force is required and overwrites conflicting generated files
npx @iwsdk/create@latest . --yes --force --target vr
Useful extras: --no-install (inspect first), --no-git, --language js,
--skip-reference-warmup (skip the reference model download). Confirm before --force: it
overwrites generated files, keeps unrelated files and the existing git repo.
What lands in the project (full table: references/generated-files.md):
iwsdk.config.json project authority: scene, asset/component modules, world.xr, features, dev.emulator
src/index.ts World.create(container, projectOptions from 'virtual:iwsdk-project') + registerSystem
src/assets.ts defineAssets({...}): the asset catalog shared by runtime and editor
src/components.ts defineComponents([...])
public/scenes/main.iwsdk.scene.json authored scene (iwsdk.scene.v1)
public/ui/welcome.uikitml spatial UI panel
AGENTS.md + CLAUDE.md CLAUDE.md is "@AGENTS.md"
.claude/ skills (12), rules (4), agents/iwsdk-project-code-reviewer.md, settings.json
Change features in iwsdk.config.json (world.features, world.xr.features), not by
re-scaffolding. Editing it restarts Vite in place.
4. Install and connect Claude Code
cd my-game
npm install # skip if create already installed
npx @iwsdk/cli adapter sync --tools claude # create runs `adapter sync` (all tools) after installing
npx @iwsdk/cli adapter status
npx @iwsdk/cli reference warmup # one-time download of the reference corpus + pinned model
npx @iwsdk/cli reference status
adapter sync --tools claude writes .mcp.json with up to three stdio servers, each run with
node and an absolute path into node_modules:
| Server | Runs | Gives Claude |
|---|---|---|
iwsdk-runtime |
@iwsdk/cli/dist/cli.js mcp stdio |
55 tools in 1.0.1: xr_* (16), browser_* (6), scene_* (13, incl. 3 live-runtime inspectors), ecs_* (11), ui_* (3), asset_render_preview, runtime_* (5, session and headset pairing). Meta's pages say 45 (0.5.3) or 32; trust npx @iwsdk/cli mcp inspect |
iwsdk-reference |
@iwsdk/reference entrypoint |
semantic search, API lookup, component/system lists |
metavr |
@meta-quest/metavr/bin.js mcp server |
Quest device control, Meta docs search, 3D asset search |
It also adds enabledMcpjsonServers and narrow mcp__<server>__* allow rules to
.claude/settings.json, and removes an old enableAllProjectMcpServers: true if present.
Then restart the Claude Code session and check with /mcp. Snippet and details:
references/claude-code-mcp.md.
If MCP tools are missing or deferred, use the CLI: every tool has a CLI twin
(xr_get_session_status = npx @iwsdk/cli xr status, browser_screenshot =
npx @iwsdk/cli browser screenshot). npx @iwsdk/cli mcp inspect --tool <name> prints a schema.
Cloned a teammate's repo? .mcp.json, .cursor/mcp.json, .vscode/mcp.json,
.codex/config.toml and .iwsdk/ are git-ignored by the scaffold. Run npm install, then
npx @iwsdk/cli adapter sync --tools claude and reference warmup on each machine.
5. Start the dev server
npm run dev # = iwsdk dev restart --open --foreground (headed, attached)
npx @iwsdk/cli dev up --ai-mode agent # headless, fixed 800x800 viewport, returns to the shell
npx @iwsdk/cli dev up --ai-mode collaborate # one visible managed Chromium window with Runtime/Editor
npx @iwsdk/cli dev status # data.runtimeUrls.local / .network, data.state.browserCommandReady
npx @iwsdk/cli dev logs --tail 100
npx @iwsdk/cli dev down
- The developer owns headed vs headless. Announce a change before restarting.
- Wait for
browserCommandReady: truebefore browser, XR or ECS commands;dev upcan return earlier. (Meta's AI page also namesstate.session.browser.commandReady; in 1.0.1browserCommandReadyis computed from it.) - Port 8081 (
vite.config.tsserver.port) fails if busy instead of moving. Stop the other process (lsof -i :8081) or change the port. - HTTPS is on:
iwsdkDev()generates a self-signed certificate cached in.iwsdk/httpsand installs no CA. The managed browser accepts it; a headset shows a one-time warning.iwsdkDev({ https: false })opts out (WebXR then only works onlocalhost). - First smoke test:
npx @iwsdk/cli browser screenshot --output-file artifacts/first.png, thennpx @iwsdk/cli xr enterandnpx @iwsdk/cli xr status.
6. Emulator (IWER) settings
In iwsdk.config.json → dev.emulator (defaults from @iwsdk/vite-plugin-dev types):
| Key | Default | Notes |
|---|---|---|
device |
metaQuest3 |
also metaQuest2, metaQuestPro, metaVRGlasses, oculusQuest1. metaVRGlasses (IWSDK 1.0.0+, IWER 2.5.0+) = Quest 3 capabilities plus the glasses' view mask (74° × 68°: 25° up, 43° down) and a gaze source; pick Gaze + Hands in the toolbar (iwsdk-vr-glasses) |
activation |
localhost |
emulate only on localhost; always or a RegExp |
userAgentException |
/OculusBrowser/ |
never emulate in Quest Browser |
environment |
none (AR scaffolds use living_room) |
living_room, meeting_room, music_room, office_large, office_small. 1.1.0-rc.1 replaces them with sunlit_living_room, home_office, conference_room, open_office, kitchen, bedroom, music_studio, open_studio (old ids still load, mapped) |
iwer |
true |
false = never inject (browser-only apps) |
injectOnBuild |
false |
keep false for store builds |
Next to it, dev.targetDevicePreview.gazeSimulation: "head" (1.0.1) adds a head-directed test
gaze source to a real Quest session when the app requests gazeTracking; dev server only, and
it needs iwer left on (iwsdk-quest-device-testing §7).
7. Cloud and headless machines
- The managed browser is Playwright Chromium. It picks GPU or SwiftShader automatically;
override with
IWSDK_GPU=auto|gpu|swiftshader(vite-plugin-dev/src/managed-browser/launch.ts). SwiftShader frame times are meaningless for performance. Executable doesn't exist at …/chromium_headless_shell-…: install the browser for the Playwright version the project resolves:npm ls playwright, thennpx playwright@<that version> install chromium(on Linux CI add--with-deps).- Long screenshots cost context:
--screenshot-width 500 --screenshot-height 500ondev up.
8. Adding IWSDK to an existing Vite app
Prefer scaffolding a throwaway project with the same target and copying its iwsdk.config.json,
vite.config.ts, src/assets.ts, src/components.ts, .claude/ and AGENTS.md. The runtime
needs one shared Three.js instance:
{
"dependencies": { "@iwsdk/core": "^1.0.1", "three": "npm:super-three@0.181.0" },
"overrides": { "three": "npm:super-three@0.181.0" }
}
(pnpm reads the override from pnpm-workspace.yaml.) Import Three.js classes from
@iwsdk/core, not three. Keep every @iwsdk/* package on the same version.
9. Side effects and privacy
Scaffolds add @meta-quest/metavr (Meta's Quest CLI) as a dev dependency. Tell the user, before
the first npm install, what it does:
- Postinstall writes outside the project (read in
postinstall.js/download.jsof 1.8.1): it downloads themetavrbinary fromsecurecdn.oculus.cominto~/.metavr(or$METAVR_HOME) and appends a completions block to~/.zshrc, or~/.bash_profile/~/.bashrc, or the PowerShell profile. To avoid that, install withMETAVR_SKIP_DOWNLOAD=1 npm install(the binary is then fetched on firstmetavrrun), or remove the package. - Telemetry: when it is installed,
@iwsdk/cliand the Vite plugin report each runtime tool call (tool name, duration, a fixed failure code, session id) throughmetavr, which also has its own telemetry.npm exec metavr -- telemetry status/telemetry disable(essential only). npm uninstall @meta-quest/metavrstops both, and removes themetavrMCP server and device tools (you can still useadbdirectly). Let the user choose.
Troubleshooting
| Symptom | Fix |
|---|---|
Unsupported Node from @iwsdk/cli |
Node outside the engine range (step 1) |
dev up fails, port in use |
another server on 8081; stop it or change server.port |
browser_not_launched |
started with --no-open; npx @iwsdk/cli dev restart --open |
| Runtime commands time out | xr status → browser logs → browser reload → dev restart, in that order |
iwsdk-runtime tools absent in Claude |
adapter sync --tools claude, restart session, /mcp; use CLI meanwhile |
| Reference tools say warmup required | npx @iwsdk/cli reference warmup |
Cryptic errors from node_modules/.vite/deps/chunk-*.js after an update |
stop the server, rm -rf node_modules/.vite/deps, start again (IWSDK troubleshooting page) |
| "Only pmndrs/uikit components can be added as children" | duplicate Three/UIKit graph; keep the scaffold's resolve.dedupe in vite.config.ts |
Scaffold's install step fails with EALLOWSCRIPTS (--allow-scripts not allowed in project installs), seen with npm 11.19 |
The project is created; install by hand: npm install, then npm install-scripts approve esbuild protobufjs and npm install-scripts deny @meta-quest/metavr onnxruntime-node (the intent of the scaffold's pnpm settings). Denying metavr's script also skips its ~/.metavr download and shell-profile edit (§9) |
| Two IWSDK apps on one machine | Both scaffolds use 8081 and the port is strict; give the second app another server.port (and use that port on the headset) |
/mcp shows two or three metavr servers, and every hz-* skill twice |
Someone ran metavr init, which installs Meta's plugin, skills and an MCP entry at user scope (metavr 1.8.0.17.10, 2026-10-25). Keep adapter sync's entry and one source of skills; this library's docs/meta-reference/ai-tools.md §3 lists what metavr init writes and how to move it into the project |
Sources
- https://github.com/facebook/immersive-web-sdk (commit
0778f518, 1.0.1):packages/create/src/cli.ts,src/catalog.ts,src/project-files.ts,packages/cli/src/mcp-adapters.ts,agent-adapters.ts,help.ts,packages/vite-plugin-dev/src/types.ts,template/common/vite.config.ts - https://iwsdk.dev/guides/01-project-setup.html
- https://iwsdk.dev/guides/02-testing-experience.html
- https://iwsdk.dev/ai/getting-started.html, https://iwsdk.dev/ai/modes.html
- https://iwsdk.dev/skill.md (headless GPU and Playwright notes)
- https://www.npmjs.com/package/@iwsdk/create (1.0.1, 2026-10-16)
EALLOWSCRIPTSwith npm 11.19 and theinstall-scriptsfix: seen while scaffolding an IWSDK 1.0.1 VR prototype, 2026-10-16- npm
@iwsdk/cli1.0.1dist/cli.js(RUNTIME_MCP_TOOLS,tools/list,isRuntimeBrowserCommandReady); npm@iwsdk/core1.0.1 and 1.1.0-rc.1dist/project/types.d.ts,environments.js(read 2026-10-17;nexttag 1.1.0-rc.1 published 2026-10-13) - https://developers.meta.com/horizon/documentation/iwsdk/ai/mcp-tools/ (2026-09-04, "45 tools", IWSDK 0.5.3), /ai/getting-started/ (2026-09-23)
- npm
iwer2.6.0lib/device/configs/headset/meta.js(metaVRGlassesview mask) metavr init(metavr 1.8.0.17.10) run on macOS with Claude Code 2.1.310, 2026-10-25
Last verified: 2026-10-25 (the metavr init row); 2026-10-17 (the rest)