summer-engine 3.0.0 → 3.2.0

package/library/skills/make-game/references/3d-fps.md

@@ -0,0 +1,177 @@
+# 3D FPS - Core
+
+First-person shooter blueprint: player hierarchy, mouse look, movement feel,
+and level setup. Shooting, weapons, interaction, and HUD live in
+`3d-fps-systems.md`.
+
+Rule for Summer Engine builds: scene operations (.tscn) go through the scene
+tools (`summer_add_node` / `summer_set_prop` / `summer_set_resource_property`,
+or one `summer_batch`, always with `scenePath`); script files (.gd) go through
+`summer_write_file` / `summer_replace_text`. Never cross the streams. For a
+production controller with air control and external velocity, see the
+`fps-controller` skill.
+
+## Minimum playable base (build this first)
+
+Level with ground + light + WorldEnvironment, the player scene below, mouse
+look + WASD + jump. Prove "walk around and look" before any weapon exists.
+
+## Player hierarchy (non-negotiable)
+
+```
+Player (CharacterBody3D, group "player", collision_mask 6)
+  StandingShape (CollisionShape3D, capsule r 0.35 h 1.8, at y 0.9)
+  CrouchingShape (CollisionShape3D, capsule r 0.35 h 1.0, at y 0.5, disabled)
+  Head (Node3D, y 1.5)                # receives PITCH
+    Camera3D (fov 70)
+      WeaponHolder (Node3D, (0.2, -0.15, -0.4))
+      InteractionRay (RayCast3D, target (0,0,-2.5), mask 4)
+      ShootRay (RayCast3D, target (0,0,-100), mask 6)
+  CeilingCheck (RayCast3D, at y 1, target (0,1,0), mask 2)
+```
+
+Why this exact shape:
+
+- Yaw rotates the Player ROOT, pitch rotates Head. Rotating the camera on
+  both axes causes gimbal lock and drift.
+- Camera under Head inherits both rotations; WeaponHolder under Camera makes
+  weapons track the view exactly.
+- Two collision shapes for crouch, toggled via `disabled`. Resizing one
+  shape at runtime glitches physics.
+- Short InteractionRay (2.5m) and long ShootRay (100m) are separate rays with
+  separate masks.
+
+Collision layers: 1 Player, 2 Environment, 3 Interactable, 4 Enemy. ShootRay
+mask 6 = Environment + Enemy (never the player). InteractionRay mask 4 =
+Interactable only.
+
+Input map before any scripts: move_forward/back/left/right, jump (Space),
+sprint (Shift), crouch (C), shoot (LMB), aim (RMB), reload (R), interact (E),
+weapon_1/2/3, pause (Escape).
+
+## Controller script
+
+Tuning baseline: walk 5.0, sprint 8.0, crouch 2.5, acceleration 10.0, jump
+4.5, mouse sensitivity 0.002, FOV 70 default / 80 sprint / 50 aim.
+
+```gdscript
+func _ready() -> void:
+	Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
+
+func _unhandled_input(event: InputEvent) -> void:
+	if event.is_action_pressed("ui_cancel"):
+		Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
+		return
+	if event is InputEventMouseButton and event.pressed \
+			and Input.mouse_mode == Input.MOUSE_MODE_VISIBLE:
+		Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
+		get_viewport().set_input_as_handled()
+		return
+	if event is InputEventMouseMotion:
+		rotate_y(-event.relative.x * mouse_sensitivity)
+		head.rotate_x(-event.relative.y * mouse_sensitivity)
+		head.rotation.x = clampf(head.rotation.x, deg_to_rad(-85.0), deg_to_rad(85.0))
+```
+
+Mouse capture is mandatory or look does not work; the Escape release +
+click-to-recapture pair is mandatory or the player cannot quit.
+
+Movement (in `_physics_process`, never `_process`):
+
+```gdscript
+func _handle_movement(delta: float) -> void:
+	var input_dir := Input.get_vector("move_left", "move_right", "move_forward", "move_back")
+	var direction := (transform.basis * Vector3(input_dir.x, 0.0, input_dir.y)).normalized()
+	if direction:
+		velocity.x = lerpf(velocity.x, direction.x * current_speed, acceleration * delta)
+		velocity.z = lerpf(velocity.z, direction.z * current_speed, acceleration * delta)
+	else:
+		velocity.x = lerpf(velocity.x, 0.0, acceleration * delta)
+		velocity.z = lerpf(velocity.z, 0.0, acceleration * delta)
+	if is_on_floor() and Input.is_action_just_pressed("jump") and not is_crouching:
+		velocity.y = jump_velocity
+```
+
+Gravity from project settings, not a magic number:
+`velocity.y -= ProjectSettings.get_setting("physics/3d/default_gravity") * delta`
+when not on floor. Then `move_and_slide()`.
+
+### Sprint + stamina
+
+Sprint only while pressing sprint, moving (velocity > 0.5), not crouching,
+and stamina > 0. Drain 20/s, regen 15/s to 100. Sprinting also pushes FOV to
+80 (lerp at 5.0/delta), aim pulls to 50 - the FOV lerp is a big part of feel.
+
+### Crouch
+
+Toggle: swap which CollisionShape3D is disabled, lerp `head.position.y`
+between 1.5 and 0.8 at 8.0/delta. Standing up first checks
+`ceiling_check.is_colliding()` - refuse to stand under low geometry.
+Crouching cancels sprint and blocks jump.
+
+### Headbob + footsteps
+
+```gdscript
+func _handle_headbob(delta: float) -> void:
+	var speed := Vector2(velocity.x, velocity.z).length()
+	if speed < 0.5 or not is_on_floor():
+		camera.position.y = lerpf(camera.position.y, 0.0, 5.0 * delta)
+		camera.position.x = lerpf(camera.position.x, 0.0, 5.0 * delta)
+		return
+	headbob_time += delta * (14.0 if is_sprinting else 10.0)
+	var intensity := 0.05 if is_sprinting else 0.03
+	var bob_y := sin(headbob_time) * intensity
+	camera.position.y = bob_y
+	camera.position.x = sin(headbob_time * 0.5) * intensity * 0.5
+	if headbob_last_y >= 0.0 and bob_y < 0.0:
+		_play_footstep()   # sine crossing zero downward = foot plants
+	headbob_last_y = bob_y
+```
+
+The lerp-to-zero branch when stopped is required - without it the camera
+freezes mid-bob. The zero-crossing footstep trigger syncs audio to motion
+for free.
+
+## Level scene
+
+The real level comes from real assets, not primitives: route the need through
+the `asset-strategy` skill (`summer_search_assets`, then `summer_import_asset` /
+`summer_import_asset_by_id`), import a ready location or kit that fits, and build
+gameplay inside it; weapons and props should share its style. A PlaneMesh ground
+is only the walk-test blockout and for pieces no asset covers — never the
+shipped level when a real one is available.
+
+Blockout minimum: Node3D root + WorldEnvironment + ground (StaticBody3D with
+BoxShape3D collision AND a PlaneMesh visual - a MeshInstance3D alone has no
+collision) + DirectionalLight3D at (-45, 30, 0) with shadows + the player
+instance at (0, 1, 0).
+
+Environment presets:
+
+- Outdoor: ProceduralSkyMaterial sky, angled DirectionalLight3D with
+  shadows, ambient from sky.
+- Indoor: no sky (custom color background), Omni/SpotLights per room, low
+  ambient, SSAO on, optional fog.
+
+## Build order
+
+1. Input map + collision layer names.
+2. Player scene per the hierarchy above (MCP), controller script (files).
+3. Level: blockout ground, light, environment. Walk test.
+4. Swap the blockout for an imported location + props (`asset-strategy`).
+5. Hitscan shooting + one weapon + crosshair (`3d-fps-systems.md`).
+6. Interaction (door, pickup), HUD, then weapon roster.
+
+## Traps
+
+- Mouse look on the Camera directly - split yaw (root) / pitch (Head) or
+  you get gimbal lock.
+- Movement in `_process` - variable framerate stutter. CharacterBody3D
+  moves in `_physics_process` only.
+- Forgetting `MOUSE_MODE_CAPTURED` (look does nothing) or the Escape
+  release (player trapped).
+- Camera at y 0 - you see from your feet. Head height is 1.5-1.7.
+- Level geometry without StaticBody3D collision - the player falls through
+  anything that is only a MeshInstance3D.
+- One resized collision shape for crouch instead of two toggled shapes.
+- ShootRay mask including the Player layer - you shoot yourself; mask 6.

