iwsdk-project-setup
Skill1 starsChanged 30 days agoMITView on GitHub
Sets up a machine and a project for Meta Immersive Web SDK (IWSDK) WebXR development with Claude Code: checks Node, maps the game pitch to `npm create @iwsdk@latest` flags (vr/ar/browser, physics, locomotion, grabbing, scene understanding), explains the generated files (AGENTS.md, .claude skills/rules/agent), connects Claude Code to the iwsdk-runtime (55 tools), iwsdk-reference and metavr MCP servers with `adapter sync`, starts the CLI-managed dev server (HTTPS, port 8081, IWER incl. `metaVRGlasses`, agent or collaborate mode), and fixes headless/cloud setups (IWSDK_GPU, Playwright Chromium). Use when starting an IWSDK or WebXR project, when the user says "set up IWSDK", "npm create @iwsdk", "scaffold a WebXR game", "MCP tools missing", "which MCP tools exist", "iwsdk-runtime not connected", "Node version unsupported", "port 8081 in use", "Executable doesn't exist" (Playwright), "EALLOWSCRIPTS" in the scaffold's install, when cloning a teammate's IWSDK repo, or when adding IWSDK to an existing Vite app.
- Deletes or force-pushes
- Installs packages
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-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-native-xr-testSkill
- 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
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 1 is distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 41
Never run npm i -g or edit ~/.claude without a yes.
- Very specific: line 44
Don't install duplicate skills: Every scaffold already contains the 12 official skills in .claude/skills/ (and a copy in .agents/skills/).
- Very specific: line 47
Always use the scoped name npx @iwsdk/cli ...
- Very specific: line 49
Check flags with --help before relying on them: npx @iwsdk/create@latest --help, npx @iwsdk/cli dev up --help.
- Very specific: line 86
Every boolean also has a --no-… form.
- Distinctive: line 89
If the pitch is ambiguous in a way that changes the target or a feature, ask.
- Very specific: line 149
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, …
- Very specific: line 169
Wait for browserCommandReady: true before browser, XR or ECS commands.
- Very specific: line 209
Prefer scaffolding a throwaway project with the same target and copying its iwsdk.config.json, vite.config.ts, src/assets.ts, …
- Very specific: line 234
Telemetry: when it is installed, @iwsdk/cli and the Vite plugin report each runtime tool call (tool name, duration, a fixed failure code, …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
IWSDK project setup
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 --versionThe 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 vrUseful 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.jsonChange 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 statusadapter 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)
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.

