summer-engine 3.0.0 → 3.2.0

package/library/skills/make-game/references/2d-survivors-progression.md

@@ -0,0 +1,201 @@
+# 2D Survivors - Progression
+
+The systems layer on top of `2d-survivors.md`: enemy roster, wave-driven
+spawning, elites, level-up upgrades, the between-wave shop, weapon evolution,
+and characters. Build these only after the core loop (move + auto-fire + chase)
+runs.
+
+## Enemy roster (one script, many behaviors)
+
+All types share `enemy_base.gd` (Area2D, "enemies" group), configured through
+`setup(type, wave)` - no per-type scenes. HP/speed scale with wave number:
+
+| Type | Behavior | Health | Speed | Special |
+|---|---|---|---|---|
+| Walker | chase + wobble | 15 + wave*8 | 55 + wave*2 | standard horde unit |
+| Runner | fast chase | 8 + wave*4 | 110 + wave*3 | 0.7x scale |
+| Tank | slow, big | 50 + wave*15 | 35 + wave*1 | 1.5x scale, 3 XP |
+| Boss | massive | 500 + wave*80 | 45 | 2.8x scale, 25 XP |
+| Ranged | keeps distance | 12 + wave*5 | 50 + wave*1.5 | fires projectiles |
+| Charger | telegraph + dash | 20 + wave*7 | 50 + wave*1.5 | 550px/s burst |
+| Spawner | stays back | 80 + wave*20 | 30 | spawns 2-3 minions |
+
+Behavior dispatch is a `match behavior:` in `_physics_process`. Give every
+enemy a randomized wobble (`_wobble_phase = randf() * TAU`, per-enemy speed and
+amplitude) so hordes look organic instead of converging in a straight line.
+
+Charger is a 4-state machine: WALK -> TELEGRAPH (0.45s, within 320px trigger
+range) -> CHARGE (0.4s at 550px/s in the locked direction) -> RECOVER (0.3s),
+then 3.5s cooldown. The telegraph is what makes it fair - flash/scale the sprite
+during it.
+
+Knockback: on hit, set `_knockback_vel = (pos - source).normalized() * 180`,
+decay with `move_toward(Vector2.ZERO, 900 * delta)` and add to movement.
+
+### Hit feedback and death (non-negotiable)
+
+`take_damage(amount, source_pos, is_crit)` must: flash the sprite, spawn a
+floating damage number (bigger + colored on crit), spawn directional particles,
+apply knockback, show the health bar. Death: `GameManager.add_kill()`,
+`add_xp(xp_value)`, drop gold (rare health orb), particle burst, then disable
+before animating out:
+
+```gdscript
+set_physics_process(false)
+set_deferred("monitoring", false)
+set_deferred("monitorable", false)
+var tween := create_tween().set_parallel(true)
+tween.tween_property(self, "scale", scale * 1.5, 0.1)
+tween.tween_property(self, "modulate:a", 0.0, 0.1)
+tween.chain().tween_callback(queue_free)
+```
+
+The `set_deferred` pair matters: freeing an Area2D mid-physics-callback without
+disabling monitoring first throws errors.
+
+## Spawner and wave data
+
+The spawner reads a per-wave config and spawns groups on an interval, always
+off-screen (650-900px from the player, clamped to arena bounds):
+
+```gdscript
+func _random_spawn_pos() -> Vector2:
+	var angle := randf() * TAU
+	var dist := randf_range(650.0, 900.0)
+	var pos := GameManager.player_node.global_position + Vector2.from_angle(angle) * dist
+	pos.x = clampf(pos.x, -ARENA_HALF_SIZE, ARENA_HALF_SIZE)
+	pos.y = clampf(pos.y, -ARENA_HALF_SIZE, ARENA_HALF_SIZE)
+	return pos
+```
+
+Each WaveConfig: `enemy_weights: Dictionary`, `spawn_interval`, `group_size`,
+`max_alive`, `elite_chance`, `boss: bool`, `hazards: int`, `duration`. Type
+selection is weighted random over the dictionary. Hand-tune 20 waves; the ramp
+that matters:
+
+| Wave | Types | Interval | Group | Max alive | Elite % | Boss | Duration |
+|---|---|---|---|---|---|---|---|
+| 1 | walker | 2.5s | 2 | 25 | 0% | no | 20s |
+| 3 | +runner | 2.0s | 4 | 45 | 0% | no | 20s |
+| 5 | +charger | 1.7s | 5 | 65 | 3% | no | 22s |
+| 8 | +tank +ranged | 1.3s | 8 | 100 | 6% | no | 22s |
+| 10 | all 6 | 1.1s | 10 | 120 | 8% | YES | 30s |
+| 15 | tank heavy | 0.75s | 15 | 190 | 13% | no | 28s |
+| 20 | max density | 0.45s | 22 | 250 | 20% | YES | 30s |
+
+Do NOT scale difficulty by HP alone. The ramp is spawn rate + group size +
+max alive + type diversity + elite chance + new mechanics at fixed waves.
+Bosses spawn 3s into their combat phase via a scene-tree timer.
+
+Arena hazards from wave 3+: spike traps (static) and fire pools (drift at
+15-35px/s). Tick damage every 0.6s (6 + wave*1.5) to enemies in radius, half
+damage to the player - positioning pressure for both sides.
+
+## Elites
+
+`elite_system.gd` is a static RefCounted helper applied at spawn time with
+`elite_chance` probability. One of four modifiers, 3x XP:
+
+- FAST: speed x1.8, HP x1.3, lightened color
+- TANKY: HP x3, scale x1.3, contact damage x1.5, darkened
+- SPLITTING: HP x1.5, green; on death spawns 2 walker copies at 0.6x scale,
+  0.3x HP (use `call_deferred("add_child", copy)` - you are inside a physics
+  callback)
+- VAMPIRIC: HP x2; heals 8% max HP every 3s
+
+Give elites a visible pulse tween so players can prioritize them.
+
+## Two-track progression
+
+Track 1 - mid-wave level-ups: on level-up the tree pauses, 3 random stat
+upgrades from the pool are offered, each stackable to level 3. Also vacuum all
+pickups (`attract()` on the "pickups" group) as a reward beat.
+
+| Upgrade | Per level | Stat touched |
+|---|---|---|
+| Might | +15% damage | player_damage_mult |
+| Haste | +12% attack speed | player_attack_speed_mult |
+| Swiftness | +20 speed | player_speed |
+| Vitality | +15 max HP (and heal 15) | player_max_health |
+| Magnetism | +20 pickup range | player_pickup_range |
+| Armor | +1 flat reduction | player_armor |
+| Regeneration | +0.5 HP/s | player_regen |
+| Critical Eye | +5% crit | player_crit_chance |
+
+`get_random_choices(3)` filters out maxed upgrades, shuffles, takes 3.
+`apply_upgrade` bumps level and writes the stat straight onto GameManager.
+Armor applies as `maxi(1, amount - player_armor)` - always at least 1 damage.
+
+Track 2 - between-wave shop: 4 random items, gold-priced, 4 tiers (Common /
+Uncommon / Rare / Legendary). Tier odds shift with wave - by wave 16+:
+15% Legendary / 30% Rare / 35% Uncommon / 20% Common; waves 1-5 have no
+Legendary at all. Prices scale `cost_base * (1.0 + wave * 0.12)`; reroll costs
+`2 + reroll_count + wave / 5` (escalates within a single shop visit).
+
+Items are either stat dictionaries applied to GameManager
+(`{"player_armor": 2}`) or weapon grants that call
+`player.add_or_upgrade_weapon(id)`. The interesting ones trade off:
+
+```gdscript
+_add("glass_cannon", "Glass Cannon", 2, 40,
+	{"player_damage_mult": 0.35, "player_max_health": -25}, ["offense"])
+_add("berserker_mask", "Berserker Mask", 2, 45,
+	{"player_damage_mult": 0.25, "player_attack_speed_mult": 0.20,
+	 "player_armor": -3}, ["offense"])
+```
+
+Do not skip the shop. Without a between-wave decision point the game is just
+"survive longer"; trade-off items are what create builds.
+
+## Weapon evolution
+
+A base weapon evolves when the player owns it AND a specific catalyst upgrade
+is maxed (level 3). Check after every upgrade pick and shop purchase; emit
+`evolution_available` once per recipe:
+
+| Evolved | Base weapon | Catalyst | Effect |
+|---|---|---|---|
+| Piercing Barrage | Projectile | Multi Shot | pierces 4+, faster bullets |
+| Radiant Barrier | Orbital | Armor | 4 large orbitals + damage pulses |
+| Supernova | Holy Nova | Might | bigger AoE + burning ground DOT |
+
+Evolving replaces the node: `queue_free()` the old weapon, erase from the
+player's `_weapons` dict, instantiate the evolved script, screen flash + zoom
+pulse. DOT zones (Supernova) are a Polygon2D + tween loop: N tick callbacks at
+0.5s intervals doing a group distance scan, then fade and free. Guard every
+tick with `is_instance_valid` - the zone can outlive enemies and vice versa.
+
+## Characters
+
+Four picks before the run, each a starting weapon + stat override dictionary:
+
+- Sentinel: projectile, no overrides (baseline)
+- Berserker: projectile, damage_mult 1.4, speed 240, max HP 80
+- Warden: orbital, max HP 150, armor 3, attack_speed 0.85
+- Arcanist: nova, attack_speed 1.25, damage_mult 1.15, max HP 70
+
+`GameManager.reset_run()` resets all stats to base, then applies
+`selected_character.stat_overrides` via `set(key, value)` and fills health to
+max. Character select is just 4 cards that set `selected_character` and load
+the arena.
+
+## UI stack (all procedural, all CanvasLayer, all process_mode ALWAYS)
+
+- HUD: health + dash bars top-left, wave counter + timer top-center,
+  gold/kills/level top-right, full-width 6px XP bar at the bottom.
+- LevelUpUI (layer 20): dark overlay, 3 cards, gamepad focus.
+- ShopUI (layer 25): stats panel left, 4 tier-colored item cards, reroll +
+  next-wave buttons, "SOLD" placeholders, live stat refresh after purchase.
+- PauseMenu / GameOverUI (layer 40): game over shows victory or death plus
+  time / kills / level / wave, retry + menu.
+
+Retry = `get_tree().paused = false` THEN `reload_current_scene()`. Forgetting
+the unpause is the classic frozen-retry bug.
+
+## Audio integration points
+
+Pooled AudioManager (16 global + 16 positional players, round-robin; all play
+methods null-safe so missing streams never crash). Pitch variance 5% global /
+10% positional prevents machine-gun repetition. Hook: enemy hit + death
+(positional), pickup collect, level-up, shop purchase, weapon fire (-6dB, it
+fires constantly), music on combat start with fade.

