> 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/03-game-loops-and-onboarding.md).

# Game Loops And Onboarding

**Project:** FactionOS — The War Effort **Document role:** Player experience spec / onboarding flow

## 4. The Core Loops (by timescale)

### Seconds — "The Glance Loop"

Look at battlefield → read the war state instantly (who's active, any flares, any new Blight) → dopamine tick from motion/banners → back to your own work. *Design target: the battlefield must be **interesting to look at when nothing is wrong** (ambient peon activity, building smoke, patrol idles) and **impossible to misread when something is** (flare/gate/siege).*

**Fourth-pass addition — the War Tide meter.** Objective gap: the glance answers *"is anything wrong?"* (single-pulse `alertFocus`, §14.6) but not *"are we winning?"* — the design's many numbers (essence, XP, standings) have no topline. Fix: one **tide bar** above the board — a frontline push-pull between faction color and Legion dark, computed over a trailing war-day window from real deltas only: gains = verified banners planted, camp HP removed, skirmisher/ram kills; losses = new camp mass, re-fog ticks, siege advance. Three legible states: **advancing / holding / losing ground**. Self-relative (never comparable across players — no Goodhart surface), honest (every input is a real event), and reduced-motion renders it as a signed delta chip. This is the number a player brags about at a glance: "the tide's with us today."

### Minutes — "The Command Loop"

A flare or gate goes up → player responds (answer the agent, approve the plan, resolve the permission) → immediate game payoff: hero surges, strike lands, XP bonus for **response time** ("Swift Command" bonus — rewards the genuinely valuable behavior of unblocking your agents quickly).

### Session (a run) — "The Campaign Loop"

Each cockpit session is a **war day**. Session start = dawn (daily scan reveals Legion moves). Player aims heroes at quests/missions. Session end produces the **Battle Report** (SessionRollup exists — reskin as an end-of-run screen: territory delta, banners planted, loot gained, MVP hero, efficiency grade). The replay panel (exists) becomes **"watch the battle again."**

### Hours/Overnight — "The Return Loop" (second pass addition)

Pass one never designed *coming back*. When the player returns after hours away, the cockpit must open on a **Dawn Report**: a \~20-second auto-playing recap composed from data that already exists — daily-scan delta (Legion overnight moves), any loop/headless activity (`loop_update`, orchestration queue progress), banners planted by long-running missions, and War Room catch-up (`warroom_pending_catchup` exists). Skippable in one click, and the report ends by focusing the single most urgent thing (a flare > a gate > a siege > a new camp). *Rule: never make the player reconstruct what happened from raw feeds; the game narrates absence.*

### Week/Season — "The War Loop"

Territory map persistence, building levels, hero hall-of-fame, faction standings (exists), War Room alliance leagues (§8), and a **seasonal prestige**: at season end the map is chronicled (a saga entry), veterans retire to the **Hall of Banners** (permanent gallery), and the map re-fogs with new Legion strength scaled to the codebase's current issue census. Prestige without loss: you keep tomes, titles, cosmetics, saga history.

***

### The First Ten Minutes (second pass addition — onboarding as ceremony)

Pass one had no new-player experience. Script the opening so the work→fun conversion is *proven* to the player immediately, using only shipped pieces:

1. **Minute 0–1:** faction pick (exists) framed as an oath; the empty board is fully fogged except the home keep. One line of promise: *"Your army is real. Send it to work."*
2. **Minute 1–3:** first hero spawn → "First Banner Raised" (exists, bronze) fires immediately — the player learns unlocks are real within 3 minutes.
3. **Minute 3–8:** the first mission runs. The player *watches* tool events become essence ticks and fog pushback in real time — this is the aha: the numbers moved because the agent read a file, not because they clicked.
4. **Minute 8–10:** first `mission_complete` → banner plant + loot roll + Battle Report teaser. If the codebase scanner has run, reveal exactly ONE Blight camp with the line *"They were always here. Now you can see them."* (Withholding the full Legion reveal until session two is deliberate — day-two hook.)

### Existing Generated Asset References

Before building new loop/report visuals, check `manifest.md`. Relevant production-generated assets already present for this file:

* `assets/generated/game-design/phase06/war-tide/war-tide-meter-sheet.png` covers advancing, holding, losing, signed-delta chip, gain/loss icon, and static badge variants for the War Tide meter.
* `assets/generated/game-design/phase06/battle-report/battle-report-frame.png` covers the end-of-session Battle Report frame; live metrics and labels still need DOM/data wiring.
* `assets/generated/game-design/phase06/dawn-report/dawn-report-recap-backdrop.png` covers Dawn Report recap framing, beat cards, urgent-focus handoff, and replay-card rails.
* `assets/generated/game-design/phase06/war-council/war-council-objective-board.png` covers the War Council objective-board frame, reroll token area, completion seal, and icon wells.
* `assets/generated/game-design/phase06/onboarding/first-ten-minutes-onboarding-sheet.png` covers oath, first-banner, first-mission, and single-camp reveal treatments.
* `assets/generated/game-design/phase08/hall-of-banners/hall-of-banners-gallery-backdrop.png` covers the veteran gallery backdrop for the Week/Season loop.
* `assets/generated/game-design/phase11/seasons-saga/seasons-saga-visuals-sheet.png` covers season rollover, chronicle, saga page, re-fog, Golden Age, snapshot, veteran banner, and saga-stat treatments for the Week/Season loop.

## 4B. War Council — Session Stakes (fourth pass)

Objective gap in passes one–three: the Campaign Loop has a beginning (dawn) and an end (Battle Report) but no *declared stakes* in between — the Battle Report grades a session against nothing, so a "war day" is a diary, not a story. Stories need intention → obstacle → payoff.

**The mechanic.** When a session opens (after the Dawn Report), the **War Council** proposes up to three objectives, *selected — never generated —* from the real needed-work census already in the projection and Quest Board:

* **Raze** a named high-severity camp (top of the existing severity order).
* **Relight** the sector with the oldest `lastTouchedAt` (fights re-fog).
* **Swift hand:** keep mean command response under the player's own trailing `swiftCommand.meanMs` (self-relative, per §9 grading philosophy).
* **Slay a nemesis** (§10, fourth pass) when one exists.
* **Break the siege / kill the ram** when the Legion is at the gates.

Rules that keep it honest and fun:

1. **Objectives are buffs, never gates.** Ignoring the council costs nothing; completing an objective fires a war-horn ceremony, advances title progress, and writes a saga line. No score is withheld for declining.
2. **Selection is deterministic** from projection + scan state — no RNG, no server work; a pure picker beside `gameProjection`. One re-roll allowed (the council "reconsiders"), framed as ceremony.
3. **Anti-Goodhart by construction:** the picker can only choose from work the real census already says is needed, and it prefers exactly what §9 scoring already values (verified, complex, swiftly-commanded). Chasing objectives *is* doing the right work.
4. **The Battle Report opens with the ledger:** objectives declared at dawn vs. achieved at dusk. This single change gives every session a beginning-middle-end arc using a screen that already exists.

## 4A. Implemented Loop Support

These shipped surfaces already support the glance, session, return, and replay loops. They should be reskinned as reports and time-lapse war playback, not treated as unrelated analytics.

### Heatmaps And Rollups

Code references: `apps/web/src/lib/missionHeatmap.ts`, `apps/web/src/components/MissionHeatmap.tsx`, `apps/web/src/components/SessionRollup.tsx`, `apps/web/src/store/useGameStore.ts`. Focused tests: `apps/web/tests/missionHeatmap.test.ts`, `apps/web/tests/MissionHeatmap.test.tsx`.

* The mission heatmap already renders seven days by twenty-four local hours, ordered oldest day to current day.
* Heatmap cells count mission starts and aggregate tool counts, with filters for hero, faction, and mission tag.
* Heatmap stats include total missions, active cells, peak count, hottest day, and hottest hour.
* A twenty-four-hour hero activity timeline already combines mission-start buckets, tool-use overlay, peak-hour summary, active-hour summary, and faction-accented bars.
* SessionRollup already excludes dismissed heroes and reports completed missions, tool calls, tokens, estimated cost, live active hero count, and projected hourly cost when there is active signal.

### Replay

Code references: `apps/web/src/store/useGameStore.ts`, `apps/web/src/lib/replayLink.ts`, `apps/web/src/components/ReplayPanel.tsx`, `apps/web/src/lib/hostedPersistence.ts`, `apps/web/src/store/useWsClient.ts`. Focused tests: `apps/web/tests/replayBuffer.test.ts`, `apps/web/tests/replayPersist.test.ts`, `apps/web/tests/replayLink.test.ts`, `apps/web/tests/replayShareButton.test.tsx`.

* The event log captures server events with an in-memory buffer capped at 500 events and a persisted local buffer capped at 100 events.
* Replay persistence is debounced, excludes replay-generated events while a replay is running, and restores state by reapplying captured events.
* Replay windows already cover the last 30 seconds, 2 minutes, and 5 minutes at 1x, 2x, and 4x speeds with gap capping between events.
* The visible replay list is capped at 50 rows and preserves priority mission, tool, permission, guarded-action, and hero state events when noisy.
* Share links encode up to 200 redacted events in local URL fragments, with clipboard copy fallback and disabled replay/share/clear controls while replay is in flight.
* Design implication: replay is a battle-recorder and Dawn Report sequencer input, but §14.9's honesty guard still applies.


---

# 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/03-game-loops-and-onboarding.md?ask=<question>&goal=<endgoal>
```

`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.