Skip to content

Medals

Medals are the horizontal achievement layer that sits on top of the linear military rank progression. Where rank measures how much a player has done (point thresholds → trading bonus, max-turns bonus, combat bonus), medals commemorate what specific things a player has done — ten thousand combat kills, a successful diplomatic treaty, a deep-nebula shard run, mentioning the right cat to the right guard.

The award lifecycle (storage, dispatcher, realtime events, admin tools) lives in ../../SYSTEMS/medal-service.md. This doc covers the catalog — what medals exist, what they commemorate, what they grant, and the lore that grounds them.

🚧 Partial. The medal system is shipped — storage, the award dispatcher + realtime events, and the bespoke per-medal effect layer (§ Effects). Nine medals auto-award through play (the three combat-tier checks in medal_service.check_combat_medals for Bronze Cluster / Silver Cluster / Quantum Cross, plus six wired in WO-CG2). The catalog below is the launch target: the remaining entries are admin-grant-only until their auto-award counters land, and a few await systems not yet built.

Categories

Five categories at launch, expandable:

Category What it commemorates
Combat Kills, victories, survival under fire
Economic Trade volume, port ownership, market dominance
Exploration Sectors discovered, gates built, deep-nebula runs
Diplomatic Treaties, multi-faction reputation, council service
Special / Hidden Easter eggs, lore beats, one-off achievements

The schema enum (medal_category) is closed at launch but extensible — additional categories like GENESIS, GOVERNANCE, SOCIAL, or SEASONAL can be added when their gameplay loops mature.

Tiers

Tier Visual treatment Where it appears
BRONZE Bronze metallic First-tier achievements
SILVER Silver metallic Mid-tier achievements
GOLD Gold metallic High-tier achievements
PLATINUM Platinum / iridescent Capstone achievements
UNIQUE One-of-a-kind / lore-themed Special and one-off medals; no tier escalation

In addition to color-coded tiers, every medal has a shape tier (circle / hexagon / star / shield / cross) — a colorblind-safe second axis so players can distinguish medals at a glance even when the color cue is degraded by accessibility settings.

Effects philosophy

✅ Shipped — medal_service.get_active_medal_bonuses() folds held-medal effects into the combat-damage / trade-rate / turn-regen / haggle-band hooks under the hard per-hook caps; one-time grants are idempotent on award; 33 medals are seeded with effects (WO-CG c1a0333). The full per-medal effect table + magnitudes live in the design spec (audit/design-briefs/medal-effects-spec.md). Auto-award dispatchers cover nine medals (the three combat-tier checks plus six more, WO-CG2 7a069f4); the remaining catalog is admin-grant-only until its counters land.

Medals carry bespoke, per-medal effects. Each medal grants a small gameplay effect tied to the loop it celebrates — a combat medal buffs combat, an explorer medal eases exploration, a trade medal sharpens trade. The effect must be diegetically grounded (the lore makes the effect, not the other way around), and a medal whose celebrated loop exposes no per-player stat to buff stays prestige-only rather than inventing a mechanic. Rank remains the primary progression layer; medal effects are a deliberately small celebration sprinkle on top.

Application model. Each catalog entry carries an effect; medal_service.get_active_medal_bonuses() reads held medals and folds their effects into the three bonus stacks the resolvers already consume — the rank-bonus dict (combat damage / trade rate), the Player.aria_bonus_multiplier (turn-regen rate, never the ADR-0004 turn cap), and the haggle band multiplier. Effects are passive-while-held or one-time-on-award (idempotent on the medal-award insert).

Per-hook caps — the hard ceiling. Total held-medal bonus is clamped per hook: combat_damage ≤ +3%, trading_discount ≤ −2%, turn_regen ≤ +0.05 (within the 1.0–1.5 aria clamp), haggle_band ≤ +0.08 — all tiny against rank's reach (+40% combat / −50% trade). The flat per-hook cap is the real stacking guarantee. No medal effect may mint credits outside a bounded faucet or perturb a canon invariant.

One-time grants — a bounded celebration faucet, fired once per medal per account (lifetime total ≈ 6,050 cr + 25 turns, well under a single month of the Galactic Citizen perk; a sprinkle, not an income channel):

Medal Tier Grant
First Blood bronze +150 cr, +10 turns
Colonizer bronze +200 cr
Quartermaster bronze +700 cr
Pathfinder bronze +15 turns
Cartel Breaker silver +1,000 cr
Bounty Hunter silver +1,000 cr
Genesis Award gold +1,000 cr + a passive +0.02 turn-regen while held
Worldsmith platinum +2,000 cr

