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.