package/library/skills/make-game/references/3d-horror-systems.md

@@ -0,0 +1,186 @@
+# 3D Horror - Systems
+
+The dread machinery on top of `3d-horror.md`: the tension-driven atmosphere
+controller, the stalker AI, procedural audio, interactables, and the escape
+objective chain.
+
+## Atmosphere controller (tension in, dread out)
+
+One Node3D in the level reads `GameManager.tension_level` and escalates
+three channels. It auto-discovers OmniLights from a sibling "Lights" node
+and creates 4 roaming AudioStreamPlayer3D emitters (Ambient bus, max
+distance 20).
+
+### Flickering lights
+
+Per-frame chance `0.005 * (1.0 + tension)` per light. A flicker is a tween
+of 2-5 random off/on cycles (off 0.02-0.08s at energy 0-0.3, on 0.02-0.1s
+at 50-100%), then restore. Random durations - regular flicker reads as a
+broken script, not a broken light.
+
+### Positional ambient sounds
+
+Every 15-45s (interval shrinks to half at max tension), one emitter
+teleports to a random point around the player
+(x/z +-15, y 0-5 - behind walls, above the ceiling) and plays from a pool
+that GROWS with tension:
+
+- base: door close, pipe stress, wind vent
+- tension > 0.3: + creature whisper
+- tension > 0.5: + distant scream
+- tension > 0.7: + creature growl
+
+Random volume -12..-4 dB and pitch 0.7-1.3 so nothing repeats exactly.
+
+### Tension events
+
+Every 30s at base, down to ~12s at max tension, pick one of FIVE:
+0 = flicker all lights, 1 = audio stinger + tension +0.05, 2 = brief
+darkness, 3 = extra ambient sound, 4 = NOTHING. The nothing case is
+deliberate - a scare that never comes after buildup is the horror.
+
+Brief darkness: tween all lights to energy 0.05 over 0.5s, hold a random
+0.5-2s, restore over 0.3s, tension +0.08. Save original energies first.
+
+## Stalker AI
+
+A solid-black unshaded capsule (CapsuleMesh r 0.2 h 2.2, albedo 0.01 -
+reads as a silhouette in any lighting). Mesh and collision built at
+runtime, no assets. Core mechanic: it only moves when you are NOT looking.
+
+```gdscript
+func _process_showing(delta: float) -> void:
+	look_at(Vector3(player.global_position.x, global_position.y, player.global_position.z))
+	var to_me := (global_position - player.global_position).normalized()
+	var player_fwd := -player.global_transform.basis.z.normalized()
+	var angle := rad_to_deg(acos(clampf(player_fwd.dot(to_me), -1.0, 1.0)))
+	if angle < 20.0:
+		# player looking directly: freeze and stare back
+		stare_timer += delta
+		if stare_timer >= stare_time:      # 2.0s of being watched
+			_disappear()
+	else:
+		stare_timer = 0.0
+		var dir := (player.global_position - global_position).normalized()
+		dir.y = 0.0
+		velocity = dir * approach_speed    # 1.5 m/s
+		move_and_slide()
+		if global_position.distance_to(player.global_position) < catch_distance:  # 1.5m
+			AudioManager.play_sfx(ProceduralAudio.get_creature_screech(), 0.0)
+			GameManager.set_state(GameManager.GameState.GAME_OVER)
+```
+
+Pacing rules (tuned, keep them):
+
+- First appearance at 15s - the player needs time to find the flashlight.
+- Reappear interval starts 18s, shrinks 15% per appearance, floor 8s:
+  `reappear_interval = maxf(reappear_interval * 0.85, 8.0)`.
+- Spawn selection: from a hand-placed spawn-point list, pick the FARTHEST
+  point that is between 6m and 18m from the player. Under 6m is unfair -
+  no time to react.
+- On appear: whisper from its own 3D emitter + low-pitched stinger
+  (pitch 0.5-0.8) + tension +0.1.
+- Fully idle while `GameManager.is_reading_note` or state != PLAYING -
+  notes are safe rooms.
+- After `stare_time` of being watched it vanishes (visible = false) and
+  the wait timer restarts. Player-facing check is a dot-product cone of
+  20 degrees, not a raycast - cheap and good enough.
+
+## Procedural audio
+
+`ProceduralAudio` is a static class generating every sound from math into
+cached AudioStreamWAVs - zero audio files; swap in recordings later
+without touching call sites. Catalog: footsteps (4 variations),
+door open/close/locked, ambient drone (detuned 40Hz sines, looping),
+tension hit (sub boom + metallic ring), pickup chime, creature
+whisper/growl/screech, heartbeat, distant scream, water drip, machinery
+hum, wind vent, fluorescent buzz, pipe stress, radio static.
+
+Generation pattern all sounds follow (16-bit, 22050 Hz):
+
+```gdscript
+static func _generate_example() -> void:
+	var num_samples := int(duration * SAMPLE_RATE)
+	var samples := PackedByteArray()
+	samples.resize(num_samples * 2)
+	for s in num_samples:
+		var t := float(s) / SAMPLE_RATE
+		var envelope := exp(-t * 3.0)
+		var value := sin(t * 440.0 * TAU) * envelope * 0.3
+		var sample := clampi(int(value * 16000), -32768, 32767)
+		samples[s * 2] = sample & 0xFF
+		samples[s * 2 + 1] = (sample >> 8) & 0xFF
+	_stream = AudioStreamWAV.new()
+	_stream.format = AudioStreamWAV.FORMAT_16_BITS
+	_stream.mix_rate = SAMPLE_RATE
+	_stream.data = samples
+	# looping sounds: loop_mode = LOOP_FORWARD, loop_begin = 0, loop_end = num_samples
+```
+
+Recipes that matter: creature sounds = low fundamentals (30Hz growl) +
+inharmonic partials; whispers/screams = filtered noise; drones = slightly
+detuned sine pairs (beating); always exponential envelopes.
+
+## Interactables
+
+Same duck-typed interface as 3d-fps: `interact(player)` +
+`get_interaction_prompt() -> String`, found by the InteractionRay (mask 4).
+
+### HorrorDoor
+
+Node3D rotating on Y, hinge at the parent origin (mesh offset
+(0.5, 1.4, 0)), lerp `rotation.y` toward target at open_speed. Opens away
+from the player (approach-side check). Horror-specific exports:
+
+- `required_key`: locked until `GameManager.has_item(key)`; unlocking
+  consumes the key. Locked interaction plays a rattle - +-2 degree shake
+  tween + locked sound. Prompt: "Locked" / "Unlock" / "Open" / "Close".
+- `auto_close_delay`: door closes itself behind the player (room traps).
+- `creepy_auto_open`: opens by itself ONCE after a delay - cheapest scare
+  in the kit.
+
+### InteractableItem
+
+RigidBody3D with `freeze = true`, bob + rotate idle (randomized phase),
+per-type runtime mesh + OmniLight3D glow:
+
+| Type | Effect | Visual |
+|---|---|---|
+| KEY | `add_item(item_id)` | gold box, warm glow |
+| FLASHLIGHT | `player.pickup_flashlight()` | gray cylinder, amber glow |
+| NOTE | `open_note(id, text)` - NOT consumed | paper-white flat box |
+| BATTERY | battery +30 (cap 100) | dark blue box, blue glow |
+
+Everything except notes `queue_free()`s on pickup.
+
+### EscapeZone
+
+Area3D (mask 1) at the exit with a green OmniLight beacon. On player
+enter: with the exit key -> `set_state(ESCAPED)`; without it -> open a
+note ("The door is chained from the outside. I need a key.") - the
+rejection delivers story instead of a dead trigger.
+
+## Objective chain
+
+The loop is explore -> find -> unlock -> escape:
+
+1. Spawn in entry area, find flashlight.
+2. Main hall, Note 1 hints at the storage key.
+3. Side corridor -> office -> storage key.
+4. Storage room (locked) -> exit key.
+5. Back corridor (darkest) -> escape zone with exit key -> ESCAPED.
+
+The whole chain is data: `required_key` on doors, `item_id` on pickups,
+`required_key` on the EscapeZone, and note texts for direction. Re-theme a
+level by editing strings, not code. Keys live in dead ends so the stalker
+gets backtracking time; notes double as the hint system - no quest UI.
+
+## Escalation timeline (why it works)
+
+Minute 1: quiet, base ambient sounds, flashlight secured. Minute 2-3:
+first stalker appearance, whispers join the pool. Mid-game: battery
+pressure, screams, shorter stalker gaps, brief-darkness events. Endgame:
+tension near 1.0 - vignette closed in, breathing sway, growls, stalker
+every 8s, in the darkest corridor with the exit key. All of it falls out
+of one passive float plus event spikes; tune the drain rate, the
+reappear floor, and ambient intervals - not scripted scares.

