Maps: turn the building into a castle (or a map of your own), with a throne, a line of waiting workers and peasants who age as they work

[webdevcody]

Maps: the building can be something other than the office — starting with a castle

Under ⚙️ Settings → 🏢 Building → Map, anyone can change what the whole building looks like inside, for everyone on every floor, and back again. Everything that makes the office work comes along unchanged: workers and their terminals, the issues / PR / queue / services boards and their board agents, the task queue, meetings, the merge gong, PRs, budget and limits.

🏰 The castle

• The hall. A long stone hall under a timber roof. It has:
  • clustered pillars with pointed arches down both sides;
  • stained glass high in the walls and a rose window;
  • banners in each project's colours, the great one behind the throne carrying the project's name;
  • chandeliers, torches, braziers and a hearth;
  • stone knights and suits of armour;
  • great arched doors, and a red carpet up the middle.
• A throne of iron blades stands on a dais at the far end. You arrive seated on it, and stay on it across floor switches and reloads.
• The line.
  • A worker that's done, or needs input, gets up from its table and walks to the line before the throne. Whoever has waited longest is at the front (the same order as N).
  • From the throne, E is for whoever's first in line; P, O, X and C work as at a desk.
  • Once it's been seen to, it walks back to its seat and the others shuffle up.
• The Hand of the King stands at your left.
  • Speak to him with E beside him, or K from the throne. Say what a new worker should do, and it runs off to the first free seat at the tables. Everyone sees it run.
  • Hand him an issue card and he sends someone out for it.
  • Queue-hired workers come in through the great doors. Workers sent home walk out through them, box in arms.
• Peasants who wear out.
  • Workers wear a smock, rope belt and coif.
  • The longer one has worked, the more spent it looks. This is cumulative working time, tracked by the server and kept through restarts.
  • It shows as a beard that grows from brown to grey to white and down to the floor, dirt, patched clothes, bushy brows, bags under the eyes, a hunch and a slower shuffle. It's complete after 30 minutes of work.
• The rest of the hall:
  • Long tables with benches. Laptops become leather tomes that show the live terminal.
  • Scribes at lecterns under the boards on the side walls (the board agents).
  • A "small council" round table for meetings, with its easel board.
  • The gong by the dais, and ale by the hearth (it works like the office's coffee).
  • Its own warm, torchlit lighting (no rain indoors), and its own sounds.

Maps are configuration

• A map is plain data (MapConfig, in src/shared/maps/). The castle itself is just src/shared/maps/castle.ts.
• Your own maps. Drop a JSON file in the office's .agent-office/maps/. You can either:
  • extend a built-in map and change a few numbers, e.g. { "id": "my-hall", "name": "My hall", "extends": "castle", "boards": { "issues": { "z": 3 } }, "stations": { "issues": { "z": 3 } } }; or
  • start from docs/maps/castle.json, a full copy of the castle to edit, which a test keeps in sync.
• Loading and errors.
  • The folder is re-read whenever someone opens Settings or joins, so no restart is needed.
  • A map that won't load is listed with the reason: bad JSON, too few seats, something outside the hall or inside furniture, a prop reaching over the walls, an unknown prop kind, extending itself, and so on.
  • If the building was on it, the building falls back to the office and returns once the file is fixed.
• Seats are map-agnostic. Every map places the office's own seat ids (16 desks, 12 overflow seats, the 3 board agents, 5 meeting chairs). So the server, the queue, meetings and saved workers work on any map, and a map can change while workers are working.
• Adding a new style takes no main.ts changes. Register a builder in src/client/world/styles.ts that returns a World. New prop kinds go in an exhaustive table, so a missing builder won't compile. Details are in docs/maps.md.

How it's built

• src/shared/maps/:
  • the schema, the castle, and the prop kinds (footprints, heights);
  • planMap, which validates every field the builder reads and works out where every seat, lectern, line spot and board goes, plus what's in the way;
  • extends resolution and custom-map checking.
• src/shared/nav.ts: refactored into a NavGrid class, so any map gets its own walk grid. The office's behaviour and API are unchanged (checked against the old version on 12k random calls).
• src/server/maps.ts:
  • the building's pick, kept in .agent-office/map.json;
  • map.set / map messages;
  • seats are validated against the current map;
  • a taken seat is refused (sit.refused).
• src/server/workers.ts: keeps workedMs / workingSince for every worker.
• src/client/world/world.ts: the World interface that main.ts uses (seats, boards, colliders, walks in and out, confetti, room, sounds, lighting, herald, dispose). The office is adapted to it.
• main.ts: swaps worlds at runtime, the way it already swaps in the rooftop. Office-only features (elevator, garage, roof, ladder and poles, balcony, jukebox, dog, pictures, basketball) are gated to the office.
• The castle, client side:
  • src/client/world/castle.ts, the builder;
  • court.ts, workers walking between their seats and the line;
  • the peasant outfit and ageing on Worker;
  • a tome style for the laptop;
  • a placeable gong;
  • Sky.setIndoors;
  • map-aware camera bounds and sounds.

Reviews

Three review rounds, each with independent reviewers, and every finding fixed:

• Round 1: the main.ts integration, the castle/court/looks code, and the shared maps and server code.
• Round 2: multiplayer and lifecycle edge cases, a fresh bug hunt over the whole diff, and architecture against the "new maps without code changes" goal.
• Round 3: checked that the fixes were correct, that the office didn't regress, and walked through the original brief end to end.

Notable fixes from the reviews:

• Hardening against custom maps that could hang browsers.
• Only one person on the throne at once.
• New hires that never walked to their seats.
• A ride / switchFloor loop.
• Map changes mid-trip.
• A Web Audio crash.

Testing

• npm run typecheck, npm run build and npm test all pass (294 tests).
• New tests/maps.test.ts covers:
  • every built-in map places every seat id with the same roles;
  • every castle seat can walk to the door and to every line spot, and back;
  • extends merging and null removal;
  • custom-map errors, including configs that would hang a browser;
  • the castle JSON copy staying in sync;
  • every map in the docs loading;
  • the work clock.
• Headless-Chrome smokes against a scratch server checked:
  • arriving on the throne;
  • fake workers in every state walking to the line in order, and back when answered;
  • sending one home from the line (out through the doors);
  • hiring through the Hand (the worker runs from beside him), and K from the throne with a line;
  • E at an empty seat, the council table, a lectern, the ale and the gong;
  • two floors in the castle (the floor menu has no roof);
  • a custom map and a broken one;
  • switching office ↔ castle live (the office comes back as it was);
  • about 110–220 fps on the GPU.

🤖 Generated with Claude Code