summer-engine 3.1.0 → 3.2.0

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.

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

@@ -0,0 +1,220 @@
+# 3D Third-Person - Systems
+
+The combat and content layer on top of `3d-third-person.md`: melee, bullets,
+grenade with arc preview, two enemy archetypes, coins, destructible boxes,
+and the HUD.
+
+## Shared damage interface
+
+Everything hittable (player, enemies, boxes) implements:
+
+```gdscript
+func damage(impact_point: Vector3, force: Vector3) -> void
+```
+
+and joins the "damageables" group. `impact_point` is
+`global_position - body.global_position` (direction from body to impact),
+`force` is the knockback vector. Enemies additionally join "targeteables"
+for grenade lock-on. One interface, three weapons, all content - keep it.
+
+## Weapons
+
+Tab toggles DEFAULT and GRENADE (a `weapon_switched` signal drives the HUD
+icons). DEFAULT: left-click = melee from the hip, aim (RMB) + left-click =
+ranged shot with over-shoulder camera + crosshair. GRENADE: left-click
+throws with a live arc preview.
+
+### Melee (animation-gated hitbox)
+
+The MeleeAttackArea's CollisionShape3D starts disabled. The "Attack"
+animation (0.3-0.5s) has method-call tracks: `activate()` at the impact
+frame (~0.15s), `deactivate()` at the end. The area's `body_entered` damages
+"damageables" with force pointing away from the player. Player side:
+`attack()` plays the animation, fires the skin's punch OneShot, and sets
+`velocity = rotation_root.basis * Vector3.BACK * attack_impulse` (forward
+lunge). Movement is locked while the attack animation plays.
+
+Animation-gated hitboxes beat timer-gated ones: the active window is
+authored visually next to the swing frames.
+
+### Bullet (shared by player AND enemies)
+
+Node3D moved manually in `_process` - no physics body:
+
+```gdscript
+func _ready() -> void:
+	_area.body_entered.connect(_on_body_entered)
+	look_at(global_position + velocity)
+	_alive_limit = distance_limit / velocity.length()
+
+func _process(delta: float) -> void:
+	global_position += velocity * delta
+	_time_alive += delta
+	_bullet_visuals.scale = Vector3.ONE * scale_decay.sample(_time_alive / _alive_limit)
+	if _time_alive > _alive_limit:
+		queue_free()
+
+func _on_body_entered(body: Node3D) -> void:
+	if body == shooter:
+		return
+	if body.is_in_group("damageables"):
+		body.damage(global_position - body.global_position, velocity)
+	queue_free()
+```
+
+The `shooter` reference prevents self-hits, which is what lets one bullet
+scene serve both sides. Distance limit expressed as time
+(`distance / speed`); visual scale decays via an exported Curve so bullets
+fade with range. Player shots originate at `global_position + Vector3.UP`
+and fly toward `camera_controller.get_aim_target()`.
+
+Fast projectiles tunnel through thin walls: keep speeds moderate (player
+10, enemies 6) or fatten the Area3D shape.
+
+### Grenade launcher (arc preview + lock-on)
+
+While GRENADE is equipped the launcher is visible and every physics frame:
+camera tilt lerps throw distance between min 7 and max 16; a ShapeCast3D
+finds the landing point; if the cast hits a "targeteables" body, the landing
+snaps to that enemy (lock-on, SnapMesh indicator); initial velocity
+decomposes into vertical `sqrt(2 * gravity * peak_height)` and horizontal
+`distance / time_to_land`; the preview trail is a triangle-strip mesh built
+with SurfaceTool sampling the parabola at 0.05s steps.
+
+The grenade itself is a CharacterBody3D using `move_and_collide` (NOT
+move_and_slide) so it can bounce:
+
+```gdscript
+func _physics_process(delta) -> void:
+	_velocity += Vector3.DOWN * gravity * delta
+	var collision := move_and_collide(_velocity * delta)
+	if collision:
+		_velocity = _velocity.bounce(collision.get_normal(0)) * 0.7
+		if _explosion_start_timer.is_stopped():
+			_explosion_start_timer.start()
+```
+
+First bounce arms the fuse timer. Explosion: damage all overlapping
+"damageables" in the ExplosionArea EXCEPT the Player (`not body is Player` -
+self-immunity), spawn explosion visuals, hide, await the sound, free. On
+throw, add a collision exception between grenade and thrower via
+`PhysicsServer3D.body_add_collision_exception`.
+
+## Enemies
+
+Both are RigidBody3D with a PlayerDetectionArea (big sphere Area3D), a
+reaction label ("!" / "?" animations on detect/lose), and the same death
+choreography: play defeat sound, set `_alive = false`, DISCONNECT the
+detection signals (dead enemies must not react), enable the death collider,
+enable gravity so the body drops, wait 2s, spawn a smoke puff, `await
+puff.full`, burst coins out of the smoke, `queue_free()`.
+
+The smoke puff emits `full` from an animation keyframe at peak opacity -
+awaiting it makes coins appear to burst out of the cloud instead of
+clipping through a half-formed puff.
+
+### Bee bot (flying turret)
+
+RigidBody3D with `gravity_scale = 0` (floats). While a target is set:
+
+```gdscript
+var target_transform := transform.looking_at(_target.global_position)
+transform = transform.interpolate_with(target_transform, 0.1)
+```
+
+Fires the SAME bullet scene as the player every 1.5s at speed 6, aimed at
+`target.global_position + Vector3.UP`. `damage()` applies an impulse
+(clamped length 3) then runs the death choreography; gravity_scale flips to
+1.0 so it falls out of the air.
+
+### Beetle bot (NavigationAgent3D chaser)
+
+RigidBody3D with rotation axes locked (rigid until death). Chase loop:
+
+```gdscript
+_navigation_agent.target_position = _target.global_position
+var next := _navigation_agent.get_next_path_position()
+if not _navigation_agent.is_target_reached():
+	var direction := (next - global_position)
+	direction.y = 0                      # never dive/fly
+	direction = direction.normalized()
+	var collision := move_and_collide(direction * delta * 3)
+	if collision and collision.get_collider() is Player:
+		var force := -(global_position - collider.global_position)
+		force.y = 0.5
+		collider.damage(impact_point, force * 10.0)
+		_beetle_skin.attack()
+```
+
+`look_at` the target with Y flattened to its own height. On death, unlock
+all angular axes so the corpse tumbles.
+
+Navigation requirements: the level MUST have a baked NavigationRegion3D or
+the beetle stands still forever; the target must be reachable on the
+navmesh; always zero the Y of path directions.
+
+Enemy skins: AnimationTree state machines (Idle/Walk/Attack/Shake/PowerOff)
+with a secondary-action timer firing random idle shakes every 3-8s;
+`power_off()` stops that timer.
+
+## Coins
+
+RigidBody3D collectible, either placed in the level or scattered by
+`spawn()` (random impulse: direction rotated randomly around UP, range 2-4,
+height 1-3). Collection is DELAYED: layer 3 collision is off for
+`coin_delay` (0.5s default, 1.5s when the player drops them) so coins from
+a kill do not vacuum back instantly.
+
+Magnet: when the player enters the coin's detection area (mask = Player
+layer 4), freeze physics and tween to the player:
+
+```gdscript
+func set_target(new_target: PhysicsBody3D) -> void:
+	PhysicsServer3D.body_add_collision_exception(get_rid(), new_target.get_rid())
+	if _target == null:
+		sleeping = true
+		freeze = true
+		_initial_tween_position = global_position
+		_target = new_target
+		var tween := create_tween()
+		tween.tween_method(_follow, 0.0, 1.0, 0.5)   # lerp start -> player
+		tween.tween_callback(_collect)
+```
+
+`_follow` lerps from the captured start to the LIVE player position, so the
+coin homes even while the player runs. Collect: random-pitch sound,
+`player.collect_coin()`, hide, await audio, free. Coin model: spin
+`rotation.y += 1.5 * delta`, bob `sin(t) * 0.04`.
+
+## Destructible boxes
+
+`damage()` on the box: spawn 5 coins with `spawn()`, instantiate a
+pre-fractured debris scene, disable own collision (deferred), play sound,
+await it, free. Debris scene = 6 hidden frozen RigidBody3D pieces; on ready,
+shuffle and launch 3 random ones with `apply_force(rand_vector * 500)`,
+leave the rest hidden. Half-count random debris looks as good as full
+simulation at a fraction of the cost.
+
+## HUD
+
+```
+UI (CanvasLayer)
+  AimRecticle (%unique, ColorRect centered)   # visible only while aiming
+  CoinsContainer (%unique, HBoxContainer)     # slides in on change
+    CoinIcon + CoinsLabel + Timer
+  WeaponUI (PanelContainer)                   # Flash / Grenade icons
+```
+
+Coin counter: slides from y -100 to y 20 on `update_coins_amount`, restarts
+its display timer per change, slides back out on timeout. Weapon icons:
+inactive at alpha 0.2, tween to full white on select; `switch_to()` guards
+against reselecting the current one. Use unique names (%) so the deep
+player script reaches UI without brittle paths.
+
+## Order of work
+
+1. Melee: attack animation + gated hitbox + a destructible box to punch.
+2. Coins with magnet + HUD counter (the reward loop).
+3. Aim mode: over-shoulder pivot + crosshair + bullet.
+4. Bee bot (reuses your bullet), then beetle bot (navmesh required).
+5. Grenade launcher last - arc preview, lock-on, explosion.