package/library/skills/make-game/references/2d-survivors.md

@@ -0,0 +1,237 @@
+# 2D Survivors - Core
+
+Vampire Survivors-style auto-battler blueprint: arena, wave state machine, player,
+and auto-firing weapons. The player only moves and dashes; weapons aim and fire
+themselves. Waves, enemies, upgrades, shop, and evolution live in
+`2d-survivors-progression.md`.
+
+## Minimum playable base (build this first)
+
+One arena scene: player CharacterBody2D with WASD movement, one auto-firing
+projectile weapon, a handful of chasing enemies, and visible feedback on every
+hit (flash + damage number). Prove "move, enemies chase, weapon kills them"
+before waves, shop, or characters exist.
+
+Two rules for every scene:
+
+- Dynamic viewport: `display/window/stretch/mode = "canvas_items"`,
+  `stretch/aspect = "expand"`. All UI uses Control anchors, never hardcoded
+  pixel positions. Spawn enemies relative to the player (650-900px out), never
+  from screen coordinates.
+- Playable slice, not tech demo: every hit needs shake/flash/particles/damage
+  number. A silent wave where numbers move but nothing feels alive fails.
+
+## Architecture
+
+```
+res://
+  scenes/
+    main.tscn                  # main menu (run entry point)
+    levels/arena.tscn          # THE gameplay scene (owns everything)
+    player/player.tscn
+    enemies/enemy.tscn         # one scene reused for ALL enemy types
+    enemies/enemy_projectile.tscn
+    pickups/pickup.tscn        # gold coin / health orb
+    weapons/projectile.tscn
+    ui/character_select.tscn
+  scripts/
+    autoloads/{game_manager,audio_manager}.gd
+    player/player.gd
+    enemies/{enemy_base,enemy_spawner,enemy_projectile,elite_system}.gd
+    weapons/{projectile_weapon,projectile,orbital_weapon,area_weapon}.gd
+    weapons/evolved/{piercing_projectile_weapon,radiant_orbital_weapon,supernova_weapon}.gd
+    systems/{wave_data,upgrade_data,upgrade_manager,weapon_evolution,
+             item_data,item_manager,item_registry,character_data,
+             character_registry,pickup,camera_effects,arena_hazard}.gd
+    ui/{main_menu,character_select_ui,hud,level_up_ui,shop_ui,
+        pause_menu,game_over_ui}.gd
+```
+
+Two autoloads only: `GameManager` (single source of truth for ALL run state -
+stats, gold, XP, health, wave, signals) and `AudioManager` (pooled SFX + music).
+Every system reads and writes GameManager; UI listens to its signals.
+
+## Physics layers
+
+| Layer | Bit | Name |
+|-------|-----|------|
+| 1 | 1 | Player |
+| 2 | 2 | Enemies |
+| 3 | 4 | Pickups |
+| 4 | 8 | PlayerProjectiles |
+| 5 | 16 | Walls |
+| 6 | 32 | EnemyProjectiles |
+
+Wiring: Player body layer 1 mask 16 (walls only). Player Hurtbox layer 0 mask 34
+(Enemies + EnemyProjectiles). PickupRange layer 0 mask 4. Enemies layer 2 mask 0.
+Player projectiles layer 8 mask 2. Enemy projectiles layer 32 mask 1.
+
+Input map: move_up/down/left/right (WASD + left stick), dash (Space + R2),
+pause (Escape + Start).
+
+## Wave state machine (arena.gd)
+
+The arena scene owns the player, spawner, all managers, and all UI CanvasLayers.
+Everything wires together via signals in `_ready()`. Per wave, 4 phases:
+
+```
+PRE_WAVE (1.5s announce) -> COMBAT (timed, 20-30s) ->
+WAVE_CLEAR (2.5s: kill all, vacuum gold, slow-mo) ->
+SHOPPING (buy/reroll/next) -> next PRE_WAVE
+```
+
+20 waves total, bosses at 10 and 20, victory after 20, death = game over.
+
+```gdscript
+# arena.gd core
+enum WaveState { PRE_WAVE, COMBAT, WAVE_CLEAR, SHOPPING }
+
+func _physics_process(delta: float) -> void:
+	if GameManager.current_state != GameManager.State.PLAYING:
+		return
+	match _wave_state:
+		WaveState.PRE_WAVE:
+			_state_timer -= delta
+			if _state_timer <= 0.0: _start_combat()
+		WaveState.COMBAT:
+			_combat_time_remaining -= delta
+			hud.update_wave_timer(_combat_time_remaining)
+			if _combat_time_remaining <= 0.0: _start_wave_clear()
+		WaveState.WAVE_CLEAR:
+			_state_timer -= delta
+			if _state_timer <= 0.0: _start_shopping()
+```
+
+Wave clear = spawner off, `kill_all_enemies()`, gold bonus (5 + wave*2),
+flash + slow_motion(0.4, 0.8) + zoom pulse. GameManager pauses the tree for
+LEVEL_UP / SHOPPING / PAUSED / GAME_OVER states and unpauses on PLAYING:
+
+```gdscript
+func change_state(new_state: State) -> void:
+	current_state = new_state
+	state_changed.emit(new_state)
+	match new_state:
+		State.PLAYING: get_tree().paused = false
+		State.PAUSED, State.LEVEL_UP, State.SHOPPING, State.GAME_OVER:
+			get_tree().paused = true
+```
+
+Arena is a 6000x6000 field: background ColorRect, StaticBody2D walls on layer 5
+at +-3020, Line2D border for visibility. Player collides with walls; enemies
+do not (spawn logic clamps them).
+
+## Player
+
+```
+Player (CharacterBody2D, layer 1, mask 16/Walls)
+  CollisionShape2D (CircleShape2D radius 14)
+  Body (Polygon2D, arrow shape, character color)
+  Hurtbox (Area2D, layer 0, mask 34)
+    CollisionShape2D (CircleShape2D radius 12)
+  PickupRange (Area2D, layer 0, mask 4)
+    CollisionShape2D (CircleShape2D radius 140, driven by GameManager stat)
+  WeaponMount (Node2D)         # weapons attach here
+  Camera2D (smoothing on, speed 4.0)
+```
+
+Movement is trivial by design - all depth lives in the build:
+
+```gdscript
+func _move() -> void:
+	var input := Input.get_vector("move_left", "move_right", "move_up", "move_down")
+	velocity = input * GameManager.player_speed
+	move_and_slide()
+	if input.length_squared() > 0.01:
+		body.rotation = input.angle()
+```
+
+Dash: 0.14s invincible burst at 650px/s, 1.2s cooldown, afterimage ghost
+(Polygon2D copy, tween alpha to 0 over 0.2s) every 0.025s. Invincibility timer =
+dash duration + 0.08. HUD shows the cooldown bar.
+
+Contact damage: do NOT use `area_entered` signals. Check
+`hurtbox.get_overlapping_areas()` manually each `_physics_process` and apply
+damage with a 0.6s invincibility window. Signals miss continuous contact;
+polling + i-frames is reliable.
+
+Player also handles: regen tick (1s interval, `GameManager.player_regen` HP),
+pickup magnet (attract pickups inside PickupRange), and a `_weapons` Dictionary
+keyed by weapon id - `add_or_upgrade_weapon(id)` upgrades if owned, else
+instantiates the weapon script onto WeaponMount.
+
+## Weapons (auto-fire, no aiming)
+
+All weapons are Node2D scripts on WeaponMount, firing from `_physics_process`.
+Damage scales with `GameManager.player_damage_mult`, cooldowns divide by
+`player_attack_speed_mult`, crits roll `player_crit_chance` for 2x. Three bases:
+
+- Projectile: fires at nearest enemy within 800px (compare
+  `distance_squared_to` against 640000, never sqrt). Extra projectiles fan out
+  at 0.15 rad spread. If no target, retry in 0.1s instead of a full cooldown.
+- Orbital: N shields orbit at radius 80, speed 3.5 rad/s. Per-enemy hit
+  cooldown Dictionary (0.4s keyed by instance id) so one orbit does not
+  multi-hit the same enemy every frame.
+- Area (nova): every 3.0s damage all enemies within radius 120 (group scan +
+  distance_squared), show an expanding ring tween.
+
+```gdscript
+func _find_nearest_enemy() -> Node2D:
+	var nearest: Node2D = null
+	var best := MAX_TARGET_RANGE_SQ
+	for enemy in get_tree().get_nodes_in_group("enemies"):
+		if not is_instance_valid(enemy): continue
+		var d := global_position.distance_squared_to(enemy.global_position)
+		if d < best:
+			best = d
+			nearest = enemy
+	return nearest
+```
+
+Group scan is fine to ~250 enemies (the max_alive cap); past that use spatial
+hashing.
+
+## Pickups and XP
+
+XP is NOT a physical pickup - it auto-earns on kill (`GameManager.add_xp`,
+amount = enemy xp_value). Gold and health orbs ARE physical Area2D pickups in
+the "pickups" group with magnet behavior: once `attract()` is called (player
+range overlap, or level-up vacuums all), accelerate toward the player at up to
+650px/s and collect within 12px. Level-up curve:
+`xp_needed = 5 + level*level + level*3`.
+
+## Camera effects (the juice layer)
+
+`camera_effects.gd` attaches as a child of the player's Camera2D. Provides
+`screen_shake(intensity, duration)` (tween_method randomized offset decaying to
+zero), `screen_flash(color, duration)`, `slow_motion(scale, duration)` (set
+`Engine.time_scale`, restore via tween with `set_ignore_time_scale(true)`),
+`zoom_pulse`, and a low-HP vignette shader that fades in below 35% health.
+Register it on GameManager (`GameManager.camera_fx`) so every system can call it.
+
+## Build order
+
+1. project.godot: autoloads, input map, layer names, main scene, 1920x1080
+   canvas_items/expand stretch. Audio buses: Master, Music, SFX.
+2. Scenes smallest-first: pickup, projectile, enemy_projectile, enemy, player,
+   character_select, main, arena.
+3. Base loop: player move + dash, projectile weapon, walker enemies chasing.
+4. GameManager stats + HUD (health, gold, XP bar, wave timer, kills, dash bar).
+5. Wave state machine + spawner + wave data (progression file).
+6. Level-up upgrades, shop, elites, evolution, characters (progression file).
+
+## Traps
+
+- Physics-based enemies. Never RigidBody2D or move_and_slide for enemies -
+  direct `position +=` on Area2D. Hundreds of colliding bodies kill perf;
+  enemies only need to chase, not collide with each other.
+- Heavy enemy scenes. One Area2D + CollisionShape2D + Polygon2D + ProgressBar.
+  No AnimationPlayer, no particles, no per-enemy shader materials - you will
+  have 200+ alive.
+- UI without `process_mode = ALWAYS`. The tree pauses during level-up, shop,
+  and game over; without ALWAYS, no button responds and the game soft-locks.
+- Manual aim. The entire input surface is move + dash. Weapons auto-target;
+  adding aim breaks the genre.
+- Editor-connected signals on runtime-instantiated scenes. Connect in `_ready()`
+  via code for enemies/projectiles/pickups - editor connections on templates
+  are fragile and undebuggable.
+- On-screen spawns. Always 650-900px from the player, clamped to arena bounds.

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

