demo-anno: Product Brief¶
Status: approved (W-016).
Target app: apps/demo-anno. Refs: concept §8.
1. Vision¶
Player builds a small Anno-style settlement on an island: placing producers, a warehouse, and houses, watching goods flow along production chains, and growing the population until it reaches the settlement goal.
2. Audience and purpose¶
- Audience: developers learning ECS / flecs concepts on koota. The demo must still be a relaxing 10–15 minute city-builder session on its own.
- Teaches: world-level singletons (treasury, game clock), exclusive relations (
StoredIn: a good is in exactly one place), relation target filters (everything stored in this building),Changeddetection for live stock and status displays, a fixed per-tick system pipeline (ecs-schedule), and save/load of a settlement (ecs-serialize).
3. Core loop¶
- User sees the island, the stock of every good, the treasury, and the status of each building.
- Player places a building (producer, warehouse, or house) on a free cell and pays its cost.
- Producers turn inputs into goods; carriers move goods between buildings; the user sees goods pile up, flow, or run short.
- Houses consume food and building material; satisfied settlers pay taxes and move in.
- Player reads the bottlenecks (missing input, full output, nobody to carry) and adds or rearranges buildings.
- Repeat until the settlement goal is reached (or the treasury runs out), then restart.
4. ECS showcase¶
| flecs concept | Shown by | Package |
|---|---|---|
| Entities, components, tags | Buildings with Position, Producer recipe data, Housing; Warehouse / Idle / Blocked tags (ANNO-F01, ANNO-F02) |
koota |
| Singletons | Treasury and game clock as world-level traits (ANNO-F01, ANNO-F05) | koota |
| Exclusive relations | StoredIn(building): moving a good to another building replaces its old location (ANNO-F03) |
koota |
| Relation target filters | "All goods stored in this warehouse" and "all goods of this kind anywhere" for stock counts and carrier pick-up (ANNO-F03, ANNO-F05) | koota |
| Pipeline phases, ordered systems | Per-tick pipeline: produce → carry → consume → economy, with pause and speed control (ANNO-F02, ANNO-F05) | ecs-schedule |
Changed queries |
Stock counters and building status badges update only when the data changed (ANNO-F05) | koota |
| Observers | Messages like "Sawmill has no wood" on trait add/remove (ANNO-F05) | koota |
| Serialization | Save and resume a settlement (ANNO-F08) | ecs-serialize |
| Explorer-style inspection | Live entity/trait/relation panel (ANNO-F10) | ecs-devtools |
5. Backlog¶
| ID | Feature | Milestone | Work |
|---|---|---|---|
| ANNO-F01 | User sees an island grid with a starting treasury, and player can place and demolish buildings (Lumberjack, Sawmill, Fisher, Warehouse, House) on free cells for a cost | M1 | |
| ANNO-F02 | User sees producers work in cycles: a Lumberjack makes Wood, a Sawmill turns Wood into Planks, a Fisher makes Fish; each building shows progress and a reason when it is idle (missing input, output full) | M1 | |
| ANNO-F03 | User sees carriers move goods from producers to the buildings that need them or to the warehouse, and every good is in exactly one place at a time | M1 | |
| ANNO-F04 | User sees houses consume Fish and Planks from supply; satisfied houses pay taxes and grow their population, unsatisfied houses stall and lose income | M1 | |
| ANNO-F05 | User sees a HUD with stock per good, treasury, income per cycle, and population; player can pause and change the game speed; the user is told which building is starved or blocked | M1 | |
| ANNO-F06 | User sees a settlement goal (e.g. population 50) and victory or bankruptcy, and can restart | M1 | |
| ANNO-F07 | Player can settle a second island and ship goods between the two islands' warehouses | M2 | |
| ANNO-F08 | Player can save a settlement and resume it after reload | M2 | |
| ANNO-F09 | Player can control the whole game from the keyboard with on-screen key hints | M2 | |
| ANNO-F10 | User can open a devtools panel listing entities, traits, and StoredIn pairs live |
M2 | |
| ANNO-F11 | Player can pick the scenario (island, start budget, goal) from a list in content data | M2 | |
| ANNO-F12 | Player can upgrade houses to a second settler tier with new needs (e.g. Tools, Bread) and longer chains | later | |
| ANNO-F13 | Player can trade with AI merchants at fluctuating prices | later | |
| ANNO-F14 | User sees roads, building coverage radii, and path-based carriers | later |
M1 order: ANNO-F01, ANNO-F02, ANNO-F03, ANNO-F04, ANNO-F05, ANNO-F06.
Notes:
- Every M1 action (placing, demolishing, pause, speed) must already be keyboard-reachable (demo rule); ANNO-F09 adds hints and polish.
- Dependency/risk (timing): ecs-schedule v0 has no intervals, rates, or fixed step (concept §8). Production cycles and tax ticks therefore run from the game clock's dt and per-building timers in the demo. The brief does not need the schedule to grow.
- Dependency/risk (ANNO-F08): needs the ecs-serialize implementation, whose spec is done. The core loop stays playable without it, hence M2.
- Dependency/risk (ANNO-F10): needs ecs-devtools v0. Moved to M2 so M1 depends only on koota and ecs-schedule.
- Dependency/risk (ANNO-F07): a second island means two settlements with separate stock in one world; the spec decides how they are told apart.
6. Non-functional targets¶
- Performance: up to 40 buildings and 500 goods entities on one island of at most 24×24 cells; UI stays at 60 FPS at the fastest game speed; one game tick resolves in under one frame of logic.
- Accessibility: all actions, including placement and demolishing, keyboard-reachable; WCAG AA contrast; building status and shortages shown as text, not color alone; grid cells have text labels for their occupant.
- Persistence: M1 none. M2 saves the full settlement (buildings, goods and
StoredInpairs, production timers, treasury, clock, population) viaecs-serialize.
7. Path to a real app¶
- Building, recipe, and good definitions, costs, and goals live in
src/content/and can be swapped for other data files. - Game clock behind one seam, so the pipeline can be driven by a fixed-step schedule once it exists, or by tests, and ticks can be replayed.
- Tick pipeline as
ecs-schedulephases, so new phases (ships, events, upkeep) slot in without rewriting systems. - Carrier assignment behind one decision function (M1: nearest need), replaceable by path-based logistics later.
- World state serializable, leaving room for multiple settlements and scenarios.
8. Out of scope¶
- Roads, pathfinding, building coverage radii, and terrain in M1 (see ANNO-F14).
- Settler tiers and upgrades, trade with AI merchants, random events, and diplomacy in M1.
- Ships and a second island in M1 (see ANNO-F07).
- More goods than Wood, Planks, and Fish in M1.
- Combat, campaigns, and multiplayer.
- 3D rendering (R3F) and animation polish; plain 2D UI only.