Passthrough Mixed Reality in the Player's Room in Godot 4 (WebXR immersive-ar)
A passthrough game on the studio's Godot GameXR kit: hide the virtual setting when GameXR.passthrough() turns on, place the play area from the head, move it by pointing at the floor and pinching, ground things with contact shadows, keep drawn pixels opaque, and fall back to a virtual room everywhere else.
- vr
- xr
- webxr
- passthrough
- mixed reality
- mr
- ar
- immersive-ar
- room
- tabletop
- placement
- contact shadow
- alpha
- quest
- transparent_bg
No demo.
When to Use & Field Best Practices
A passthrough game (game.json "passthrough": true) plays in the player's own room on a headset whose browser can show it: the page starts an immersive-ar session, the kit turns transparent_bg on and every environment's sky and fog off for the session, and the headset shows the room wherever nothing is drawn. The same link plays as ordinary VR on a headset that can't, and flat on a computer or phone, so a passthrough game always keeps its virtual setting.
- One switch, read on start:
GameXR.passthrough()is true in a passthrough session; react on the rig'ssession_startedand undo onsession_ended. - Hide the setting, keep the toys: keep sky dome, walls, floor and far scenery under one
Node3DnamedEnvironmentand setvisible = false. Don't switch theWorldEnvironmentback to a sky whileGameXR.passthrough(). - The real floor is the rig's floor (
local-floor). Nothing knows where the furniture is: place the play area fromGameXR.head()at the start, and let the player move it. - Move it by pointing: a pinch while a hand's aim points down at the floor puts the play area there, facing the player.
- No artificial locomotion:
GameXR.locomotion({"move": "none", "turn": "none"}); the player walks in their room. - Belong in the room: a soft round contact shadow (a
Decal, or a transparent quad with a radial texture) under what rests or lands; even warm light; opaque materials. - Alpha is the mask: opaque materials write alpha 1; the cleared background is alpha 0, the room. Additive or alpha-0 effects let the room through.
Mathematical & Algorithmic Core
- Placement from the head: head origin
h, forward-zof its basis flattened,f_xz; eye heighte = h_y - y_floor: $p = (h_x, y_floor, h_z) + d\,f_xz + (0, clamp(k e, 0.7, 1.1), 0), d ≈ 0.45, \ k ≈ 0.85$ - Point-at-floor: aim origin
o, directiona = -z_aimwitha_y < -0.15:t = (y_floor - o_y)/a_y,0 < t ≤ 4. - Contact shadow: scale
s_0(1 + 0.6c), alphaα_0(1 - c),c = clamp(y/1.5, 0, 1)for height $y$ over the surface.
Engine Implementation
Passthrough stage (Assets/Game/Scripts/vr/passthrough_stage.gd)
extends Node
## The play area in the player's room: in a passthrough session the setting (environment) is hidden, the stage is
## placed in front of the player from their head and moved by pointing a hand at the floor and pinching.
@export var environment: Node3D
@export var stage: Node3D
@export var reach := 0.45
@export var height_share := 0.85
var _placed := false
var _pinched := {"left": false, "right": false}
func _ready() -> void:
var rig := GameXR.rig()
if rig == null:
return
rig.session_started.connect(_on_started)
rig.session_ended.connect(_on_ended)
func _on_started() -> void:
if not GameXR.passthrough():
return
if environment != null:
environment.visible = false
GameXR.locomotion({"move": "none", "turn": "none"})
_placed = false
func _on_ended() -> void:
if environment != null:
environment.visible = true
_placed = false
func _floor_y() -> float:
var rig := GameXR.rig()
return rig.origin.global_position.y if rig != null and rig.origin != null else 0.0
func _process(_delta: float) -> void:
if not GameXR.passthrough() or stage == null:
return
var head := GameXR.head()
var floor_y := _floor_y()
if not _placed:
var f := -head.basis.z
f.y = 0.0
f = f.normalized() if f.length_squared() > 1e-4 else Vector3.FORWARD
var y := floor_y + clampf((head.origin.y - floor_y) * height_share, 0.7, 1.1)
stage.global_position = Vector3(head.origin.x, y, head.origin.z) + f * reach
stage.global_rotation = Vector3(0.0, atan2(f.x, f.z) + PI, 0.0)
_placed = true
for side in ["left", "right"]:
var hand := GameXR.hand(side)
var now := hand != null and hand.tracked and hand.pinching
if now and not _pinched[side]:
_place_at_floor(hand, head, floor_y)
_pinched[side] = now
func _place_at_floor(hand, head: Transform3D, floor_y: float) -> void:
var o: Vector3 = hand.aim.origin
var a: Vector3 = -hand.aim.basis.z
if a.y > -0.15:
return
var t := (floor_y - o.y) / a.y
if t <= 0.0 or t > 4.0:
return
var hit := o + a * t
stage.global_position = Vector3(hit.x, stage.global_position.y, hit.z)
var to_player := head.origin - hit
stage.global_rotation = Vector3(0.0, atan2(to_player.x, to_player.z), 0.0)
hand.pulse(0.4, 0.03)
A contact shadow: a Decal pointing down under the object, its albedo a radial gradient (GradientTexture2D, fill radial, black to transparent), modulate.a and size set each frame from the height formula above.
Test with the simulated passthrough session (Assets/Game/Tests/play/test_passthrough.gd)
extends GameTest
func test_passthrough_hides_the_setting_and_places_the_stage() -> void:
await load_main()
var env := get_tree().root.find_child("Environment", true, false) as Node3D
var stage := get_tree().root.find_child("Stage", true, false) as Node3D
var xr := GameXR.sim()
await xr.enter(true)
await seconds(0.1)
assert_true(GameXR.passthrough(), "a passthrough session")
assert_false(env.visible, "the setting is hidden")
var head := GameXR.head()
assert_gt((stage.global_position - head.origin).dot(-head.basis.z), 0.2, "the stage is in front of the player")
await xr.exit()
await seconds(0.1)
assert_true(env.visible, "the setting is back after the session")
Pitfalls
- A sky or backdrop in passthrough covers the room; the save's check samples the headset's layer and fails when nothing is transparent.
- Turning the environment's sky back on (a day/night script) while
GameXR.passthrough()undoes the kit's clearing. - Assuming a table: the kit has no plane detection; a stage floating at hand height in front of the player is honest.
- Locomotion in a real room moves the virtual things away from the room; walking is the player's.
- Forgetting the fallback: test both
await xr.enter()andawait xr.enter(true).
Official references
- Meta Mixed Reality Design Guidelines (Passthrough, Scene placement)
- WebXR Device API environmentBlendMode
- Godot 4 XR passthrough (Viewport.transparent_bg)
More Godot 4 games
Games made with GameCrew on the same engine. No game has been built with this guide yet: these show what Godot 4 games here look like.

