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. Resources regrow over time *(M1c)*.

### 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)* Snap-together pieces: wood floor, wall, door, roof, stairs, with
  snap points and Valheim-style **structural support** (stability falls off
  with distance from the ground; unsupported pieces collapse).
- **Shelter detection**: you count as sheltered when rays upward hit a roof and
  most sideways rays hit walls. That drives "dry" and "rested" status.

### 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.
- Weather is a seeded state machine: clear → cloudy → rain → storm, plus
  **snow** on cold days and always near the snowline. Each state sets the
  cloud cover, fog, wind (grass/trees already read wind), particles and
  sound, plus a warmth modifier. Transitions blend over about a minute.

### 2.8 Creatures & hunting *(M1d)*
- **Rabbit**: skittish, fast, gives a little meat.
- **Deer**: flees on sight or sound, gives meat and hide.
- **Boar**: neutral; charges if hit; gives meat and hide.
- *(later)* **Wolf**: night predator, hunts in packs.
- Simple state machines (idle / wander / flee / attack) on navigation-free
  steering over the heightmap. Spawned around the player within budget.

### 2.9 Weapons & combat *(M1d)*
- Club (hand), wooden spear (thrust; can be thrown), bow + arrows (workbench;
  needs feathers and flint).
- A melee swing is a short shape cast in front of the camera. It costs stamina
  and has a cooldown. Damage numbers come from item data.

### 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. *(Later: weather.)*

### 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** | weather (rain, storm, snow) + wet/shelter, snap building (floor/wall/roof/door) with support, bed spawn point, resource regrowth | you build a hut and wait out a storm |
| **M1d** | rabbit/deer/boar AI, club/spear/bow, hides, cooked food buffs | 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.