M1a: survival core, pause menu, title screen and save/load

Design: docs/SURVIVAL_DESIGN.md (core loop, systems, architecture, phases).

Survival core (M1a):
- Items/recipes as data (data/*.json) in the addon SDK's define_item /
  define_recipe shape; procedural item meshes and offscreen-rendered icons
- Inventory class (40 slots, hotbar = row 1) shared by player and chests;
  click / right-click split / shift-click quick-move
- Actions autoload: the intent layer (craft, pickup, harvest_hit, place,
  transfer) that validates every change; becomes the RPC surface in M2
- Gathering: ground pickups (sticks, stones, flint); trees chopped with an
  axe fall and leave stumps; boulders mined with a pickaxe shrink per hit
- Crafting screen with station checks (workbench); placement mode with
  green/red ghost, rotation and overlap/slope validation
- Pieces: campfire (light, flames, embers), workbench, chest (16 slots)
- HUD: hotbar, held tool view model with swing, prompts, toasts

Menus and saving:
- ESC pause menu: resume, controls, fullscreen, mouse sensitivity, quit
- Title screen over a flyover of the island: Continue / New World (name +
  seed) / Load World (with delete) / Quit
- Saves autoload: one folder per world under user://worlds, atomic writes
  with a .bak; stores only player changes (player, pieces, chest contents,
  harvested resources, taken pickups) and regenerates the rest from the seed
- Autosave every 2 min, Save & Quit to title/desktop, save on window close

Fixes: UI screens now fill the viewport (were pinned top-left); title
backdrop no longer captures the mouse.

Tests: test_survival_core (31 checks), test_save_load (round trip + slots),
test_terrain_edges now checks 8 seeds for deep pits / unbanked water.

docs/SETUP_ON_NEW_MACHINE.md

@@ -17,10 +17,20 @@ download — the M0 world is generated in code.
 ```bash
 # Boundary: tries to walk/jump out of the valley in 24 directions
 godot --headless --path . --fixed-fps 30 --script res://tests/test_boundary.gd
-# Terrain: no pits/hanging water just inside the boundary wall
+# Terrain: no deep pits / floating water at the boundary, across 8 seeds
 godot --headless --path . --script res://tests/test_terrain_edges.gd
+# Survival loop: inventory, crafting, chopping, mining, pickups, building, chests
+godot --headless --path . --script res://tests/test_survival_core.gd
+# Save/load round trip + world slots (uses user://test_worlds, not your saves)
+godot --headless --path . --script res://tests/test_save_load.gd
 ```
 
+## Save files
+Worlds are per machine, under
+`~/Library/Application Support/Godot/app_userdata/Valheimlike/worlds/` on
+macOS (`%APPDATA%\Godot\app_userdata\Valheimlike\worlds\` on Windows). Copy a
+world's folder across to move it to another machine.
+
 ## 2. Get the project onto the machine
 You have the folder (from the zip, or a git remote). Then:
 

docs/SURVIVAL_DESIGN.md

@@ -0,0 +1,161 @@
+# 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).
+
+### 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. *(Later: stats, time of day, weather, regrowth timers.)*
+
+### 2.11 Death *(M1c)*
+- 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** | hunger/warmth/stamina/health HUD, day/night cycle, campfire warmth + fuel, cooking, bushes (fiber, berries), torches | you survive your first night by the fire |
+| **M1c** | weather (rain, storm, snow) + wet/shelter, snap building (floor/wall/roof/door) with support, death + grave bag, 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.