Auto Warz — Notifications¶
Document Type: Design Document Version: 0.1 Status: Approved — pending implementation in M2.7 Last Updated: 2026-03-31 Vault destination:
01_Design DocumentsFolder:01_Design Documents
Overview¶
The Auto Warz notification system communicates important events to the player without interrupting gameplay. The factory always keeps running. Notifications are non-blocking — they inform, they do not force a response unless explicitly marked as requiring acknowledgement.
The system has two layers: - Toast notifications — immediate, appear in the world, fade automatically - Log — persistent history, lives in the right flap Log tab
Design Principles¶
- Non-intrusive by default. Info-level notifications should feel like a light tap on the shoulder, not an alarm.
- Escalating urgency. The visual weight of a notification matches how much attention it actually needs.
- Never spam. Similar notifications are grouped or throttled — the player does not see 12 "belt blocked" toasts in a row.
- Always recoverable. If a player misses a toast, it is always in the Log. Nothing is lost.
- Charming tone. Notification copy is brief, dry, and slightly characterful — consistent with Genesis's voice.
Toast Notifications¶
Position¶
Top-centre of the screen, below the top bar. Toasts stack vertically if multiple appear simultaneously — newest on top, older ones push down.
Appearance¶
Toasts slide in from above, pause briefly, then fade out and slide back up.
Visual style varies by level:
| Level | Border | Icon | Behaviour |
|---|---|---|---|
| Info | Subtle neutral border | ℹ Small info mark | Appears, pauses, fades. No interaction required. |
| Warning | Yellow border + glow | ⚠ Warning triangle | Appears, pauses longer, fades. Tapping dismisses early. |
| Critical | Red border + stronger glow | ✕ or ❗ | Appears and stays until player acknowledges. Does not auto-fade. |
Timing¶
- Info: visible for ~3 seconds, then fades over 0.5 seconds.
- Warning: visible for ~5 seconds, then fades over 0.5 seconds.
- Critical: does not fade. Stays on screen until player clicks to acknowledge.
Grouping / Throttling¶
- If the same notification fires more than once within 10 seconds, subsequent instances are grouped: "Belt blocked (×4)" rather than four separate toasts.
- A cooldown prevents the same notification type from appearing more than once every 10 seconds unless the level is Critical.
Dismissal¶
- Info and Warning toasts can be clicked to dismiss early.
- Critical toasts must be clicked to dismiss — clicking opens the right flap Log tab directly so the player can see the full context.
Copy Style¶
Notifications are written in Genesis's voice — brief, dry, slightly deadpan. Examples:
| Event | Toast Copy |
|---|---|
| Power grid deficit | "Grid 2 is drawing more than it produces." |
| Building idle | "Smelter has been idle for 3 minutes." |
| Resource critical | "Metal Ore supply is critically low." |
| Milestone reached | "First ship launched. The galaxy is watching." |
| Trade received | "Incoming delivery from [Player]. Ready to collect." |
| Grid merged | "Grid 2 and Grid 3 merged into Grid 2." |
| Grid split | "Grid 2 split. Grid 4 now active." |
| Session unsaved | "Session unsaved for 20 minutes. Consider saving." |
Log (Persistent History)¶
Full specification in 17_HUD Panel Flap.md under Tab 6: Log.
Summary: - Lives in the right flap Log tab - Every toast generates a log entry — nothing is lost if the player misses a toast - Filterable by level, system, and time window - Critical entries remain highlighted until acknowledged - Player-defined notifications via circuitry also appear here
System-Generated Notifications¶
Power System¶
| Event | Level | Copy |
|---|---|---|
| Grid deficit detected | Warning | "Grid [N] is drawing more than it produces." |
| Grid failure imminent (< 60s) | Critical | "Grid [N] will fail in under a minute." |
| Grid failure | Critical | "Grid [N] has lost power." |
| Grid restored | Info | "Grid [N] is back online." |
| 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." |
Production System¶
| Event | Level | 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." |
| Resource surplus overflow | Info | "[Resource] storage is full. Production has stalled." |
Genesis System¶
| Event | Level | Copy |
|---|---|---|
| Genesis carry full | Info | "Genesis carry inventory is full." |
| Genesis task failed | Warning | "Genesis could not complete: [Task]." |
| Genesis idle (queue empty) | Info | "Genesis is idle. No tasks queued." |
Session System¶
| Event | Level | Copy |
|---|---|---|
| Unsaved for 20 minutes | Warning | "Session unsaved for 20 minutes. Consider saving." |
| Autosave completed | Info | "Session autosaved." |
| Milestone: first launch | Info | "First ship launched. The galaxy is watching." |
| Milestone: first territory | Info | "First territory claimed." |
| Milestone: Master Rill | Info | "Master Rill complete. The war effort notices." |
Contributions System¶
| Event | Level | Copy |
|---|---|---|
| Incoming delivery ready | Info | "Incoming delivery from [Player]. Ready to collect." |
| Transport ship arrived | Info | "Transport ship arrived at [Station]." |
| Trade Station inactive | Warning | "Trade Station has no transport ship assigned." |
Player-Defined Notifications (Circuitry System)¶
Available once the circuitry system is researched (future milestone).
How It Works¶
Players define custom notification triggers by wiring circuitry signals to a Notification Node placed in the world. The Notification Node is configured with:
- Condition — the circuit signal that triggers the notification (e.g. chest item count drops below threshold)
- Message — custom text written by the player
- Level — Info / Warning / Critical
- Acknowledgement required — yes or no
- Cooldown — minimum time between repeat triggers (default 10 seconds, player-adjustable)
Examples of Player-Defined Conditions¶
- Chest drops below 50 Metal Ore → Warning: "Ore chest running low — send Genesis to mine."
- Smelter output full → Info: "Smelter output chest full — check belt."
- Any building idle for > 5 minutes → Warning: "Something stopped. Check factory."
- Power grid surplus drops below 10 PU → Warning: "Grid headroom getting tight."
In the Log¶
Player-defined notifications appear in the Log filtered under the system the player assigned them to, or under a "Custom" category if no system is assigned.
Notification Node (World Object)¶
The physical object placed in the world to enable player-defined notifications.
- Buildable in the world like any other building
- Small visual indicator showing its active/inactive state
- Wired to circuit network like any other circuit-aware building
- Can be renamed by the player for easy identification in the Log
Full specification deferred to the circuitry system design document.
Relation to Flap Attention System¶
The notification system drives the flap attention system directly:
- Every Warning or Critical notification causes the relevant flap tab icon to pulse.
- Every Critical notification causes the flap handle to bounce/prod from the screen edge.
- Resolving the underlying condition (e.g. power restored, resource resupplied) clears the pulse automatically.
- Critical notifications that require acknowledgement keep the flap bouncing until the player opens the Log and dismisses them.
Implementation Notes¶
ToastManager autoload (src/ui/hud/ToastManager.gd):
- Singleton — any system can emit a notification via ToastManager.notify(message, level, system).
- Handles toast queue, grouping, throttling, and display.
- Writes every notification to the Log automatically.
Log storage: - Log entries stored in memory during session. - Persisted to save file on save so log survives session reload. - Maximum log size: 500 entries. Oldest entries pruned when limit reached.
Revision History¶
| Version | Date | Notes |
|---|---|---|
| 0.1 | 2026-03-31 | Initial draft — toast system, log, system notifications, player-defined notifications via circuitry |