> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/docs/game-design/04-world-map-and-combat-systems.md). # World Map And Combat Systems **Project:** FactionOS — The War Effort **Document role:** World systems spec / combat model ## 5. Territory & The Living Map The single 16:9 board (exists) evolves into a **territory map of the actual repository**. This is the second-biggest fun idea: * **Map sectors = top-level directories / workspaces** of the repo(s) the agents work in (file\_access + file\_read events already carry paths; MissionHeatmap already aggregates this). * A sector **clears** (fog pushed back, faction banner colors it) as heroes complete missions touching it; it **re-fogs slowly** if untouched for weeks and *actively corrupts* if the scanner finds new issues there. * **Buildings** (faction building names exist: Stronghold/Keep/Tree of Life/Necropolis...) anchor the home sector and **level up from cumulative real output**: * *War Mill / Workshop / Salt Forge* levels with Edit/Write volume → visual upgrades (bigger smoke, banners) + loot-roll luck bonus. * *Arcane Sanctum / Ancient of Lore / Temple of the Damned* levels with plans completed → unlocks plan-ritual cosmetics. * *Beastiary / Hunter's Hall / Crypt* levels with subagent (Task) usage → peon skins. * *Library (all factions)* levels with scroll collection → reveals tome lore pages (flavor content drip). * **Multi-project = multi-front war.** Each cwd/project the player runs agents in is a **front** with its own mini-map tab; the war spans fronts. *Implementation posture: this stays within the shipped 2D DOM/CSS contract (docs/battlefield.md scope decisions) — sectors are DOM regions over the board art; no engine change required for v1.* **Existing generated asset references:** check `manifest.md` before creating new map, combat, or home-sector art. `assets/generated/game-design/phase03/live-enemies/live-enemy-effects-sheet.png` is available for live enemy markers, ram/wraith/siege pressure, scrying, strike impacts, combo stages, shield breaks, and blank status frames. `assets/generated/game-design/phase03/strike-vocabulary/strike-vocabulary-effects-sheet.png` is available for tool-family strike vocabulary and joint-assault trims. `assets/generated/game-design/phase03/reduced-motion/reduced-motion-static-badges-sheet.png` is available for static twins of combat, scrying, alert, siege, boss, loot, alliance, rally, disabled, and fallback states. `assets/generated/game-design/phase07/territory-map/territory-map-base.png` is available as a territory base layer under live sector labels, fog, corruption, tabs, and patrol routes. `assets/generated/game-design/phase07/home-sector/home-sector-building-dressings.png` is available for keep/building dressings with live DOM building names, levels, smoke state, upgrades, and resource counts. `assets/generated/game-design/phase09/siege/siege-set-piece-static.png` is available later as a static twin for dramatic siege states. ## 5A. Combat Resolution — The Fight IS the Stream (second pass) Objective gap in pass one: it said "accept quest → camp burns" but never defined what a *fight looks like* between those two moments. Answer: **there is no simulated combat. The live tool-event stream of the linked mission is played back as the battle.** Deterministic, zero RNG damage, zero fake state: * Accepting a quest **links the mission to the camp**. Third-pass code verification (`questBoardActions.ts`, `missions.ts`, `missionTags.ts`): the pass-two assumption "keep the camp id on it as a tag via missionTags" is **wrong** — `missionTags.ts` is pure client-side *regex inference* over prompt text; `Mission` has no tags field at all. The real mechanism is better and needs zero protocol change: the accept response (`SuggestionAcceptRestResponse`) returns the exact `prompt` dispatched to the chosen `heroId` (and the client already knows it up front as `CodebaseIssue.suggestedPrompt`). `Mission.prompt` is documented as the *verbatim* prompt that started the mission. So `gameProjection.ts` records a **pending link** `{campId, heroId, prompt, expiresAt: accept+2min}` on accept success, and binds `missionId → campId` when a `mission_start` arrives whose `heroId` and verbatim `prompt` match (fallback: first mission on that hero inside the window). Deterministic, wire-format untouched, works for older servers. * While that mission runs, each of its real events renders as a strike on the camp: `Edit/Write` = hammer blow, `Bash` = fireball, `Read/Grep` = scouting circle tightening around the camp, `tool_result` error = the camp **counterattacks** (hero knockback flash), `Task` subagent = a peon flanks. * Camp **HP = the scanner finding's issue count/severity**; the HP bar only falls on *plausibly-fixing* events (edits/bashes), and the camp only **dies when the quest completes and verifies** (`task_verification`) — the burn-down + celebration burst (exists) is the kill shot. * If the mission fails, the camp survives, visibly scarred — partial progress is remembered (the next attempt starts against a weakened camp). Repeated survivals feed the nemesis promotion rule (§10, fourth pass). * **Joint assault (fourth pass):** multiple concurrent missions linked to the same camp render as a coordinated siege — each linked hero strikes the same target, strike trims distinguish attackers, and a verified kill credits a banner to *every* linked hero. (Previously undefined; the linkage model already permits it since `campLinks` is mission-keyed.) Why this is the right resolution model: it makes a running mission *genuinely entertaining to watch* (the single weakest moment in pass one — watching was passive), it costs almost nothing (every input event already streams), and it cannot lie (Fun Law 1: no fight happens that isn't real work happening). ## 5B. Reality Constraints (second pass — the shipped surface this must fit) Facts from `docs/battlefield.md` + code the design must respect, with the design answer for each: | Constraint (shipped) | Design answer | | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BATTLEFIELD_HERO_LIMIT = 12` standees on the board | >12 heroes = the overflow **garrisons the keep** (roster chip with count); garrison heroes still earn/emit, and any hero with a flare/gate auto-swaps onto the board — urgency always wins a slot | | Positioning: `x,z ∈ -5..5` → clamped % of a 16:9 DOM board | Sectors are a fixed grid of DOM regions over the board art; a top-level directory hashes to a stable cell, missions touching it position their hero toward that cell. No engine change; stays in the 2D DOM/CSS contract | | Reduced-motion contract (every effect needs a static variant) | Every §3/§5A juice row ships its static twin at design time, not retrofitted: camp HP as a number chip, strikes as state badges, patrol as a dotted line | | Clean/small codebase = no scanner findings = empty Legion | **The Legion floor:** re-fog + ambient *neutral* wildlife keep the map alive, clearly styled non-work (no loot, no urgency). Never fabricate fake issues — an empty Legion is a bragging state, celebrated by a "Golden Age" board treatment (rare, aspirational) | | Public demo is static, no workspace imports | Demo ships a **synthetic front** (scripted Legion + heroes) so the game layer is visible pre-install; mirrors the demo-parity pattern already used | | No baked labels in board/backdrop art | All game additions (camps, pennants, patrols, sector tint, labels, fog, and counters) remain live DOM/CSS layers. Production backdrops from `manifest.md` may be promoted only when the owning phase wires live labels, fallbacks, reduced-motion parity, and provenance/cache records; bespoke enemy art still enters through the media pipeline + provenance gates | **War Games substrate (fourth-pass hold-out graduation).** The synthetic demo front above already has its engine shipped: the settings mock generator / seed-data toggles (previously held out in `12-utility-admin-holdout-inventory.md` as dev controls). Framed as **War Games** — a clearly bannered drill mode driving the scripted Legion and heroes for the public demo and for showing the game layer pre-install. Hard guard: drill events must never accumulate into the persisted `gameProjection` (same posture as the §14.9 replay honesty guard); War Games mint spectacle, never progress. The adjacent settings/audio/scan *reset* controls remain utility. ## 5C. Implemented Board And Quest Substrate ### Battlefield Code references: `apps/web/src/components/battlefield/Battlefield.tsx`, `apps/web/src/components/battlefield/RemoteParticipantOverlay.tsx`, `apps/web/src/lib/battlefield2d.ts`, `apps/web/src/lib/battlefieldHeroes.ts`, `apps/web/src/store/useWarRoomStore.ts`, `apps/web/public/battlefield/`. Focused tests: `apps/web/tests/Battlefield.test.tsx`, `apps/web/tests/BattlefieldInteraction.test.tsx`, `apps/web/tests/battlefield2d.test.ts`, `apps/web/tests/battlefieldHeroes.test.ts`, `apps/web/tests/WarRoomBattlefieldOverlay.test.tsx`. * The shipped board is a 2D tactical battlefield over a universal 16:9 background. * Visible heroes render as faction standees, falling back to faction initials when standee assets are unavailable. * Hero tokens are native buttons for keyboard-accessible selection; empty terrain clears selection. * Battlefield coordinates map hero world position into responsive screen percentages and scale the visible extent when heroes spread beyond the default coordinate range. * The visible battlefield cap is 12 heroes, prioritized by selected, active, awaiting input, verifying, error, spawning, idle, and dismissed state. * State-specific rings, badges, glows, warning styles, dimming, selected halo, active mission labels, adaptive label placement, and reduced-motion static labels already provide the visual vocabulary for Phase A. * Remote War Room participant markers already overlay on the battlefield. ### Quest Board Code references: `packages/protocol/src/suggestions.ts`, `apps/server/src/managers/suggestionManager.ts`, `apps/server/src/routes/suggestions.ts`, `apps/server/src/lib/idleSuggestionLifecycle.ts`, `apps/server/src/lib/codebaseScanOrchestrator.ts`, `apps/server/src/lib/projectScanEngine.ts`, `apps/web/src/lib/questBoard.ts`, `apps/web/src/lib/questBoardModel.ts`, `apps/web/src/lib/questBoardActions.ts`, `apps/web/src/components/QuestBoard.tsx`, `apps/web/src/store/useGameStore.ts`. Focused tests: `apps/server/tests/suggestionRoutes.test.ts`, `apps/server/tests/suggestionManager.test.ts`, `apps/server/tests/questIgnore.test.ts`, `apps/web/tests/QuestBoard.test.tsx`, `apps/web/tests/questBoardActions.test.ts`, `apps/web/tests/questBoardStore.test.ts`. * Canonical suggestion updates already normalize into Quest Board cards with legacy idle-suggestion compatibility. * Quest sources cover idle hero work, codebase issues, session follow-ups, analysis items, project scan items, and legacy idle suggestions. * Severity levels, source ordering, source counts, dismissed state, and total counts are already computed. * The board caps canonical cards at 24 and legacy idle suggestions at 12, giving the Legion layer a natural legibility budget. * Actionable idle quests support accept, assignment to selected idle hero, dismissal, optimistic updates, rollback on failure, in-flight action keys, and bounded-concurrency bulk dismissal. * Codebase, analysis, and project scans can be triggered from the Quest Board; scan status, scan root selection, ignore patterns, and safe file labels are already present. * Keyboard shortcuts accept the top three actionable idle quests, bulk-dismiss idle suggestions, and focus the Quest Board reply target. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/docs/game-design/04-world-map-and-combat-systems.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.