Special-case perks — exempt from the medal caps. A few medals record perks sized by their lore moment, not the medal cap:

Medal Effect
Orange Cat Society The +15% persuasion bonus granted during first-login dialogue (see first-login.md). The medal records it; the bonus is the lore beat, exempt from the haggle cap.
Honorary Tabby +1 starting reputation with Mercantile Guild, applied at first Mercantile interaction (one-time).
Pillar of the Pioneer Office −2% per-pioneer migration fee at any Capital Sector's Class-0 station (clamp range unchanged).

Catalog

Combat

Medal Tier Trigger Commemorates
Bronze Cluster Bronze 100 combat victories Survival of the first hundred fights — the threshold past which a recruit becomes a veteran.
Silver Cluster Silver 1,000 combat victories A career soldier's record; the back of the navy is built on Silver Clusters.
Quantum Cross Gold 10,000 combat victories The vanishingly few who have made killing other ships their life's work.
First Blood Unique First successful PvP victory against another player The transition from NPC scuffles to player-vs-player combat — the moment the universe gets real.
Carrier-Killer Platinum Destroy a Carrier-class ship in single-pilot combat Pulling down a capital hull with a single ship — feat, not statistic.
The Longest Hour Unique Survive a 5-on-1 engagement where you were the 1, and finish with hull > 0 Coming out the other side of being outnumbered five-to-one.
Cabal-Breaker Unique Participate in a successful raid on the Cabal HQ (per Cabal lore) The endgame trophy — only one award per Cabal HQ clear cycle.

Economic

Medal Tier Trigger Commemorates
Trader's Merit Bronze 500 completed trades and lifetime trade revenue ≥ 1,000,000 cr The first real merchant — past the early-game grind, into actual commerce.
Guild Order of the Manifest Silver Lifetime trade revenue ≥ 100,000,000 cr and Mercantile Guild reputation ≥ Allied Recognition by the Guild itself — the ledger is your ledger.
Pillar of the Pioneer Office Silver Transport ≥ 10,000 colonists in cryosleep transit, lifetime The frontier moves on the backs of colonist haulers; this medal says you carried more than your share. (Effect allowlist — see above.)
Port Sovereign Gold Own ≥ 5 ports simultaneously for 30 consecutive real-time days Holding a network of ports long enough that the sector's commerce flows through your gates.
The Cornered Market Platinum Hold ≥ 70% of total active galactic supply of a single core commodity for 24 consecutive real-time hours The whales-only medal — a brief, demonstrable monopoly. Quietly disliked by the Mercantile Guild.

Exploration

Medal Tier Trigger Commemorates
Pathfinder Bronze First-discover 100 sectors The early cartographer's badge — before there were maps, you made them.
Cartographer's Compass Silver First-discover 500 sectors across at least 3 distinct regions A surveyor who's worked more than one region's stars.
Quantum Harvest Silver Personally harvest ≥ 500 Quantum Shards from nebulae (not bought, not pooled) The shard-runner's medal — earned shard by shard in the deep nebulae.
Gate Architect Gold Construct ≥ 3 player-built warp gates Reshaping the topology of the galaxy itself, not just mapping it.
The Lost Cluster Platinum First-discover an isolated cluster (no natural-tunnel link to the main network — reachable only via Quantum Jump) True frontier — a cluster nobody had ever been to until you jumped blind.

Diplomatic

Medal Tier Trigger Commemorates
Concordat Seal Silver Be the negotiating signatory on ≥ 1 inter-region treaty (trade, defense, non-aggression, or cultural) that survives ≥ 30 real-time days Diplomacy that holds — a treaty that didn't collapse the next week.
Ambassador of Two Banners Gold Reach Honored or higher reputation with ≥ 2 mutually-rivalrous factions simultaneously Threading the needle between rivals — the diplomat-spy archetype.
The Peacemaker's Star Gold Mediate the resolution of a declared inter-region war Ending a war you weren't fighting. (📐 depends on launch-target war declaration system.)
Voice of the Council Silver Serve a full term on a Regional Council via election Civic service — quiet medal, earned by showing up. (📐 depends on regional governance launch.)

Special / Hidden

These medals are not shown in the public catalog until earned (Medal.is_hidden = true).

