Queue Screen
This page owns the explicit execution view for queued work. It sits below Current Plan and Objectives. It executes atomic activities, with mission or planning context shown only as supporting labels.
Role
The Queue screen should answer:
- what activities are executing now
- what activities are queued next
- what is blocked or waiting
- what mission or planning context each activity belongs to when that context exists
- what actor or site each line belongs to
Queue State Vocabulary
The queue has one canonical state vocabulary. Every UX surface that surfaces a queue row — Queue screen, Current Plan, Territory dossier wide and full panels, Objectives — uses these words verbatim. Local synonyms drift the player's mental model and are a process FAIL.
| State | Meaning |
|---|---|
| Running | The activity is the active head of the queue and is consuming actor or world time right now. |
| Queued | The activity has been committed to the queue and will run when its predecessors finish; no blocker is known. |
| Blocked | The activity is in the queue but cannot start. A blockedReason chip on the row explains why (missing prerequisite, prevailing condition, prior blocker). |
| Preview | A pre-commit overlay state for activities the player is staging but has not yet enqueued. The route preview overlay is the canonical example. Preview is not a queue row; it surfaces in the shell overlay layer. |
| Suggested | A recommendation surfaced in the queue's footer section. The player has not committed it; it is a presented option, not a queued activity. |
| Scheduled-Repeat | A routine activity authored to fire on a cadence or trigger. Schedule-repeat rows have their own visual treatment so the player can distinguish "this fires every day at dawn" from a one-shot Queued row. |
Filter vs decoration vs section
The QueueNavigator filter tabs are all | now | queued | scheduled and only
these four. Blocked is not a filter tab; it is a row decoration chip
applied to a Queued or Running row when a blocker is known. Suggested is not
a filter tab; it is a footer section underneath the filtered queue rows.
Today the Suggested footer is populated from "first five activities currently available at the player's territory" client-side. Server-pushed Suggested activities are a planned extension, not yet implemented; until that ships, the Suggested footer is best-effort client derivation.
blockedReason on a queue row is client-only today. The server snapshot does
not yet carry a blockedReason field; populating it from the server is
planned but deferred.
ContextPanel as a Queue Entry Point
The right-click TerritoryContextPanel on the strategic map is one of the
canonical entry points into the queue. ContextPanel selections route through
the same enqueue path as compact and wide panel buttons (the
enqueueScheduledActivity and enqueueTravel calls), so a ContextPanel-driven
queue row is indistinguishable from any other queue row except by source
attribution. See
gd-shell-screen-model.md § ContextPanel for the
shell-level contract.
Activity Detail as a Queue Inspection Layer
Queue rows — Running, Queued, and queue rows carrying the Blocked decoration — are canonical openers for the shared Activity Detail inspector defined in gd-shell-screen-model.md § Activity Detail. BottomQueueSlots is also a queue-origin opener; a filled slot click opens Activity Detail with the slot's queue item reference; an empty slot click promotes to the Activities panel as today and may surface Activity Detail when the player selects a catalog row.
Clicking a queue row opens Activity Detail with queue-origin opener context:
source surface 'queue', the queue item reference, the activity def id, and
the actor reference. The inspector surfaces description, costs and rewards,
the effect-plan preview when available, and queue commands (Cancel for an
active run, Remove for a queued row, Move Up / Move Down for reordering) that
route through the canonical queue command path. The Queue screen remains the
execution owner; Activity Detail is a read / inspect / command surface that
invokes existing queue commands, never a parallel execution path.
The blockedReason chip on a queue row surfaces on the row itself as a compact
chip; Activity Detail may surface the same reason in an expanded form. The
server-confirmed blocked-reason field on the queue snapshot is planned but
deferred — Wave B-owned, pending sync — and the current blockedReason on
queue items is client-derived. See § Queue State Vocabulary for the canonical
Blocked decoration definition.
The recursive drill-stack inside Activity Detail is navigable from a
queue-origin opening once Wave B projects the parent-run / child-run
references onto the activity run snapshot (Wave B-owned, pending sync). A
Running run's Activity Detail will then expose a child-run drill-in and a
parent-run back-link, both opening another Activity Detail entry with
source surface 'detail'. The drill stack carries arbitrary depth with
cycle and depth guards.
Design Rules
- The queue should stay concrete and low-ambiguity.
- Queue rows should remain atomic activities even when the player thinks about them as part of a larger plan.
- Higher-level planning labels should not replace queue rows.
- Ordering, cancellation, and dependencies must be readable.
- Queue rows should link back to the objective or place that caused them.
- Older shorthand should be rewritten to activity rather than treated as a competing behavior noun.
- Queue-state wording follows the canonical vocabulary above. Surfaces that drift from this vocabulary are corrected back, not allowed to coexist.
Implementation status
| Surface / Behavior | Shipped wave | Status |
|---|---|---|
| Queue row → Activity Detail (description, costs, rewards) | Wave C | Ships via the queue navigator row click into the Activities panel; opener-context tag 'queue' is the Wave M target |
| Queue commands (Cancel / Remove / Move Up / Move Down) exposed in Activity Detail | Wave C | Ships via the canonical queue command path |
Running-row example (RecruitGarrison) — elapsed time, duration, preview, Cancel | Wave C / docs-only | Activity Detail surface ships; example illustrates the queue-origin contract |
Blocked-row example (WeaponsmithPractice) — blocked chip, Remove only | Deferred, Wave B | Blocked chip is client-derived today; server-confirmed blocked-reason field is Wave B-owned, pending sync; example marked illustrative until Wave B lands |
| BottomQueueSlots → Activity Detail (filled slot opens queue-origin detail) | Wave C | Partial: filled slot opens the Queue panel today; opener-context tag 'bottom-queue-slots' is the Wave M target |
| Recursive drill-stack from a queue-origin Activity Detail | Deferred, Wave B | Requires parent-run / child-run reference projection on the activity run snapshot — Wave B-owned, pending sync |