# rimlike — game design

> Companion to [`memory.md`](../memory.md). Read `memory.md` first for project north-star (pillars, vertical slice, open questions). This file is the **game design**: core loop, mechanics, simplifications from Rimworld.

## Problem / motivation

A 2D, tile-based **medieval-fantasy** colony management sim — Rimworld DNA, **Going Medieval** as the closest lodestar — but **slimmer** and **shaped for mobile / handheld**. Most of Rimworld's fundamentals are present (pawns with needs and work priorities, base building, food production, hostile events, progression), but simulation, UI, and session length are tuned for short bursts on a small touch screen.

The aesthetic anchor is **cute farming RPG meets medieval colony sim** (peasants, wood/stone/iron, swords/bows, wild beasts) — bright, cheerful, Stardew-adjacent in palette while keeping the colony-sim depth of Rimworld and the medieval scope of Going Medieval. Driven by owned art (see [`art.md`](./art.md): ElvGames "Ultimate Farming RPG" bundle as primary, Ventilatore Fantasy Tileset as medieval accent secondary).

## Core loop (one play session)

1. **Open app** → instant resume from autosave, brief "while you were away" summary (if any background events fired during the timeskip).
2. **Triage** → storyteller prompt(s) waiting (e.g. "Stranger arrived. Recruit?", "Winter in 4 days").
3. **Plan** → adjust work priorities, queue construction/research, designate areas. The slow, deliberate phase — pause is fine here.
4. **Run time** → game speed defaults to fast; auto-pauses on threats / pawn-down / dialog events. Player watches a few in-game hours fly by.
5. **React** → 1–2 events resolve.
6. **Stop** → close app at any time, autosave is always current.

## Simplifications from Rimworld

What we deliberately *do not* build:

- **No body-part injury system.** Single HP per pawn + status effects (Bleeding, Infected, Sick, Tired, Hungry, Downed). ~80% of the drama for ~5% of the code.
- **No deep social web.** Relationships exist as +/- mood thoughts; no schism / lover triangles in MVP.
- **No temperature simulation in MVP.** Winter = food penalty + storyteller pressure, not a heat-leak simulation.
- **~4–5 skill categories** (Manual Labor, Crafting, Cooking, Medicine, Combat) instead of 12.
- **No mods/scripting in MVP** — punt.
- **No multi-Z-level / mountain-base.** Single ground layer; "roofed" is a flag, not a Z.
- **No prefab-house hand-painting.** Players build tile-by-tile from walls/floors.

## Skills

5 categories per pawn, 0–10 each. Level by use. Multiplicative speed/quality bonus on relevant work. **Skills modify duration and quality, never permission** — Bob with Cooking 0 can still cook, slowly and slightly worse.

| Skill | Affects |
|---|---|
| Manual Labor | Mining, hauling, construction, chopping |
| Crafting | Workbench output, repair quality |
| Cooking | Meal speed and food poisoning rate |
| Medicine | Treatment success, infection clear rate |
| Combat | Hit chance, damage |

## Health & status effects

Single HP per pawn (default 100). Statuses tracked separately, each with severity 0–100, decay/grow rates, and an interrupt urgency flag (see [`architecture.md`](./architecture.md) for how statuses become AI interrupts).

| Status | Source | Effect |
|---|---|---|
| Hungry | Time without food | Slow movement/work; eventually damages HP |
| Tired | Time awake | Slow work; eventually forces sleep |
| Bleeding | Combat / accident | Continuous HP loss; high-priority interrupt |
| Sick | Storyteller / hygiene | Reduces work speed; needs rest + treatment |
| Infected | Untreated wound | Can escalate; treat with Medicine |
| Downed | HP near 0 | Cannot act; carry to bed; bleeds out if untreated |

## Mood system

Per-pawn mood is a single 0–100 score, computed each tick as `BASE + sum(thought_modifiers)`. Thoughts come from current state (persistent) or recent events (decay over time).

### Mood bands & break risk

| Band | Range | Effect |
|---|---|---|
| Inspired | 90+ | +20% work speed (rare positive event windows) |
| Happy | 65–90 | +10% work speed |
| Content | 35–65 | normal |
| Stressed | 15–35 | −30% work speed |
| Breaking | < 25 sustained ≥ 30 in-game min | **soft break** — see below |

### Soft breaks

When a pawn's mood is < 25 for 30 in-game minutes (sustained — momentary dips don't trigger), they enter a soft break, randomly **sulking** or **wandering**:

