Companions

A top-down survival‑RTS management sim. Command a tiny party of precious, mortal companions across a procedurally generated island — gather, survive, build a settlement, and move on when the land wears out.

Living document · mirrors the in-game F1 help and extends it with developer reference · describes build v0.3.0 · last revised 2026-07-22

What changed in v0.3.0 short form

Everything this build brought, one line each — so this page says what it is before it says how the game works. The long form, with every reason and number behind them, is CHANGELOG.md in the repository.

v0.3.0 this build 2026-07-22

Changes

• An overloaded pack (user decision)
• One "how many?" prompt, and uniform shift gestures (user decision)
• Companion cards open under the pointer (user decision)
• The wiki remembers its own versions (user decision)

Fixes

• A pot boils all at once
• Boiled water goes into a waterskin, never a pack

Overview

What the game is, and the shape of a run.

You control a party of three companions (recruiting more, up to ten, is planned) from an RTS-style top-down view: box-select, right-click to command. There is no player avatar — the three are equals. Every one has the full set of survival stats and can die individually; losing one is meant to feel tragic. The hardest difficulty is permadeath. The only threats are nature — food, water, temperature, weather, seasons and distance — plus reactive wildlife that may defend itself. Nothing ever attacks your base.

A run is a cycle of three phases

1. The manual opening — everything by hand, no automation. Scout for a viable site, live hand-to-mouth off what you find.
2. The automated base — buildings unlock jobs, each companion's rule program runs the day, the settlement hums.
3. Exhaustion → migration — the land wears out, the party packs what it can carry, treks, and starts over stronger: skills, equipment and recruits persist, the place does not. Each year winters bite harder.

The 512×512 map is budgeted for roughly 3–5 settlement cycles — that is the designed run length. Phases 1 and 2 exist today; phase 3 (a forced push and a tools/equipment system) is the big open milestone.

Move & look WASD · F · Tab

• WASD pans the camera (free look). The view stays where you put it — selecting or commanding never yanks the camera.
• F centres the camera on the selected character and follows it (a group is framed at its centre). Tab does the same while switching companions.
• Right-click commands every selected character (see Command); a green ping marks the ordered spot. Hold right-click to steer continuously — the selection follows the cursor until you release.
• Dense forest and loose sand slow walking to 80%.
• Mouse wheel or +/- zoom; M snaps to the widest zoom. Mouse at a window edge scrolls the view (tune speed/width in Esc → Settings → Gameplay).
• There is no minimap and no overview map — you never see the whole island at once. Reading and remembering the land is part of the game.
• The time-warp bar sits top right (pause, 1–10×). Switch on Esc → Settings → Graphics → Show FPS and the frame rate appears directly under it — green above 50, amber above 30, red below. It updates four times a second on real time, so time warp and pause do not change how it reads.

Your party 3 → 10 companions

