summer-engine 3.1.0 → 3.2.0

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.

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.