@@ -0,0 +1,216 @@
+# 3D FPS - Systems
+
+The combat and interaction layer on top of `3d-fps.md`: hitscan and
+projectile shooting, the data-driven weapon system, raycast interaction, and
+the HUD.
+
+## Shooting: hitscan vs projectile
+
+Hitscan (raycast) for rifles/pistols, projectiles for rockets/grenades.
+Most weapons should be hitscan - instant, cheap, reliable.
+
+### Hitscan
+
+Uses the player's ShootRay (RayCast3D under Camera3D, target (0,0,-100),
+mask 6 = Environment + Enemy):
+
+```gdscript
+func _shoot() -> void:
+	if not can_shoot:
+		return
+	can_shoot = false
+	shoot_cooldown = 0.1  # fire rate
+	shoot_ray.force_raycast_update()
+	if shoot_ray.is_colliding():
+		var collider := shoot_ray.get_collider()
+		_spawn_hit_effect(shoot_ray.get_collision_point(), shoot_ray.get_collision_normal())
+		if collider.has_method("take_damage"):
+			collider.take_damage(25.0)
+```
+
+`force_raycast_update()` matters: the ray otherwise reports last frame's
+state and fast turns produce misses. Cooldown ticks down in `_process` and
+re-arms `can_shoot`.
+
+### Projectile
+
+CharacterBody3D moved with `move_and_collide` (not RigidBody - you want
+deterministic flight):
+
+```gdscript
+func _physics_process(delta: float) -> void:
+	time_alive += delta
+	if time_alive >= lifetime:   # 5s despawn, always
+		queue_free()
+		return
+	velocity = direction * speed
+	if gravity_affected:
+		velocity.y -= 9.8 * delta
+	var collision := move_and_collide(velocity * delta)
+	if collision:
+		var collider := collision.get_collider()
+		if collider and collider.has_method("take_damage"):
+			collider.take_damage(damage)
+		_explode()
+		queue_free()
+```
+
+Spawn from the camera, not the weapon model, so shots go where the
+crosshair points:
+
+```gdscript
+proj.global_position = camera.global_position
+proj.direction = -camera.global_transform.basis.z
+get_tree().current_scene.add_child(proj)
+```
+
+## Weapon system (data-driven)
+
+WeaponData is a Resource; one .tres (or in-code instance) per weapon:
+
+```gdscript
+class_name WeaponData
+extends Resource
+
+@export var weapon_name: String = "Pistol"
+@export var damage: float = 25.0
+@export var fire_rate: float = 0.15      # seconds between shots
+@export var reload_time: float = 1.5
+@export var magazine_size: int = 12
+@export var max_ammo: int = 120
+@export var is_automatic: bool = false
+@export var is_hitscan: bool = true
+@export var spread: float = 0.0          # radians of random spread
+@export var projectile_scene: PackedScene = null
+@export var weapon_model_scene: PackedScene = null
+```
+
+WeaponManager (Node3D child of Player) owns `weapons: Array[WeaponData]`,
+current index, magazine/reserve ammo, and these signals for the HUD:
+`weapon_changed`, `ammo_changed(current, reserve)`,
+`reload_started(time)`, `reload_finished`.
+
+Core rules learned the hard way:
+
+- Automatic vs semi-auto is one branch: automatic polls
+  `Input.is_action_pressed("shoot")`, semi-auto uses
+  `is_action_just_pressed`.
+- Fire path: refuse if `not can_shoot or is_reloading`; if magazine empty,
+  auto-start reload instead of firing; decrement ammo and emit
+  `ammo_changed` BEFORE resolving the hit.
+- Spread: randomize `shoot_ray.target_position` x/y within +-spread before
+  the raycast, then RESET it to (0,0,-100) after - a forgotten reset makes
+  every later weapon inherit the spread.
+- Switching: clear WeaponHolder children (`queue_free`), instantiate the
+  new `weapon_model_scene`, reset `is_reloading`/`can_shoot`/`shoot_timer`.
+  Guard against re-equipping the same index.
+- Reload:
+
+```gdscript
+func _start_reload() -> void:
+	if is_reloading or magazine_ammo == current_weapon.magazine_size:
+		return
+	if reserve_ammo <= 0:
+		return
+	is_reloading = true
+	can_shoot = false
+	reload_started.emit(current_weapon.reload_time)
+	var tween := create_tween()
+	tween.tween_interval(current_weapon.reload_time)
+	tween.tween_callback(_finish_reload)
+
+func _finish_reload() -> void:
+	var available := mini(current_weapon.magazine_size - magazine_ammo, reserve_ammo)
+	magazine_ammo += available
+	reserve_ammo -= available
+	is_reloading = false
+	can_shoot = true
+	ammo_changed.emit(magazine_ammo, reserve_ammo)
+	reload_finished.emit()
+```
+
+The `is_reloading` guard is not optional - without it players stack reload
+timers. Partial reloads take `mini(needed, reserve)`, never a full magazine.
+
+Weapon switching by number keys: loop `weapons.size()` checking
+`Input.is_action_just_pressed("weapon_%d" % (i + 1))`.
+
+## Interaction system
+
+Duck-typed interface - any node is interactable if it implements:
+
+```gdscript
+func interact(player: Node3D) -> void
+func get_interaction_prompt() -> String
+```
+
+The player polls its InteractionRay every physics frame and caches
+`look_target`. Check the collider AND its parent for the methods (the
+collider is often a StaticBody3D child of the actual object):
+
+```gdscript
+func _update_interaction_target() -> void:
+	if interaction_ray.is_colliding():
+		var target: Node = interaction_ray.get_collider()
+		if target and not target.has_method("get_interaction_prompt"):
+			target = target.get_parent()
+		if target and target.has_method("get_interaction_prompt"):
+			look_target = target
+			return
+	look_target = null
+```
+
+### Door pattern
+
+Node3D root that rotates; mesh + StaticBody3D child positioned at
+(0.5, 1.4, 0) so the hinge is the parent origin, not the door center.
+`_process` lerps `rotation.y` toward `target_rotation`. Open away from the
+player by checking which side they are on:
+
+```gdscript
+var to_door := global_position - player.global_position
+var local_dir := global_transform.basis.inverse() * to_door
+target_rotation = deg_to_rad(open_angle if local_dir.z > 0 else -open_angle)
+```
+
+Prompt reflects state: "Locked" / "Open" / "Close". The door body's
+collision_layer is 6 (Environment + Interactable) so it both blocks
+movement and answers the interaction ray.
+
+### Pickup pattern
+
+RigidBody3D with `freeze = true` (physics off, still hit by rays), idle bob
+(`base_y + sin(bob_time) * 0.05`) and slow rotate, randomized starting
+phase (`bob_time = randf() * TAU`) so a row of pickups does not bob in
+lockstep. `interact()` applies the effect and `queue_free()`s.
+
+## HUD
+
+```
+HUD (CanvasLayer)
+  Crosshair (TextureRect, centered 16x16)
+  InteractionPrompt (Label, bottom center, "[E] Open")
+  AmmoLabel (Label, bottom right, "12 / 120")
+  HealthBar (ProgressBar, bottom left)
+  DamageOverlay (ColorRect, full rect, red, alpha 0)
+```
+
+Wiring pattern: the HUD finds the player via the "player" group in
+`_process` (retry until found - spawn order is not guaranteed), then
+connects `weapon_manager.ammo_changed`. Interaction prompt shows
+`"[E] " + player.look_target.get_interaction_prompt()` while `look_target`
+is set, hides otherwise.
+
+Damage feedback: on hit, set the overlay to `Color(1, 0, 0, 0.3)` and fade
+alpha down at 2.0/s in `_process`. Cheap and effective.
+
+## Order of work
+
+1. Hitscan fire on the base controller (fixed 25 damage, no weapon data).
+2. Hit effects + damage overlay - shooting must feel real before it is
+   configurable.
+3. WeaponData + WeaponManager, migrate the hardcoded fire into it, add
+   ammo/reload + HUD ammo label.
+4. Second and third weapons (one automatic with spread, one projectile) to
+   prove the data path.
+5. Interaction ray + door + pickup + prompt label.