feat: firemaking skill implemented. overhauled how ground items and despawn are handled.

1 files changed, 40 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 5de818b..624034b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -90,6 +90,46 @@ Same as gathering but use `type: use` behavior (see `UseConfig` in `internal/act
 2. Add a case in `handleGameCommand()` in `internal/game/game.go`
 3. Update `data/help/` YAML files
 
+## Firemaking (`burn` / `stoke`)
+
+Firemaking is implemented as standalone actions (not behavior-YAML-driven) in `internal/game/action_burn.go`. The flow:
+
+| Command | Action | Description |
+|---------|--------|-------------|
+| `burn [item]` | `"burn"` | Start a fire from logs. Checks ground items first, then inventory. Requires a `tool_type: fire` item. |
+| `stoke [item]` | `"stoke"` | Add logs from inventory to an existing fire object for XP. No tool required. |
+
+**Burn flow (3 phases):**
+- Phase 0 (inventory only): Drops 1 log to ground, outputs "You drop the X and begin to make a fire..."
+- Phase 1: "You try burning the X on the ground..." (waits tool_speed ticks)
+- Phase 2: Skill check (firemaking level vs log's `fire_level`). On fail, outputs "You can't seem to get a fire going" and retries at Phase 1. On success, creates a `fire` object (`quality` = log's `burn_ticks`), gives XP, broadcasts to room.
+
+**Stoke flow:**
+- One-time "You begin to tend to the fire."
+- Loops: waits 10 ticks → "You throw X onto the fire", gives XP, adds `burn_ticks/2` to fire `quality`
+- Ends when out of the item: "You're out of X and the fire is roaring."
+
+**Fire objects:**
+- Created dynamically via `World.AddObjInstance()`, tracked by `ObjState.Quality`.
+- Each tick, `FireTick()` decrements quality; at 0, `RemoveObjInstance()` cleans up.
+- `inroom_description` on object YAML replaces the generic "A X is here."
+- `props.quality_description` (with `{quality}` placeholder) is used by `look <fire>`.
+
+**Item fields for firemaking:**
+- `burn_ticks: <int>` — how long the log burns (fire quality). Only items with `burn_ticks > 0` are burnable.
+- `fire_level: <int>` — required firemaking level to burn.
+- `fire_xp: <int>` — XP awarded.
+- `quality: <int>` / `max_quality: <int>` — for tools like lighter (start value / max value).
+- `EquipQuality map[string]int` on Player tracks quality of equipped items with quality.
+
+**Fire tools:** `matches` (stackable, consumed on use), `firesteel` (non-consumable), `lighter` (quality-based, `MaxQuality: 100`, decreases per use).
+
+**Smart defaults:** `burn` auto-selects if only one burnable type on ground OR in inventory. `stoke` auto-selects if only one burnable type in inventory.
+
+**Level-up messages:** All skills that gain XP (gathering, combat, use, firemaking) output `*** You are now level N <skill>! ***` when the player levels up.
+
+**Stoke error messages:** "There's no fire here to stoke" (no fire), "You have no logs to stoke with!" (no burnable items), "Stoke what?" (ambiguous). Fire going out mid-stoke interrupts immediately with "The fire went out!".
+
 ## Two Depletion Mechanics
 
 **Per-drop depletion** (mining, regular trees): Set `depletes: true` on a drop entry. The resource depletes on first successful gather of that drop. Rocks don't show despawn timers when not depleted.