Emberwild/docs/PROGRESSION_DESIGN.md

# Progression and challenges design

Status: **P1-P6 built** (iron, stone, adversaries, hazards, the Old Stag,
and uses for every material).

*As built in P6 (0.3.0, every material earns its place):*
- Clay jar (8 clay, fired at a campfire): 6 slots, food inside ages at a
  third of the rate (`Inventory.keep_mult`, which moves the "rot" stamps).
- Bedroll (3 hide, 6 feathers, 4 fibre): a bed (group "bed", like the bed
  everywhere a spawn bed is looked for) that needs no shelter, only no rain
  or snow on it.
- Wolf-pelt rug (3 wolf pelts): a rug, so Cozy like the fur rug.
- Fang necklace (2 fangs, 1 alpha pelt): a "charm" carried anywhere in the
  bag; hits whose cause names a wolf do 70% (`Actions.charm_mult`).
- Bear cloak (2 bear hide, 2 hide): +40 warmth, the warmest.
- Pemmican (2 cooked meat, 3 berries, 1 bear fat at a campfire, makes 3):
  meat and greens, keeps 30 days.
- Rotten food is fishing bait: carried, bite waits x0.6, a bite uses one.
- Lights to place (after 0.3.0): tallow candle (bear fat and fibre, makes 4,
  7 m) and torch stand (11 m, shadows), always lit (`lamp.gd`).
- `Q` drops what you hold (shift: one), at your feet, online too; `K`/`M`
  move the hotbar up and down the bag's five rows (any slot can be held).
- `tests/test_items_more.gd` checks every material has a use.

*As built in P1:*
- Iron nuggets (70, in the scree under the rim), clay (60, on the lake
  shore) and rusty boulders (about a quarter of the boulders, mostly near
  the rim; iron ore when mined) are on every island, old worlds included.
- Charcoal kiln (2 wood -> 1 charcoal, 20 s), smelter (1 ore or 3 nuggets +
  1 charcoal -> 1 bar, 30 s) and forge. Kiln and smelter open like chests
  and work on their own (also through a slept night and on a server).
- At the forge: iron axe and pickaxe (twice as fast), iron spear, iron
  arrows (x1.5 damage, the bow uses them first), nails, lantern.
- **Durability** (decided: yes): stone tools 60 uses, club 80, wooden spear
  50, bow 100, rod 80, iron tools 200 (iron spear 180). A bar on the slot;
  a warning near the end; it breaks at 0. Repair in the crafting panel's
  Repair tab: stone and wood at a workbench (a flint, wood or fibre), iron
  at the forge (an iron bar). Wear stays with the item in chests, graves,
  on the ground (a thrown spear) and in saves.
- Not yet: the cooking pot and stews, the iron-banded door (with P3, when
  something can break doors), iron armour.

*As built in P2:*
- Stonecutter (workbench: 8 wood, 4 iron, 10 stone) cuts 2 stone into a
  block of cut stone. No granite outcrops yet: the stonecutter is the only
  source.
- At the stonecutter: stone floor (4), wall (6), pillar (3), stairs (4),
  window (5), doorway with a wooden door (6 + 4 wood), hearth (10).
- At the workbench: wooden stairs, window and palisade (with nails), a
  wooden post, a palisade gate.
- Support: stone loses 5% going up (wood 10%); wood can't hold stone up
  ("Stone needs stone or the ground under it"); through a pillar any step
  up or down counts as vertical, so a post under a span carries it.
- Hearth: a campfire (fuel, cooking, wolves) with 1.5x the heat radius that
  rain never speeds up. A sheltered room with mostly stone walls is 6
  warmer. Shelter rays now run 0.6 m up, under window sills, so a room with
  windows still counts.
- Palisade: 3 m tall, blocks like a wall online too. No fences.

*As built in P3 so far (the alpha):*
- Wolf moon: nights 7, 14, 21... (worked out from the day, so every game on
  a server agrees). The moon turns red and a toast warns you.
- The alpha (135 HP, bites for 16) comes out of the den with the pack and
  leaves at dawn. It isn't afraid of fire and never runs. If it can't reach
  you it batters the nearest shut door near you: a wooden door (or the
  wooden leaf in a stone doorway or palisade gate) gives way after about
  five blows and hangs broken until mended (E, 2 wood); then it comes in.