- **Sulking** — pawn walks to a quiet corner, sits there, won't accept work. Ends at mood ≥ 35 or after 8 in-game hours.
- **Wandering** — pawn paces aimlessly, refuses work, may eat/sleep. Ends same conditions.

Soft breaks are a player signal: "address this pawn's needs." No destruction, no violence in MVP.

### Thought list (~13)

**State-driven (persistent while condition holds):**

| Thought | Effect | Source |
|---|---|---|
| Hungry | −5 → −15 (severity ramp) | Hunger need ≥ 60 |
| Tired | −3 → −10 | Sleep need ≥ 70 |
| Damp / Soaked | −3 / −6 | Wet status (see weather) |
| Cold | −10 | Outdoors during a Cold Snap |
| In darkness | −3 | At night, in unlit tile (see Lighting) |
| Cramped quarters | −3 | Sleeping in a room < 4 tiles (see Rooms) |
| Beautiful room | +3 | Sleeping in a room with high beauty score |
| Ugly room | −3 | Sleeping in a low-beauty / dirty room |

**Event-driven (fire and decay):**

| Thought | Effect | Decay |
|---|---|---|
| Slept well / poorly | +5 / +0 / −2 / −5 / −8 (sleep gradient, locked) | next sleep |
| Saw corpse | −3 (stacks per corpse) | 8h |
| Ate raw food | −5 | 6h |
| Ate fine meal | +3 | 6h |
| Witnessed death | −10 | 2 days |
| Recently injured | −3 (while wound healing) | wound heal |

> Numbers are placeholders — tune in prototype.

The system is **data-driven**: thoughts live in a registry, easy to add/remove. We ship with these 13; expand by playtest.

## Lighting

Each tile tracks "is this lit at night?" Lights are emitting furniture (torch, hearth, candle, oil lamp). Visual: lit tiles render in normal color at night; unlit tiles render with a darkening overlay. Players physically see darkness — atmosphere ahead of pure simulation.

**Light sources (initial):**

| Source | Radius | Fuel | Build cost |
|---|---|---|---|
| Torch (wall-mounted) | 3 tiles | none | 2 wood |
| Candle | 2 tiles | none | 1 cloth |
| Hearth | 5 tiles + warmth flavor | wood (slow burn) | 10 stone, 5 wood |
| Oil lamp | 6 tiles | oil (post-MVP fuel sim) | 5 metal, 1 cloth |

Fuel system simplified for MVP — most lights don't deplete; hearth consumes wood from adjacent stockpiles slowly. Full fuel-sim is post-MVP.

## Rooms

Auto-detected from walls. Each enclosed area is a Room with:

- `cells: Array[Vector2i]`
- `furniture: Array[Furniture]` (everything inside)
- `beauty: float` (computed; see Beauty)
- `dirtiness: float` (computed; see Cleaning)
- `inferred_type: String` ("Bedroom" if contains bed; "Kitchen" if contains stove; else "Room")
- `owners: Array[Pawn]` (pawns whose beds are here)

Used by mood thoughts (Cramped quarters, Beautiful/Ugly room) and the day-summary screen ("Bob slept in his bedroom (beautiful)").

Rooms recompute when walls or furniture change; cheap given enclosure detection already runs.

## Beauty & Quality

### Beauty

