# 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.

- **Canonical page:** https://gamecrew.ai/techniques/godot/passthrough-mixed-reality
- **Techniques hub:** https://gamecrew.ai/techniques
- **Engine:** Godot 4
- **Category:** vr
- **Tags:** `vr`, `xr`, `webxr`, `passthrough`, `mixed reality`, `mr`, `ar`, `immersive-ar`, `room`, `tabletop`, `placement`, `contact shadow`, `alpha`, `quest`, `transparent_bg`
- **Verification:** Compile-verified pattern
- **Revision:** 1 (2026-11-13)
- **Demo:** 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 $\mathbf{h}$, forward $-\mathbf{z}$ of its basis flattened, $\hat{\mathbf{f}}_{xz}$; eye height $e = h_y - y_{\text{floor}}$:
  $$\mathbf{p} = (h_x, y_{\text{floor}}, h_z) + d\,\hat{\mathbf{f}}_{xz} + (0, \mathrm{clamp}(k e, 0.7, 1.1), 0), \quad d \approx 0.45, \ k \approx 0.85$$
- **Point-at-floor**: aim origin $\mathbf{o}$, direction $\hat{\mathbf{a}} = -\mathbf{z}_{\text{aim}}$ with $a_y < -0.15$: $t = (y_{\text{floor}} - o_y)/a_y$, $0 < t \le 4$.
- **Contact shadow**: scale $s_0(1 + 0.6c)$, alpha $\alpha_0(1 - c)$, $c = \mathrm{clamp}(y/1.5, 0, 1)$ for height $y$ over the surface.

## Engine Implementation

### Passthrough stage (`Assets/Game/Scripts/vr/passthrough_stage.gd`)

```gdscript
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`)

```gdscript
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)
