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.