anno-117-docs/docs.md

# Anno 117: Pax Romana — Sandbox Mode Data Reference (API-Style)

> **Version:** 0.2 (compiled from provided research files; not yet a full extracted DB)  
> **Focus:** Sandbox / Endless Mode mechanics (no controls/UI bindings)  
> **Data Sources:** research_1.txt  [oai_citation:0‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64), research_2.txt  [oai_citation:1‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973), research_3.txt  [oai_citation:2‡research_3.txt](sediment://file_00000000e73871f6bf8844e9c7de47e3)  
>
> **Scope Warning (important):**  
> This document only includes **entities and numeric stats explicitly present** in the supplied research files.  
> Where a field is unknown, it is marked `Unknown` (not guessed).

---

## Table of Contents

- [Schemas](#schemas)
  - [Schema: Building](#schema-building)
  - [Schema: Good](#schema-good)
  - [Schema: PopulationTier](#schema-populationtier)
  - [Schema: ProductionChain](#schema-productionchain)
  - [Schema: Specialist](#schema-specialist)
  - [Schema: ShipHull](#schema-shiphull)
  - [Schema: ShipModule](#schema-shipmodule)
- [Entities](#entities)
  - [Population Tiers](#population-tiers)
  - [Goods](#goods)
  - [Buildings](#buildings)
  - [Production Chains](#production-chains)
  - [Trade & Logistics](#trade--logistics)
  - [Ships & Naval](#ships--naval)
  - [Specialists](#specialists)
  - [Economy & Diagnostics](#economy--diagnostics)
  - [Monuments](#monuments)
- [Troubleshooting Playbooks](#troubleshooting-playbooks)
- [Glossary](#glossary)

---

## Schemas

### Schema: Building

**Entity Type:** `Building`

| Field | Type | Notes |
|------|------|------|
| id | string | stable anchor id |
| name | string | display name |
| category | string | Production / Service / Safety / Monument / etc. |
| description | string | 1–2 lines max |
| requiredPopulationTier | string | link to tier |
| buildCost | object | `{ gold?, goods[] }` |
| constructionTime | string | usually instant per research |
| maintenance | object | `{ goldPerMin?, workforce[] }` |
| workforce | array | `[{ tier, count }]` |
| placementConstraints | array | coast/marsh/forest/fields/etc |
| roadRequired | boolean | |
| warehouseRequired | boolean | implies “in range of Warehouse/Trading Post” |
| inputGoods | array | links to goods |
| outputGoods | array | links to goods |
| cycleTimeSeconds | number | production cycle time |
| areaEffects | array | `{ type, value, target, radius? }` |
| productionChain | array | links to chain(s) |
| unlockCondition | string | tier, research, count, etc |
| usagePatterns | string | short |
| commonPitfalls | string | short |

---

### Schema: Good

**Entity Type:** `Good`

| Field | Type | Notes |
|------|------|------|
| id | string | stable anchor id |
| name | string | |
| category | string | Food / Construction / Intermediate / etc |
| usedFor | array | Construction, Consumption, Input, Trade |
| providesAttributes | array | `{ attribute, value, consumer? }` |
| producedBy | array | building links |
| consumedBy | array | building/tier links |

---

### Schema: PopulationTier

**Entity Type:** `PopulationTier`

| Field | Type |
|------|------|
| id | string |
| name | string |
| region | string |
| workforceFraction | number |
| needsCategories | array |
| notes | string |
| commonPitfalls | string |

---

### Schema: ProductionChain

**Entity Type:** `ProductionChain`

| Field | Type |
|------|------|
| id | string |
| name | string |
| steps | array | `{ building, in[], out[], cycleSeconds }` |
| recommendedRatios | array | `{ building, count }` |
| bottlenecks | array | goods/buildings |
| notes | string |

---

### Schema: Specialist

**Entity Type:** `Specialist`

| Field | Type |
|------|------|
| id | string |
| name | string |
| rarity | string |
| category | string |
| slotType | string |
| scope | string |
| effects | array | `{ type, target, value, scope }` |
| improvesBuildings | array | building links |
| stackRules | string |
| usagePatterns | string |
| commonPitfalls | string |

---

### Schema: ShipHull

**Entity Type:** `ShipHull`

| Field | Type |
|------|------|
| id | string |
| name | string |
| sizeClass | string |
| moduleSlots | number |
| notes | string |

---

### Schema: ShipModule

**Entity Type:** `ShipModule`

| Field | Type |
|------|------|
| id | string |
| name | string |
| effect | string |
| tradeoffs | string |
| notes | string |

---

## Entities

## Population Tiers

### Tier I — Liberti (Latium) / Waders (Albion) {#tier-i}

- **Entity Type:** PopulationTier
- **workforceFraction:** `0.50`  [oai_citation:3‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **needsCategories:** Food, Public Service, Fashion  [oai_citation:4‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **notes:** Avoid upgrading all Tier I housing at once; you can lose Tier I workers needed for basic chains.  [oai_citation:5‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **commonPitfalls:** “Everything upgraded” ⇒ fisheries/farms/sawmills understaffed.

### Tier II — Plebeians (Latium) / Mercators or Smiths (Albion) {#tier-ii}

- **Entity Type:** PopulationTier
- **workforceFraction:** `0.30`  [oai_citation:6‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **notes:** Tier II introduces major upkeep spikes (mills/bakeries/bricks, etc.).  [oai_citation:7‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **commonPitfalls:** Overbuilding production buildings drains gold via maintenance.  [oai_citation:8‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

### Tier III — Equites (Latium) / Higher Albion tiers {#tier-iii}

- **Entity Type:** PopulationTier
- **workforceFraction:** `0.20`  [oai_citation:9‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **notes:** Higher complexity; shortages cascade across chains.  [oai_citation:10‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

### Tier IV — Patricians (Latium) {#tier-iv}

- **Entity Type:** PopulationTier
- **workforceFraction:** `0.00` (reported “no workforce”)  [oai_citation:11‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **notes:** Very high needs; unlock monuments like Amphitheatre.  [oai_citation:12‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

---

## Goods

### Sardines {#good-sardines}

- **Entity Type:** Good
- **category:** Need / Food
- **usedFor:** Consumption (Liberti Food need)
- **providesAttributes:** +1 Population, +1 Income
- **buyPrice:** 12 Dinare
- **sellPrice:** 4 Dinare
- **producedBy:** [Fishing Hut (Latium)](#building-fishing-hut)
- **consumedBy:** [Liberti](#tier-i)
- **availableFrom:** Liberti

### Porridge {#good-porridge}

- **Entity Type:** Good
- **category:** Food
- **usedFor:** Consumption (Tier I Food need)
- **providesAttributes:** +2 Population (per house when fulfilling Food need)  [oai_citation:14‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **producedBy:** [Porridge Stand](#building-porridge-stand)
- **consumedBy:** [Tier I](#tier-i)

### Oats {#good-oats}

- **Entity Type:** Good
- **category:** Agricultural
- **usedFor:** Input (Porridge)
- **producedBy:** [Oat Farm](#building-oat-farm)
- **consumedBy:** [Porridge Stand](#building-porridge-stand)

### Hemp {#good-hemp}

- **Entity Type:** Good
- **category:** Agricultural
- **usedFor:** Input (Tunics)
- **producedBy:** [Hemp Farm](#building-hemp-farm)
- **consumedBy:** [Spinner](#building-spinner)

### Tunics {#good-tunics}

- **Entity Type:** Good
- **category:** Clothing / Fashion
- **usedFor:** Consumption (Tier I Fashion need)
- **providesAttributes:** +2 Population (reported)  [oai_citation:15‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **producedBy:** [Spinner](#building-spinner)
- **consumedBy:** [Tier I](#tier-i)

### Mackerel {#good-mackerel}

- **Entity Type:** Good
- **category:** Raw Material / Agricultural
- **usedFor:** Input (Garum production)
- **buyPrice:** 16 Dinare
- **sellPrice:** 6 Dinare
- **producedBy:** [Mackerel Fishing Hut (Latium)](#building-mackerel-fishing-hut)
- **consumedBy:** [Garum Maker (Latium)](#building-garum-maker)
- **availableFrom:** Plebeians

### Flax {#good-flax}

- **Entity Type:** Good
- **category:** Raw Material / Agricultural
- **usedFor:** Input (Wigs production chain, Togas production chain)
- **producedBy:** [Flax Farm (Albion)](#building-flax-farm-albion), Flax Farm (Latium)
- **consumedBy:** Hairnet Weaver, Weaver

---

### Salt {#good-salt}

- **Entity Type:** Good
- **category:** Raw Material
- **usedFor:** Input (Garum production)
- **producedBy:** [Salt Gardens (Latium)](#building-salt-gardens)
- **consumedBy:** [Garum Maker (Latium)](#building-garum-maker)
- **availableFrom:** Plebeians

### Garum {#good-garum}

- **Entity Type:** Good
- **category:** Need / Food
- **usedFor:** Consumption (Plebeians Food need)
- **producedBy:** [Garum Maker (Latium)](#building-garum-maker)
- **consumedBy:** [Plebeians](#tier-ii)
- **availableFrom:** Plebeians

### Timber (Planks) {#good-timber}

- **Entity Type:** Good
- **category:** Construction Material
- **usedFor:** Construction, Inputs
- **producedBy:** [Sawmill](#building-sawmill)
- **consumedBy:** Many (construction costs reference Timber widely)  [oai_citation:16‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

---

## Buildings

### Woodcutter Hut {#building-woodcutter-hut}

- **Entity Type:** Building
- **category:** Production / Raw Materials
- **description:** Produces Logs from forest density.
- **requiredPopulationTier:** [Tier I](#tier-i)
- **buildCost:** `{ goods: [{ good: "Timber", amount: 2 }] }`  [oai_citation:17‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **constructionTime:** Instant (reported general rule)  [oai_citation:18‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **maintenance:** `{ goldPerMin: -5, workforce: [{ tier: "Tier I", count: 2 }] }` (approx.)  [oai_citation:19‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **workforce:** `[{ tier: Tier I, count: 2 }]`  [oai_citation:20‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **placementConstraints:** Forest overlap required; low density reduces productivity.  [oai_citation:21‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **roadRequired:** true  [oai_citation:22‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **warehouseRequired:** true  [oai_citation:23‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **inputGoods:** none
- **outputGoods:** `Unknown (Logs)` (named in text; Good entry not separately defined)
- **cycleTimeSeconds:** 30  [oai_citation:24‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **productionChain:** [Chain: Timber](#chain-timber)
- **unlockCondition:** Tier I  [oai_citation:25‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **usagePatterns:** Place deep in dense forest, keep a warehouse in range.
- **commonPitfalls:** Sparse forest ⇒ “mystery” timber shortages downstream.

---

### Sawmill {#building-sawmill}

- **Entity Type:** Building
- **category:** Production / Construction Materials
- **description:** Converts Logs → Timber planks.
- **requiredPopulationTier:** [Tier I](#tier-i)
- **buildCost:** `{ goods: [{ good: "Timber", amount: 2 }] }`  [oai_citation:26‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **constructionTime:** Instant  [oai_citation:27‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **maintenance:** `{ goldPerMin: -5, workforce: [{ tier: "Tier I", count: 2 }] }` (approx.)  [oai_citation:28‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **workforce:** `[{ tier: Tier I, count: 2 }]`  [oai_citation:29‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **placementConstraints:** None special (but requires logistics)
- **roadRequired:** true  [oai_citation:30‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **warehouseRequired:** true  [oai_citation:31‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **inputGoods:** `Unknown (Logs)`
- **outputGoods:** [Timber](#good-timber)
- **cycleTimeSeconds:** 30  [oai_citation:32‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **productionChain:** [Chain: Timber](#chain-timber)
- **unlockCondition:** Tier I
- **usagePatterns:** Pair 1:1 with Woodcutters (matching cycle times).
- **commonPitfalls:** Too many sawmills ⇒ upkeep drain without benefit.

---

### Fishing Hut (Latium) {#building-fishing-hut}

- **Entity Type:** Building
- **region:** Latium
- **category:** Production / Fishery
- **description:** Coastal fishery producing Sardines.
- **requiredPopulationTier:** [Liberti](#tier-i)
- **buildCost:** `{ goods: [{ good: "Planks", amount: 2 }] }`
- **maintenance:** `{ gold: -6, workforce: [{ tier: "Liberti", count: 4 }] }`
- **dimensions:** 3x8 (base), 4x11 (with roads)
- **placementConstraints:** Harbor Area required
- **inputGoods:** none
- **outputGoods:** [Sardines](#good-sardines)
- **cycleTimeSeconds:** 60
- **providesAttributes:** +1 Population, +1 Income
- **productionChain:** [Chain: Tier I Food](#chain-tier-i-food)
- **unlockCondition:** Liberti
- **usagePatterns:** Cluster fisheries for specialist + area-effect stacking.
- **commonPitfalls:** Overbuilt fisheries ⇒ gold bleed; also "need flicker" if storage/transport dips.
- **specialists:** Servia Bellia (+25% productivity, +1 income area effect), Netzangler (+10% productivity), Umdenkerin (-25% workforce), Venator der Artemis (-33% workforce, -66% maintenance), Uiscarix (+1.5 income area effect)

---

### Mackerel Fishing Hut (Latium) {#building-mackerel-fishing-hut}

- **Entity Type:** Building
- **region:** Latium
- **category:** Production / Fishery
- **description:** Coastal fishery producing Mackerel for Garum production.
- **requiredPopulationTier:** [Plebeians](#tier-ii)
- **buildCost:** `{ goods: [{ good: "Planks", amount: 2 }, { good: "Bricks", amount: 1 }] }`
- **maintenance:** `{ gold: -8, workforce: [{ tier: "Liberti", count: 4 }] }`
- **dimensions:** 4x9 (base), 6x13 (with roads)
- **placementConstraints:** Harbor Area required, Fish Population required
- **inputGoods:** none
- **outputGoods:** [Mackerel](#good-mackerel)
- **cycleTimeSeconds:** 60
- **unlockCondition:** Plebeians
- **specialists:** Servia Bellia (+25% productivity), Fischdozentin (+10% productivity for Garum chain), Umdenkerin (-25% workforce, changes to Plebeian workforce), Venator der Artemis (-33% workforce, -66% maintenance), Uiscarix (+1.5 income area effect)

---

### Salt Gardens (Latium) {#building-salt-gardens}

- **Entity Type:** Building
- **region:** Latium
- **category:** Production / Raw Materials
- **description:** Coastal salt extraction facility.
- **requiredPopulationTier:** [Plebeians](#tier-ii)
- **placementConstraints:** Harbor Area required
- **inputGoods:** none
- **outputGoods:** [Salt](#good-salt)
- **unlockCondition:** Plebeians
- **specialists:** Servia Bellia (+25% productivity), Fischdozentin (+10% productivity for Garum chain)

---

### Garum Maker (Latium) {#building-garum-maker}

- **Entity Type:** Building
- **region:** Latium
- **category:** Production / Food Processing
- **description:** Produces Garum fish sauce from Mackerel and Salt.
- **requiredPopulationTier:** [Plebeians](#tier-ii)
- **inputGoods:** [Mackerel](#good-mackerel), [Salt](#good-salt)
- **outputGoods:** [Garum](#good-garum)
- **unlockCondition:** Plebeians
- **specialists:** Fischdozentin (+10% productivity for Garum chain)

---

### Flax Farm (Albion) {#building-flax-farm-albion}

- **Entity Type:** Building
- **region:** Albion
- **category:** Production / Farm
- **description:** Produces Flax for clothing production chains.
- **requiredPopulationTier:** Nobles (Tier 5 Celtic)
- **buildCost:** `{ goods: [{ good: "Planks", amount: 1 }, { good: "Bricks", amount: 2 }, { good: "Concrete", amount: 2 }] }`
- **maintenance:** `{ gold: -8, workforce: [{ tier: "Waders", count: 3 }] }`
- **dimensions:** 4x5 (base), 6x7 (with roads)
- **placementConstraints:** Fields required
- **aqueductSupport:** Yes (can be improved with aqueduct connection)
- **inputGoods:** none
- **outputGoods:** [Flax](#good-flax)
- **cycleTimeSeconds:** 90
- **unlockCondition:** Nobles
- **specialists:** Irrigator (-50% water consumption), Excellent Hair Artist (+20% productivity for Wigs chain), Princeps of Porphyry (+20% productivity for Togas chain), Tullus Caecilius Cornutus (-40% workforce, -80% maintenance), Casponia Casta (+25% productivity, +1 Flax every 10 cycles, +1 Faith area effect, requires Ceres as island god)

---

### Cockle Picker (Albion) {#building-cockle-picker}

- **Entity Type:** Building
- **category:** Production / Food (Fishery analogue)
- **description:** Coastal gatherer producing Cockles for Waders.
- **requiredPopulationTier:** [Tier I](#tier-i)
- **buildCost:** `Unknown` (research says “similar to Fishing Hut”, but not hard numbers)  [oai_citation:42‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **maintenance:** `Unknown`
- **workforce:** `Unknown`
- **placementConstraints:** Coast (Albion)  [oai_citation:43‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **cycleTimeSeconds:** `Unknown (reported ~60s but not asserted)`
- **usagePatterns:** Albion starter food option.
- **commonPitfalls:** Confusing coast vs marsh producers in Albion.  [oai_citation:44‡research_3.txt](sediment://file_00000000e73871f6bf8844e9c7de47e3)

---

### Eel Grabber (Albion) {#building-eel-grabber}

- **Entity Type:** Building
- **category:** Production / Food (Marsh fishery)
- **description:** Marshland fish producer (Eels).
- **requiredPopulationTier:** [Tier I](#tier-i)
- **buildCost:** Unknown
- **maintenance:** Unknown
- **workforce:** Unknown
- **placementConstraints:** Marshland placement required (Albion-specific).  [oai_citation:45‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **cycleTimeSeconds:** `Unknown (likely 60s per research wording; not asserted as fact)`  [oai_citation:46‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **usagePatterns:** Place in marsh; pair with coastal cockles early.
- **commonPitfalls:** Trying to place on coast; marsh-only building.  [oai_citation:47‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

---

### Oat Farm {#building-oat-farm}

- **Entity Type:** Building
- **category:** Production / Agriculture
- **description:** Produces Oats; uses field modules; aqueduct optional.
- **requiredPopulationTier:** [Tier I](#tier-i)
- **buildCost:** `{ goods: [{ good: "Timber", amount: 3 }] }`  [oai_citation:48‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **constructionTime:** Instant  [oai_citation:49‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **maintenance:** `{ goldPerMin: -4, workforce: [{ tier: "Tier I", count: 3 }] }`  [oai_citation:50‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **workforce:** `[{ tier: Tier I, count: 3 }]`  [oai_citation:51‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **placementConstraints:** Requires fields; requires relevant fertility (oat/grain).  [oai_citation:52‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **roadRequired:** true  [oai_citation:53‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **warehouseRequired:** true  [oai_citation:54‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **inputGoods:** none
- **outputGoods:** [Oats](#good-oats)
- **cycleTimeSeconds:** 60  [oai_citation:55‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **productionChain:** [Chain: Porridge](#chain-porridge)
- **unlockCondition:** Tier I
- **usagePatterns:** Keep fields compact; warehouse nearby; consider aqueduct support.
- **commonPitfalls:** Insufficient fields/fertility ⇒ low output; long travel distance ⇒ apparent underproduction.

---

### Porridge Stand {#building-porridge-stand}

- **Entity Type:** Building
- **category:** Production / Food
- **description:** Converts Oats → Porridge.
- **requiredPopulationTier:** [Tier I](#tier-i)
- **buildCost:** `{ goods: [{ good: "Timber", amount: 2 }] }`  [oai_citation:56‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **constructionTime:** Instant  [oai_citation:57‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **maintenance:** `{ goldPerMin: -8, workforce: [{ tier: "Tier I", count: 2 }] }`  [oai_citation:58‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **workforce:** `[{ tier: Tier I, count: 2 }]`  [oai_citation:59‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **placementConstraints:** Needs road/warehouse.
- **roadRequired:** true  [oai_citation:60‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **warehouseRequired:** true  [oai_citation:61‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **inputGoods:** [Oats](#good-oats)
- **outputGoods:** [Porridge](#good-porridge)
- **cycleTimeSeconds:** 60  [oai_citation:62‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **productionChain:** [Chain: Porridge](#chain-porridge)
- **unlockCondition:** Tier I
- **usagePatterns:** Pair 1:1 with Oat Farms for balanced flow (both 60s).
- **commonPitfalls:** Oats delivered too slowly ⇒ porridge “flicker” and population drops.

---

### Hemp Farm {#building-hemp-farm}

- **Entity Type:** Building
- **category:** Production / Agriculture
- **description:** Produces Hemp for Tunics; uses fields; aqueduct optional.
- **requiredPopulationTier:** [Tier I](#tier-i)
- **buildCost:** `{ goods: [{ good: "Timber", amount: 2 }] }`  [oai_citation:63‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **maintenance:** `{ goldPerMin: -4, workforce: [{ tier: "Tier I", count: 3 }] }`  [oai_citation:64‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **placementConstraints:** Fields + correct fertility.  [oai_citation:65‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **roadRequired:** true  [oai_citation:66‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **warehouseRequired:** true  [oai_citation:67‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **outputGoods:** [Hemp](#good-hemp)
- **cycleTimeSeconds:** 60  [oai_citation:68‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **productionChain:** [Chain: Tunics](#chain-tunics)
- **usagePatterns:** Keep close to Spinner; reduce hauling delays.
- **commonPitfalls:** Too few fields or long hauling times ⇒ spinner starvation.

---

### Spinner {#building-spinner}

- **Entity Type:** Building
- **category:** Production / Clothing
- **description:** Converts Hemp → Tunics; provides local income area effect.
- **requiredPopulationTier:** [Tier I](#tier-i)
- **buildCost:** `{ goods: [{ good: "Timber", amount: 2 }] }`  [oai_citation:69‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **maintenance:** `{ goldPerMin: -8, workforce: [{ tier: "Tier I", count: 3 }] }`  [oai_citation:70‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **inputGoods:** [Hemp](#good-hemp)
- **outputGoods:** [Tunics](#good-tunics)
- **cycleTimeSeconds:** 30  [oai_citation:71‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **areaEffects:** `[{ type: "IncomeAreaEffect", value: +1, target: "Nearby buildings (incl residences)", radius: "Unknown" }]`  [oai_citation:72‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **productionChain:** [Chain: Tunics](#chain-tunics)
- **usagePatterns:** Place near residences to maximize income area effect.
- **commonPitfalls:** Spinner output can be fine while income effect is wasted if placed far from housing.

---

### Bakery {#building-bakery}

- **Entity Type:** Building
- **category:** Production / Food (Tier II)
- **description:** Produces Bread (Tier II staple); high upkeep.
- **requiredPopulationTier:** [Tier II](#tier-ii)
- **buildCost:** `Unknown in supplied snippets` (but bakery upkeep is explicitly given)  [oai_citation:73‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **maintenance:** `{ goldPerMin: -14, workforce: [{ tier: "Tier II", count: 3 }] }`  [oai_citation:74‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **inputGoods:** `Unknown (Flour + Charcoal implied by chain text)`  [oai_citation:75‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **outputGoods:** `Unknown (Bread)`  [oai_citation:76‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **cycleTimeSeconds:** 60 (from bread chain summary)  [oai_citation:77‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **usagePatterns:** Only scale to actual consumption; bakeries are a common cashflow killer.
- **commonPitfalls:** Overbuilding bakeries ⇒ negative income swings; missing charcoal ⇒ “mystery” bread shortages.  [oai_citation:78‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

---

## Production Chains

### Chain: Timber {#chain-timber}

- **Entity Type:** ProductionChain
- **steps:**
  - `{ building: [Woodcutter Hut](#building-woodcutter-hut), in: [], out: ["Logs"], cycleSeconds: 30 }`  [oai_citation:79‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
  - `{ building: [Sawmill](#building-sawmill), in: ["Logs"], out: [Timber](#good-timber), cycleSeconds: 30 }`  [oai_citation:80‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **recommendedRatios:** Woodcutter 1 : Sawmill 1 (matching 30s cycles)  [oai_citation:81‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **bottlenecks:** Forest density (Woodcutter placement)  [oai_citation:82‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

### Chain: Tier I Food {#chain-tier-i-food}

- **Entity Type:** ProductionChain
- **steps:**
  - `{ building: [Fishing Hut](#building-fishing-hut), in: [], out: [Sardines](#good-sardines), cycleSeconds: 60 }`  [oai_citation:83‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
  - `{ building: [Oat Farm](#building-oat-farm), in: [], out: [Oats](#good-oats), cycleSeconds: 60 }`  [oai_citation:84‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
  - `{ building: [Porridge Stand](#building-porridge-stand), in: [Oats](#good-oats), out: [Porridge](#good-porridge), cycleSeconds: 60 }`  [oai_citation:85‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **notes:** Many Tier I settlements produce both Sardines and Porridge to maximize population.  [oai_citation:86‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

### Chain: Porridge {#chain-porridge}

- **Entity Type:** ProductionChain
- **steps:**
  - Oat Farm (60s) → Oats  [oai_citation:87‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
  - Porridge Stand (60s) + Oats → Porridge  [oai_citation:88‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **recommendedRatios:** Oat Farm 1 : Porridge Stand 1 (both 60s)
- **bottlenecks:** Field layout, fertility, hauling distance.  [oai_citation:89‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

### Chain: Tunics {#chain-tunics}

- **Entity Type:** ProductionChain
- **steps:**
  - Hemp Farm (60s) → Hemp  [oai_citation:90‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
  - Spinner (30s) + Hemp → Tunics  [oai_citation:91‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **recommendedRatios:** `Unknown` (cycle mismatch suggests multiple spinners can consume one farm; exact throughput not given in files)
- **notes:** Spinner provides an income area effect (+1) near buildings.  [oai_citation:92‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

### Chain: Bread (summary) {#chain-bread}

- **Entity Type:** ProductionChain
- **steps (summary only):**
  - Wheat Farm (60s) → Grain
  - Grain Mill (30s) → Flour
  - Bakery (60s) + (requires Charcoal) → Bread  [oai_citation:93‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **recommendedRatios:** 2 Wheat : 1 Mill : 2 Bakeries  [oai_citation:94‡research_3.txt](sediment://file_00000000e73871f6bf8844e9c7de47e3)
- **bottlenecks:** Charcoal availability; bakery upkeep.  [oai_citation:95‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  [oai_citation:96‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

---

## Trade & Logistics

### Entity: TradeRoute {#entity-traderoute}

- **Entity Type:** SystemEntity
- **description:** Automated ship loop moving goods between islands.
- **configuration:**
  - Select ship
  - Enable Trade Route
  - Assign goods per cargo slot
  - Assign islands for load/unload
- **rules:**
  - Route loops indefinitely
  - Used to supply production chains across islands
- **usagePatterns:** Specialize islands (agricultural vs industrial) and route goods accordingly.  [oai_citation:97‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **commonPitfalls:** Under-shipping (not enough cargo throughput) ⇒ need flicker and income oscillation.

### Entity: DiplomaticTrade {#entity-diplomatictrade}

- **Entity Type:** SystemEntity
- **description:** Passive buy/sell orders at Trading Post with AI via treaties.
- **configuration:** Set fixed buy/sell orders, price, quantity.  [oai_citation:98‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
- **usagePatterns:** Monetize surplus production; import hard-to-get goods.  [oai_citation:99‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

---

## Ships & Naval

### Shipyard (system) {#system-shipyard}

- **Entity Type:** SystemEntity
- **description:** Ships are constructed in a Shipyard; construction consumes resources and time.
- **rule:** Insufficient workforce slows ship construction.  [oai_citation:100‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

### Hulls {#naval-hulls}

#### Penteconter {#hull-penteconter}
- **Entity Type:** ShipHull
- **sizeClass:** Small
- **moduleSlots:** 2  [oai_citation:101‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
- **notes:** Fewer slots; cheaper; likely faster acceleration.

#### Trireme {#hull-trireme}
- **Entity Type:** ShipHull
- **sizeClass:** Medium
- **moduleSlots:** 3  [oai_citation:102‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

#### Quinquireme {#hull-quinquireme}
- **Entity Type:** ShipHull
- **sizeClass:** Large
- **moduleSlots:** 4  [oai_citation:103‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
- **notes:** More capacity and HP; slower acceleration.  [oai_citation:104‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

### Modules {#naval-modules}

#### Mast {#module-mast}
- **Entity Type:** ShipModule
- **effect:** +long-distance speed (wind)  [oai_citation:105‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

#### Rows (Oars) {#module-rows}
- **Entity Type:** ShipModule
- **effect:** +base speed, acceleration, maneuver  [oai_citation:106‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
- **tradeoffs:** Consumes more crew than sails.  [oai_citation:107‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

#### Reinforced Hull {#module-reinforced-hull}
- **Entity Type:** ShipModule
- **effect:** +health/durability  [oai_citation:108‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

#### Archer Tower {#module-archer-tower}
- **Entity Type:** ShipModule
- **effect:** short-range multi-arrow attack (all-around)  [oai_citation:109‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
- **tradeoffs:** Requires more soldiers/crew.  [oai_citation:110‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

#### Scorpio {#module-scorpio}
- **Entity Type:** ShipModule
- **effect:** side-mounted high-damage spears (medium range)  [oai_citation:111‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

#### Onager {#module-onager}
- **Entity Type:** ShipModule
- **effect:** forward catapult (long range, high damage, low accuracy)  [oai_citation:112‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

### Ship Design Slots {#naval-design-slots}

- **rule:** Save up to 2 custom designs per hull per shipyard (6 total).  [oai_citation:113‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
- **rule:** Ships cannot be refitted after building (per research text).  [oai_citation:114‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

---

## Specialists

### Specialist System (general) {#system-specialists}

- **Entity Type:** SystemEntity
- **description:** Specialists slot into certain buildings and modify stats (productivity, workforce, upkeep, etc.).
- **known effect examples:** +25% productivity, −25% workforce needed (examples referenced)  [oai_citation:115‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **sources:** Obtained via quests, events, or trade.  [oai_citation:116‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

### Uiscarix, Hygiean Fishmonger {#specialist-uiscarix-hygiean-fishmonger}

- **Entity Type:** Specialist
- **rarity:** Epic (from user screenshot)
- **category:** Finance (from user screenshot)
- **slotType:** Specialist (from user screenshot)
- **scope:** Fisheries in range (from user screenshot)
- **effects:**

| Effect Type | Target | Value | Scope |
|------------|--------|-------|-------|
| Income Area Effect | Fisheries | +1.5 | Radius-based |

- **improvesBuildings:**
  - [Eel Grabber](#building-eel-grabber)
  - [Oyster Bed](#building-oyster-bed) *(not defined in supplied files; placeholder)*
  - [Cockle Picker](#building-cockle-picker)
  - [Scomber's Shack](#building-scombers-shack) *(placeholder)*
  - [Fishing Hut](#building-fishing-hut)
  - [Sturgeon Hatchery](#building-sturgeon-hatchery) *(placeholder)*

- **stackRules:** Unknown (not present in supplied files)
- **usagePatterns:** Slot into a coastal hub building covering many fisheries.
- **commonPitfalls:** Misplaced radius ⇒ zero value; does not fix overproduction warnings.

---

## Economy & Diagnostics

### Maintenance Model {#system-maintenance}

- **rule:** Nearly every building has ongoing gold + workforce maintenance.  [oai_citation:117‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **example:** Fishing Hut costs −6 gold/min and uses 4 Tier I workers.  [oai_citation:118‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **example:** Bakery costs −14 gold/min and uses 3 Tier II workers.  [oai_citation:119‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **rule:** Deleting buildings stops upkeep and frees workforce.  [oai_citation:120‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

### Area Effects {#system-area-effects}

- **rule:** Buildings can give positive/negative proximity modifiers (shown by green/red arrows on placement).  [oai_citation:121‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **example:** Spinner gives income boost near buildings.  [oai_citation:122‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **example:** Polluters (e.g., Charcoal Burner) decrease happiness/health (mentioned).  [oai_citation:123‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

### Statistics Screen {#system-statistics-screen}

- **rule:** Use statistics to compare production vs consumption; overproduction flagged (e.g., “too much Sheep”).  [oai_citation:124‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
- **diagnostic:**  
  - Green bar high ⇒ overproduction ⇒ export/demolish/disable  
  - White bar high ⇒ shortage ⇒ add buildings or fix logistics  [oai_citation:125‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)

---

## Monuments

### Amphitheatre {#monument-amphitheatre}

- **Entity Type:** Building (Monument)
- **unique:** One per island (reported)  [oai_citation:126‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **unlockCondition:** Patricians exist (Tier IV)  [oai_citation:127‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **construction:** 4 stages; large time + resources; later stages require expensive materials (marble/glass/iron mentioned)  [oai_citation:128‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **effects (complete):** +3 Population, +3 Happiness, +7 Prestige (large radius)  [oai_citation:129‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **events:** Hosts events (local games / grand games / naumachia) consuming goods/workforce for city buffs.  [oai_citation:130‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
- **commonPitfalls:** Starting monument too early can bankrupt you (maintenance + diverted materials).

---

## Troubleshooting Playbooks

### Playbook: “My income is bouncing up and down” {#playbook-income-bouncing}

1. **Check upkeep spikes:** did you place a high-upkeep building (e.g., Bakery)?  [oai_citation:131‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
2. **Check need flicker:** are food/clothing stocks dipping to zero intermittently? (storage/transport)  [oai_citation:132‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
3. **Check workforce:** red hammer / missing tier workers after upgrades.  [oai_citation:133‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
4. **Open Statistics Screen:** verify production vs consumption bars.  [oai_citation:134‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)  
5. **Fix by priority:** Tier I Food → Tier I Fashion → Tier II staple chains.

### Playbook: “Game says I have too much Sheep” {#playbook-too-much-sheep}

1. Confirm overproduction in Statistics Screen.  [oai_citation:135‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)  
2. Add/scale downstream processor (Felter) if present in your build.  
3. Export surplus via trade routes or diplomatic orders.  [oai_citation:136‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)  
4. Demolish/disable extra farms to stop upkeep drain.  [oai_citation:137‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  

### Playbook: “Why are my houses not upgrading?” {#playbook-houses-not-upgrading}

1. Ensure at least one need per category is met.  [oai_citation:138‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
2. Ensure service buildings’ area coverage includes houses (roads/range).  [oai_citation:139‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
3. Ensure storage has the goods (not just “producing”, but delivered).  [oai_citation:140‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  

---

## Glossary

- **Need Flicker:** A need repeatedly turning on/off because storage hits zero intermittently.
- **Area Effect:** Radius-based modifier from a building or specialist (income, happiness, safety).
- **Upkeep:** Ongoing gold loss and workforce reservation for a building.
- **Throughput:** Effective goods per time, impacted by cycle time and logistics.
- **Warehouse Cloud:** Shared island storage accessible via connected warehouses/trading post.  [oai_citation:141‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)

---

## Placeholders (defined for linking; no data in supplied files)

### Oyster Bed {#building-oyster-bed}
- **Entity Type:** Building
- **status:** Placeholder (no stats in supplied research files)

### Scomber's Shack {#building-scombers-shack}
- **Entity Type:** Building
- **status:** Placeholder (no stats in supplied research files)

### Sturgeon Hatchery {#building-sturgeon-hatchery}
- **Entity Type:** Building
- **status:** Placeholder (no stats in supplied research files)