summer-engine 3.0.0 → 3.2.0

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

@@ -0,0 +1,93 @@
+# 2D Platformer - Enemies, Hazards, Juice, Progression
+
+Add these only after the core loop (run/jump/goal/death) from `2d-platformer.md`
+feels good. Combat mechanics reuse the `combat-basics` skill.
+
+## Patrol enemy
+
+A `CharacterBody2D` that walks, turns at ledges/walls, and hurts on contact. Ledge
+detection via a downward `RayCast2D` at the front foot.
+
+```gdscript
+extends CharacterBody2D
+@export var speed: float = 60.0
+var dir: float = 1.0
+var gravity: float = ProjectSettings.get_setting("physics/2d/default_gravity")
+@onready var ledge: RayCast2D = $LedgeCheck   # points down, ahead of feet
+
+func _physics_process(delta: float) -> void:
+	if not is_on_floor():
+		velocity.y += gravity * delta
+	if is_on_wall() or (is_on_floor() and not ledge.is_colliding()):
+		dir *= -1.0
+		ledge.position.x *= -1.0
+		$Sprite2D.flip_h = dir < 0.0
+	velocity.x = dir * speed
+	move_and_slide()
+```
+
+Give it a hurtbox (masks PlayerHurtbox) and a Health node from `combat-basics`.
+
+## Stomp-to-kill
+
+The classic platformer verb. A separate Area2D under the player masking only the
+Enemies layer; on overlap, kill the enemy and bounce the player.
+
+```gdscript
+# in player, StompArea (Area2D) child
+func _on_stomp_body_entered(enemy: Node) -> void:
+	if velocity.y > 0.0 and enemy.has_method("die"):
+		enemy.die()
+		velocity.y = jump_velocity * 0.7   # bounce
+```
+
+Falling (`velocity.y > 0`) distinguishes a stomp from a side hit that should damage
+the player instead.
+
+## Hazards
+
+- Spikes/lava: an Area2D on the Triggers layer that calls `player.die()`.
+- Bounce pad: Area2D that sets `player.velocity.y = -launch_force` on enter.
+- Bottomless pit: one wide killzone under the level.
+
+## Juice (the difference between prototype and game)
+
+Route through a small helper so every hit feels alive:
+
+- Hit flash: `modulate` to white, tween back over 0.06s.
+- Screen shake: offset the Camera2D by decaying random noise for ~0.2s.
+- Hitstop: `Engine.time_scale = 0.05` for one frame on a kill, then back to 1.0.
+- Floating text: spawn a Label that rises and fades on coin/hit.
+- Squash/stretch: tween the sprite `scale` to (1.2, 0.8) on land, back over 0.1s.
+- Dust particles on land and on turn.
+
+A silent, still platformer fails the 30-second bar even if every system works.
+
+## Progression: coins, gems, and a level goal
+
+- Coins increment `GameManager.score`; emit `score_changed` for the HUD.
+- A `level_end` Area2D (flag/door) triggers the level-complete screen with time and
+  coin count, then advances to the next room `.tscn`.
+- Save unlocked rooms + best times via the `save-load` skill.
+
+## Metroidvania gating (optional)
+
+For an interconnected map with ability gates:
+
+- `AbilityManager` autoload: `unlocked: Dictionary`, `has(name)`, `unlock(name)`.
+- Ability pickup: Area2D that calls `AbilityManager.unlock("double_jump")`.
+- Ability gate: a wall/door that only opens if `AbilityManager.has("dash")`, or a
+  ledge only reachable with double jump.
+- The player controller checks `AbilityManager.has("double_jump")` before allowing
+  a second air jump, `has("dash")` before a dash, etc.
+
+Keep gating data-driven: one place lists what each ability unlocks, so designers
+tune it without touching the controller.
+
+## Traps
+
+- Enemies as RigidBody2D fight the player physically; use CharacterBody2D or Area2D.
+- Stomp check without a `velocity.y > 0` guard kills enemies on any touch.
+- Ledge raycast that does not flip with direction walks enemies off cliffs.
+- Piling on juice at once (shake + hitstop + flash on every coin) reads as noise;
+  reserve the big feedback for kills and damage, keep coins light.

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

