4640f5e577
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.
162 lines
8.5 KiB
Markdown
162 lines
8.5 KiB
Markdown
# 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.
|