#VR mode for creators
Every world you publish on wilds.ai is VR-playable on day one. The platform decides automatically how to render it — full 3D presence for `realtime-3d` worlds, curved cinema screen for everything else — and your blueprint's `xrSettings` field tunes the experience.Every world you publish on wilds.ai is VR-playable on day one. The platform decides automatically how to render it — full 3D presence for realtime-3d worlds, curved cinema screen for everything else — and your blueprint's xrSettings field tunes the experience.
You don't have to do anything for your world to work in VR. This guide is for when you want to tune it.
#How wilds.ai resolves VR mode
When a player on a WebXR-capable headset hits your world, the platform walks three checks:
- Capability — does the browser support
immersive-vr? Quest 3 / Vision Pro Safari / Valve Index via SteamVR / Pico 4 all say yes. Flat browsers say no, the Enter VR button stays invisible, nothing changes for them. - Per-blueprint opt-in — your
xrSettings.mode. Three values:'native'mounts the family's 3D viewport,'cinema'projects the flat viewport onto a curved screen,'auto'lets the family decide. Default is'auto'.'off'hides the Enter VR button on your blueprint entirely. - Family capability —
realtime-3ddeclaresxrCapability: 'native'and ships a full 3D dungeon viewport. The other 11 families (arcade,platformer,roguelike,crawler,ttrpg,survival,strategy-sim,narrative,visual-novel,point-and-click,board-game) declarexrCapability: 'cinema'and project as a curved screen at a virtual seat.
The native path skips the cinema overlay entirely — your world's R3F scene mounts directly inside the player's headset. The cinema path keeps your flat viewport rendering as it always did and paints its canvas onto a 1.8m × 1.2m curved panel at 1.5m distance.
#The xrSettings field
Lives on your blueprint at the top level. Every field is optional; defaults below are platform-wide.
| Field | Type | Default | What it does |
|---|---|---|---|
mode | 'off' | 'cinema' | 'native' | 'auto' | 'auto' | Top-level VR enable. 'off' hides the Enter VR button. |
vrTier | 'off' | 'playable' | 'verified' | 'playable' | Surfaces the VR Ready badge on browse tiles. 'verified' adds a checkmark; only flip when you've actually tested on hardware. |
characterMode | 'off' | 'portrait' | 'avatar' | 'portrait' | 'portrait' floats a 2D character billboard at the player's right shoulder. 'avatar' mounts the rigged 3D avatar when the character has one. 'off' hides the character in VR. |
locomotion | 'teleport' | 'smooth' | 'auto' | 'auto' | Movement style. 'auto' mounts both and lets the player pick from the wrist menu. Teleport is the default-comfortable choice. |
vignetteIntensity | 'off' | 'low' | 'medium' | 'high' | 'medium' | Tunnel-vision vignette on motion. Higher = less sickness for sensitive players. |
snapTurn | boolean | true | Discrete 30° turns vs continuous rotation. Off = smoother, but motion-sickness risk goes up. |
sittingOk | boolean | true | Lets the player play seated instead of room-scale. Off means your world requires standing (rare). |
#When to override the defaults
Tune characterMode to 'avatar' if you generated a 3D avatar for one or more characters via the Studio "Generate 3D avatar" button and you want it to appear in VR by default. The rigged path adds asset cost; the portrait path is always free.
Drop vignetteIntensity to 'low' for slow-paced worlds (narrative, visual-novel, crawler) where the player isn't moving fast. Default 'medium' is tuned for combat.
Bump vignetteIntensity to 'high' for fast-movement worlds (realtime-3d action, arcade racing) where motion sickness risk is high.
Set snapTurn to false when your world is slow + you want max immersion. Most players prefer snap turn even when it looks discrete.
Flip vrTier to 'verified' AFTER you've actually launched VR on a real Quest / Vision Pro and confirmed it plays well. The badge tells other players "this creator has tested on hardware."
Set mode to 'off' only when you're sure VR isn't a fit. Most creators leave it at 'auto'.
#The VR Ready badge
The badge appears on your world's tile in the marketplace and explore feed when xrSettings.vrTier !== 'off' AND xrSettings.mode !== 'off'. It's how VR-headset players spot your world at a glance from the grid.
Two states:
- VR Ready — default for any blueprint with VR enabled. Means "this world supports VR." No checkmark.
- VR Verified — only when
vrTier === 'verified'. Means "the creator has personally tested this on a headset." Adds a checkmark icon.
Don't flip 'verified' without actually testing. Players who select against the verified badge expect a tighter experience.
#Per-family rendering
| Family | Default xrCapability | What you get in VR |
|---|---|---|
realtime-3d | 'native' | Full 3D dungeon scene runs inside the headset. Combat, AI, boss, pickups, save/load, leaderboard — all live. Cinematic cameras clamp to ≤0.3m rig nudges so head pose stays under the headset's control. In-VR HUD overlay (HP / coins / keys / status badges / boss bar / threat ticker / minimap). VR controllers map: left thumbstick moves, right trigger melees, A ranges, grip dodges, B fires ability. |
board-game (chess only) | 'cinema' default; 'native' per-blueprint | Chess blueprints can opt into a native 3D tabletop scene (wood pedestal + 32 low-poly pieces + ray-cursor click-to-select). Set gameDef.xrCapability = 'native' on your chess blueprint to flip. Other board games (hex-settlers, deckbuilder, council-table) stay cinema mode. |
arcade / platformer / roguelike / crawler / ttrpg / survival / strategy-sim | 'cinema' | Flat viewport renders as a curved screen at a virtual seat. HUD floats next to the screen on a side panel. Cinema config per family: arcade gets a sharper 2.4m screen at 1.4m, roguelike + crawler get a 1.8m screen at 1.5m. |
narrative / visual-novel / point-and-click | 'cinema' (DOM source) | The DOM viewport renders through a Drei <Html> portal inside the curved 3D panel. Text + choices + scene art all stay readable. Same wrist menu navigation as the rest of the shell. |
#Character presence in VR
By default every character appears as a 2D portrait billboard floating to the player's right at shoulder height. The portrait carries a colored ring (the mood ring — PAD state tints it) and a pulsing inner ring tied to TTS voice amplitude. It spring-follows the player's head so it stays in their peripheral vision.
When your character has avatar_3d_url populated (via the Studio "Generate 3D avatar" button → asset-forge → Meshy / Tripo3D / Hunyuan), the player sees a rigged VRM 1.0 humanoid instead. The avatar:
- Stands on the dungeon floor (or sits at the chess table if board-game native)
- Spring-rotates to face the player
- Has cyan mood-ring glow at their feet
- Lip-syncs the
aaviseme to TTS amplitude - Mood-driven facial expression overlay
- HEXACO personality biases the resting pose subtly
Set xrSettings.characterMode = 'avatar' to default to the 3D avatar; players can still toggle back via their per-persona XR defaults.
#Performance budget
VR rendering doubles your per-frame cost (one pass per eye). Quest 2 / Quest 3 / Vision Pro target 90Hz; Vision Pro can go to 120Hz with the right scene. To hit those budgets the platform automatically:
- Disables shadows on the realtime-3d Canvas in VR mode (shadow-map passes are 3-4× the render cost; the dungeon is legible without them at Quest 3 camera distances).
- Halves particle counts in VR mode (boss-phase bursts, swing decals, etc).
- Skips post-FX (bloom + AO) in VR.
- Foveated rendering at 0.5 on Quest 3 (sharp center, soft periphery).
- Adaptive resolution at the headset level — the system drops resolution when frame budget breaches for 5+ seconds.
You don't tune these manually. If your world has so much custom geometry that it can't hit 90Hz on Quest 3, consider toggling vrTier back to 'playable' (without verified) so players know to set expectations.
#Studio panel
The full Studio surface mounts an XR panel under the Settings section (glasses icon). It exposes every xrSettings field with inline previews + a "Generate 3D avatar" button per character. Changes flow through the standard draft / debounced PATCH save pattern — no separate save step.
#Common questions
Will publishing a VR-tuned world hurt my flat-mode metrics? No. The Enter VR button is invisible on flat browsers; non-VR players see your world exactly as they always did. The VR Ready badge appears only on VR-capable browsers.
My character's avatar is "loading" forever in VR. The rigged-avatar path needs a successful Meshy / Tripo / Hunyuan generation + (eventually) a VRM 1.0 conversion step. If generation failed, the portrait shows as fallback automatically. Check the Studio character editor for the generation status.
Does VR cost me extra credits? Only if you generate a 3D character avatar (the same credit cost as any character mesh generation). Cinema mode, native mode, the in-VR HUD, the character portrait — all free.
How do I test my world in VR before publishing? Open the play lobby for your blueprint in a WebXR browser (Chrome desktop + the WebXR Emulator extension OR Quest 3 / Vision Pro browser). Click Enter VR. Walk through the player setup guide for what to expect.
Per-blueprint native opt-in for chess. Chess blueprints can flip to native 3D by setting gameDef.xrCapability = 'native' in your blueprint's gameDef override. The XRBoardGameViewport renders a tabletop scene; other board games fall back to cinema mode automatically.
#Where things live in the code
xrSettingsschema:packages/core/schema/src/system/xr.ts- Per-family capability declarations:
packages/families/*/src/<family>-family.ts - Native viewport for realtime-3d:
packages/families/realtime-3d/src/viewport/XRRealtime3DViewport.tsx - Native viewport for board-game chess:
packages/families/board-game/src/viewport/XRBoardGameViewport.tsx - Cinema mode mount:
src/components/session/GameSessionRuntime.tsx(the<CinemaModeAttachment>sibling) - Capability probe:
src/lib/client/xr-capability-probe.ts - VR Ready badge:
src/components/shared/VrReadyBadge.tsx