# Tinyworld Webxr

> Tinyworld Webxr is an Agent Skill for development published in the jasonkneen/tiny-world-builder repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when adding or modifying WebXR, AR placement, VR immersion, headset controller input, or XR rendering modes in Tiny World Builder.

- Skill name: `tinyworld-webxr`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/jasonkneen/tiny-world-builder/blob/HEAD/.codex/skills/tinyworld-webxr/SKILL.md
- Repository: jasonkneen/tiny-world-builder (1,444 GitHub stars when collected)

## SKILL.md

# Tiny World WebXR

Tiny World uses a pinned global `THREE` r185 compatibility bundle (`vendor/three/tinyworld-three.r185.min.js`), not runtime module imports or `ARButton`/`VRButton` addons. Keep WebXR integration vanilla and single-file inside `tiny-world-builder.html`.

Platform split — WebXR covers "Google" AR (Android Chrome / Quest, via `immersive-ar` + `hit-test`), but Apple devices have no WebXR. iOS/iPadOS web AR is **AR Quick Look only**: an `<a rel="ar">` pointing at a `.usdz` opens the system viewer, which finds a surface, places the model, and lets the user walk around it. So both paths must exist for full coverage.

Patterns:

- For Apple AR, export the live world to USDZ on demand with `THREE.USDZExporter` from the r185 global bundle. USDZExporter only understands `MeshStandardMaterial`, so snapshot `worldGroup` into a fresh group, convert each Lambert/Basic/Shader material to a Standard equivalent (preserving colour/emissive/map), recentre on the origin with the base at y=0, and scale to a tabletop size. Wrap the resulting `Uint8Array` in a `model/vnd.usdz+zip` Blob → object URL, and launch via an `<a rel="ar">` that contains a single `<img>` child (Safari's requirement) clicked programmatically.
- Gate the Apple AR button on `document.createElement('a').relList.supports('ar')`; gate the WebXR buttons on `navigator.xr` support. Show the XR panel if either is available so iOS users see just the Apple AR button.

- Enable WebXR with `renderer.xr.enabled = true` and drive the main loop with `renderer.setAnimationLoop(animate)` so desktop and headset frames share one path.
- Keep headset transforms on `xrWorldRoot`, a scene-level parent for board/runtime meshes. Do not scale/move `worldGroup` alone; hover, selection, clouds, weather, smoke, crop duster, and previews must stay in the same local world space.
- Keep controllers/reticles in `scene`, not `xrWorldRoot`; they are physical XR-space objects.
- For AR desk mode, request `immersive-ar` with required `hit-test`, optional `anchors`, and a `domOverlay` root. Use the reticle pose to set `xrWorldRoot` and use anchors when available, but gracefully fall back to the last hit-test pose.
- For floating mode, prefer `immersive-ar`, then fall back to `immersive-vr`; place the mini board in front of the current XR camera.
- For inside mode, use `immersive-vr` with `local-floor` and leave `xrWorldRoot` at meter scale (`scale = 1`) so one tile is walkable room scale.
- When picking tiles from controllers, raycast against `worldGroup.children`, then convert `h.point` through `xrWorldRoot.worldToLocal()` before deriving tile-local offsets. Desktop pointer picking can keep using screen-space raycasts.
- Restore `scene.background`, `xrWorldRoot` transform/visibility, reticle state, and UI state on XR session end or failure.

Validation:

- `npm test` and the inline script `node --check` must pass.
- Real AR hit-test/VR entry requires HTTPS plus a headset/browser with WebXR support; browser smoke tests can only verify non-XR fallback UI and syntax.

---

Source: https://www.openparable.com/skill/development/tinyworld-webxr (OpenParable). Cite the canonical URL above.