Each furniture/floor/decor item has a `beauty: int`. Room aggregates as average beauty across cells; some items have wide influence (a statue contributes to a 5-tile radius even if it's one tile).

Categories displayed to player:
```
Beauty < −2     Ugly           "−3 mood Ugly room"
−2 ≤ B < 0      Dingy          slight negative
0 ≤ B < 3       Plain          no thought
3 ≤ B < 6       Nice           "+1 mood Nice room"
6+              Beautiful      "+3 mood Beautiful room"
```

### Quality

All crafted items roll a Quality on creation: **Shoddy / Normal / Excellent / Masterwork / Legendary.**

- Roll function of crafter's relevant skill + RNG. Shoddy at low skill is common; Masterwork at high skill is rare.
- Quality multiplies item stats (weapon damage, armor coverage, bed comfort, beauty contribution to room).
- Item names are color-coded: grey/white/green/blue/purple.
- Affects all crafted goods: weapons, armor, furniture, meals.

The "Bob crafted a Masterwork chair" / "Mira's Legendary sword" moments are core Rimworld magic; this system lights them up.

## Dirtiness & Cleaning

Floor tiles accumulate `dirtiness: float (0..100)`:

- Dirtiness grows over time, faster on high-traffic tiles (pawns walking through), faster outdoors-tracked-in.
- Specific events spike dirtiness: blood from combat (~20), corpse decay (~5/h), spilled food.
- Dirtiness above 30 reduces room beauty; above 60 contributes "Ugly room" thought directly.

**Cleaning** is an 8th work category in the priority matrix. Cleaning Job toils: walk to dirty tile, perform timed cleaning (modified by Manual Labor skill), reduce dirtiness to 0.

Mostly low-skill chore work — gives Manual-Labor pawns something to do when not building/mining/hauling.

## Production chains & workbenches

2-step chains where it makes medieval sense; 1-step where simpler is fine. Going Medieval / Banished flow without runaway recipe authoring.

### Material flow

```
Raw material         Intermediate       Finished
────────────────────────────────────────────────
Wood log             —                  Walls/floors (1-step), furniture
Stone                —                  Walls (1-step)
Iron ore             Iron ingot         Iron tools/weapons/armor
Copper ore           Copper ingot       (decor/wires future)
Silver / Gold ore    Silver/Gold ingot  (currency / luxury items future)
Cloth / hide         —                  Beds, curtains (1-step furniture)
Grain                Flour              Bread
Vegetables           —                  Meals (cooked)
Meat                 —                  Meals (cooked)
Corpse               Meat (butchering)  →
```

### Workbenches (5 in MVP)

| Workbench | Skill | Recipes |
|---|---|---|
| **Carpenter's bench** | Crafting | Chair, table, bed, crate, barrel — wood goods |
| **Smelter** | Crafting | Iron / Copper / Silver / Gold ore → ingots (consumes wood as fuel) |
| **Smithy / Anvil** | Crafting | Iron tools (axe, pickaxe, hammer), iron weapons (sword), iron armor (helm/cuirass/boots) |
| **Cooking hearth** | Cooking | Basic meal, fine meal, bread, butcher (corpse → meat) |
| **Millstone** | Crafting | Grain → flour |

Skipped for MVP: stonecutter (raw stone builds walls fine), tailor (no cloth clothing — only metal armor), drug lab, brewery.

### Recipe authoring (~22 for MVP)

Each `Recipe` is a data record:

```
Recipe:
  id: "forge_iron_sword"
  workbench: "smithy"
  inputs: [{iron_ingot: 4}, {wood: 1}]
  outputs: [{iron_sword: 1}]   # quality rolled on creation
  skill: CRAFTING
  duration_ticks: 200
  min_skill_required: 0  // optional, default 0
```

Output quality is rolled at job completion based on **crafter skill + RNG only**. Input quality doesn't influence output (standard Rimworld/Going Medieval — keeps balance simpler).

### Bills (recipe queue per workbench)

Each workbench has a list of **Bills** (queued recipes). A pawn with Crafting (or Cooking) work picks a bench with active bills and runs the next.

**Bill modes (full Rimworld fidelity):**

- **Do X count** — run this recipe N times, then remove the bill.
- **Forever** — keep running until paused or removed.
- **Until N in stockpile** — most-used; bill is dormant when stockpile + crate count of output ≥ N, becomes active when below.

**Optional filters per bill:**

- **Ingredient quality minimum** — "use Excellent+ iron ingots only." Bill waits if none qualify.
- **Pawn skill minimum** — "only Crafting ≥ 8 takes this bill." For Masterwork-attempting bills.

### Bill priority within a workbench

Bills run in display order (top to bottom). Drag to reorder. The active pawn finishes the current job, then re-checks priorities.

### Updated skill list (5)

Same five skills; Crafting now spans more bench types:

| Skill | Affects |
|---|---|
| Manual Labor | Mining, hauling, construction, chopping, **cleaning** |
| Crafting | **Carpenter, smelter, smithy, millstone** — quality of crafted goods |
| Cooking | Cooking hearth, butchering, food poisoning rate |
| Medicine | Treatment success, infection clear rate |
| Combat | Hit chance, damage |

### Updated work category list (9)

Construction · Mining · Hauling · Cleaning · **Crafting** · Cooking · Plant · Doctor · Combat

The priority matrix is now 9 columns wide. Still scrollable on a phone (sticky pawn-name column, swipe horizontally).

## Storyteller

Sandbox + light storyteller prompts — soft, dismissible nudges that give each short session shape without forcing scenarios. Per Tynan Sylvester's design talks: drama from situation, mix of opportunity and threat, quiet/threat alternation, player choice for big events.

### Picker mechanism

- **Daily roll** at 6am in-game time. Storyteller picks one event from a weighted pool.
- **Cooldowns per category**: no two threats within 3 days; no two wanderers within 5 days; nudges fire at most once per pawn-need-state.
- **Tension model**: a running "tension score" tracks recent dramatic events. High tension → reduce threat weight. Low tension → boost threat weight. Keeps the pacing breathing.
- **State-triggered events** (e.g. "First Beds" fires while no beds exist) get higher weight than random ones.
- **Display flavor**:
  - **Nudges** → ambient top banner, no pause, dismissible.
  - **Seasonal/ambient beats** → ambient banner with seasonal art tint.
  - **Modal events** (wanderer, threat, disease, choice) → auto-pause + dialog.

### Prompt corpus (MVP — 25 prompts)

#### 🌾 Soft nudges (dismiss-only, low priority)

| ID | Title | Body | Trigger | Effect |
|---|---|---|---|---|
| 1 | First Beds | *"Your settlers slept on the cold ground again. They are starting to ache."* | day 2+, beds < pawn count | nudge only |
| 2 | Empty Larder | *"The larder is bare. Spring won't last forever."* | day 3+, no farm zone | nudge |
| 3 | No Fire | *"Without a hearth, the cold will bite by night."* | day 4+, no hearth/torch | nudge |
| 4 | Walls? | *"Sleeping under stars is romantic until the wolves arrive."* | day 5+, no walls | nudge |

#### 🍂 Seasonal beats (ambient banner)

| ID | Title | Body | Trigger | Effect |
|---|---|---|---|---|
| 5 | Spring Awakens | *"The thaw runs in every stream. Crops will grow fast now."* | spring start | +10% crop growth season |
| 6 | Summer's Heat | *"The sun beats down. Unsheltered work will tire faster."* | summer start | outdoor work −5% |
| 7 | Autumn's Harvest | *"The fields are heavy with the last of the year's bounty."* | autumn start | +15% harvest yield |
| 8 | Winter's Edge | *"Frost has come. The road is closed; you are alone."* | winter start | no wanderers for 5 days; threat weight ↑ |

#### 🚶 Wanderer events (modal, choice)

| ID | Title | Body | Trigger | Choices |
|---|---|---|---|---|
| 9 | A Traveler | *"A weary traveler stumbles toward your gate. They look hungry. Will you welcome them?"* | ghost state OR ~8 days | Welcome (+1 pawn) / Send away |
| 10 | The Refugee Family | *"A family fleeing bandits arrives. They have nothing, but they would work hard."* | post-day-15 | Welcome (+2 pawns, low skills) / Refuse (−2 mood colony 1 day) |
| 11 | The Old Soldier | *"A retired soldier offers his blade for a place by your fire. Combat 8, but old and tired."* | post-day-20 | Welcome / Refuse |
| 12 | The Wandering Healer | *"A traveling healer asks for shelter. She brings knowledge of medicine."* | any pawn Sick | Welcome (+1, Medicine 6) / Refuse |

#### 🐺 Threat events (modal, auto-pause)

| ID | Title | Body | Trigger | Effect |
|---|---|---|---|---|
| 13 | Wolves at the Edge | *"Wolves howl in the distance. They will be here by nightfall."* | season-weighted threat slot | 1–3 wolves at edge in 2h |
| 14 | Lone Wolf | *"A starving wolf circles your livestock."* | low-threat random | 1 wolf |
| 15 | Pack Hunt | *"A hunting pack moves through the forest. They smell your colony."* | post-day-30 threat | 4–6 wolves |
| 16 | Bandit Scouts | *"Strange figures watched from the treeline at dusk. Bandits, perhaps."* | post-day-25 | flavor; raises threat-likelihood (foreshadow for v2 raids) |

#### 🤒 Disease & misfortune (modal or nudge)

| ID | Title | Body | Trigger | Effect |
|---|---|---|---|---|
| 17 | Fever | *"%pawn% woke with a fever. The sickness may spread."* | random ~30 days | Sick on random pawn; 20% daily spread to neighbors |
| 18 | A Bad Cut | *"%pawn% gashed their hand chopping wood. The wound looks deep."* | chop job, low chance | Bleeding on pawn |
| 19 | The Sleeplessness | *"%pawn% has barely slept. Something weighs on them."* | random, low-mood pawn | Tired worsens; mood penalty 2 days |

#### 🌾 Resource & opportunity

| ID | Title | Body | Trigger | Effect |
|---|---|---|---|---|
| 20 | Bountiful Harvest | *"Your fields exceeded the season. The granary swells."* | harvest, random | +25% yield this harvest |
| 21 | Lumberjack's Luck | *"%pawn% found a copse of unusually thick trees."* | chop job, random | next 3 trees +50% wood |
| 22 | Veins of Iron | *"A miner reports a rich vein, deeper than expected."* | mine job, random | next mining yield ×2 |

#### 🏰 Discovery / lore (flavor, dismiss)

| ID | Title | Body | Trigger | Effect |
|---|---|---|---|---|
| 23 | Strange Stones | *"Settlers report finding carved stones in the wood — older than any memory."* | random, post-day-15 | flavor only |
| 24 | An Old Map | *"%pawn% found a tattered map. Roads to the north, half-faded."* | random, post-recruit | flavor (seeds v2 trade/exploration) |

#### 🌟 Milestone (rare, celebratory)

| ID | Title | Body | Trigger | Effect |
|---|---|---|---|---|
| 25 | One Year Survived | *"A full year. The first frost feels different now — yours is a real settlement."* | end of first winter | +5 mood "We made it" colony 2 days |

### Authoring guidelines

- **Voice**: medieval, a touch of melancholy/grit. Avoid modern phrasing.
- **Length**: 1–2 sentences. Anything longer feels like a wall on a phone.
- **Use `%pawn%` substitution** for personalized events. Game replaces with the relevant pawn's name.
- **All copy is in a string table** — i18n-ready from day one.
- **New prompts = new rows in a JSON registry**. Trivial to expand post-MVP.

## Combat

Realtime with auto-pause on threat. Two-roll resolution (hit, then damage). Cover from walls + trees. Downed-then-rescue death model for sim drama.

### Weapons (3 in MVP)

| Weapon | Type | Damage | Range | Speed | Recipe |
|---|---|---|---|---|---|
| Sword | Melee | 8 | 1 (adjacent) | 1.0 atk/sec | 4 iron ingot + 1 wood |
| Axe | Melee | 12 | 1 | 0.7 atk/sec | 3 iron ingot + 1 wood |
| Bow | Ranged | 10 | 8 tiles | 0.5 atk/sec | 1 wood + 1 cloth |

Quality multiplies all stats (Masterwork sword = 12 dmg @ 1.5 atk/sec).

Unarmed pawns fight with fists: 3 damage, 0.5/sec. Used when cornered without a weapon.

### Armor (3 slots)

| Slot | Iron variant armor value | Recipe |
|---|---|---|
| Helmet | 3 | 3 iron ingot |
| Cuirass | 8 | 5 iron ingot |
| Boots | 2 | 3 iron ingot |

Total iron set = 13. Quality multiplies. Each slot independent — pawn can wear partial armor. Leather/cloth variants post-MVP (lower armor, lower mood penalty for hot weather).

### Cover (walls + trees)

A target is "in cover" if a wall or tree tile sits between the target and the attacker along line-of-sight.

- **Wall** — full cover, **−40% to hit**
- **Tree** — partial cover, **−20% to hit**

Cover is checked per-attack. Multiple cover sources don't stack (highest applies).

### Hit / damage resolution (two roll)

```python
# Roll 1: hit
hit_chance = 50% + (combat_skill × 5%) − cover_penalty − (range_penalty if ranged)
range_penalty = max(0, (distance − 2) × 5%)
hit = (random() < hit_chance)

# Roll 2: damage (only if hit)
damage = weapon_damage × quality_multiplier − target_total_armor
damage = max(1, damage)   # always at least 1 damage on a hit
target_hp -= damage
```

Skill 10 pawn at adjacent range with no cover: 50% + 50% = ~100% hit before clamps. Same pawn at range 8 with bow against treed target: 50% + 50% − 20% (cover) − 30% (range) = 50%. Tunable.

> All numbers placeholders — tune in prototype.

### Downed & death

When HP reaches 0, pawn enters **Downed** status (not dead). Behavior:

- Drops their weapon to the ground.
- Cannot move or take any job (Layer 1 of decision pipeline).
- Bleeding continues if untreated → HP stays at 0 → death after **6 in-game hours** untreated.

**Rescue flow:**

- Doctors auto-prioritize Downed colonists (Doctor work).
- Job: walk to Downed pawn → carry → walk to nearest bed → place in bed.
- Pawn in bed gets `Resting` status; doctor visits to treat (clears bleeding, infection); HP regenerates over ~2 in-game days.

If no doctor reaches the Downed pawn in time → death → corpse entity → handled by stockpile system (Corpses filter category).

### Combat priority semantics — "Off = defends if cornered"

A pawn with Combat priority **Off**:

- Won't accept the player's forced "Attack target" job.
- Won't autonomously move toward threats.
- *Will* fight back if an enemy is adjacent and no escape path is reachable (5-tile pathfinder check).
- Tries to flee toward map interior / nearest indoor zone when threats appear.

A pawn with Combat priority **High** or **Critical**: actively engages threats in range, holds position, takes player commands.

### Forced commands

Player taps a pawn → bottom sheet → **Attack target** → tap an enemy. Issues a forced job (Layer 5 of pawn AI). Pawn engages with priority.

Same flow for **Carry to bed** (manually rescuing a downed pawn) and **Patrol** (post-MVP).

### Auto-equip

Pawns with Combat > Off auto-equip the best available weapon they can carry, prioritizing higher quality. Player can override via long-press on a weapon item → **Assign to Bob**. Locks the assignment until cleared.

### Friendly fire — ON

Projectiles travel along their LOS path; any pawn in the path is a potential hit (with reduced chance vs the intended target). Standard Rimworld semantic. Adds tension to ranged formations.

### Wolf AI (MVP's one threat type)

- Storyteller fires wolf events at night, weighted by season (more in winter).
- Wolves spawn at map edge in a small pack (1–4).
- Approach the colony, engage pawns or animals.
- Have natural weapons (bite: 6 damage, 1.0 atk/sec) and minor armor (tough hide: 2 armor).
- Flee at HP < 30% — pacing keeps them from being trivial swarm fodder.
- Death = corpse, butcherable for ~5 meat at the cooking hearth.

## Stockpiles & hauling

The unsung 30% of pawn-time. Storage has two coexisting forms: **floor stockpile zones** (areas painted on the world) and **containers** (furniture you build). Both share the same filter + priority model; haulers treat them as a unified pool of destinations.

### Filter categories — 16 chips

| Materials | Food | Equipment | Misc |
|---|---|---|---|
| 🪵 Wood | 🥕 Vegetables | 💊 Medicine | ⚰ Corpses |
| 🪨 Stone | 🍖 Meat | ⚒ Tools | |
| ⚙ Iron ore | 🌾 Grain | ⚔ Weapons | |
| 🟤 Copper ore | 🍞 Cooked meals | 🛡 Armor | |
| ⚪ Silver ore | | | |
| 🟡 Gold ore | | | |
| 🧵 Cloth & hides | | | |

Tap-toggle in a 4×4 chip grid per stockpile or container. (Future expansion: split Wood by species, etc. — punted.)

### Priorities — 5, Rimworld semantics

**Critical / Important / Preferred / Normal / Low.** Items flow from low priority to high automatically:

- **Critical** — pulls items from anywhere, immediately. The "I want this filled NOW" zone.
- **Important** — pulls from Preferred and below.
- **Preferred** — default for "nice" stockpiles (e.g. kitchen-adjacent food).
- **Normal** — standard.
- **Low** — dump zone. Items here move OUT to higher zones when those have space.

Pawns periodically rescan (every ~5 sim seconds) to migrate items low→high without burning CPU.

### Containers

A **Crate** is a furniture entity, built like any other (Build → Furniture → Crate). MVP ships **one generic crate type**: 4 stacks capacity, any allowed item types (configurable post-build). Different sizes / specialized crates are post-MVP.

- Independent of zones — placed anywhere, has its own filter + priority.
- Same 16-chip filter and 5-level priority as floor zones.
- Tap a crate → inspect screen (filter, priority, contents, Empty / Move / Demolish).
- Pawns walk adjacent (4-neighbor) to drop into a crate; container tile itself is impassable.
- Capacity: 4 stacks of allowed types.

Crates exist alongside floor stockpiles. Use floor zones for high-volume bulk (logs in a lumber yard); use crates for organized indoor storage (kitchen pantry, armory).

### Stacks — one per tile, one item type per tile

Mixed tiles disallowed. Visual quantity badge per tile. Stack maxes:

| Item | Max stack |
|---|---|
| Wood, stone, cloth, ores | 50 |
| Vegetables, meat, grain | 25 |
| Cooked meals, medicine | 10 |
| Tools, weapons, armor, corpses | 1 |

### Pawn carry

One stack at a time, capped at pawn's carry capacity (~25 wood per trip on the average pawn). Multi-type carry is v2.

### Workbench output drop tile

Each workbench has one designated cell in front. Products land there; haulers clear it via the normal pipeline. Avoids the Rimworld kitchen-mess problem.

### Forbid / allow

Long-press item → toggle hauling. Forbidden items get a 🚫 badge; haulers ignore them.

For data structure + hauling AI, see [`architecture.md`](./architecture.md). For zone painting and crate inspect UI, see [`ui.md`](./ui.md).

## Roofing, indoor, weather

Temperature simulation is cut (locked). What remains is the indoor/outdoor divide that powers shelter motivation.

### Indoor = roofed

A tile is **indoors** if it has the Roof flag set on Layer 4 (see [`architecture.md`](./architecture.md)). No further enclosure check at sim-time — we trust the auto-roof system to only place roofs in sensible places.

### Auto-roof, not player-placed

When walls form an enclosed area ≤ 8 cells across, the interior **auto-roofs**. No "place roof tile" verb. BFS from interior cells when walls change; if every direction hits a wall within 8 cells, mark Roof. Cap prevents a fence around a meadow from roofing a stadium.

Matches the player's mental model: *"I built four walls, now there's a room."*

**Big-room UX (open):** the ≤8-cell cap silently fails on rooms larger than 8×8. When the player encloses a too-large area, we should surface "this area is too large to roof — split it with an interior wall." Exact threshold + UI treatment is TBD (see `memory.md` Open questions).

### "No-roof" designation

Designation type: paint cells inside an enclosure to forbid auto-roofing. Useful for courtyards, fire pits, gardens. Same paint UX as stockpile zones.

### Roof rendering — none in MVP

Roofs are sim data only. Indoor tiles get a subtle tint (faint blue-grey overlay). No X-ray toggle. This is the genre convention for top-down sims (Rimworld does the same). Visible roofs = v2 polish.

### What roofing protects against

| Effect | Outdoor | Indoor (roofed) |
|---|---|---|
| Mood penalty for being in rain | −3 (Wet) | none |
| Mood for sleeping | −5/−2 | +0/+5 |
| Snow accumulates | yes | no |
| Food spoilage in heat wave | faster | slower |
| **Plants grow** | yes | **no** |

Crucially: **plants don't grow indoors.** No skylights / hydroponics in medieval scope. Gardens must be outside, so weather matters even after walls go up.

### Weather — 4 types, daily roll

Simple state machine. At sunrise, storyteller picks the day's weather, weighted by season.

| Weather | Effect |
|---|---|
| **Clear** | nothing special |
| **Rain** | outdoor pawns/items accumulate Wet; food spoilage slows |
| **Storm** | heavier rain, faster Wet, mood penalty outside, no harvesting jobs assigned |
| **Cold snap** | outdoor pawns: −10 mood, hunger grows faster |

### Seasons

4 seasons × 12 in-game days = **48-day year** (~4 real-time hours per year at default speed).

| Season | Clear | Rain | Storm | Cold snap |
|---|---|---|---|---|
| Spring | 50% | 35% | 10% | 5% |
| Summer | 70% | 20% | 10% | 0% |
| Autumn | 50% | 30% | 15% | 5% |
| Winter | 30% | 25% (as snow) | 25% | 20% |

> **Weights are placeholders — tune in prototype.** The shape (winter rough, summer kind) is locked; numbers are first guesses.

Storyteller can override for narrative beats ("a hard winter approaches").

### Wet status

Pawns in rain accumulate **Wet** (0–100). Decays indoors, grows outside.

```
Wet 0–25:  no effect
Wet 25–60: −3 mood "Damp"
Wet 60+:   −6 mood "Soaked", small movement-speed penalty
```

Decay ~5/in-game-hour indoors; accumulation ~10/h in rain, ~20/h in storm.

> **Numbers are placeholders — tune in prototype.** Thresholds, decay rates, and accumulation rates are starting values, not locked decisions.

### Sleep mood (the strong gradient)

```
+5  Slept in bed, indoors
+0  Slept in bed, outdoors (under stars)
−2  Slept on bedroll/ground, outdoors with no bed
−5  Slept on the ground, indoors
−8  Slept on the ground, outdoors
```

Forces players to build (a) beds and (b) walls/roof to house them. Simple, legible gradient.

> **Numbers are placeholders — tune in prototype.** The shape (worse outdoors, worse on ground, both compound) is the design intent; specific values get tuned by playtest.

### Explicitly not simulated

- Temperature (locked).
- Wall-material insulation — all walls equivalent.
- Lightning, fires — defer.
- Wind, projectile drift — defer.
- Sunlight angles — plants either get sky (grow) or don't.

## Failure state — Ghost colony

When all colonists die or leave, the world enters **ghost state.** No game-over screen.

- Buildings, stockpiles, containers, items, beds — all persist exactly as they were.
- Time continues at slow speed; pawn-side simulation is paused.
- Within **3–5 in-game days**, the storyteller fires a **Wanderer event**: a stranger arrives at the map edge, prompting recruit/refuse.
- If accepted: new pawn enters, you control them, ghost state ends.
- If refused: another wanderer eventually appears; world stays ghost until accepted.

**Why this works for mobile:** "lost my colony of 200 hours" on a phone is brutal UX. Ghost state preserves the world, the player's investment, and lets a session end on a softer note. Permadeath drama still lives in *individual* pawn deaths.

## Death & corpses

### Cause of death tracking

Each pawn entity stores `death_cause: String` and `death_day: int`. Used by pawn-detail screen ("Bob the Carpenter — died Day 27 of Spring 1, killed by wolf") and by grave markers (tap a grave → see that screen).

### Corpse decay

Corpses decay over time. Each corpse has `decay_severity: float (0..100)`, growing ~33/in-game-day:

| Severity | State | Effect |
|---|---|---|
| 0–50 | Fresh | Butcherable for ~5 meat. Standard −3 mood per stack. |
| 50–100 | Rotting | No longer butcherable. Mood penalty grows: −5 per stack. Visible green-grey tint. |
| 100 | Rotted | Still removable (bury or cremate); butcher disabled. |

Rotting corpses don't attract predators in MVP (clean cut for scope) — but rot creates urgency: bury or cremate fast.

### Burial mechanic

Designate a **Graveyard** zone — a special stockpile that only accepts Corpses (filter has a single chip on, Corpses).

Burial Job toils (Construction-priority pawns):

```
walk to corpse → carry → walk to graveyard cell
→ dig grave (~30 sim sec, modified by Manual Labor skill)
→ place corpse → place grave marker tile
```

Result: corpse entity destroyed, grave marker placed. Marker is a 1-tile decorative entity:

- Beauty: +1 (modest contribution to room beauty)
- Persistent until demolished
- Tap → opens pawn-detail showing the deceased's record

### Cremation pyre

Buildable furniture (Build → Furniture → Pyre, costs ~10 stone + 5 wood). Plays the role of a workbench but accepts a single recipe:

- **Cremate corpse** — input: 1 corpse + 5 wood. Output: nothing (corpse gone). Time: ~20 sim sec. Skill: Crafting.

Player adds a "Cremate" bill to the pyre; a Crafting-priority pawn auto-hauls a corpse, walks to the pyre, performs the rite (visual: brief flame + smoke), corpse destroyed.

Faster than burial; doesn't preserve a memorial. Clean for "send the wolves we killed back into the world."

### Grave markers

Single-tile decorative entity placed by burial. Beauty +1 each. Cluster in a graveyard zone gives a small "Beautiful (somber) garden" feel — beauty bonus stacks.

Tap a marker → pawn-detail screen for the deceased: name, role, death day, cause, days-lived, statuses-at-death.

### What we deliberately don't build

- **Resurrection** — no MVP feature. Death is permanent.
- **Hauntings / ghosts** — flavor for v2, not needed.
- **Funeral ritual** with attendance + mood — interesting but adds a system.
- **Decay attracts predators** — was an option; cut for MVP scope (creates negative-feedback-spiral risk).

## What lives elsewhere

- **Pawn AI / job system, work priorities mechanics** — see [`architecture.md`](./architecture.md).
- **Touch UI for work priorities + other screens** — see [`ui.md`](./ui.md).
- **Tileset strategy + assets + art license** — see [`art.md`](./art.md).
- **Vertical slice spec** — see [`memory.md`](../memory.md).