Fernlight
Raise a carved whistle to your lips in a fog-drowned forest, coax a glowing bird onto your open hand, and point to send it off to light the dark.
More Godot 4 techniques
CharacterBody3D Slopes, Snap & Coyote Jump in Godot 4 →
Crisp Godot 4 CharacterBody3D locomotion combining floor_snap_length, apex hang gravity, jump-cut, coyote time, and zero-arg move_and_slide.
Context Steering, Patrol Paths & Telegraphed Enemy Encounters in Godot 4 →
Typed GDScript 4 context steering, LevelData patrol-path following, line-of-sight perception with memory hysteresis, attack-token pacing, and telegraphed combat state machines.
Frame-Rate-Independent Springs, Squash-Stretch & Ribbon Trails in Godot 4 →
Typed GDScript 4 second-order damped springs, volume-preserving visual squash-stretch, Eiserloh T^2 FastNoiseLite camera trauma, and ImmediateMesh sword/dash ribbon trails.
Stylized Water, Gerstner Waves & Depth Shoreline Foam in Godot 4 Compatibility →
Godot 4.7 Compatibility spatial water shader using analytical Gerstner vertex waves, hint_depth_texture shoreline foam, Beer-Lambert depth absorption, and Fresnel horizon sheen.
Use verified techniques inside a real game
Describe your game idea for free or connect an MCP assistant to search and contribute techniques.