- Iron-banded door (forge: 2 iron, 4 wood, 4 nails) can't be broken.
- Drops: alpha pelt, 1-2 fangs, meat. Alpha cloak (+35 warmth) at the
  workbench. Network protocol 7.

*As built in P3 so far (the bear):*
- One bear per island (220 HP, hits for 24, runs at 7 m/s: slower than you
  sprinting). Home is the densest forest near the rim, at least 60 m from
  the spawn and the den, picked from the seed. It sleeps there at night.
- From day 3, by day, it sniffs out food within 60 m: a chest with food in
  it or food left on the ground, with nobody within 12 m. It walks over,
  eats all the food (nothing else) and wanders off. Food it can't walk to
  is safe: fenced in = all 32 level rays from it hit building pieces (a
  palisade ring, a closed hut; an open door lets it in). It breaks nothing.
- Closer than 8 m it rears up and warns you; stay within 6 m and it
  charges. Hit it and it charges; under a quarter health it runs.
- Killed, it comes back 3 days later at dawn, when nobody's near its home.
  Its death (and a wounded bear's health) is saved with the world.
- Drops: bear hide, 2-3 fat (fire fuel, three times wood), 5-7 meat. Fur
  rug (bear hide, 2 fibre): in a sheltered room, Cozy: +4 warmth and
  Rested twice as fast. Network protocol 8.

*As built in P3 (crows and foxes):*
- Food left on the ground with nobody within 10 m for 20 s draws a thief
  from 35 m away (at most 3 at once): a crow by day, a fox from 17:30 to
  06:30. Food in a chest is never touched by them.
- A crow flies in, lands and eats one every 3 s; anyone within 7 m and it
  takes off. Shot down: 1-2 feathers.
- A fox slinks up and runs off with the whole stack; come within 10 m
  while it's creeping in and it bolts empty-handed. Kill it while it's
  carrying and it drops the food; let it get 45 m from everyone and it's
  gone. Raw meat and a hide.

*As built in P3 (the barrow):*
- One per island, on open ground (55 m+ from the spawn, 70 m+ from the
  den; looser on lumpy islands): a grass mound you can walk over, a stone
  passage into a 4 x 4 m chamber with a coffin, ringed by standing stones.
- Three guards (80 HP, hit for 20, move at 3.4 m/s: slower than you walk)
  stand at their posts. They wake when someone is inside the stone ring at
  night or any time after day 10, when the coffin is opened, or when one
  is hit. Fire and torches don't bother them. Beyond 22 m from the barrow
  they give up and walk back to their posts.
- The club is blunt: +50% on bone. Guards drop a little iron.
- The coffin: 1-3 iron bars, 3-6 nuggets and a barrow key piece (three
  open the standing stones, P5). It fills again 5 days after it was
  emptied, at dawn with nobody about, and the fallen guards are back.
  Emptied coffin and fallen guards are saved. Network protocol 10.
- Not yet: iron scrap (bars and nuggets instead); the standing stones and
  the Old Stag (P5).

*As built in P4 (hazards):*
- Spoilage: food carries a "rots at" world time on its stack (stamped when
  it first goes into a bag or chest; merged stacks average it), so it rots
  in bags, chests, graves, racks and on the ground, and through sleep and
  saves. Raw meat and fish 2 days, berries 3, mushrooms and cooked food 4,
  roasted mushrooms 6, smoked 12, salted 20. Rotten food is junk; food
  rotting on the ground just goes. A bar on the slot runs green to brown;
  the tooltip says Fresh / Going off / Nearly rotten, with hours left.
- Rot speed: normal, slow (half) or off. Chosen on the New World page
  (meta.json "rot"); on a server, "rot" in server.json or /set rot.
- Smoking rack (by hand: 6 sticks, 4 wood, 4 fibre): 2 raw meat + a wood,
  or 2 perch (or 1 trout) + a wood, make 2 smoked, a minute a batch.
- Salt: 40 crusts on the cliff tops above the sea. 2 raw meat (or 2 perch,
  or 1 trout) + a salt: 2 salted, by hand.
- Food poisoning: raw meat 35%, raw fish 20%. A minute of half-speed
  stamina and no eating. Cooked, smoked and salted food are safe.
- Blizzards: fog x7; out in one, an extra 18 warmth lost on top of the
  cold, and you cool twice as fast. A hard-winter blizzard freezes you by
  day without a coat; a hide cloak keeps you out of Freezing; a hearth room
  stays Warm. Snow piles on roofs (a look only).
- Hard winters: days 12-14, 24-26, ... (every 12 days): always cold, 8
  colder than a cold day, snowier, half the animals, the lake's edge frozen
  (walkable ice, no fishing through it). Warned the day before.
- Lightning (decided: trees only): in a storm, a strike every 50-110 s on a
  tree within 90 m of someone, the taller and nearer the rim the likelier.
  It burns 40 s (you can warm yourself by it), falls, and leaves 2 charcoal.
- Network protocol 11.

*As built in P5 (the Old Stag):*
- The standing stones: 7 tall stones in a ring at the foot of the rim with
  an altar in the middle (from the seed; 60 m+ from the spawn and den, 50 m+
  from the barrow, 42 m+ from the bear's home). E on the altar sets barrow
  key pieces in its three hollows; with all three in, at night, it calls
  the Old Stag.
- The Old Stag: 900 health, 3.8 m at the shoulder. It circles, lowers its
  antlers (1.2 s warning), and charges in a straight line through where
  you were: 30 if it catches you, nothing if you step aside. Then it's
  stunned for 2.5 s, when hits do half as much again. Below 2/3 it calls 3
  spirit wolves; below 1/3 2 more, quicker warnings (0.8 s), a 1.5 s stun,
  and a stamp (15 to anyone within 5.5 m, every 4 s). No fear of fire.
- It goes back into the mist at dawn, or 5 s after everyone's left the
  stones or died: the key pieces stay in the altar for another night.
- Beaten: its antler and a trophy (a placeable stand) where it fell, the
  key pieces used up, and the world remembers (day and, on a server, who;
  everyone's told). Three new key pieces call it again.
- In a group (on a server): anyone can set key pieces in the altar. It has
  60% more health for each extra living player within 45 m when it's
  called (900 alone, 1980 for three), and calls one more wolf each time for
  each extra player (up to 4 more). It remembers everyone whose blow,
  arrow or spear hit it; when it falls, all of them are named ("Beaten by
  Alice, Bob and Cara on day 2") and saved. The antler and trophy go to
  whoever picks them up first (tests/test_net_boss.gd: three players).
- Antler pickaxe (forge: the antler, an iron bar, 2 wood): tier 3, 3.0 a hit
  (iron 2.0), 250 uses (iron 200), 4 stamina a swing (iron 6).
- Network protocol 12; creature health now goes over the wire in tenths
  (up to 6553), so the stag's 900 fits.

Today the island runs out of goals after a few days: once you have stone
tools, a hut, a bow and a fire, the only threats are wolves at night, the
cold and your diet. This plan adds a **second tier of materials** (iron and
cut stone) that makes you go somewhere risky to get them, and **new
adversaries and hazards** that grow over the days, so there's always a next
thing to build toward and a reason to.

All content stays procedural or CC0, data-driven (`data/items.json`,
`data/recipes.json`, new `data/creatures.json`), and runs through Actions,
so it works on a server the same way everything else does after M2.4/M2.5.

## 1. The progression in one picture
```
 stone tools ──> find iron (nuggets, rust-streaked boulders, the barrow)
      │                    │
      │           clay + stone ──> charcoal kiln, smelter
      │                    │        (ore + charcoal -> iron bar, takes time and fuel)
      │                    v
      │                  forge ──> iron axe / pickaxe / spear / arrows,
      │                    │        nails, hinges, lantern, cooking pot
      │                    v
      └──────────> stonecutter (needs iron) ──> stone walls, floors,
                                                 pillars, stairs, hearth
```
Each step needs something from a harder, more dangerous part of the island,
so progression and challenge pull on each other.

## 2. Iron
**Where it comes from:**
- **Iron nuggets**: small ground pickups in the scree at the foot of the
  mountain rim and in stream beds. A handful per day; enough for your first
  bars, not for a base. (Regrow slowly, like flint.)
- **Rust-streaked boulders**: a new resource node, red-brown streaks in the
  rock, mostly high on the rim slopes and around the wolf den. Needs a stone
  pickaxe; gives stone plus 2-4 iron ore. These are the main supply.
- **The barrow** (§4): iron scrap and a few ready bars inside, guarded.

**Clay** (new): lumps on the lake shore and in the shallows, picked by hand.

**Processing** (all new pieces, placed like a campfire, state on the server):
| Piece | Recipe | Does |
|---|---|---|
| Charcoal kiln | 10 stone, 6 clay | wood in, charcoal out (1 per 2 wood, 30 s each) |
| Smelter | 15 stone, 10 clay, 2 iron nuggets | iron ore or 3 nuggets + 1 charcoal -> 1 iron bar (45 s); burns charcoal, goes out in heavy rain without a roof |
| Forge (anvil + hearth) | 6 iron bars, 10 stone, 4 wood | the station for iron recipes |

Smelting **takes real time** and the smelter keeps working while you're
away (like a campfire burning), so you load it, go and do something else,
and come back. On a server everyone can see the glow and use it.

**What iron makes** (at the forge):
| Item | Recipe | Why you want it |
|---|---|---|
| Iron Axe | 2 iron, 2 wood | tier 2: fells trees in half the hits, better weapon (14) |
| Iron Pickaxe | 3 iron, 2 wood | tier 2: mines rust boulders fast, and **granite** outcrops (cut stone) |
| Iron Spear | 2 iron, 3 wood | 26 damage, 40 thrown |
| Iron Arrows x10 | 1 iron, 4 sticks, 4 feathers | +50% damage |
| Nails x10 | 1 iron | building upgrades (below) |
| Iron Lantern | 2 iron, 1 resin | hands-free light you hang on a wall or carry; wolves hesitate like a torch, rain doesn't put it out |
| Cooking Pot | 3 iron | placed over a fire: **stews** that count for two diet groups at once (e.g. meat + greens), so a balanced diet is easier once you've earned it |
| Iron-banded Door | 2 iron, 4 wood, nails | strong door (wolves, later raiders, can't break it) |
| Iron armour (later) | bars + hide | damage reduction; heavy, slows stamina regen |

**Tool durability** (new, recommended): tools and weapons wear with use and
break (stone ~60 uses, iron ~200). Repair at a workbench (stone) or forge
(iron) for a little material. This is what makes iron worth getting rather
than a nice-to-have, and keeps you coming back to the forge.

## 3. Stone building
**Cut stone** comes from granite outcrops (iron pickaxe) or from cutting
ordinary stone at a **stonecutter** (8 wood, 4 iron, 10 stone).

New pieces (same 2 m grid, snap with the wood ones):
| Piece | Recipe | Notes |
|---|---|---|
| Stone floor | 4 cut stone | |
| Stone wall | 6 cut stone | |
| Stone pillar | 3 cut stone | carries load: resets support for what's on top |
| Stone stairs | 4 cut stone | first real stairs (also a wooden version) |
| Stone hearth | 10 cut stone | an indoor fire: heat in a radius 1.5x a campfire's, never rained out, cooks |
| Arch / doorway | 6 cut stone | takes a wood or iron door |

**Support rules:** stone that touches the ground has support 1 and loses
only 5% going up, so you can build tall stone towers and use **stone at the
bottom, wood on top** (Valheim style). Wood can't hold stone up: a stone
piece on a wooden one has no support. Stone pillars inside a wooden hall
let it span further. Interior walls and doors work as they do now.

**Why bother:** stone is sturdier (§4: things that break walls can't break
stone), it's warmer (a stone room counts as better shelter, a little extra
warmth), it doesn't burn (§5, lightning), and it lets you build big.

**Wooden upgrades** too, using nails: windows (light, still sheltered),
wooden stairs, fences and a **palisade wall + gate** (a ring round your base,
taller than a wolf can jump).

## 4. Adversaries
Each one is a different kind of problem, not just more HP.
| Adversary | Where / when | What it does | What beats it | Drops |
|---|---|---|---|---|
| **Wolves** (today) | nights from day 4 | pack circles, darts in | fire, torch, walls | pelt |
| **Alpha wolf** | every 7th night (the "wolf moon": the moon turns red, a big howl) | leads the pack, 3x HP, **breaks wooden doors** | iron door, stone walls, a fight with iron weapons | alpha pelt (warmest cloak), fang |
| **Bear** | daytime, deep forest near the rim; one per island | wanders, sniffs out food: **raids unattended chests with food and campfires with meat** | a palisade, stone storage, or a hard fight (spears, arrows from cover) | big hide (rugs, warm bedding: better rest), fat (resin/lantern fuel), lots of meat |
| **Barrow guards** | the **barrow**: an ancient burial mound with a stone ring, generated from the seed (like the den) | skeletal guards wake if you enter at night (or always after day 10); slow, hit hard, ignore torches | daylight raids, blunt weapons (club does +50% to bone) | iron scrap, a few iron bars, a **barrow key piece** (§6) |
| **Crows / foxes** | anytime, near food | steal berries and raw meat left on the ground or in open fires | a closed chest | — |

Creatures run on the server (needs M2.5's server-side creature framework),
so on a server everyone faces the same bear and the same alpha.

## 5. Hazards and pressure (not creatures)
- **Food spoilage**: raw meat and fish rot after 2 in-game days (berries
  3, mushrooms 4). A **smoking rack** (wood, fibre) and **salt** (from the
  sea-cliff rocks) preserve them. Cooked food keeps longer. Makes storing
  food a choice, and feeds the bear/crow raids. *Decided: a server (and a
  new single-player world) can set slower rot*, like the difficulty rules.
- **Food poisoning**: raw meat sometimes makes you sick (stamina regen
  halved, can't eat for a minute). Cooking fixes it.
- **Blizzards**: on cold days a blizzard can roll in: visibility drops,
  warmth falls fast outside, snow piles on roofs. Being sheltered matters.
- **Lightning**: in storms, lightning can strike tall things near the rim;
  a struck tree catches fire and burns for a while. *Decided: trees only,
  for now* (buildings are never struck; losing a base to weather can feel
  unfair). Wooden pieces burning may come later as a server rule.
- **Hard winters**: every ~12 days, three cold days in a row (snow down to
  the valley, the lake edge freezes, fewer animals). A seasonal goal: stock
  food and fuel before it.

## 6. Something to aim for: the Old Stag (optional boss)
Three **barrow key pieces** (from barrow chests) open the **standing
stones** on the rim. At night they summon the **Old Stag**, a huge antlered
spirit: charges, summons a wolf pack, has phases. Beating it drops its
antler: the **antler pickaxe** and a trophy. The world remembers it was
beaten (a message on a server). *Decided: the boss is in.* The antler
pickaxe mines faster than iron, lasts a little longer and costs less
stamina a swing (no granite: P2 didn't add it).

It's a milestone, not a gate: nothing is locked behind it except bragging
rights and the best pickaxe. More bosses can come with new worldlets.

## 7. Phases and tests
| Phase | Delivers | Done when |
|---|---|---|
| **P1 Iron** | nuggets, rust boulders, clay, charcoal kiln, smelter, forge, iron tools/weapons/arrows/nails/lantern/pot, durability and repair | a test smelts a bar from ore it mined and crafts an iron axe; the axe fells a tree in half the hits and wears out after ~200 uses |
| **P2 Stone** | stonecutter, granite, stone pieces, stairs, pillars, hearth, stone-on-wood rule, windows, palisade | a stone tower 10 m high stands; stone on wood refuses; a hearth keeps a stone room Sheltered and Warm in a blizzard |
| **P3 Adversaries** | alpha wolf + wolf moon, bear and food raids, crows/foxes, the barrow and its guards | the alpha breaks a wooden door but not an iron one; the bear empties an unguarded food chest and ignores one behind a palisade |
| **P4 Hazards** | spoilage and preserving, food poisoning, blizzards, hard winters, (lightning) | meat rots on schedule and keeps on the rack; a blizzard drops warmth outdoors and not in a hearth room |
| **P5 Boss** | key pieces, standing stones, the Old Stag | a scripted fight test reaches the end and drops the antler |

**Order:** P1 and P2 are items, recipes and pieces through Actions, so they
work online straight away and can come any time (before or after M2.5).
P3 and P5 are creatures, so they should come **after M2.5**, built directly
on the server-side creature code instead of being written twice. P4 can come
any time; spoilage on a server runs with the shared clock.

## 8. Decisions
1. **Durability:** tools wear out and are repaired (built in P1).
2. **Lightning and fire:** lightning strikes trees only, for now; it never
   sets buildings alight.
3. **Raids:** adversaries can damage and raid (the alpha breaks wooden
   doors, the bear empties food chests; built in P3).
4. **The boss:** yes, the Old Stag (P5).
5. **Order:** P1, P2, M2.5, P3 done; P4 next, then P5.
6. **Spoilage:** a server (or a new world) can set slower rot.
7. **Antler pickaxe:** mines faster than iron, lasts a little longer, less
   stamina a swing.