GameCrew AIEarly access
Sign in
Godot 4vrRevision 1 · Compile-verified pattern

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.

  1. One switch, read on start: GameXR.passthrough() is true in a passthrough session; react on the rig's session_started and undo on session_ended.
  2. Hide the setting, keep the toys: keep sky dome, walls, floor and far scenery under one Node3D named Environment and set visible = false. Don't switch the WorldEnvironment back to a sky while GameXR.passthrough().
  3. The real floor is the rig's floor (local-floor). Nothing knows where the furniture is: place the play area from GameXR.head() at the start, and let the player move it.
  4. Move it by pointing: a pinch while a hand's aim points down at the floor puts the play area there, facing the player.
  5. No artificial locomotion: GameXR.locomotion({"move": "none", "turn": "none"}); the player walks in their room.
  6. 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.
  7. 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 -z of its basis flattened, f_xz; eye height e = 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, direction a = -z_aim with a_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() and await 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.
Plays in VR

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

physics

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.

ai

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.

gameplay

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.

water

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.

Learn about collaboration