summer-engine 3.1.0 → 3.2.0

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

@@ -0,0 +1,234 @@
+# 2D Action RPG - Content Systems
+
+The content layer on top of `2d-rpg.md`: enemies, NPCs and dialogue, quests,
+inventory, loot, perks, status effects, and save/load. Everything here talks
+to the rest of the game only through EventBus and the autoloads.
+
+## Enemies (data-driven, five archetypes)
+
+EnemyData resource defines stats + behavior; enemy_base.gd implements all
+five behaviors and reads the data. No per-enemy scenes.
+
+```gdscript
+enum BehaviorType { CHASE, RANGED, SWARM, TANK, BOSS }
+```
+
+- CHASE (slime): direct pursuit, melee lunge, low knockback resistance.
+- RANGED (skeleton archer): holds preferred distance, fires projectiles,
+  strafes at range, backs off when crowded.
+- SWARM (bat): fast, random jitter movement, contact damage.
+- TANK (golem): slow, high HP, knockback_resistance 0.8, ground slam with
+  screen shake.
+- BOSS (dark mage): cycling pattern (single shot -> fan of 3 -> charge),
+  phase 2 at 40% HP (faster everything + aura), can summon minions. Emits
+  `boss_health_changed` for the HUD boss bar.
+
+EnemyData fields that matter for tuning: max_health, contact_damage,
+move_speed, detection_range 200, attack_range 35, attack_cooldown 1.2,
+knockback_resistance, xp_value, gold_min/max.
+
+EnemyDatabase registers everything in code (no .tres files):
+`db.get_enemy("slime")`, `db.get_enemies_for_wave(5)` returns a
+wave-appropriate mix. Built-ins: slime, skeleton_archer, bat, golem,
+dark_mage.
+
+Contract: every enemy is in the "enemies" group and exposes
+`take_hit(damage: int, source_position: Vector2, is_crit: bool = false)`.
+Weapons and projectiles call it directly. Death drops XP + gold orbs via
+`_drop_loot()` and emits `EventBus.enemy_killed(enemy, xp_value)`.
+
+EnemySpawner is wave-based: `wave_interval` 12s, `enemies_per_wave_base` 3,
+`enemies_per_wave_growth` 1, `max_enemies` 20, `difficulty_scale` 1.08
+(HP/damage multiplier per wave). `spawn_boss("dark_mage", pos)` for arenas.
+
+## NPCs and dialogue
+
+DialogueData is a resource with a speaker name and a lines array. Each line
+is a dictionary supporting optional keys:
+
+```gdscript
+{
+  "text": "Hello!",
+  "speaker": "Elder",                        # override
+  "choices": [{"text": "Yes", "next": 2}],   # branching
+  "action": "start_quest:slay_monsters",
+  "condition": "quest_complete:slay_monsters"
+}
+```
+
+Actions: `start_quest:<id>`, `give_item:<resource_path>`, `give_gold:<n>`,
+`heal`. Conditions: `quest_complete:<id>`, `quest_active:<id>`,
+`has_item:<id>`. This tiny string DSL covers most RPG dialogue needs -
+resist building a graph editor.
+
+Interaction flow (the pause dance):
+
+```gdscript
+func interact(player: Node2D) -> void:
+	EventBus.dialogue_started.emit(npc_name)
+	GameManager.change_state(GameManager.GameState.DIALOGUE)  # pauses tree
+	await _run_dialogue(start_index)
+	EventBus.dialogue_ended.emit()
+	GameManager.change_state(GameManager.GameState.PLAYING)
+	player.end_interaction()
+```
+
+NPC = CharacterBody2D + CollisionShape2D + child Area2D named EXACTLY
+"InteractionArea" on the interactions layer. Player entering shows a prompt;
+interact key starts dialogue. When building NPCs in code, add the node tree
+first, `add_child` it, THEN set script properties (npc_name, dialogue,
+quest_to_give) - properties set before the script enters the tree can be
+stomped by `_ready`.
+
+DialogueBox: typewriter at 40 chars/sec, click skips to full text, click
+again advances, choices render as buttons. Must be process_mode ALWAYS (tree
+is paused during dialogue).
+
+## Quests
+
+QuestData: id, title, description, objectives array
+(`{"id": "kill_slimes", "description": "Kill 3 slimes", "target": 3}`),
+xp_reward, gold_reward, prerequisite_quest_id.
+
+QuestManager (autoload) API: `start_quest(data)`,
+`progress_objective(quest_id, objective_id, amount = 1)`,
+`is_quest_active/complete(id)`, `get_objective_progress(id, obj_id)`. When
+all objectives hit target the quest auto-completes, grants rewards, and
+emits `quest_completed`.
+
+Wiring kills to quests happens in the LEVEL script, not the enemy:
+
+```gdscript
+func _ready() -> void:
+	EventBus.enemy_killed.connect(_on_enemy_killed)
+
+func _on_enemy_killed(_enemy: Node2D, _xp: int) -> void:
+	QuestManager.progress_objective("slay_monsters", "kill_enemies")
+```
+
+Enemies stay dumb; levels decide what counts.
+
+## Inventory and items
+
+InventoryManager (autoload): 20 item slots, 3 equipment slots (weapon,
+armor, accessory), gold. `add_item()` returns false when full;
+`use_item()` only works on consumables; `equip_item()` auto-routes by the
+item's slot; `get_total_stat_bonus("attack")` sums equipment bonuses for the
+stats pipeline; `clear()` on restart.
+
+ItemData: ItemType (CONSUMABLE/WEAPON/ARMOR/ACCESSORY/KEY_ITEM), Rarity
+(COMMON/UNCOMMON/RARE/EPIC with white/green/blue/purple colors),
+`stat_bonuses: Dictionary` ("attack" -> 5), heal_amount, buy/sell price.
+
+## Loot
+
+- LootTable: guaranteed gold range + guaranteed XP, then `drop_chance` roll
+  over weighted entries (`{"item", "weight", "min_count", "max_count"}`).
+  `table.roll()` returns the drops.
+- PickupOrb: XP/gold orbs from dead enemies, magnet-pull within 100px,
+  accelerating toward the player.
+- TreasureChest: interactable static body - guaranteed item + gold orbs +
+  a loot table roll on open.
+- ItemDrop: dropped items render with a rarity glow.
+
+## Perks (level-up progression)
+
+PerkData: id, name, description (supports a `{value}` token), max_level 3,
+`stat_modifiers: Dictionary`, `special_effect: String` + effect_value for
+non-stat perks. Built-in pool:
+
+| ID | Effect per level |
+|----|------|
+| attack_up | +3 attack |
+| speed_boost | +20 speed |
+| thick_skin | +2 defense |
+| vampirism | 3% lifesteal |
+| burning_strikes | apply burn on hit |
+| frost_touch | 30% slow on hit |
+| critical_eye | +5% crit |
+| multishot | +1 projectile |
+| thorns | 20% reflect |
+| regeneration | 1 HP/sec |
+| xp_boost | +25% XP |
+| last_stand | +50% damage below 30% HP |
+
+PerkPool: `roll_selection(3)` (unowned or upgradable only),
+`acquire_perk()`, `get_stat_bonus("attack")`, `has_effect("lifesteal")` +
+`get_effect_value()`, `reset()` per run.
+
+Level-up flow: `stats.add_xp()` true -> emit `player_leveled_up` then
+`level_up_ready` -> PerkSelectionUI shows 3 cards (LEVEL_UP state pauses
+tree) -> pick emits `perk_selected` -> player acquires and applies stat
+modifiers via `stats.add_modifier` -> resume. Special effects (lifesteal,
+thorns, multishot) are checked at their point of use via
+`pool.has_effect()`, not applied as stats.
+
+## Status effects
+
+StatusEffect base (Node): effect_id, duration 3s, tick_interval 1s,
+max_stacks 3. Override `tick()`, `on_expire()`, `on_max_stacks()`,
+`get_speed_multiplier()`. `add_stack()` refreshes duration.
+
+EffectManager attaches to any entity: `apply_effect(BurnEffect, entity)`
+handles stacking, `get_speed_multiplier()` returns the product of all active
+effects (feed it into movement), `remove_effect/remove_all`.
+
+Built-ins and their max-stack payoffs (the interesting design bit -
+stacking to cap triggers a burst):
+
+- Burn: 3 dmg per 0.5s, 5 stacks; at cap, a 15x damage burst.
+- Freeze: 30% slow per stack, 3 stacks; at cap, full 2s stun.
+- Poison: 2 dmg/s, 3 stacks; each new stack extends duration 2s; supports
+  lifesteal back to the source.
+
+## Juice quick reference
+
+```gdscript
+Juice.shake(4.0)                          # camera shake
+Juice.hitstop(0.05)                       # freeze frame on big hits
+Juice.flash_node(enemy, Color.WHITE, 0.1)
+Juice.spawn_float_text(node, "+50 XP", Color.GOLD)
+Juice.spawn_hit_particles(pos, Color.RED, 6)
+Juice.bounce(node, 1.2)                   # scale bounce
+Juice.register_camera(camera)             # once, from player _ready()
+```
+
+If `register_camera` is never called, shake silently does nothing - a
+classic "why is there no juice" bug.
+
+## HUD and notifications
+
+HUD subscribes to EventBus only: health/energy/XP bars, level, gold, active
+quest list, and a notification label (fade in, 2s hold, fade out) driven by
+`EventBus.notification_requested.emit("Quest complete!", Color.GOLD)`.
+HUD also owns pause and inventory toggles.
+
+## Audio
+
+AudioManager: `play_music(path)` crossfades (pass false for hard cut),
+`play_sfx(stream, pitch_variation)`, `play_sfx_at(stream, pos, variation)`
+positional. Auto-creates Music and SFX buses if missing. Town theme in the
+hub, battle music in combat areas, switch on `scene_ready`.
+
+## Save/load
+
+GameManager saves to `user://savegame.cfg` (ConfigFile): current level path
++ spawn position, player stats (level, XP, health, attack, defense),
+inventory + equipment as resource paths, gold, quest state (active with
+progress, completed ids). `save_game()` from the pause menu,
+`load_game() -> bool` from Continue, `has_save()` gates the button.
+`restart_game()` clears inventory, resets perks, returns to town.
+
+Save items by resource path, not serialized objects - paths survive schema
+changes; serialized Resources do not.
+
+## Order of content work
+
+1. Enemy roster (CHASE first, then RANGED; TANK/SWARM/BOSS after combat
+   feels right) + spawner in the forest level.
+2. Loot orbs + level-up perks (progression pull).
+3. One NPC with dialogue in town, one kill quest wired through the level.
+4. Inventory + a treasure chest + equipment stat bonuses.
+5. Status effects on weapons/perks (burning_strikes, frost_touch).
+6. Boss + dungeon kill gate, then save/load last - it serializes everything
+   above, so build it when the shapes are stable.

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

