Auto Warz — Notifications¶
Document Type: Design Document Version: 0.2 Status: Approved — pending implementation in M2.7 Last Updated: 2026-09-11 Vault destination:
01_Design DocumentsPhase: Phase 1 — Launch release Related Documents:[16_HUD Layout Design](<./16_HUD Layout Design.md>)·[17_HUD Panel Flap](<./17_HUD Panel Flap.md>)·[09_UI-UX Design Document](<./09_UI-UX Design Document.md>)·[10_Tutorial & Onboarding Design](<./10_Tutorial & Onboarding Design.md>)·[36_Progression Arc Design](<../Content/36_Progression Arc Design.md>)·[40_Genesis Design](<../Systems/40_Genesis Design.md>)·[11_Achievements Design Document](<../Content/11_Achievements Design Document.md>)·[00_Canonical Design Facts](<../../04_Project Management/00_Canonical Design Facts.md>)Closes: OI-372
1. The Two Jobs¶
Added 2026-09-11, and everything below follows from it.
The interface has two jobs. Tell me what my factory is doing wrong, and mark the moments. Everything else is chrome.
The first job is why Analytics, Power, Production and Pollution exist. The second is why the game feels like anything.
v0.1 did the first job and not the second. "First ship launched. The galaxy is watching" was an Info toast, which is the same visual weight as "Session autosaved". The finale of the Launch release had the presentation of a save confirmation. §7 fixes that.
The factory always keeps running. Notifications are non-blocking — they inform, they do not force a response unless explicitly marked as requiring acknowledgement.
2. Five Tiers, Three Purposes¶
| Tier | Says | Auto-fades |
|---|---|---|
| Info | Something happened | Yes, ~3s |
| Warning | Something is going wrong | Yes, ~5s |
| Critical | Something is wrong now | No. Requires acknowledgement |
| Primer | Something is new | Yes, but longer. Dismissible |
| Moment | Something happened that matters | Yes. Never takes input |
The first three are the existing urgency ladder and are unchanged. Primer and Moment are not urgency at all, which is why they sit outside it rather than above Critical.
- Primer teaches, once, the first time a thing is relevant. §6.
- Moment marks a beat from
[36_Progression Arc Design](<../Content/36_Progression Arc Design.md>). §7.
2.1 Design principles¶
- Non-intrusive by default. Info should feel like a light tap on the shoulder, not an alarm.
- Escalating urgency. Visual weight matches how much attention is actually needed.
- Never spam. Similar notifications are grouped or throttled. The player never sees twelve belt blocked toasts in a row.
- Always recoverable. A missed toast is always in the Log. Nothing is lost.
- Charming tone. Brief, dry, slightly characterful, consistent with Genesis.
3. Genesis Is the Voice, And It Vocalises¶
Decided 2026-09-11. Closes OI-372. Genesis talks and makes sounds, and the sounds are not speech.
Genesis vocalises. It does not speak. A small library of non-verbal sounds — a curious chirp, an affirming trill, an alarmed warble, a flat descending tone when something dies — paired with the text toast.
Why not voice acting, which was the obvious reading: recording budget, a localisation pass per language, and a session needed for every notification added afterwards. For a solo developer that makes the notification list expensive to extend, which is the opposite of what this system needs.
Vocalisations are keyed to tier and category, never to individual messages. That is the whole saving: a new notification type costs a line in a table and no audio work at all.
3.1 What the sound buys beyond character¶
A sound has a location. Genesis is somewhere.
So a notification can come from a direction, panned and attenuated from Genesis's position in the world. A factory that answers you from over there feels considerably more alive than one that beeps in the centre of your head, and it is free information: you learn where Genesis is without looking.
3.2 Rules¶
- ⚠️ Vocalisations are throttled harder than toasts. Sound is more intrusive than text. At most one vocalisation in any short window, and Critical always wins the slot. Getting this wrong turns a charming companion into a smoke alarm.
- ⚠️ Never sound-only. Every vocalisation has its text toast, always. The sound is an accompaniment, never the carrier, and it is separately mutable in Settings.
- In co-op, your Genesis speaks to you. Genesis is per player
(
[40_Genesis Design](<../Systems/40_Genesis Design.md>)), so a world event makes each player's own Genesis vocalise from its own position. No attribution is involved, per[00_Canonical Design Facts](<../../04_Project Management/00_Canonical Design Facts.md>)§25. - Silence is meaningful, and §4 is where that is specified.
4. Notifications Have Range¶
Decided 2026-09-11. [40_Genesis Design](<../Systems/40_Genesis Design.md>) §7.1 requires a satellite before Genesis can hear
a remote planet. That makes this system diegetic: it is not an omniscient overlay, it is a thing
with range.
| Where | Behaviour |
|---|---|
| The planet you are standing on | Always notifies. No satellite needed to hear the room you are in |
| A remote planet with a satellite | Notifies normally |
| A remote planet without a satellite | Silent. Not degraded, not vague. Silent |
| Arriving at a planet | Delivers the backlog into the Log |
The silence is the entire sales pitch for the satellite. Softening it into "something may be wrong somewhere" would sell nothing and would also be a worse experience than either extreme.
Arrival delivering the backlog is what keeps it fair. You find out late rather than never, which is the honest version of not having been watching. It is also the moment a player decides to build the satellite, which is exactly where that decision belongs.
5. Notifications Are Structured Events, Not Strings¶
Decided 2026-09-11. A notification is an event with fields. The UI formats it; the Log filters and sorts on it.
| Field | Purpose |
|---|---|
event_id |
Stable identifier. What kind of thing this is |
tier |
Info / Warning / Critical / Primer / Moment |
system |
Power, Production, Threats, Pollution, Genesis, Space, Session |
scope |
World / planet / grid / zone / building |
subjects |
References to the things involved, so the Log can jump to them |
values |
The numbers. Deficit, tier shed, count, rate |
ceremonial |
Moment only. Mirrors the Ceremony column in [36_Progression Arc Design](<../Content/36_Progression Arc Design.md>) §3 |
Why this is not an implementation detail. v0.1's power copy was "Grid 2 is drawing more than it produces", which is useless during a cascading shed — and a cascading shed is the entire First Blackout beat. A player needs to know what was dropped and by how much, and a string cannot carry that without the event carrying it first.
It also makes the Log filterable properly, rather than by substring matching on display text.
5.1 Worked example — First Blackout, all three purposes on one beat¶
This is the test case the whole tier system exists to pass.
| When | Tier | What the player gets |
|---|---|---|
| The first time any grid runs a deficit | Primer | "Power has priorities. A grid that cannot pay drops its lowest tier first." Fires on the warning, before anything is lost |
| The grid sheds | Critical | "Grid 2 shed Tier 3. Deficit 47 PU." Names the tier and the number |
| The beat completes | Moment, non-ceremonial | First Blackout is marked, logged, and unlocks its achievement |
Note the ordering. The primer fires before the lesson costs anything, on the warning rather than on the failure. That is the rule in §6.2, and this is the case that produced it.
6. Primers — Teaching at the Moment of First Relevance¶
Decided 2026-09-11. A primer is a one-off informational note that appears the first time something new is relevant.
The tutorial teaches the hand. Primers teach the game.
[10_Tutorial & Onboarding Design](<./10_Tutorial & Onboarding Design.md>) gets a player to a working chain in eleven steps, which is the
right length. Everything after it — wind, shedding, threats, remediation, barrelling, settlement — is
taught where and when it first matters, not in steps twelve through forty.
6.1 Rules¶
- Once per concept, account-scoped. A veteran starting a new world is not lectured again.
- Never blocking. It is a card, not a modal. The factory keeps running.
- Always re-readable. Every primer lands in the Log and is filterable as its own category, so a player who dismissed one by reflex can find it.
- Dismissible immediately, and silenceable entirely in Settings for players who want none.
6.2 The timing rule¶
A primer fires before the lesson costs you, not after.
Not when the farm withers — when the farm is placed. Not when the grid fails — when it first runs a deficit. The trigger is the moment of first relevance, which is usually a precondition rather than a consequence.
⚠️ This is what pays OI-381. Wind is invisible, and it ships in the Launch release for everyone
([26_Pollution, Waste & Organic Systems Design](<../Systems/26_Pollution, Waste & Organic Systems Design.md>) §3b.3), so a player who cannot see it places a
farm downwind and has no way to deduce why it died. The wind primer fires when the first farm is
placed, and the top bar carries the indicator from then on ([16_HUD Layout Design](<./16_HUD Layout Design.md>) §Top Bar).
6.3 Launch release primer list¶
Not a target, a count ([00_Canonical Design Facts](<../../04_Project Management/00_Canonical Design Facts.md>) §23a). These are the concepts that currently
have no other teacher:
| Concept | Fires when |
|---|---|
| Wind | The first farm is placed |
| Power priorities | The first grid deficit warning |
| Pollution equilibrium | Emission first exceeds absorption |
| Native territory | Pollution first reaches a zone boundary |
| Ferals and power signature | The first feral contact |
| Damage and wrecks | The first building is damaged |
| Barrels are a loop | The first barrelling machine is placed |
| Molten is local | The first smelter outputs Liquid Metal |
| Satellites and range | The first time the player leaves a planet running |
7. Moments — Marking the Beats¶
Decided 2026-09-11. A beat from [36_Progression Arc Design](<../Content/36_Progression Arc Design.md>) §3 is not a toast.
A Moment fires once, as world state, and everyone present sees it. Per §7a of the progression arc, and per
[00_Canonical Design Facts](<../../04_Project Management/00_Canonical Design Facts.md>)§25: the world ascended, not a player.
7.1 Ceremony is a flag, not a tier¶
The progression arc already decides which beats carry ceremony, and this document does not second-guess it:
| Beat | Ceremonial | Presentation |
|---|---|---|
| First Assembly | No | Marked and logged. Genesis reacts |
| First Ascent | Yes | Music change, screen acknowledges it, Genesis reacts strongly |
| First Blackout | No | Marked and logged |
| First Restoration | No | Marked and logged |
| First Launch 🚀 | Yes | The largest in the release |
Inflating all five to ceremony would flatten the two that matter. A Moment that happens five times is a notification tier; a Moment that happens twice is an event.
7.2 Constraints¶
- ⚠️ A Moment never takes input. The factory always keeps running is a principle of this document, and a modal celebration would break it at precisely the instant the player is most engaged. Audiovisual, never blocking.
- A Moment fires once per world. Not once per player. A guest joining later earns nothing retroactively, which is the progression arc's decision, not a new one.
- Every Moment unlocks its achievement (§7.3), for every player present.
7.3 Beats are achievements¶
Decided 2026-09-11. Each beat maps to an achievement in
[11_Achievements Design Document](<../Content/11_Achievements Design Document.md>). ACH_FIRST_LAUNCH already existed and is now explicitly the
First Launch beat; the other four are added there.
Because a beat is world state and an achievement is account state, everyone present when the beat fires unlocks it. That is the same rule that governs the XP, so it needs no special case.
8. Toast Presentation¶
Position¶
Top-centre, below the top bar. Toasts stack vertically, newest on top.
Appearance¶
| Tier | Border | Icon | Behaviour |
|---|---|---|---|
| Info | Subtle neutral | ℹ | Appears, pauses, fades |
| Warning | Yellow border and glow | ⚠ | Appears, pauses longer, fades. Click dismisses early |
| Critical | Red border, stronger glow | ❗ | Stays until acknowledged. Does not auto-fade |
| Primer | Distinct from all three. Neutral, softer, wider | 💡 | Longer dwell. Click dismisses. Never urgent-coloured |
| Moment | Not a toast. Own presentation | — | See §7 |
⚠️ A primer must not look like a warning. It is good news wearing an unfamiliar coat, and giving it a yellow border would teach the player that learning something new is a problem.
Timing¶
- Info: ~3 seconds, fading over 0.5.
- Warning: ~5 seconds, fading over 0.5.
- Critical: does not fade. Stays until clicked.
- Primer: ~8 seconds. It contains a sentence to read, not a status to glance at.
Grouping and throttling¶
- The same notification firing more than once in 10 seconds is grouped: "Belt blocked (×4)".
- A cooldown prevents the same type appearing more than once every 10 seconds unless Critical.
- Primers and Moments are never grouped, because they never repeat.
Dismissal¶
- Info, Warning and Primer can be clicked to dismiss early.
- Critical must be clicked, and clicking opens the right flap Log tab so the player sees full context.
9. System-Generated Notifications¶
Copy is written in Genesis's voice: brief, dry, slightly deadpan.
9.1 Power¶
| Event | Tier | Copy |
|---|---|---|
| First grid deficit ever | Primer | "Power has priorities. A grid that cannot pay drops its lowest tier first." |
| Grid deficit detected | Warning | "Grid [N] is drawing more than it produces. Deficit [X] PU." |
| Grid failure imminent (< 60s) | Critical | "Grid [N] will fail in under a minute." |
| Grid sheds a tier | Critical | "Grid [N] shed Tier [T]. Deficit [X] PU." |
| Grid restored | Info | "Grid [N] is back online." |
| Tier restored | Info | "Grid [N] restored Tier [T]." |
| Grid merged | Info | "Grid [N] and Grid [M] merged into Grid [N]." |
| Grid split | Warning | "Grid [N] split. Grid [M] now active." |
| Power source offline | Warning | "[Building] has gone offline." |
9.2 Production¶
| Event | Tier | Copy |
|---|---|---|
| Building idle > threshold | Warning | "[Building] has been idle for [X] minutes." |
| Bottleneck detected | Warning | "[Building] is throttling your [Resource] chain." |
| Resource critically low | Warning | "[Resource] supply is critically low." |
| Resource depleted | Critical | "[Resource] has run out. [N] buildings are starving." |
| Storage full, production stalled | Info | "[Resource] storage is full. Production has stalled." |
| First barrelling machine placed | Primer | "Barrels come back empty, or they do not come back. Build the return." |
| First Liquid Metal output | Primer | "Molten metal does not travel. Cast it, then ship the metal." |
9.3 Pollution¶
New 2026-09-11, following [26_Pollution, Waste & Organic Systems Design](<../Systems/26_Pollution, Waste & Organic Systems Design.md>) §3b.
| Event | Tier | Copy |
|---|---|---|
| First farm placed | Primer | "The wind carries your air. Whatever is downwind breathes it." |
| Emission first exceeds absorption | Primer | "The planet absorbs a little. Past that, it accumulates." |
| Emission exceeds absorption | Warning | "Emitting [X] against [Y] absorbed. Pollution is climbing." |
| Farm output suppressed | Warning | "[Farm] output down [X]%. The air here is dirty." |
| Solar output suppressed | Warning | "Solar output down [X]% under the smog." |
| Pollution reaches a native zone | Critical | "Your air has reached [Zone]. Something there noticed." |
| Back under the line | Info | "Absorption has caught up. Pollution is falling." |
| Waste storage near full | Warning | "Waste storage [X]% full." |
| E-waste drawing attention | Critical | "Exposed e-waste is attracting ferals." |
9.4 Threats¶
New 2026-09-11, following [37_Planet Threats & Defence Design](<../Systems/37_Planet Threats & Defence Design.md>).
| Event | Tier | Copy |
|---|---|---|
| First contact with a native zone | Primer | "They were here first. They are territorial, and pollution is what wakes them." |
| First feral contact | Primer | "Ferals do not hold ground. They hunt power." |
| Native zone stirring | Warning | "[Zone] is stirring." |
| Native attack incoming | Critical | "[Zone] is attacking [Location]." |
| Feral contact | Warning | "Ferals inbound on [Location]." |
| First building damaged | Primer | "Damage is a scale, not a switch. It still works, worse." |
| Building damaged | Warning | "[Building] is damaged. Efficiency down [X]%." |
| Building destroyed | Critical | "[Building] is destroyed. The wreck remains." |
| Defence line out of ammunition | Critical | "[Turret] is out of ammunition." |
| Zone calmed | Info | "[Zone] has settled." |
9.5 Genesis¶
| Event | Tier | Copy |
|---|---|---|
| Carry inventory full | Info | "Genesis carry inventory is full." |
| Task failed | Warning | "Genesis could not complete: [Task]." |
| Queue empty | Info | "Genesis is idle. No tasks queued." |
| Queue complete | Info | "Genesis has finished the queue." |
| Bots out of charge | Warning | "Bots are out of charge. Genesis is building alone." |
9.6 Space and planets¶
New 2026-09-11, following [39_Space Layer Design](<../Systems/39_Space Layer Design.md>).
| Event | Tier | Copy |
|---|---|---|
| First time leaving a planet running | Primer | "You will not hear from a planet you cannot see. That is what a satellite is for." |
| Ship arrived | Info | "[Ship] has arrived at [Planet]." |
| Ship low on fuel | Warning | "[Ship] does not have the fuel to return." |
| Satellite online | Info | "[Planet] is on the network." |
| Satellite offline | Warning | "[Planet] has gone quiet." |
| Remote chain stalled | Warning | "[Planet]: [Building] has been idle for [X] minutes." |
| Backlog on arrival | Info | "[N] events happened here while you were away." |
9.7 Restoration¶
| Event | Tier | Copy |
|---|---|---|
| First wreck available | Primer | "It remembers what it was. Rebuilding it costs what it cost." |
| Restoration bill available | Info | "[Wreck] can be restored. [N] materials required." |
| Restoration complete | Info | "[Building] restored." |
9.8 Session¶
| Event | Tier | Copy |
|---|---|---|
| Unsaved for 20 minutes | Warning | "Session unsaved for 20 minutes. Consider saving." |
| Autosave completed | Info | "Session autosaved." |
| Player joined | Info | "[Player] has joined." |
| Player left | Info | "[Player] has left." |
9.9 Moments¶
| Beat | Ceremonial |
|---|---|
| First Assembly | No |
| First Ascent | Yes |
| First Blackout | No |
| First Restoration | No |
| First Launch 🚀 | Yes |
Copy lives with the beat in [36_Progression Arc Design](<../Content/36_Progression Arc Design.md>), not here, so a beat's wording and its
meaning stay in one document.
10. Log¶
Full specification in [17_HUD Panel Flap](<./17_HUD Panel Flap.md>) Tab 6.
- Lives in the right flap Log tab.
- Every notification generates a log entry, primers and Moments included.
- Filterable by tier, system, scope and time window.
- Primers are their own filter, so the set can be read as a reference.
- Critical entries stay highlighted until acknowledged.
- Player-defined notifications appear here.
- A remote planet's backlog is written here on arrival, timestamped when it happened rather than when it was heard.
11. Player-Defined Notifications (Circuitry)¶
Available once circuitry is researched. Unchanged from v0.1.
Players wire a circuit signal to a Notification Node placed in the world, configured with a condition, a message, a tier (Info / Warning / Critical only — a player cannot author a Primer or a Moment), acknowledgement, and a cooldown.
Examples: a chest dropping below a threshold, a smelter output full, a building idle beyond a time, grid headroom getting tight.
The Notification Node is an ordinary building, wired like any other circuit-aware building, renameable for identification in the Log. Full specification deferred to the circuitry design document.
12. Relation to the Flap Attention System¶
- Every Warning or Critical causes the relevant flap tab icon to pulse.
- Every Critical causes the flap handle to bounce from the screen edge.
- Resolving the underlying condition clears the pulse automatically.
- Critical notifications requiring acknowledgement keep the flap bouncing until dismissed in the Log.
- ⚠️ Primers and Moments never bounce the flap. Neither is a problem, and teaching the player that the handle only bounces for trouble is worth more than the extra visibility.
13. Implementation Notes¶
ToastManager autoload (src/ui/hud/ToastManager.gd):
- Singleton. Any system emits an event, not a string:
ToastManager.notify(event). - Owns the toast queue, grouping, throttling and display.
- Owns vocalisation selection and its separate throttle (§3.2).
- Writes every event to the Log automatically.
Primer state lives in PlayerProfile, not the save file, because primers are account-scoped.
Range filtering happens before the queue: an event scoped to a planet the player cannot hear is written nowhere and delivered on arrival instead (§4).
Log storage: in memory during the session, persisted on save. Maximum 500 entries, oldest pruned. ⚠️ Primers and Moments are exempt from pruning, since both are permanent records rather than traffic.
Open items for this document are tracked in docs/open-items.md, area ui.
Open Questions¶
- What a vocalisation actually sounds like. The design says non-verbal and characterful; the library itself is an audio task
- Whether a guest joining mid-session sees any acknowledgement of beats already fired. Inherited
from
[36_Progression Arc Design](<../Content/36_Progression Arc Design.md>)§7a, which suggests a line in the world summary rather than an award - The idle and bottleneck thresholds, which are tuning values
- Whether primers should be re-offered in a new world after a very long gap, or stay permanently dismissed
Revision History¶
| Version | Date | Notes |
|---|---|---|
| 0.2 | 2026-09-11 | The two jobs stated (§1): tell me what my factory is doing wrong, and mark the moments. Two new tiers that are not urgency — Primer (something is new) and Moment (something happened that matters) — sitting outside the Info/Warning/Critical ladder rather than above it. Genesis vocalises rather than speaks (§3), closing OI-372: non-verbal sounds keyed to tier and category, so a new notification costs no audio work; spatialised from Genesis's position, throttled harder than toasts, and never sound-only. Notifications have range (§4): the planet you stand on always notifies, a remote planet without a satellite is silent, and arrival delivers the backlog. Notifications become structured events (§5) because v0.1's power copy could not express a cascading shed, which is the whole First Blackout beat; §5.1 works that beat through all three purposes. Primers (§6) teach at the moment of first relevance, with the rule that a primer fires before the lesson costs you — which is what pays OI-381's wind debt. Moments (§7) mark beats, fire once as world state, never take input, and carry ceremony as a flag so the two ceremonial beats are not flattened by the three that are not. Beats become achievements (§7.3). Five new notification tables: pollution, threats, space, restoration, and an extended Genesis set. |
| 0.1 | 2026-03-31 | Initial draft — toast system, log, system notifications, player-defined notifications via circuitry |