Tinyworld Webxr
Developmenttinyworld-webxrTinyworld 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/jasonkneen/tiny-world-builder/blob/HEAD/.codex/skills/tinyworld-webxr/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tinyworld-webxr, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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.USDZExporterfrom the r185 global bundle. USDZExporter only understandsMeshStandardMaterial, so snapshotworldGroupinto 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 resultingUint8Arrayin amodel/vnd.usdz+zipBlob → 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 onnavigator.xrsupport. Show the XR panel if either is available so iOS users see just the Apple AR button. -
Enable WebXR with
renderer.xr.enabled = trueand drive the main loop withrenderer.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/moveworldGroupalone; hover, selection, clouds, weather, smoke, crop duster, and previews must stay in the same local world space. -
Keep controllers/reticles in
scene, notxrWorldRoot; they are physical XR-space objects. -
For AR desk mode, request
immersive-arwith requiredhit-test, optionalanchors, and adomOverlayroot. Use the reticle pose to setxrWorldRootand use anchors when available, but gracefully fall back to the last hit-test pose. -
For floating mode, prefer
immersive-ar, then fall back toimmersive-vr; place the mini board in front of the current XR camera. -
For inside mode, use
immersive-vrwithlocal-floorand leavexrWorldRootat meter scale (scale = 1) so one tile is walkable room scale. -
When picking tiles from controllers, raycast against
worldGroup.children, then converth.pointthroughxrWorldRoot.worldToLocal()before deriving tile-local offsets. Desktop pointer picking can keep using screen-space raycasts. -
Restore
scene.background,xrWorldRoottransform/visibility, reticle state, and UI state on XR session end or failure.
Validation:
npm testand the inline scriptnode --checkmust 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.