Colonym · Flow Map · Excavation → Residency

Digging a Room → An NPC Moves In

The full path from a pickaxe hitting a tile to a named resident standing in the room. The surprise: every step here is static or procedural — the only real LLM call (NPC dialogue) happens after move-in and is usually mocked. Whether an NPC actually moves in comes down to a single 70% dice roll per newly-detected room. Click any node for its source, gating logic, and the data it hands downstream; click a data chip to trace how world → room → npc flows through the pipeline.

Static content User input User reaction AI call AI synthesis (handoff) Branch point

Context Inspector

Click a data field to highlight every node that produces (solid green) or consumes (dashed blue) it. Makes the "one comment amplified across five prompts" problem visible.

Produces Consumes

Notes & caveats

Digging does not directly trigger anything. digTile only mutates the world grid (tile → AIR, materials → inventory). Room detection is a separate pass — fired by the Scan button or a periodic check — so there is real latency and indirection between carving a space and the game noticing it.

Eligibility gates (a room must clear all of these to host a resident):
• Flood-fill region of 9–100 tiles, enclosed (≥60% perimeter, gaps ≤3 tiles for doors) — else no Room object exists.
• Room must be "truly new" — its tile set must not match any room already in state (compared via JSON.stringify(tiles.sort())).
• Math.random() < 0.7 — a 70% per-room dice roll.
• npcs.length < maxNPCs (25) — global resident cap.

A skipped room is permanent. The dice roll happens only for new rooms, and the room is committed to state on the same pass whether or not an NPC spawns. So a room that loses the ~30% roll is no longer "new" next pass and will never re-roll — it stays empty unless its tile set physically changes.

No "AI" in this flow. NPC creation routes through aiService.generateNPC(), but the active implementation is MockAIService — name, role, personality, and skills are drawn from hardcoded pools keyed by room type. The genuine Claude pathway (ClaudeAIService.generateDialogue → /api/npc-dialogue, model claude-3-haiku-20240307) only runs after move-in, when the player talks to an NPC, and only if an API key is present. NPC offers (binary choices) are likewise post-move-in and fully hardcoded. Both are out of scope for this map.

Source files: src/components/Game.tsx (dig & scan triggers, lines 651–840), src/hooks/useGameState.tsx (digTile 354–534, detectAndUpdateRooms 630–752, spawn gate 651–661, commit 739–747), src/utils/roomDetection.ts (flood-fill 14–104, determineRoomType 197–239), src/systems/smartBuilding.ts (analyzeRoomFunctionality 19–157), src/utils/aiService.ts (MockAIService.generateNPC 23–64, role map 191–203, placement 400–403), src/components/EnhancedNPCRenderer.tsx (canvas render).