@@ -0,0 +1,241 @@
+# 2D Action RPG - Core
+
+Top-down action RPG blueprint: event-driven architecture, player controller,
+stats pipeline, combat components, weapons, and area transitions. NPCs,
+dialogue, quests, inventory, perks, status effects, and enemies live in
+`2d-rpg-content.md`.
+
+## Minimum playable base (build this first)
+
+One level extending LevelBase: player with 8-way movement + one sword swing +
+dodge roll, a couple of chase enemies with `take_hit()`, HUD health bar. Prove
+"move, hit enemy, get hit, see numbers" before any dialogue or quest exists.
+
+Two rules for every scene:
+
+- Dynamic viewport: `display/window/stretch/mode = "canvas_items"`,
+  `stretch/aspect = "expand"`. UI via Control anchors; compute spawn points and
+  bounds from `get_viewport_rect().size`, never hardcoded 1920x1080.
+- Playable slice: every input gets feedback through the Juice autoload (shake,
+  flash, float text, hitstop). A silent build fails even if every system works.
+
+## Architecture: modules + EventBus
+
+Systems NEVER reference each other directly. All cross-system communication
+flows through EventBus, a global signal bus autoload. Each module can be added
+or removed without breaking others.
+
+```
+core/
+  autoloads/{event_bus,game_manager}.gd
+  levels/level_base.gd
+  player/{player.gd,player.tscn}
+modules/
+  audio/audio_manager.gd
+  combat/{hitbox_component,hurtbox_component,knockback_component,
+          stats,modified_value}.gd
+  dialogue/{dialogue_box,dialogue_data,npc}.gd
+  enemies/{enemy_base,enemy_data,enemy_database,enemy_spawner}.gd
+  effects/{status_effect,effect_manager,burn_effect,freeze_effect,poison_effect}.gd
+  inventory/{inventory_manager,inventory_ui,item_data}.gd
+  juice/juice.gd
+  loot/{area_transition,item_drop,loot_table,pickup_orb,treasure_chest}.gd
+  progression/{perk_data,perk_database,perk_pool,perk_selection_ui}.gd
+  quests/{quest_data,quest_manager}.gd
+  weapons/{weapon_base,weapon_data,weapon_manager,projectile}.gd
+  weapons/weapons/{sword,bow,staff,orb}.gd
+content/levels/{town,forest,dungeon}.gd
+ui/{hud/hud.gd, menus/{main_menu,pause_menu,game_over}.gd}
+```
+
+Six autoloads, in this order: EventBus, GameManager, AudioManager,
+QuestManager, Juice, InventoryManager.
+
+### EventBus signal groups (define up front)
+
+Player: `player_health_changed`, `player_energy_changed`, `player_died`,
+`player_leveled_up`, `player_xp_gained`. Combat: `damage_dealt`,
+`enemy_killed(enemy, xp_value)`, `player_attack_executed`. Interaction:
+`interaction_available/unavailable`, `dialogue_started/ended`. Inventory:
+`item_picked_up/used/equipped/unequipped`, `gold_changed`. Quests:
+`quest_started/updated/completed`, `quest_objective_progressed`. Progression:
+`level_up_ready`, `perk_selected`, `perk_applied`. Scene:
+`scene_transition_started/completed`, `scene_ready`. Spawner:
+`wave_started/cleared`. UI: `notification_requested(text, color)`,
+`boss_health_changed`.
+
+## Physics layers and input
+
+| Layer | Name |
+|-------|------|
+| 1 | terrain |
+| 2 | player |
+| 3 | enemies |
+| 4 | player_hitbox |
+| 5 | enemy_hitbox |
+| 6 | interactions |
+| 7 | pickups |
+
+Hitbox on 4/5, hurtbox monitors the opposite side's layer.
+
+Input map (9 actions): move_up/down/left/right (WASD + arrows + stick), attack
+(LMB/Space), dodge (RMB/Shift), interact (E), pause (Esc), inventory (I).
+
+## GameManager: states and transitions
+
+```gdscript
+enum GameState { MAIN_MENU, PLAYING, PAUSED, DIALOGUE, INVENTORY, LEVEL_UP, GAME_OVER }
+```
+
+Everything except MAIN_MENU/PLAYING pauses the tree; `change_state()` handles
+pause/unpause. Gate gameplay input on `GameManager.is_gameplay_active()`.
+
+Scene transition flow (fade overlay owned by GameManager):
+`transition_to_scene(path, spawn_point, spawn_direction)` -> fade to black
+0.3s -> emit `scene_transition_started` -> `change_scene_to_file` -> wait TWO
+process frames -> emit `scene_ready`, state PLAYING -> fade in -> emit
+`scene_transition_completed`. The player reads
+`GameManager.player_spawn_point` / `player_spawn_direction` in `_ready()`.
+Guard with an `_is_transitioning` flag; never call transition from inside a
+transition callback.
+
+Area transitions are trivial once this exists - an Area2D with three exports
+(`target_scene`, `spawn_point`, `spawn_direction`) whose `body_entered` calls
+`GameManager.transition_to_scene()`. Place at map edges and doorways.
+
+## Player controller
+
+```
+Player (CharacterBody2D, layer 2, group "player")
+  CollisionShape2D (circle, radius 8)
+  WeaponManager (Node2D)
+  HurtboxComponent (Area2D)
+    CollisionShape2D (circle, radius 10)
+  InteractionArea (Area2D)
+    CollisionShape2D (circle, radius 30)
+  Camera2D
+```
+
+State machine: `IDLE, MOVE, ATTACK, DODGE, HURT, DEAD, INTERACT`.
+
+```gdscript
+var input := Input.get_vector("move_left", "move_right", "move_up", "move_down")
+if input.length() > 0.1:
+	facing = input.normalized()
+	velocity = facing * stats.get_speed()
+	state = State.MOVE
+else:
+	velocity = velocity.move_toward(Vector2.ZERO, stats.get_speed() * 10.0 * delta)
+	state = State.IDLE
+move_and_slide()
+```
+
+- Attack: manual aims at mouse direction; optional auto_attack targets the
+  nearest enemy within 250px. Delegate to
+  `weapon_manager.attack(direction)` gated by `can_attack()`.
+- Dodge roll: costs 20 energy (`stats.use_energy` returns false if broke),
+  0.25s duration, invincible for the duration, fading trail rects.
+- Hurt: ignore if invincible/dead/dodging. `stats.take_damage`, 0.5s i-frames,
+  knockback velocity, `Juice.shake(5)`, red flash, float text, emit
+  `player_health_changed`.
+
+## Stats: the ModifiedValue pipeline
+
+`final = (base + additive_sum) * (1.0 + multiplicative_sum)`. Modifiers are
+tagged with a source string so a whole buff can be removed in one call:
+
+```gdscript
+stats.add_modifier("attack", 5, "fire_buff")
+stats.remove_modifier("attack", "fire_buff")
+```
+
+Stats resource: base_max_health 100, base_attack 10, base_defense 5,
+base_speed 120, base_crit_chance 0.05, base_crit_multiplier 1.5. Key methods:
+`take_damage()` returns `{damage, killed}`, `calculate_damage(is_crit)`,
+`roll_crit()`, `add_xp()` returns true on level-up, `use_energy()`.
+
+MUST call `stats.initialize()` in `_ready()` - forgetting it leaves the
+pipeline null and everything crashes on first hit.
+
+Level-up: +10 max HP, +2 attack, +1 defense, +3 speed, full heal.
+XP needed = `50 + level * 30`.
+
+## Combat components (reusable trio)
+
+- HitboxComponent (Area2D): the damage dealer. `damage`, `knockback_force`,
+  `hit_cooldown` (per-target cooldown dictionary), `try_hit(target) -> bool`,
+  `activate()/deactivate()` (deactivate clears cooldowns). Emits
+  `hit_landed(target, damage, knockback)`.
+- HurtboxComponent (Area2D): the receiver. `invincibility_duration` 0.3s,
+  emits `damage_received(amount, source, knockback)` via
+  `take_hit(damage, source, knockback)`.
+- KnockbackComponent (Node on any CharacterBody2D): decaying velocity,
+  `resistance` 0-1, `decay_rate` 8. `apply_knockback(force)` then add
+  `get_knockback_velocity()` to movement.
+
+Attach these to player, enemies, chests - anything hittable. This trio is
+what keeps combat code out of entity scripts.
+
+## Weapon system (data-driven)
+
+WeaponData resource carries everything: type string, base_damage,
+attack_speed (attacks/sec), knockback, range, piercing, projectile
+speed/count/fan_angle, area_radius, orbit_count/speed, color. WeaponManager
+(child of player) equips, switches (1-4 keys / scroll), and delegates attacks;
+a `WEAPON_SCRIPTS` const maps type string -> preloaded script.
+
+Four archetypes:
+
+- Sword: 120-degree arc swing, alternating direction, ease-out for weight,
+  forward lunge, physics cone query, trail.
+- Bow: 0.15s draw, then a fan of projectiles (count + fan_angle from data).
+- Staff: homing bolts (homing_strength 3.0) + optional `trigger_nova()` AoE.
+- Orb: passive - orbits the player, contact damage with per-enemy cooldown,
+  always active regardless of selected weapon.
+
+One generic projectile script serves bow, staff, AND enemies: straight or
+homing, piercing (tracks hit bodies to prevent double-hit), knockback, trail,
+lifetime despawn. Configure per-shot via properties + `collision_mask` and a
+`source_node` so it never hits its shooter.
+
+## LevelBase and level authoring
+
+All levels extend LevelBase, which does the boring wiring once:
+
+```gdscript
+func _ready() -> void:
+	_spawn_player()      # instantiate player.tscn
+	_setup_ui()          # HUD, PauseMenu, DialogueBox, Inventory, GameOver, PerkSelectionUI
+	_setup_connections()
+```
+
+A concrete level sets `level_name`, calls `super._ready()`, then adds its
+spawner / NPCs / AreaTransitions. Town = safe hub with NPCs. Forest = combat
+area with wave spawner. Dungeon = boss arena with a kill gate.
+
+## Build order
+
+1. project.godot: 6 autoloads in order, input map, layer names, 1920x1080
+   canvas_items/expand.
+2. EventBus with the full signal catalog (empty handlers are fine).
+3. Stats + ModifiedValue, then the combat component trio.
+4. Player: movement -> dodge -> WeaponManager with sword only.
+5. One chase enemy + Juice feedback + HUD health bar. Playable slice check.
+6. GameManager transitions + LevelBase + a second area with AreaTransition.
+7. Content systems from `2d-rpg-content.md`: enemies, NPCs, quests,
+   inventory, perks, effects, save/load.
+
+## Traps
+
+- Direct module references. Never `get_node("/root/QuestManager")` from a
+  weapon script - emit an EventBus signal. Modules only know EventBus and
+  their own data types; anything else rots into circular dependencies.
+- Skipping `stats.initialize()`. Null pipeline, crash on first damage.
+- Huge `_ready()` chains needing other nodes. Await
+  `get_tree().process_frame` or connect to `EventBus.scene_ready` instead.
+- UI without `process_mode = ALWAYS`. Dialogue, inventory, level-up, and
+  pause all pause the tree; the UI must keep processing.
+- Wrong hitbox/hurtbox layers. Hitbox layer 4/5, hurtbox masks the OPPOSING
+  side. Getting this backwards silently produces no hits.
+- Renaming InteractionArea. NPC scripts access `$InteractionArea` by exact
+  name; a rename kills interaction with no error at parse time.

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.