Skip to content

0068 — Player experience and ARIA narration hooks (Group O)

Status

Accepted.

Context

Fourteen audit findings on player-feel work — mechanics that exist server-side but lack UI affordance or ARIA narration. One critical (P-F4 first pirate encounter warning); the rest are narration spec for moments where the system has a state change but the player isn't told about it.

The cluster's natural shape is a canonical ARIA narration hook catalog — one place that lists every event ARIA narrates, when it fires, and a sample line. Cross-references then point each feature doc at the catalog entry rather than re-spec'ing per-doc.

Decision

P-F4 — Tier-readiness pre-warn on sector approach (critical)

ARIA emits a pre-engagement warning when the player approaches a sector containing a pirate holding ≥ Outpost tier OR a Roving Fleet. Warning content scales by player rank vs holding tier:

  • Stronghold encountered by sub-Lieutenant rank: explicit "this is way above your weight class — recommend turning back, or returning with a 4-player team."
  • Outpost encountered by sub-Ensign rank: cautionary "this is at the edge of your effective combat envelope — solo attempts succeed only with optimal builds; a 2-player team is the design assumption."
  • Camp encountered (any rank): silent — Camps are intended discovery content.
  • Roving Fleet encountered (any rank): factual situational report — "I'm reading three pirate signatures here. Mobile group; they may pursue if you engage. Up to you."

Triggered on the sector-presence event when sector.pirate_holdings is non-empty AND the highest tier is Outpost+. Once narrated, ARIA suppresses the same warning for that holding for 24 hours (so the player isn't re-warned every approach).

Canonical ARIA narration hook catalog

The full catalog lands in ../FEATURES/gameplay/aria-companion.md under a new "ARIA narration hooks — event catalog" section. Each entry carries:

  • Event — the trigger (state change or boundary crossing).
  • When — the precise moment ARIA speaks.
  • Sample dialogue — illustrative, not canonical wording.
  • Source ADR — which ADR ratifies the trigger (Group O / ADR-0068 for the new ones; older ADRs where they apply).

The catalog covers all 14 Group O findings:

Finding Event Trigger
P-F1 First-trade arbitrage suggestion Player completes their first profitable trade in a session
P-F2 Haggling option surface Trade UI opened with commodity ∈ player.success_history
P-F3 Subscription tier benefits Player views the subscription-upgrade screen
P-F4 Pirate-encounter pre-warn Sector entry with holding ≥ Outpost or Roving Fleet (per pick above)
P-F6 Subscription lapse Login after subscription_status flipped to lapsed (extends existing line in monetization.md)
P-F7 Contract board discovery First docking at any station with available contracts
P-F8 Rank tier crossing fanfare military_rank changes (after combat ends, per ADR-0061 S-I4)
P-F9 Region taxation visibility First trade in a non-home region with region.tax_rate > 0
P-I1 Contract acceptance Contract.status transitions posted → accepted for this player
P-I2 Region Owner governance tutorial First login as a Region Owner (Region.owner_id matches player and no prior tutorial state)
P-A1 Combat victory Combat resolves with player as winner; cooldown 5 minutes per combat partner
P-A2 Sector discovery Player first enters a sector flagged discovered = false for them
P-A3 Team join Player.team_id transitions from null to non-null
P-A4 Pirate-holding abandonment warning Owned holding's last_visit_at + 23 days reached (7-day warning before 30-day abandonment)
P-I3 Raid-failure partial-credit First docking after a failed raid where citadel was damaged ≥ 25%

All entries use ARIA's existing dialogue infrastructure (per ../SYSTEMS/aria-dialogue.md) — no new realtime-bus events; existing event taxonomy already carries the underlying state changes.

Cross-references in feature docs

Each affected feature doc gets a one-line pointer at the relevant mechanic:

  • FEATURES/economy/haggling.md — point at P-F2 catalog entry.
  • FEATURES/economy/contracts.md — point at P-I1 + P-F7 catalog entries.
  • OPERATIONS/monetization.md — point at P-F3 + P-F6 catalog entries.
  • FEATURES/gameplay/ranking.md — already references P-F8 via the ADR-0061 S-I4 mid-combat-deferral note.
  • FEATURES/gameplay/regional-governance.md — point at P-I2 + P-F9 catalog entries.
  • FEATURES/galaxy/pirate-holdings.md — point at P-F4 + P-A4 catalog entries.
  • FEATURES/gameplay/first-login.md — point at P-A2 catalog entry.

Suppression / cooldown rules (anti-spam)

ARIA narration is gated by a per-event-class cooldown to prevent spam:

  • Per-trigger event: each catalog entry has its own cooldown (e.g., P-F4 24h per holding; P-A1 5 min per combat partner; P-A2 once per sector ever).
  • Global narration ceiling: at most one ARIA narration line per player per minute (queued; oldest discarded if the queue exceeds 3 entries).
  • Player setting: the existing assistance_level setting (per ../FEATURES/gameplay/aria-companion.md#player-controlled-assistance-level) gates which catalog entries fire — minimal skips all P-A (minor narrations); quiet skips all P-A + P-I*; standard and full fire everything.

Consequences

  • The narration-hooks catalog is the single source of truth for "when does ARIA speak." New mechanics that warrant narration add a row; the catalog stays in sync as the doc evolves.
  • The 24h pre-warn cooldown on P-F4 prevents the warning from becoming background noise. Player can manually request a re-explanation via dialogue.
  • Cross-references in feature docs are minimal (one line each); the catalog table carries the substance. Avoids the "specify ARIA narration in 7 places" problem.
  • The assistance_level setting becomes load-bearing — it determines which catalog entries fire. Existing minimal / quiet / standard / full levels per ../FEATURES/gameplay/aria-companion.md don't change semantics; the catalog rows are sliced by level.
  • Sample dialogue is illustrative, not canonical. The actual lines are produced at runtime by ARIA per the dialogue engine in ../SYSTEMS/aria-dialogue.md, with cultural-context tagging per ../OPERATIONS/i18n.md.

Alternatives considered

  • Always-narrate any pirate presence regardless of tier (P-F4). Rejected per user pick — floods low-tier explorers with redundant warnings; Camps are discovery content.
  • Only narrate Stronghold sectors; lower tiers silent (P-F4). Rejected per user pick — misses the mid-tier (Outpost) mismatch case, which is the most common danger surface for unprepared players.
  • Spec ARIA narration in each feature doc separately (whole group). Rejected — the cross-doc spec drift would re-emerge within a few sprints. Catalog + one-line pointers is the durable shape.
  • Add new realtime-bus events for narration triggers. Rejected — narration runs on top of existing events (sector-presence, combat-resolved, rank-promoted, etc.); no new event types needed. ARIA dialogue subscribes to existing channels.