Emberwild/docs/SURVIVAL_DESIGN.md

# Survival game design

How the survival game plays and how it is built. The core idea: **the world is
beautiful but indifferent.** You arrive on the island with nothing and have to
work out how to stay fed, warm and dry, then turn that into a home.

## 1. Core loop

```
gather  ──►  craft  ──►  build / equip  ──►  survive the night & weather
  ▲                                                     │
  └──────────── hunt, explore, upgrade tools ◄──────────┘
```

A good first evening for a new player (the "first hour" we tune toward):
1. Pick up sticks, stones and flint from the ground. (Hands only.)
2. Craft a **stone axe** and a **stone pickaxe**.
3. Chop trees for wood, mine boulders for stone.
4. Build a **campfire** before dark. It's light, warmth and (later) cooking.
5. Build a **workbench**, then a **chest** to stash what you've gathered.
6. Rain rolls in at night: build a rough shelter so you can dry off by the fire.
7. Hunger bites: hunt a rabbit or deer, cook the meat on the fire.

## 2. Systems

### 2.1 Items (data-driven)
All items and recipes are **data** (`data/items.json`, `data/recipes.json`) in the
same shape the addon SDK uses (`define_item` / `define_recipe`, see
ADDON_SDK.md). An addon adding an item later uses the same path as the base game.

Item fields: `id`, `name`, `description`, `stack`, `category`
(`resource` | `tool` | `weapon` | `food` | `placeable`), plus optional blocks:
- `tool`: `{ "kind": "axe" | "pickaxe" | "hammer", "tier": 1, "damage": 1.0 }`
- `weapon`: `{ "damage": 10, "reach": 2.2, "stamina": 8 }`
- `food`: `{ "hunger": 30, "health": 5, "spoils_after": 600 }`
- `place`: `{ "piece": "campfire", "footprint": [1.4, 1.4] }`
- `fuel`: seconds of burn time in a fire

### 2.2 Inventory & storage
- Slot grid with stacks. The player has **40 slots**; the first row of 8 is the
  **hotbar** (keys 1-8 or the mouse wheel select the held item).
- Click to pick up a stack, click to drop or swap it, right-click to split,
  shift-click to quick-move between your inventory and an open chest.
- **Chests** (16 slots) are crafted at a workbench and placed in the world.
- One `Inventory` class backs the player, chests and later corpses, so moving
  items is the same operation everywhere.

### 2.3 Gathering
| Source | Needs | Gives |
|---|---|---|
| Sticks, stones, flint on the ground | hands (E) | 1 each |
| Trees (chop, falls over) | axe | wood, sticks |
| Boulders (mine, shrinks per hit) | pickaxe | stone, flint |
| Bushes *(M1b)* | hands | fiber, berries |
| Animals *(M1d)* | weapon | raw meat, hide, bone |

Tool **tiers** gate harder resources later (e.g. iron ore needs a tier-2
pickaxe). Felled trees leave stumps.

**Regrowth** *(built in M1c, `props.gd`)*: felled trees grow back after
2400 s (2 days), mined boulders after 3600 s, picked-up sticks/stones/flint/
mushrooms after 900 s. A timer waits (retries every 2 min) while you're
standing on the spot or something is built there. Timers are saved, and
sleeping advances them.

### 2.4 Crafting & stations
Recipes list inputs, an output and an optional **station** that must be within
6 m: none (hand), `workbench`, `campfire` (cooking), later `forge`. The crafting
panel shows every recipe you know, greyed out with the missing inputs in red.

### 2.5 Building
- **Placement mode**: holding a placeable shows a ghost preview (green = valid,
  red = blocked). R rotates it, left-click places it.
- M1a pieces: campfire, workbench, chest. M1c adds a bed.
- *(built in M1c)* Snap-together wood pieces, crafted at a workbench
  (shift-click Craft makes 5): floor (2 wood), wall (2), door (4), roof
  (2 wood + 1 fiber), gable (1). Everything is 2 m on a side. A roof rises
  1 m over 2 m, so two roofs from opposite walls of a 4 m hut meet at a ridge,
  and gables close the ends. Geometry and snap points live in
  `build_piece.gd`, rules in `build_system.gd`.