@@ -0,0 +1,117 @@
+# 2D Platformer - Core
+
+Side-scrolling platformer blueprint: architecture, the level, and the core loop.
+Movement itself lives in the `character-movement` skill (base controller) and its
+`../../character-movement/references/platformer-feel.md` (coyote time, jump buffer, variable height) - do
+not rewrite it here; wire it in. For Celeste-grade precision movement (dash, wall
+jump, climb) use `celeste-momentum-platforming` instead.
+
+## Minimum playable base (build this first)
+
+Scene first (the make-game Scaffold phase): `main.tscn` with a Node2D root, a ground `StaticBody2D`
+with a `CollisionShape2D`, the player, and a `Camera2D` child of the player. Prove
+run + jump + land before anything else. Placeholder art is a colored
+`ColorRect`/`Sprite2D`.
+
+## Architecture (grows into a full game)
+
+```
+res://
+  scenes/
+    player/player.tscn
+    rooms/room_01.tscn        # one .tscn per room/level
+    enemies/patrol_enemy.tscn
+    ui/{hud,pause_menu,main_menu,game_over}.tscn
+  scripts/
+    autoloads/
+      event_bus.gd            # global signals, decouples systems
+      game_manager.gd         # score, lives, current room, checkpoint
+      audio_manager.gd        # pooled SFX + music
+      save_manager.gd
+    player/player_controller.gd
+    systems/{coin,checkpoint,killzone,moving_platform,one_way_platform,
+             crumbling_platform,bounce_pad,door,level_end}.gd
+```
+
+Add autoloads only once the base loop works. Register in Project Settings in
+dependency order: EventBus first (others reference it), then GameManager, then the
+rest. All autoloads `process_mode = ALWAYS` so they survive pause.
+
+## Collision layers (set names in Project Settings)
+
+| Layer | Name | Used by |
+|-------|------|---------|
+| 1 | World | TileMap, static platforms |
+| 2 | Player | Player body |
+| 3 | Enemies | Enemy bodies |
+| 4 | PlayerHitbox | Sword/stomp hit area |
+| 5 | EnemyHitbox | Enemy hit area |
+| 6 | PlayerHurtbox | Player hurt area |
+| 7 | EnemyHurtbox | Enemy hurt area |
+| 8 | Collectibles | Coins, gems |
+| 9 | Triggers | Doors, killzones, checkpoints |
+
+Hitboxes mask the OPPOSING hurtbox (see the `combat-basics` skill). The stomp detector is a
+separate Area under the player masking only the Enemies layer.
+
+## Building the level with a TileMap
+
+Use a `TileMapLayer` (Godot 4.3+) for the solid world. Create a `TileSet`, paint
+the collision polygon on the solid tiles, put the layer on the World collision
+layer. The player collides with it for free - no per-tile StaticBody.
+
+- One `TileMapLayer` for collidable terrain, a second (no collision, lower
+  z-index) for background decoration.
+- For large levels, split into room `.tscn`s and load the current room via a
+  RoomManager; connect doors to `change_scene_to_file` or swap room instances.
+- Parallax background: `Parallax2D` (or ParallaxBackground) layers with
+  `motion_scale` < 1 so distant layers move slower.
+
+## Moving, one-way, and crumbling platforms
+
+These three cover most platformer level tech.
+
+```gdscript
+# moving_platform.gd - AnimatableBody2D so riders move with it
+extends AnimatableBody2D
+@export var offset: Vector2 = Vector2(200, 0)
+@export var duration: float = 2.0
+func _ready() -> void:
+	var t := create_tween().set_loops().set_trans(Tween.TRANS_SINE)
+	t.tween_property(self, "position", position + offset, duration)
+	t.tween_property(self, "position", position, duration)
+```
+
+Use `AnimatableBody2D` (not StaticBody2D) for movers - it carries the player. For
+one-way platforms, enable `one_way_collision` on the platform's CollisionShape2D
+so the player jumps up through and lands on top. Crumbling platform: on
+`body_entered`, start a short timer, shake, then disable collision and fade out;
+re-enable after a respawn delay.
+
+## Checkpoints and death
+
+```gdscript
+# checkpoint.gd
+extends Area2D
+func _ready() -> void:
+	body_entered.connect(func(b):
+		if b.is_in_group("player"):
+			GameManager.checkpoint = global_position)
+
+# killzone.gd - fall/spike death
+extends Area2D
+func _ready() -> void:
+	body_entered.connect(func(b):
+		if b.is_in_group("player"):
+			b.die())   # player respawns at GameManager.checkpoint
+```
+
+## Core loop checklist (the 30-second bar)
+
+- Run + jump feels good (tuned gravity/fall multiplier, coyote + buffer).
+- Coins/goal give immediate feedback: sound + pop tween + counter tick.
+- Death is instant and respawns at the last checkpoint, no long reload.
+- A visible goal (flag/door) ends the level with a clear result.
+
+Enemies, hazards, juice, and metroidvania progression are in
+`2d-platformer-polish.md`.

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.