Medal Tier Trigger Commemorates
Orange Cat Society Unique Mention the cat (per detection rules below) during first-login dialogue Recognition that you've walked the docks before — see The Orange Cat Society below. (Effect allowlist — see above.)
Honorary Tabby Unique Complete first-login at negotiation_skill = strong, claim a rarity_tier ≥ 3 ship, and trigger the cat-mention in the same session The rare combination — you talked your way into a real ship and you noticed Pumpkin. Pumpkin remembers. (Effect allowlist — see above.)
Pumpkin's Own Unique Trigger the cat-mention while playing as a Region Owner subscriber, in a session where the guard personality rolled Tired Night-Shifter Wildly specific lore-trivia medal — the kind of thing the playerbase will catalogue on a wiki within 48 hours of launch. Pure flavor.
Ghost in the Static Unique Discover a Lost World — land inside a graph-disconnected dark-territory formation reached only by Quantum Jump (see ../galaxy/special-formations.md#lost-worlds-quantum-jump-only-content) First to step into territory that touches no warp on the chart — a ghost on the long-range scans, real only to the one who jumped blind to reach it. (📐 depends on the launch-target Lost-World discovery system.)
Static on the Wire Unique Discover a Lost Sector — the smallest dark-territory formation: a lone sector off the warp graph, reachable only by Quantum Jump (see ../galaxy/special-formations.md#lost-worlds-quantum-jump-only-content) A single pinprick of dark territory found at the end of a blind jump — no warp leads there, and almost none lead back. (📐 depends on the launch-target Lost-Sector discovery system.)
The Sol Pilgrim Unique Visit Earth orbit (the Sol-system Easter egg sector) A pilgrimage medal for finding the lore corner most players never reach. (📐 depends on Sol Easter egg landing.)
Survived the HQ Unique Enter the Cabal HQ sector and successfully escape without being destroyed Distinct from Cabal-Breaker (which requires the kill) — this is for the scout who came back alive.

The Orange Cat Society

Pumpkin

Pumpkin is an orange tabby tom, one ear notched, who lives in the Callisto Colony shipyard. Officially he belongs to nobody. Unofficially he belongs to everyone who has ever passed through the Pioneer Office — a stray that the night-shift dockworkers started feeding decades ago, kept alive long past any cat's natural span by an open secret nobody at the colony will admit on the record: the Nova Scientific Institute's medical wing on Callisto runs an experimental geriatric-feline regenerative protocol, and Pumpkin has been their unofficial test subject for three generations of dockhands. He is, depending on which mechanic you ask, somewhere between thirty and seventy years old, and he is exactly the same cat their grandfather knew.

Pumpkin patrols the shipyard like he owns it — because in every way that matters, he does. He sleeps on the warm thrust-coupling housings of ships scheduled for departure (sailors say a ship Pumpkin sleeps on comes home; sailors say a lot of things). During the security guard's interrogation in first-login, Pumpkin will do one of three things, deterministically rolled from a small table per session: weave between the player's ankles, bat at a piece of dust caught in the holographic ID scanner, or hop onto the guard's desk and sit on whatever paperwork is open. The guards pretend to shoo him. They never quite do.

The Society

The Orange Cat Society is a real thing the way most real things in shipyards are real — never written down, never officially acknowledged, but understood. It's the loose informal fraternity of veteran spacers, dockhands, customs officers, and Federation enlisted personnel who have all, at some point, stood where the player is standing and noticed the cat. Mentioning Pumpkin during an ID check is a sign — to a Callisto guard, to a Mercantile customs agent at any major Sol-system port, to a Frontier hauler comparing notes at a refueling depot — that you've been around. You're not a paper-trail traveler. You're someone who has actually walked the docks. The +15% persuasion bonus during the first-login dialogue isn't magic. It's the guard relaxing because, whoever you are, you're not new.

The Society has no membership roster. It has only one ritual: when an orange tabby crosses your path on the docks, you nod.

Detection patterns

The first-login manual provider (per SYSTEMS/first-login.md) detects cat-mentions via whole-word regex matches against the player's raw input. Whole-word boundaries are required — substring matches on words like "scattered" or "category" must not trigger.

English (en) base patterns

cat, cats, kitty, kitties, kitten, tabby, feline, orange cat, the cat, that cat, pumpkin (the proper-name reference — full bonus), meow, purr, purring, whiskers, mouser, furball, furry friend.

Locale-specific aliases

Locale Aliases
es (Spanish) gato, gata, gatito, michi, minino, atigrado
fr (French) chat, chatte, chaton, matou, minou, tigré
zh (Chinese Simplified) 猫, 猫咪, 小猫, 橘猫, 橘子
pt (Portuguese, Brazilian) gato, gata, gatinho, bichano, felino, rajado
de (Partial — see OPERATIONS/i18n.md) katze, kater, kätzchen, mieze, stubentiger

Detector contract: case-insensitive, whole-word match against the player's raw input before sanitization. Always match the player's active-locale alias list plus the English list (a Spanish-speaking player who types "cat" still triggers). One match per session is sufficient — repeated mentions don't stack.

Player-facing surfaces

Display surfaces — where medals appear

The Trophy Room is the only "see all" surface. Every other surface shows at most one medal (the player's pinned medal) plus a count.

Surface What renders Density Interaction
Trophy Room (MedalShowcase.tsx on player profile) Full collection, categorized; locked silhouettes for unearned All medals Click → medal detail modal (lore, earned-at date, conditions)
Player nameplate in chat Pinned medal icon 1 Hover → tooltip (medal name + 1-line flavor)
Sector view Pinned medal icon next to player marker label 1 Hover-tooltip + click-through to public profile
Leaderboards "Medals" count column + pinned medal icon 1 + count Click → that player's public Trophy Room
Team rosters (TeamManager.tsx) Per-member: pinned medal icon + total count badge 1 + count Click row → public profile
Combat log Combat-tier medal icon next to combatant names 1 (combat-medals only) Tooltip only
Player-discovery banner (first-encounter in a sector) Pinned medal icon under player name; "(N medals)" suffix if 5+ 1 + count None — banner is transient
Login splash (post-auth, pre-GameDashboard) If a medal was earned while offline, splash centerpieces it for ~2s; otherwise skip 1 (offline-earned) Click anywhere to dismiss
Admin player view Full collection with audit trail (granted-by, when, reason, source event) All + audit Inline actions: revoke, hide-from-public override

Pinning model

Each player can pin one medal as their public face (Player.settings.medal_privacy.pinned_medal_id). Defaults to the player's highest-prestige earned medal per the catalog's prestige ordering. Hidden medals can be pinned but only render publicly if medal_privacy.show_hidden = true.

Award notification flow

In-session toast / banner: a non-modal banner card slides into the top-center of the dashboard chrome. The medal icon shimmer-wipes into the slot over ~600 ms; banner persists ~8 seconds, then auto-dismisses to a small bottom-right toast for ~20 s. A single-shot fanfare cue plays (gated by Player.settings.audio.sfx_volume); three cue variants by tier (combat / economic / hidden). Animations respect Player.settings.accessibility.reduced_motion (collapses to a fade). Notification copy follows the tone guide below.

Cross-session (offline-earned): the award is queued as a persistent system message (Message.message_type = "system", priority = "high") plus a flag in Player.settings.medal_privacy.unviewed_awards: [medal_id...]. At next login, the splash shows the most recent unviewed award (or "N new commendations" if multiple). A "NEW" pip persists on each unviewed medal in the Trophy Room until first viewed.

Hidden-medal handling (spoiler protection): hidden medals' toast is one-shot reveal — obscured icon for the first 1.2 seconds, then unveils with hint-shaped copy ("Something noticed you. The Orange Cat Society has welcomed you in"). Subsequent views (Trophy Room, profile) show the medal in plain text — the spoiler protection is one-shot only.

Player-to-player visibility:

Audience Default Setting
Earner's own team Realtime team toast medal_privacy.broadcast_to_team (default ON)
Earner's current sector Routine medals: silent. Prestige tier (tier ≥ GOLD or category = UNIQUE): sector-wide notification Hard-coded by catalog tier, not user-tunable
Global feed None at launch (Reserved for future galaxy-tier medals)

Suppression: players can mute their own medal toasts via Player.settings.notification_preferences.medals (default: notifications on). When muted, awards still persist to inbox and Trophy Room — just no in-session banner or sound.

Award notification copy — first-pass

Tone reference: faction-lore.md (gritty space-opera, faction-flavored where applicable). All entries post-pended with "— View in Trophy Room.":

Trigger Copy
Bronze Cluster "One hundred kills logged. The brass have noticed. Bronze Cluster awarded."
Silver Cluster "A thousand ships dead in your wake. Silver Cluster awarded."
Quantum Cross "Ten thousand confirmed kills. The Federation declassified your record long enough to pin this on you. Quantum Cross awarded."
Trader's Merit "The Mercantile Guild has reviewed your trade volume and finds it sufficient to acknowledge. Trader's Merit awarded."
Pathfinder "First into the dark, first onto the charts. Pathfinder awarded — twenty unmapped sectors logged in your name."
Orange Cat Society (hidden) "Something noticed you. The Orange Cat Society has welcomed you in. They do not explain themselves."
Concordat Seal "You walked between three flags and left none of them angry. Concordat Seal awarded."

Style notes: no exclamation marks (reads MMO-cheerful, off-brand); faction-issued medals use a faction voice; hidden-medal copy hints at being observed without spelling out the trigger; combat copy is matter-of-fact (the kill counts speak for themselves).

Privacy controls

Player.settings.medal_privacy JSONB shape (see ../../DATA_MODELS/jsonb-schema.md#playersettings):

{
  "medal_privacy": {
    "visibility": "all | curated | none",
    "pinned_medal_id": "str | null",
    "curated_medal_ids": ["str"],
    "show_hidden": false,
    "show_count_publicly": true,
    "broadcast_to_team": true,
    "unviewed_awards": ["str"]
  }
}

Knob semantics:

  • visibility = "all" (default): every earned medal renders on public profile / Trophy Room (subject to show_hidden).
  • visibility = "curated": only medals listed in curated_medal_ids render publicly.
  • visibility = "none": public profile shows only count (or nothing if show_count_publicly = false); Trophy Room is owner-only.
  • show_hidden (default false): hidden-tier medals never render publicly even at visibility = "all". Intentional opt-in — earning a hidden medal is a private moment by default.

Default policy: opt-in publicity for normal medals, opt-out for hidden. Most players want to show off a Bronze Cluster; hidden medals (Orange Cat Society, easter eggs) should default private and require an explicit "yeah, share that one" toggle.

Admin override: admins always see the full collection (including hidden) via the admin player view, regardless of player privacy settings. Each view of a privacy-overridden hidden medal writes an audit_logs entry (action view_hidden_medal).

Admin actions

A new MedalAdmin.tsx page under services/admin-ui/src/components/pages/ with two tabs:

  • Grant — search a player, pick a medal from the catalog, optional reason, grant.
  • Catalog — browse the medal catalog (read-only at launch).

Single-grant workflow: search by username/id → typeahead-pick from catalog → optional reason text (≤500 chars) → submit. Server records grant via MedalService.admin_grant, writes audit_logs entry with {action: "medal_grant", actor_user_id, target_player_id, medal_id, reason}. Player gets the standard award notification flow.

Bulk grant (for events): paste up to 1,000 player IDs / usernames or upload CSV. Server returns dry-run summary ("96 valid, 4 invalid: …"); admin confirms; commits. Routes through the admin-UI bulk-rate-limit bucket per OPERATIONS/admin-ui.md (10/min). All grants in a batch share a grant_batch_id for atomic-undo. Personal toasts suppressed for batch sizes > 50 (players see medals at next-login splash).

Revocation (mistaken grants, tournament disqualifications): every revocation requires a mandatory reason text. Writes audit_logs entry; emits a personal system message to the player ("Your Medal Name has been rescinded. Reason: …"). Bulk-revoke by grant_batch_id undoes a tournament's grants in one button (with confirmation).

Auth gate: per ADR-0027, this is User.is_admin = True only — no per-permission RBAC at launch.

Naming conventions

A short style guide for future medal additions:

  1. Tier escalation borrows from era progression. Bronze/Silver/Gold are pre-spaceflight materials; Quantum/Stellar/Singularity are the SF-prestige tier. Use material-name floors for early medals; escalate to physics terms at the top.
  2. Category vocabulary is faction-flavored. Combat = military ("Star", "Cross", "Order"). Economic = guild-mercantile ("Order of the Manifest", "Guild...", "Pillar of...", "Sovereign"). Exploration = surveyor / cartographer ("Pathfinder", "Compass", "Architect"). Diplomatic = formal-civic ("Concordat", "Council", "Ambassador", "Peacemaker's"). Special = lore-noun ("Orange Cat Society", "Sol Pilgrim").
  3. Possessive titles signal earned rank, not gift. "Trader's Merit" / "Cartographer's Compass" / "Peacemaker's Star" — apostrophe-s reads as "this is what they call you now".
  4. One proper noun per name maximum. "Quantum Cross" is fine. "Federation Quantum Cross of the Sol Frontier" is too much.
  5. Avoid generic verbs ("Master Trader", "Elite Pilot"). Reads as MMO completionist filler. Prefer artifact-noun constructions that imply a physical token someone bestowed on you.

Source map

Concern Path (target)
Catalog seed data services/gameserver/src/services/medal_catalog.py
Service & lifecycle ../../SYSTEMS/medal-service.md
Player UI: Trophy Room services/player-client/src/components/ranking/MedalShowcase.tsx
Player UI: pinned medal nameplate services/player-client/src/components/common/PlayerNamePlate.tsx (target)
Admin UI services/admin-ui/src/components/pages/MedalAdmin.tsx (target)
Schema ../../DATA_MODELS/player.md Player section + new Medal/PlayerMedal entries
JSONB privacy block ../../DATA_MODELS/jsonb-schema.md Player.settings.medal_privacy