- **Snapping**: the ghost sits on your crosshair, then moves to the nearest
  pair of snap points (its own and a nearby piece's), with rotation locked to
  that piece's 90-degree grid. R turns building pieces a quarter turn. Away
  from other pieces, floors sit level on the highest ground under them.
- **Support**: touching the ground = 100%. Otherwise a piece takes the best
  of its neighbours minus 10% going up/down or 25% sideways. Under 30% it
  can't be placed, so an overhang reaches about 4 floors.
- **Dismantling**: X on any placed piece puts it back in your inventory
  (chests must be empty, graves can't be). Pieces left below 30% support
  collapse and come back to you too. Loose chests/fires/beds drop to the
  ground.
- **Shelter detection**: roofed = 3 of 5 rays straight up hit a building piece.
  Sheltered = roofed and at least 6 of 8 sideways rays hit walls within 8 m.
  Roofed keeps rain off you (and off a campfire). Sheltered cuts the weather's
  chill to a quarter, adds +8 warmth, and with a fire nearby makes you Rested
  after 20 s (stamina regen +50% for 5 min).
- **Bed**: E sets your spawn point (death respawns you there while it
  stands). E again at night (19:30 to 05:30) sleeps until 06:00 if the bed is
  sheltered: the clock, fires, regrowth and weather move on, you lose a
  little food, and you wake dry, warm and Rested.
- Grass doesn't grow through floors.

### 2.6 Survival stats *(M1b)*
| Stat | Drains from | Restored by | At zero |
|---|---|---|---|
| Health | damage, starving, freezing | food, rest | death |
| Stamina | sprint, swing, jump | resting, food buffs | can't sprint/swing |
| Hunger | time (faster when cold) | eating | health drains |
| Warmth | night, rain/wet, snow, altitude | fire, shelter, clothes | health drains, slow |

Status effects: **Wet** (rain or swimming: warmth drains faster, lasts after
you're out), **Cold** / **Freezing**, **Warm** (near a fire), **Sheltered**,
**Rested** (sat by a fire under a roof: stamina regen buff).

Built in M1b (`scripts/player/survival.gd`), current numbers:
- Hunger: full to empty in 1500 s (about 1.25 days), 1.5x faster below 30
  warmth. Eating is refused at 98+. Berries +9, mushroom +6, roasted
  mushroom +24.
- Warmth eases toward a target: air warmth (22 at night to 68 at noon, -0.9 per metre above 12 m) plus
  up to +70 from a fire or a held torch. Warms at 7/s, cools at 1.6/s.
- Wet: 90 s after leaving deep water, -22 to the warmth target, dries 3x
  faster by a fire.
- Stamina: regen 24/s after a 1 s pause. Sprint 14/s, jump 8, harvest hit 6.
- Health: -0.6/s starving, -0.5/s below 12 warmth, +0.5/s when fed (>40)
  and warm (>35).
- Campfire: starts with 2 min of fuel, holds 15 min, +fuel with wood (E),
  heat radius 7 m. Out of fuel = no heat, no cooking.
- Berry bushes regrow after 10 min. Torch = 1 stick + 2 fiber.

### 2.7 Time & weather *(M1b / M1c)*
- Day/night cycle: 20 real minutes per day by default. The sun, sky, fog and
  ambient light follow time of day. Nights are dark enough that a campfire or
  torch matters.
- *(built in M1c)* Weather is a function of the world seed and the absolute
  world time (`weather.gd`), so it isn't saved and every M2 client can
  compute the same weather. A slow noise "front" picks the state. Measured
  over 60 days on seed 1337: clear 38%, cloudy about 30%, rain/snow 33%,
  storm 12%. A wet spell lasts about 6 minutes. A new world's first
  10 minutes are always clear.
- About 1 day in 4 (never day 1) is a **cold day** (-8 warmth): rain falls as
  snow and storms become blizzards. Above the snowline (28 m) it always
  snows.
- Warmth from weather: cloudy -3, rain -6, storm -12, snow -14, blizzard -24.
  Rain on you (no roof) keeps you Wet. Snow chills but doesn't soak. Rain on
  an uncovered campfire burns its fuel up to 4x faster.
- Each state sets cloud cover, sun and ambient light, fog, wind and
  precipitation, blending over about 50 s. Storms flash lightning, with
  thunder 0.5 to 2.5 s later.
- Visuals and sound (`weather_fx.gd`, client side): GPU rain and snow
  particles stopped by a heightfield collider, so it doesn't rain indoors.
  Wet ground, settled snow (on terrain, rocks, grass and tree crowns) and wind
  strength are global shader uniforms. Rain, wind and thunder sounds are
  synthesised from filtered noise, and rain is muffled under a roof.

### 2.8 Creatures & hunting *(built in M1d)*
| Animal | HP | Run speed | Notices you | Behaviour | Butchering gives |
|---|---|---|---|---|---|
| Rabbit | 10 | 7 m/s, zig-zags | 7 m (12 m if you sprint) | flees | 1 raw meat |
| Deer | 40 | 9 m/s | 16 m (30 m if you sprint) | flees, outruns you | 2-3 meat, 1-2 hide |
| Boar | 60 | 6.6 m/s | never | neutral; hit it and it charges and gores you for 14 every 1.6 s for 18 s, and flees below 30% HP | 3-4 meat, 1-2 hide |

- *(later)* **Wolf**: night predator, hunts in packs.
- `scripts/creatures/creature.gd` runs each animal's state machine (idle,
  wander, flee, charge, dead). Steering is over the heightmap with no navmesh:
  a probe ahead turns the animal away from water, steep drops, the world edge
  and trees, rocks or buildings. Legs are animated at the hips. The meshes are
  procedural (`creature_meshes.gd`).
- `spawner.gd` keeps up to 6 rabbits, 4 deer and 3 boars, spawning 30-70 m
  away and despawning them past 100 m. Each kind prefers its habitat: rabbits
  in meadows, deer at forest edges, boars deep in the woods. A kind waits
  25 s to respawn after one dies. Animals aren't saved, so a loaded world
  repopulates straight away.
- A kill leaves a **carcass** (on the interactable layer). E butchers it, and
  arrows stuck in it come back to you. Carcasses rot away after 5 min.
- Feathers lie in the meadows as ground pickups (70, regrowing like sticks).

### 2.9 Weapons & combat *(built in M1d)*
| Weapon | Recipe | Use | Damage |
|---|---|---|---|
| Bare hands, food, torch, resources | | | 0: you need a weapon (the prompt says so) |
| Axe / pickaxe | | LMB | 6 (poor weapons) |
| Wooden Club | 4 wood | LMB, reach 2.4 m | 12 |
| Wooden Spear | 3 wood, 2 flint, 1 fiber (workbench) | LMB thrust (reach 3.1 m); RMB throws it (24 m/s, then pick it up) | 18 / 30 thrown |
| Crude Bow | 4 wood, 6 fiber (workbench) | hold LMB to draw (0.9 s full), release | 8-32 by draw |
| Flint Arrow x5 | 2 sticks, 1 flint, 2 feathers (workbench) | ammunition; misses stick in the world and can be picked up | |

- A melee swing is a box sweep in front of the camera, tall enough to reach a
  rabbit at your feet. It costs stamina and has a per-weapon cooldown.
  Animals are hit first, then trees and rocks.
- Arrows and thrown spears are projectiles (`projectile.gd`) with gravity,
  ray-cast segment by segment so fast arrows can't skip through a target.
  Damage scales with speed at impact. Arrows and spears lying in the world
  are saved.
- Getting hurt flashes the screen red and stops natural healing for 6 s.
  Animals and players use the same `damage()` path, ready for M2.

### 2.9a Food buffs and clothing *(built in M1d)*
- Raw meat: +5 food, -4 health (it can't take you below 1). Cooked meat, made
  at a campfire, gives +34 food, +12 health and **Well fed** for 10 min:
  stamina regen x1.3 and healing x2. The HUD shows the time left. Buffs are
  saved. They don't stack, so the strongest applies.
- **Hide Cloak** (4 hide + 4 fiber at a workbench): RMB to wear it. It gives
  +15 warmth and cuts the chill from being wet by 40%. You take it off from
  the inventory screen. It's saved, and it goes into your grave when you
  die.

### 2.10 Saving & worlds *(built)*
- **One continuous world per save slot.** The title screen offers Continue
  (most recent), New World (name and seed: blank = random, 1337 = the
  original island) and Load World (with delete). You can't save and reload at
  will to undo mistakes: survival tension depends on choices sticking.
- **Autosave** every 2 minutes, on Save & Quit (to the title or desktop) and
  when the window is closed.
- Saves live in `user://worlds/<id>/` (on macOS:
  `~/Library/Application Support/Godot/app_userdata/Valheimlike/worlds/`) as
  `meta.json` + `world.json`. Writes are atomic, and the previous save is
  kept as `world.json.bak`.
- A save stores only what the player changed: player position and look,
  inventory, hotbar slot; placed pieces and chest contents; tree and boulder
  damage, stumps, mined rocks; collected pickups. Everything else regenerates
  from the seed. Since M1b it also stores stats, time of day, bush regrowth
  timers, campfire fuel and graves. Since M1c: building pieces (door open or
  shut), the bed spawn point and regrowth timers. Weather isn't saved: it
  follows from the seed and the time.

### 2.11 Death *(built in M1b)*
- On death you respawn at your bed (or the island spawn) and leave a **grave
  bag** with your inventory where you died (Valheim-style: punishing but
  recoverable). The world carries on.
- Optional **hardcore** world setting later: death deletes the world.

## 3. Architecture (fits docs/ARCHITECTURE.md)
- **Intents, not results.** UI and input never change game state directly. They
  call `Actions.*` (`craft`, `harvest_hit`, `pickup`, `place`, `transfer`),
  which validates and applies. In M2 these same calls become RPCs to the
  authoritative server. That's the reason the layer exists now.
- **Model / view split.** `Inventory` is a plain data class with a `changed`
  signal. UI widgets only render it and send intents.
- **Data in JSON**, behaviour in small scripts per piece (`campfire.gd`,
  `chest.gd`, ...).
- **Everything procedural**: item meshes are built in code and turned into
  icons at startup by an offscreen renderer, so there are still no art assets
  to license.

## 4. Build phases
| Phase | Delivers | Playable "done when" |
|---|---|---|
| **M1a** *(done)* | items/recipes data, inventory + hotbar, pickups, chop/mine with tools, crafting UI, campfire / workbench / chest placement, chest storage, pause menu, **title screen + world slots + save/load + autosave** (pulled forward from M1c) | you craft an axe, fell a tree, build a fire, stash wood in a chest, quit and continue |
| **M1b** *(done)* | hunger/warmth/stamina/health HUD, day/night cycle with moon and stars, campfire warmth + fuel, cooking, bushes (fiber, berries), mushrooms, torches, **death + grave bag** (pulled forward from M1c) | you survive your first night by the fire |
| **M1c** *(done)* | weather (rain, storm, snow, blizzard, lightning, sound) + wet/shelter/rested, snap building (floor/wall/door/roof/gable) with support, dismantling and collapse, bed spawn point + sleeping, resource regrowth | you build a hut and wait out a storm |
| **M1d** *(done)* | rabbit/deer/boar AI and spawning, club/spear (thrown)/bow + arrows, butchering, hides, hide cloak, cooked meat + Well fed buff, feathers | you hunt a deer and eat its meat |

## 5. Open decisions (current defaults in bold)
- Thirst stat? **No**, to keep the stats readable (Valheim has none).
  Easy to add as a fifth stat later.
- Perspective: **first person** for now. Third person can come with the
  character model.
- Death penalty: **grave bag** (recoverable). Alternatives: lose everything
  (Rust) or keep everything (casual).
- Day length: **20 min**.
- Durability on tools: **no for M1**, revisit when metals arrive.