package/library/skills/make-game/references/3d-horror.md

@@ -0,0 +1,201 @@
+# 3D Horror - Core
+
+First-person horror blueprint: game state, the vulnerable-player controller,
+flashlight mechanics, level building, lighting, and the minimal HUD. The
+stalker AI, tension/atmosphere system, procedural audio, and interactables
+live in `3d-horror-systems.md`.
+
+The player scene reuses the 3d-fps hierarchy and controller (yaw on root,
+pitch on Head, two crouch shapes, headbob) - see `3d-fps.md`. This file
+covers what horror changes.
+
+## Design law: vulnerability
+
+No weapon, ever. The flashlight is the only tool. The moment the player can
+fight back it becomes an action game. No health bar, no minimap, no kill
+counter - the HUD shows only battery, interaction prompt, and notes.
+
+## Minimum playable base (build this first)
+
+One dark room + flashlight pickup + a locked door + the key that opens it.
+Prove "dark, need the light, find key, open door" before any AI or
+atmosphere exists.
+
+## Autoloads
+
+Two: GameManager and AudioManager, both `process_mode = PROCESS_MODE_ALWAYS`.
+
+GameManager is the single source of truth:
+
+```gdscript
+enum GameState { MENU, PLAYING, PAUSED, GAME_OVER, ESCAPED }
+
+var inventory: Array[String] = []
+var notes_found: Array[String] = []
+var has_flashlight: bool = false
+var flashlight_battery: float = 100.0
+var doors_unlocked: Array[String] = []
+var tension_level: float = 0.0        # 0 calm .. 1 max
+var is_reading_note: bool = false
+```
+
+- `set_state()` pauses the tree for PAUSED/GAME_OVER/ESCAPED, unpauses on
+  PLAYING, and force-closes any open note on leaving PLAYING.
+- Tension rises passively 0.005/sec while PLAYING; systems spike it via
+  `increase_tension(amount)`. Everything atmospheric reads this one float.
+- Note reading is a modal state: while `is_reading_note`, the player
+  controller AND the stalker both stand down (safe reading).
+- Inventory is just string ids: `add_item` / `has_item` / `remove_item`;
+  `open_note(id, text)` / `close_note()` emit signals the HUD listens to.
+
+AudioManager: 8 pooled AudioStreamPlayers on an "SFX" bus, dedicated
+ambient + music players on an "Ambient" bus, buses created at runtime via
+`AudioServer.add_bus()` if missing. `play_ambient` crossfades from -40dB.
+Bus separation is mandatory - you cannot balance or add reverb/low-pass
+later without it.
+
+## Player controller (horror deltas from 3d-fps)
+
+- Walk 3.0 / sprint 5.0 / crouch 1.5 (slow = vulnerable; FPS-speed movement
+  kills dread).
+- gravity_multiplier 1.5 - heavier, grounded.
+- ALL input gated on `GameManager.current_state == PLAYING` in both
+  `_unhandled_input` and `_physics_process` - frozen during notes, pause,
+  game over.
+- Extra child under Camera3D: Flashlight (SpotLight3D at (0.15, -0.1, -0.1),
+  hidden until picked up) + FlashlightDust (GPUParticles3D).
+- Input map adds `flashlight` (F); no shoot/aim/reload.
+- Footsteps route through the procedural audio footstep with random pitch.
+
+### Flashlight (the core mechanic)
+
+```gdscript
+func _handle_flashlight_drain(delta: float) -> void:
+	if not flashlight_on:
+		return
+	GameManager.flashlight_battery -= flashlight_drain_rate * delta / 60.0  # 15%/min, ~6.5 min life
+	GameManager.flashlight_battery = maxf(GameManager.flashlight_battery, 0.0)
+	if GameManager.flashlight_battery < 15.0:
+		# dual-sine = irregular organic flicker, not a metronome
+		var flicker := sin(Time.get_ticks_msec() * 0.03) * sin(Time.get_ticks_msec() * 0.07)
+		flashlight.light_energy = lerpf(0.3, 1.2, (flicker + 1.0) * 0.5)
+	else:
+		flashlight.light_energy = 1.5
+	if GameManager.flashlight_battery <= 0.0:
+		flashlight_on = false
+		flashlight.visible = false
+```
+
+Toggle refuses until `GameManager.has_flashlight`. Battery pickups restore
++30. Drain rate is the game's difficulty dial.
+
+Dust in the beam: GPUParticles3D (60 particles, 4s life, box emission
+2x1.5x5 in front of camera, tiny unshaded spheres radius 0.008, alpha ramp
+peaking at 0.08). Emits only while the flashlight is visible. Reads as
+volumetrics at a fraction of the cost.
+
+### Breathing (fear you can feel)
+
+```gdscript
+func _handle_breathing(delta: float) -> void:
+	var target := 0.0
+	if stamina < 30.0:
+		target += (1.0 - stamina / 30.0) * 0.5
+	target += GameManager.tension_level * 0.3
+	breathing_intensity = lerpf(breathing_intensity, target, 2.0 * delta)
+	if breathing_intensity > 0.05:
+		var t := Time.get_ticks_msec() * 0.001
+		camera.rotation.x += sin(t * 1.5) * breathing_intensity * 0.003
+		camera.rotation.z = lerpf(camera.rotation.z,
+			sin(t * 2.0) * breathing_intensity * 0.002, 3.0 * delta)
+```
+
+Involuntary camera sway from low stamina + high tension. Subtle numbers -
+resist cranking them.
+
+## Level building (library first, primitives last)
+
+The level comes from real assets: route it through the `asset-strategy` skill
+(`summer_search_assets`, then `summer_import_asset` / `summer_import_asset_by_id`)
+and look for a ready horror location (an abandoned house, a haunted forest, a
+modular horror-house kit) plus period props, keeping one coherent style. Import
+the location that fits and build gameplay inside it. Do NOT grey-box a level a
+real asset already provides.
+
+Runtime primitive geometry (BoxMesh/PlaneMesh + StaticBody3D, collision
+layer 2) is only for what the imported assets lack: interior partitions the
+imported location does not have, trigger volumes, blockers. When you do need
+it: WALL_HEIGHT 3.5, WALL_THICKNESS 0.15, helpers `_floor(center, size)`,
+`_ceiling`, `_wall_x(z, x0, x1)` / `_wall_z(x, z0, z1)`, `_prop_box(pos,
+size, mat)`. Materials: dark desaturated albedo (floor 0.12/0.11/0.1, walls
+0.18/0.17/0.15), roughness 0.85.
+
+Layout formula:
+
+1. Entry area - well-lit, flashlight pickup here.
+2. Main hall - central hub, multiple exits, player keeps returning.
+3. Side corridors - long, narrow, dim; stalker territory.
+4. Dead-end rooms - keys and notes; forced backtracking.
+5. Back corridor - darkest, highest tension.
+6. Final area - escape zone at the far end, exit key behind at least one
+   locked door.
+
+## Atmosphere rendering settings
+
+WorldEnvironment is half the horror:
+
+- Sky near-black (top 0.02/0.02/0.05); ambient color 0.03/0.03/0.05 at
+  energy 0.5 - the player MUST need the flashlight.
+- Tonemap ACES, white 6.0. SSAO on (radius 2, intensity 3 - darkens
+  corners). SSIL on (radius 3, intensity 0.5). Glow subtle (0.3 / bloom 0.1).
+- Fog density 0.02 dark; volumetric fog density 0.06, anisotropy 0.7 -
+  this is what makes the flashlight beam a visible cone.
+
+Lighting rules: OmniLights energy 0.4-0.8 (main hall 1.2 max), ALL with
+`shadow_enabled = true` (the stalker casts a shadow before you see it).
+Give each area a distinct temperature - entry warm (0.6, 0.5, 0.3),
+corridors cool (0.3, 0.4, 0.35), lab sickly green (0.3, 0.6, 0.4) - it is
+navigation AND variety without textures.
+
+Collision layers: 1 Player, 2 Environment, 3 Interactable, 4 Enemy.
+
+## HUD (minimal by design)
+
+```
+HUD (CanvasLayer)
+  Crosshair (centered dot)
+  InteractionPrompt (Label, bottom center, "[E] Open")
+  BatteryContainer (top left, HIDDEN until flashlight found)
+    BatteryBar (ProgressBar; red <20%, yellow <50%, blue else)
+  NoteBackdrop (fullscreen black, 72% alpha)
+  NotePanel (centered note text)
+  Vignette (fullscreen; alpha = 0.2 + tension * 0.4)
+```
+
+Wire to GameManager signals (`note_opened/closed`, `game_state_changed`).
+Note UX detail: 0.35s cooldown after opening before close input is
+accepted - otherwise the same interact press that opened the note closes
+it. HUD hides entirely when state is not PLAYING.
+
+## Build order
+
+1. Autoloads + input map + layers.
+2. Player from 3d-fps base, horror speeds, state gating.
+3. One room + WorldEnvironment settings + flashlight pickup + drain.
+4. Doors/keys/notes + escape zone (`3d-horror-systems.md`).
+5. Atmosphere controller, then the stalker LAST - it only lands once the
+   world already feels wrong.
+
+## Traps
+
+- Giving the player any weapon, health bar, or combat UI.
+- Ambient energy above 0.5 - no darkness, no battery economy, no fear.
+- Constant jump scares. The template leans on anticipation; one of its
+  five tension events is deliberately NOTHING.
+- Stalker always visible - players habituate; long gaps are intentional.
+- Constant music. Silence scares; use the drone + rare stingers, save
+  music for peaks and safe rooms.
+- Identical rooms - distinct color temperature per area or players get
+  lost and bored simultaneously.
+- Skipping audio buses - SFX through SFX bus, ambience through Ambient,
+  or mixing and wall-muffling effects become impossible later.