• Left-click a character to select it (green / blue / orange; a white ring marks it). Exactly one selected = it is "yours": E-gather and build use it, and it walks your right-clicks at full speed.
• Drag a box to select several and command them together.
• Left-click empty ground deselects — observer mode; everyone just runs its jobs.
• The bottom-left info panel follows the mouse: hover any tile for terrain + what stands on it (tree species & wood left, water salinity, buildings, stockpile usage, plant stock); hover a character for its current activity. Fog applies.
• Tab switches control to the next companion; 1–9, 0 select directly (tap twice to also centre the camera). Hotkeys are fixed for the run — a dead companion's number stays vacant.
• Companions learn by doing. Walking trains Running (speed), each trade trains its own skill, heavy trades & building train Strength (carry + build speed), and enduring cold/rain/exhaustion hardens Resilience (falls ill later). A run's veterans are made, and they are what you carry to the next settlement.
• Strangers come knocking. Every so often a wanderer walks in out of the wild and waits a few days at the settlement. Left-click them for their panel: name, body, base attributes — and nothing else, because a recruit arrives unskilled. Take them in or send them on; wait too long and they leave. The party is hard-capped at ten, and a new pair of hands eats before it earns.
• Not everyone means it. Some wanderers are false companions: they work slowly, help themselves to the stores, and one night they are gone with whatever they could lift. Nothing on the panel gives it away — the event log does, over days (someone at the stores after dark; a day's work that came up short). Sharp companions (Perception) name names. Expel anyone who joined from their character sheet (C) — and be wrong at your own cost.

Command — right-click RMB

Right-click sends every selected character; what happens depends on what you click. Your word is absolute — a character never breaks off an order, even to save itself. It posts a red warning when critical and carries on; abort the order yourself if you want it to live.

Shift+right-click queues the order as a waypoint. A plain right-click replaces the whole queue. Nobody looks after themselves at all — drinking, eating, warming and sleeping happen only on your order or through the rule program (T).

Gather — hold E E

Hold E next to a target; a ring fills over its harvest time. Gathered items go into that character's carry, limited by weight (~40 kg, raised by Strength).

• Trees → wood: each forest tile is one tree; the whole wood stock drops when it falls (the tile turns to grass). Strikes are banked — stop and finish later. Four species by shade: birch (10 wood), pine (20), spruce (25), oak (35).
• Rocks → stone and fishing take ~10× ordinary work — plan whole days; a mason's yard / fisher's hut put workers on them around the clock.
• Herbs, berries, roots regrow in place (not in winter). Bird nests (spring only, gone for good when robbed), mushrooms (summer+autumn, forest edge), hazel nuts (all year, never rot, but a cleared bush is finished and the next grows out of sight), mussel beds (salt coast, year-round, spoil fast).
• Free ground pickups (a half-second stoop, gone once taken): twigs & leaf piles at the forest edge, loose stones on the plains.
• Wild hemp → plant fibre — grows only on damp ground beside fresh water (river banks and lake shores; never the salt coast, never inland). Tall fanned stalks, regrows in ~5 days outside winter. Fibre is not string: spin it into cordage on the Crafting tab, and cordage is what a bowstring and a fishing line are made of. No hemp in reach → no bow and no rod, so it is one more thing that makes a settling site good or bad.
• Hunting takes a bow (craft one once a Hunting lodge stands). Deer & pigs flee faster than you walk — you shoot them: embody a hunter, hold H, a swaying reticle rises, lead the moving animal, release to loose. A hit is aim, not luck. A shot spooks the prey — one clean opening shot, then it bolts. The Hunter rule shoots the same way on its own, and with nothing in sight it takes a stand instead of falling through to the next rule: it walks to the nearest known forest cell (failing that, anywhere outdoors — never under a roof) and waits there, reading "No huntable animals in sight - waiting". Hunting is mostly waiting.
• Fishing takes a rod (a pole plus a line of cordage; craft one once a Fisher's hut stands). The hut grants the fishing right to its water, the rod is the tackle: no rod in the pack → the companion will not fish, the Fisher rule stays blocked, and the hut's task postings are left for whoever is equipped. Rods are per companion — three fishers need three rods.

Eight creatures roam: deer & pigs are the herds you live off; pigeons & crows fly where you cannot follow; beavers keep to fresh water; badgers are slow enough to corner; wolves and bears hold their ground (a bear is the biggest meat on the map). Nothing out there hunts you — yet.

Stay alive

Health, Thirst, Hunger, Tiredness and Temperature drain over time; Mood is a secondary, non-lethal stat. Every companion is a compact row top-left; hovering a row unfolds it to full bars — and that is the only thing that opens a card, so the corner never rearranges itself when control moves. Buff/debuff badges beside the card say what is on a companion — green = boon, red/magenta/violet = malus. When any Health falls into the red, the whole screen sounds the alarm (red rim, heartbeat) so an off-screen death can't be missed.

What hurts you doesn't let you heal: an empty Thirst/Hunger bar, or a freezing/ overheating body, suspends rest regeneration entirely — the sleeper rests off tiredness but wakes no healthier. Winter is the exam: farms lie dormant, plants stop regrowing, no animals are born. Stockpile in autumn; nuts, fishing and mussel beds work year-round.

Buffs & debuffs — the exact numbers

Every condition a companion can carry, what it really costs, and how to end it.

Conditions show as badges beside the HUD card and under the portrait in the character sheet (C). The colour tells you the kind before you read anything: green = a boon, and magenta / blue / violet / red = something is wrong. Every slowdown below multiplies with the others: soaked, exhausted and ill at once is a companion barely moving.

Work & trades — how each one resolves

Gathering, felling, mining, fishing and hunting are not one mechanic — they cost different time and need different things.

Every trade trains its own skill by doing it, and the skill multiplies the pace back. Heavy trades and building train Strength (a bigger carry and faster building), walking trains Running, and enduring cold, rain or exhaustion hardens Resilience (falls ill later).

Moving goods — the one hand

There is exactly one hand in the game, and every window fills it the same way.

Pick a stack up in the character sheet's carry grid, in the transfer window, or straight off a stockpile tile on the map (Shift+right-click it) — it is always the same hand, so a stack can only ever be in one place. Closing a window keeps the stack in hand, which is exactly how it gets out onto the map: carry it to a construction site, a fire's hearth, a pile or a companion and left-click it down. Esc on a clear screen puts it back where it came from.

Build — press Space Space

You start with nothing. Space opens the build ring (radial menu, 2026-07-20): an inner ring of categories — Workshops, Structure, Supply, Demolish — where left-clicking a category opens it in a second, outer ring. Hovering any entry spells it out in the info panel below the circle, cost per material included (green = affordable now, red = not). Place it, and every selected character goes to build it (nearest one if none selected). R rotates the ghost before placing.

The centre always goes back one ring, and closes the menu on the top level — the same thing right-click and Esc do, so there is one rule for the way out. Space closes it from any depth. Only two rings are ever drawn: opening a category replaces the outer ring rather than adding a third, so nesting is free and the circle never grows. Greyed entries come in two kinds that must not be confused — a padlock is a player goal (the workshop that unlocks it does not stand yet), a dashed outline is a planned placeholder that does not exist in the game yet.

There is no ready-made house. The drag-to-size prefab was retired from the player's hands (2026-07-20): every house is now designed out of walls, doors and floors, and is whatever shape you enclose. Job buildings stay simply placed and the farm stays drag-to-size — a workshop is equipment, not architecture; only the home is the player's design.

Two prices for one building. A buildable may list alternative costs — the campfire's 9 twigs or 3 wood (2026-07-21). Twigs lie on the ground everywhere, so the first fire of a run never has to wait for a felled tree. The build ring lists both, each material coloured by what the settlement holds, with an or between them; a blueprint commits to one of them (whichever it can cover, primary first) and shows only that on the site. As long as nothing has been delivered yet it re-picks by itself, so a site that asked for wood asks for twigs the moment twigs are within reach; once the first material lands, the bill is settled in it. Demolishing refunds half of what the building was really paid for — a fire raised from kindling salvages kindling.

And two fuels for one fire. The same reasoning carries past the build: a fire that can be raised from twigs can be fed with them (2026-07-21). A campfire burns wood or twigs, 3 twigs to the log, and the stone hearth the same way. Logs are always preferred where there are any — every fuel run shops the list in order, so the party falls back on kindling only when the woodpile is empty. Everything that feeds a fire goes through the one list: the right-click order, the REFUEL rule, a claimed task, holding E at it, the world hand and the panel's FUEL slot (which counts in logs but takes either).

Furnish a room — left-click inside it

A self-designed house is not an object you can click, so the furniture panel hangs on the room: left-click any cell of an enclosed room and it opens, reading the room out (cells, shelter warmth, how homely it is) and listing the furniture that may go in it. Pick a piece and the ghost only accepts cells inside those walls — otherwise it is an ordinary construction site: builders fetch the materials and raise it. Click inside the same room again, or press Esc, to close. It resolves last of all map clicks, so anything with a panel of its own (a pile, a fire, a construction site) keeps the click.

The two beds are told apart by their LABOUR, not by their price (2026-07-21): their materials are nearly identical, so what separates them is the work. A straw bed sets build_seconds_per_cell = 0 — instant: total_build_seconds() floors at 0.001, so the first frame of a builder's work finishes it. The materials still have to be carried to the site; only the labour is nil. The bed costs twice what it used to (7.2 → 14.4 s per cell). The entry tooltip quotes the labour in in-game time for one builder (BuildEntry.labour_line); helpers stack their deltas and shorten it.

A room is not yet a home. Its comfort is the average over its cells of the floor laid on them and the furniture standing in them, and that comfort lifts Mood while a companion is inside — doubled while asleep. Over-furnishing simply finishes the room; it is capped, never an exploit.

Automate — press T T

Automation is built, not switched on. Write each companion a program — an ordered list of rules reading WHEN condition(s) → DO action UNTIL release. Order is priority.

• WHEN — sensors: the body's bars (Health & Mood too), Wetness, Sickness, the clock, the season, precipitation, city stores, the own carry, the waterskin, fire fuel, a waiting site. Conditions AND together.
• DO — actions: the trades (fell, fish, farm, quarry, hunt), drink, eat, sleep, warm/cool, tend fires, build, haul the carry to stores, fetch items into the carry, and take a task off the task board.
• UNTIL — the latch: "fell wood UNTIL stores ≥ 60" keeps a rule going past its trigger so companions don't ping-pong at the threshold.
• Nothing happens that nobody asked for (11.7): no companion carries its load home on its own. A full pack stops the work that would fill it further (harvesting into a full pack destroys the node for nothing) and the rest of the program runs on. Bring it in by right-clicking a stockpile, with a WHEN Carry full → Haul rule, or via the task board — a task's goal sits in the city stores, so delivering is the last leg of it. Any haul keeps a ration of every food kind and of drinking water: the load goes, the lunch stays.
• Blocks are budgeted: a rule costs 1 block, +1 per extra WHEN, +1 for an UNTIL; the whole settlement shares one budget (base 12, +6 from a Planning table). Rules past the budget don't run — top rules are paid first.

The task board (needs a Planning table): buildings watch their own needs and post tasks — a fisher's hut calls for a fisher while stores hold under 20 fish, a burnt-down fire calls for tending, open sites post themselves. One 1-block Take a task rule claims the nearest posting, so a new recruit is just one more taker. Trades are earned: each work action stays locked until its workshop stands. Workers only seek what the party has already discovered.

Time & world

Day/night and seasons pass; the clock, temperature (°C) and weather sit top-centre. Speed controls (or -/.) run pause / 1× / 2× / 5× / 10×.

Weather follows the seasons — sunshine, cloud, rain, hail, summer drought, winter snow. Hail hurts (bleeds Health in the open; only a roof or forest canopy stops it). Rain soaks (wet = up to 30% colder). Wet clothes dry fastest at a campfire or under a roof (~4 in-game hours from soaked through) — and out in the open as fast as the sky allows: ~10 h under warm sunshine, about a third of that pace when overcast, and nothing at all in cold air or while rain, snow or hail falls. A summer soaking dries itself while the work goes on; a winter one waits for a fire. In deep winter rivers and lakes freeze (wells keep serving); a summer drought dries small ponds until the next rain.

Water has a quality as well as a salinity. A body of fresh water that never reaches the sea — a lake, a pond — is still water: drinkable, and every gulp builds the drinker's dysentery load — nothing on its own, but the pond you keep going back to breaks out as the illness. Rivers drain to the sea and count as running along their whole length, and so do wells and hot springs. A waterskin filled at a lake carries pond water with it until it is drunk dry. Choosing between a lakeside site and a river (or a well) is the point.

The cure is a fire. Right-click one and pick Boil water: the companion pours everything untreated it carries — the pack first, then its waterskin — into the hearth's pan, waits for it, and takes the clean water back (skin first, the rest into the pack). Empty-handed the same order simply collects what is already boiling. By hand it works too: right-click the tool slot in the character sheet (C) to pour the skin into your hand, then set it down on a fire (the whole skinful goes in), on a barrel, or on another companion to fill their skin.

Boiling costs time, and that is deliberate. A full waterskin takes one in-game hour on a campfire; a stone hearth is three times faster at everything it cooks. The pan holds 20 units and boils unattended while the fire burns, so you load it and walk away — but one pan cannot water a whole party, and it cannot sear fish while it boils. Boiling is the stopgap at a pond; a river or a well is the answer.

The land itself has a climate. Most of the island is temperate, but three kinds of country are not: tundra (−10°C) on the high northern fringe, desert (+8°C) in the dry south, and swamp (soaks you like rain, and a fire can't dry you while you stand in it). The seasons turn both extremes inside out — knowing which half of the year a country is survivable in is worth more than avoiding it.

Interface & keys

The companion window holds everything you do to one companion, as three tabs — each key opens its own tab (press again to close; Ctrl+Tab walks the tabs). All three are about the companion you're steering.

Architecture & conventions

Engine, layout, and the ground rules the codebase holds itself to.

• Engine: Godot 4.x, 2D top-down. GDScript only (no C#).
• Language: all identifiers, comments, node/scene names in English — no German anywhere in code or the scene tree.
• Naming: snake_case for vars/funcs/signals/files; PascalCase for classes/nodes/scenes; class_name for reusable scripts.
• Data-driven: tunables live in .tres Resources (resources_data/) and @export vars — not magic numbers. Numbers should be tunable without touching code.
• Decoupling: cross-cutting state lives in autoload singletons; systems talk through signals where it decouples them.

Autoload map

The singletons every system reaches. Persistent autoloads must reset in WorldGenerator._ready (a reload doesn't re-instantiate them).

World generation & terrain

A cell has three orthogonal per-cell layers: terrain (what it physically is — world/terrain_types.gd: PLAINS/WATER/FOREST/MOUNTAIN/SAND/SHALLOW), biome (its climate — world/biome_types.gd: temperate/ tundra/swamp/desert, grown as one region each), and landmark (world/landmark_types.gd: crater lake / hot springs / standing stones).

Key tunables — scripts/world/world_generator.gd

Rendering: world/terrain_renderer.gd (per-cell texture), terrain_snow.gdshader, tree_canopies.gd (crowns draw over walkers at z 4; _apply_walkers feeds the reveal+sway shader), room_floor_renderer.gd, fog_overlay.gd. All world colours live in resources_data/palette.tres via GamePalette. Nav: walkable_navigation_region.gd; collision: terrain_collision.gd.

Resources & animals

Companions

The companion rig is scenes/player/Player.tscn / class_name Player, instanced three times as nodes Character1/2/3 (a node name is a save key — rename via SaveManager.RENAMED_CHARACTER_NODES). Behaviour is split across small controllers on the rig.

Recruiting — scripts/world/wanderer_spawner.gd

A wanderer is a companion rig (Player.tscn) that has not joined — not a second kind of person. That is the whole design: its identity, carry, drawing and save entry are the ones every companion already has, so recruiting is PartyManager.recruit() → rename onto a free Character<N> (a node name is a save key) + Player.join_party(). A stranger is frozen while it waits (Player._halt_survival) and reveals no fog. Leaving runs the other way: Player.leave_party() attaches a fresh controller in LEAVING and the rig walks off the map and frees itself — expulsion and desertion share that one door.

Spawner knobs: first_possible_day (6), min_days_between (6), arrival_chance (0.22/day), linger_days (3), renegade_chance (0.3), approach_cells (45). One stranger on the road at a time; a full party is sent nobody. Console wanderer [spawn [renegade]|here|panel|recruit|send|desert].

The big tuning surface — scripts/player/job_runner.gd

Movement/work: move_speed, work_seconds, mine_seconds, fish_seconds. Needs/thresholds: need_trigger_ratio/recover_ratio, emergency_ratio, warm_seek_below/cool_seek_above, despondent_below. Automation: base_rule_slots (12), dev_self_care (re-enables the dormant self-care tiers — tests / a future easier difficulty). Hunting: hunt_range_cells, hunt_base/min/max_hit, hunt_giveup_seconds. Fatigue penalties live on player/player.gd (fatigue_walk_penalty, fatigue_work_penalty, mood_work_penalty).

Automation internals

Work actions are gated by standing workshops (Buildings). Old saves migrate a painted schedule into time-window rules on load. Console: rules, prog, tasks, auto.

Buildings & construction

Items, inventory & storage

Time, weather & temperature

Temperature damage: cold below 4°C / heat above 35°C (temperature_controller.gd). Pacing: the 18-minute day and ×1.8 task lengths; HARVEST_TIME_SCALE is the harvest seam.

UI & panels

Save / load

Node names are save keys (see Companions). Since recruiting (5.4) _collect_characters walks the tree, not a fixed name list, and _rebuild_character builds the rigs a fresh world doesn't have. Restore obeys a rank order (ground → structures → fixtures). Difficulty (Hard = free save/load, Brutal = suspend-only + slot wipe) is picked on the title screen. Console: saves, save, load, delsave, difficulty.

Console commands

Every command the dev console knows, what it does and one example each.

F12 opens the console (debug builds only); Esc or F12 closes it and the game pauses while it is open. Handlers live in scripts/ui/dev_console.gd — help inside the console is the authoritative list, and every new mechanic ships a command here.

Most commands act on the selection: the companions currently selected, or the whole party when nobody is. select 2 is therefore usually the first thing you type.

Companions & stats

Windows, items & the hand

World & terrain

Time & weather

Resources & animals

Building & automation

Saves, meta & staging

Testing & tools

Godot binary for this environment: ~/Downloads/Godot_v4.7-stable_linux.x86_64. After adding a class_name, rebuild the class cache before headless tests. Claude cannot see the running viewport — visual work is verified through the screenshot harness or by the developer.

Versioning

One number, one source, and the two things it is deliberately not.

The game's version lives in exactly one place: application/config/version in project.godot — the engine's own field, so an exported build carries it in the PCK for free. Everything in the game reads it through GameVersion (scripts/main/game_version.gd), a static class like BuildCategories: GameVersion.string() gives "0.3.0", GameVersion.label() gives "v0.3.0" — the one spelling every screen uses, so no label re-types the "v".

Scheme: plain semver. While the prototype runs at 0.x, MINOR goes up per completed feature batch and PATCH for fixes; 1.0.0 is reserved for the release that closes the run arc (ROADMAP Milestone 10, the migration cycle). Milestone-derived numbering was rejected — milestones complete out of order, so the version would have run backwards.

Where it shows: the title screen's bottom-right corner, the pause menu, every save's header, the console command version (which also prints the engine build and the save format), the Windows executable (mirrored into export_presets.cfg), and the line at the top of this page.

Cutting a release (full steps in CHANGELOG.md): bump project.godot, mirror the number into export_presets.cfg and this page, write the changelog section, run the headless suite, commit, then git tag -a v<version>. The suite fails if the three copies drift apart — that check is what keeps the mirrors honest.

The wiki archive — one frozen page per release

This page is a living document: it always describes the build in development. So that it can also say what an older build did, every release freezes a full copy under wiki/v<version>/ — both languages and their own copy of the screenshots, because an archived page showing today's pictures would defeat the point of archiving it. The picker in the sidebar reaches every frozen build; a frozen page wears an amber banner and links back here.

Release order, and it matters: edit both pages for the release → wiki/shots.sh (so the frozen set is this build's) → bump project.godot, export_presets.cfg and both pages → wiki/snapshot.sh → changelog, suite, commit, tag.

Keeping this in sync important

When a player-facing mechanic changes (a control, a building, a gather target, a survival rule):

1. Edit HelpPanel.HELP_TEXT in scripts/ui/help_panel.gd — the single on-screen source of player help (its nav is derived from the section headers, so keep the [font_size=17][color=#9ec1ff][b]…[/b] header format).
2. Update the matching Player Guide section here.
3. If the change touches code structure (a new file, seam, tunable or console command), update the matching Developer Reference section and, if relevant, re-shoot the screenshot.
4. Mirror every edit into wiki/index.de.html, the German twin, in the same commit.

The developer reference is derived from the seam catalogue in the project memory index (memory/MEMORY.md), where each system names its one seam — the fastest place to confirm where a mechanic actually lives.

Companions — prototype developer wiki. Player Guide mirrors the in-game F1 help; Developer Reference maps mechanics to files, seams, tunables and console commands. Screenshots made with tests/screenshot.gd (seed 12345).