skara-brae-common/docs/game/medals-honours-system.md

# Skara Brae — Medals & Honours System (Torn City-Inspired)

Source: Joplin note 4877acc671ed4bfcb0d6bf2c5323c94a, migrated 2026-10-03

> **Goal**: A deep, profile-defining achievement system in the spirit of **Torn City's Honours/Awards** — long-term goals, bragging rights, rare prestige, and a *few* meaningful permanent bonuses — layered onto every existing Skara Brae system (combat, adventure, crafting, magic, guild, economy, etc.).

Torn City's honours are a major long-term retention driver: hundreds of awards across every activity, displayed on the profile, some granting small permanent stat boosts. Skara Brae adapts this into a fantasy-flavoured, **three-tier** structure: **Medals** (tiered, category-based) → **Honours** (rare, prestigious, single awards) → **Titles** (displayed name prefixes/suffixes).

---

## 1. System Overview

| Layer | What It Is | How Earned | Reward Style |
|---|---|---|---|
| **Medals** | Tiered achievement badges, organized by category | Cumulative thresholds across gameplay | Mostly cosmetic; some grant small permanent bonus per tier |
| **Honours** | Rare, prestigious single awards for exceptional feats | Specific hard/rare accomplishments | Display + a few grant permanent bonus |
| **Titles** | Name prefixes/suffixes shown with character name | Unlocked by medals/honours | Cosmetic only |
| **Hall of Fame** | Leaderboards / rankings | Top N per category, season & all-time | Bragging rights + seasonal cosmetic |

**Design guardrail**: Permanent gameplay bonuses from honours/medals are **small, %-based, and collectively capped** (max ~+10% total across all sources) so this rewards dedication without creating unbridgeable gaps or pay-to-win pressure. The bulk of the value is **cosmetic prestige + long-term goals**.

---

## 2. Medals — Tiered Badges by Category

Each medal has **5 tiers**. Cross a threshold → earn that tier (and upgrade the badge on your profile). Tiers are cumulative counters tracked per character.

### Tier Progression (Fantasy-Flavoured)

| Tier | Name | Relative Rarity |
|---|---|---|
| T1 | **Copper** | Common — early game |
| T2 | **Silver** | Uncommon — mid game |
| T3 | **Gold** | Rare — dedicated players |
| T4 | **Platinum** | Very rare — long-term veterans |
| T5 | **Dragon** | Legendary — top-tier devotees |

### 2.1 Medal Categories & Examples

> Thresholds are illustrative; final values set in tuning. A medal marked ⚡ grants a small permanent bonus at one or more tiers (see §4 for the bonus catalogue).

#### ⚔️ Combat (PvP & PvE)
| Medal | Copper | Silver | Gold | Platinum | Dragon | Bonus? |
|---|---|---|---|---|---|---|
| Pit Fighter (arena wins) | 10 | 100 | 1,000 | 10,000 | 50,000 | ⚡ +arena XP |
| Ambusher (successful ambushes) | 5 | 50 | 500 | 2,500 | 10,000 | — |
| Survivor (survive lethal attacks <10% HP) | 1 | 10 | 50 | 200 | 1,000 | — |
| Crit Master ⚡ (critical hits landed) | 100 | 1,000 | 10,000 | 100,000 | 500,000 | +crit chance |
| Flawless (win combat without taking damage) | 5 | 50 | 250 | 1,000 | 5,000 | — |
| Duelist (1v1 ranked wins) | 10 | 100 | 500 | 2,000 | 10,000 | ⚡ +duel rewards |
| Dungeon Clearer (dungeons completed) | 1 | 10 | 50 | 200 | 1,000 | — |

#### 🗡️ Adventure (→ Torn's Crimes)
| Medal | Copper | Silver | Gold | Platinum | Dragon | Bonus? |
|---|---|---|---|---|---|---|
| Pickpocket (successful pickpockets) | 10 | 100 | 1,000 | 10,000 | 50,000 | — |
| Burglar (manors/vaults broken into) | 1 | 25 | 100 | 500 | 2,000 | — |
| Fencer (stolen goods fenced) | 10 | 100 | 1,000 | 10,000 | 50,000 | ⚡ +fence value |
| Waylayer (travelers waylaid) | 5 | 50 | 500 | 2,500 | 10,000 | — |
| Dungeon Raider (guild raids completed) | 1 | 5 | 25 | 100 | 500 | — |
| Adventurer (total adventures completed) | 100 | 1,000 | 10,000 | 50,000 | 250,000 | ⚡ +adventure gold |
| Night Owl ⚡ (nighttime adventures) | 50 | 500 | 5,000 | 25,000 | 100,000 | +stealth at night |

#### 🔨 Crafting & Gathering
| Medal | Copper | Silver | Gold | Platinum | Dragon | Bonus? |
|---|---|---|---|---|---|---|
| Smith (items crafted) | 10 | 100 | 1,000 | 10,000 | 50,000 | — |
| Artisan (Superior+ quality crafted) | 5 | 50 | 500 | 2,500 | 10,000 | — |
| Mastercraft (Masterwork crafted) | 1 | 10 | 50 | 200 | 1,000 | ⚡ +crafting crit |
| Legendary Forger (Legendary crafted) | 1 | 5 | 25 | 100 | 500 | — |
| Miner's Grit ⚡ (ore mined) | 1K | 10K | 100K | 1M | 10M | +gathering yield |
| Herbalist (herbs gathered) | 1K | 10K | 100K | 1M | 10M | — |
| Polymath (all 12 professions to Journeyman) | — | 1 | — | all to Expert | all to Master | ⚡ +crafting XP |

#### ✨ Magic & Skills (feeds the Skill/Magic System)
| Medal | Copper | Silver | Gold | Platinum | Dragon | Bonus? |
|---|---|---|---|---|---|---|
| Apprentice (any skill to rank 10) | 1 | 5 | 12 | 25 | 50 skills | — |
| Spellweaver (spells learned) | 5 | 25 | 75 | 150 | 250 | — |
| List Master ⚡ (spell list maxed) | 1 | 3 | 6 | 10 | 20 lists | +PP regen |
| Archmage (all 4 Essence schools mastered) | — | — | — | 1 | — | ⚡ +casting bonus |
| Loremaster (all Lore skills rank 20) | — | — | 1 | — | — | — |
| Jack of All Trades ⚡ (skills at rank 20+) | 5 | 15 | 30 | 50 | 80 | +DP gain |

#### 💰 Economy
| Medal | Copper | Silver | Gold | Platinum | Dragon | Bonus? |
|---|---|---|---|---|---|---|
| Coinpurse (total gold earned) | 10K | 1M | 100M | 10B | 1T | — |
| Tycoon ⚡ (net worth milestone) | 100K | 10M | 1B | 100B | 10T | +bank interest |
| Merchant (market trades completed) | 10 | 100 | 1,000 | 10,000 | 50,000 | ⚡ -listing fees |
| Gambler (inn games won) | 10 | 100 | 1,000 | 5,000 | 25,000 | — |
| Speculator (merchant ventures profited) | 1 | 10 | 50 | 200 | 1,000 | — |

#### 🛡️ Guild & Social
| Medal | Copper | Silver | Gold | Platinum | Dragon | Bonus? |
|---|---|---|---|---|---|---|
| Loyalist (guild tenure) | 1mo | 6mo | 1yr | 2yr | 5yr | — |
| War Hero (guild wars won) | 1 | 5 | 25 | 100 | 500 | ⚡ +guild rep gain |
| Benefactor (gold donated to guild) | 10K | 1M | 100M | 10B | 1T | — |
| Reputation (social reputation points) | 100 | 1K | 10K | 100K | 1M | — |
| Carouser ⚡ (inn carousing sessions) | 10 | 100 | 1,000 | 5,000 | 25,000 | +charisma temp |

#### 🏹 Slayer & Hunting
| Medal | Copper | Silver | Gold | Platinum | Dragon | Bonus? |
|---|---|---|---|---|---|---|
| Slayer (tasks completed) | 1 | 10 | 50 | 250 | 1,000 | ⚡ +slayer XP |
| Bounty Hunter (bounties claimed) | 1 | 10 | 50 | 250 | 1,000 | — |
| Exterminator (total enemies slain) | 100 | 1K | 10K | 100K | 1M | — |
| Rare Game (rare/elite enemies killed) | 1 | 10 | 50 | 200 | 1,000 | — |

#### 🗺️ Exploration
| Medal | Copper | Silver | Gold | Platinum | Dragon | Bonus? |
|---|---|---|---|---|---|---|
| Pathfinder (districts discovered) | 3 | 6 | all 11 | — | — | — |
| Voyager (offshore trips) | 1 | 5 | 25 | 100 | 500 | — |
| Tomb Raider (Lost Tombs cleared) | 1 | 5 | 25 | 100 | 500 | — |
| World Walker (all travel destinations visited) | — | — | — | — | 1 | — |

#### 🎪 Events & Seasonal
| Medal | Copper | Silver | Gold | Platinum | Dragon | Bonus? |
|---|---|---|---|---|---|---|
| Festival Goer (seasonal events joined) | 1 | 3 | 6 | 12 | 24 | — |
| The Hunt Champion (world boss dealt final blow) | — | — | 1 | 3 | 10 | — |
| Mangar's Eve survivor | — | 1 | 3 | 5 | 10 | — |

### 2.2 Hidden Medals

A subset of medals are **hidden** (like Torn's secret honours) — the name/description is `???` until earned. Examples: discover the Adventurers' Guild, find a hidden room in a dungeon, fence goods to Old Grist 100 times. Creates exploration-driven surprise and community wiki culture.

---

## 3. Honours — Rare Prestige Awards

Honours are **single, non-tiered** awards for exceptional, hard, or one-off accomplishments. Far rarer than medals. Displayed in a dedicated "Honours" ribbon on the profile. Each has a unique fantasy name and flavour text.

| Honour | Requirement | Bonus? | Notes |
|---|---|---|---|
| **First Light** | Be among the first 100 characters to reach level 50 | ⚡ +1% all XP | World-first cohort |
| **Dragonslayer** | Deal the final blow to a Dragon-tier world boss | ⚡ +2% damage to bosses | Coordination feat |
| **Archmage of Skara Brae** | Master all four Essence schools (Archmage) | ⚡ +5% spell effectiveness | Magic capstone |
| **Grandmaster Artisan** | Reach Grandmaster in all 12 professions | ⚡ +crafting crit chance | Ultimate crafter |
| **Unbroken** | Win 100 arena duels without a single loss streak | ⚡ +arena prestige | Combat excellence |
| **The Untouchable** | Reach level 50 without ever being ambushed/defeated | ⚡ +1% dodge | Pure PvE run |
| **Mangar's Bane** | Complete Act V (defeat Mangar) | ⚡ +title "Bane of Mangar" | Storyline capstone |
| **Citizen of the Year** | Win a seasonal Hall of Fame #1 | Cosmetic title | Seasonal |
| **Lucky Devil** | Roll an upward open-ended 200+ (any maneuver) | — | RNG flex |
| **Iron Will** | Resist 100 spells via Resistance Roll | ⚡ +5 RR | Anti-magic |
| **The Beggar King's Shadow** | Max all underground slayer tasks | ⚡ +stealth | Rogue capstone |
| **Champion of the Dawn** | Complete all of High Priestess Vaela's divine quests | ⚡ +blessing duration | Cleric capstone |
| **Patron of the Arts** | Hire 1,000 gold worth of inn workers | — | Gold-sink flex |
| **Survivor of the Deep** | Clear the Undercity without a party member falling | ⚡ +Undercity rewards | Solo/coordination |

Honours are intentionally **curated and limited** (target: ~40 at launch, expandable). They're the "wow" awards that make a profile stand out.

---

## 4. Permanent Bonuses — Bounded & Capped

The ⚡ bonuses are the main gameplay incentive. To prevent power creep:

- Each ⚡ bonus is **small**: typically +1% to +5% in its niche.
- **Collective cap**: total bonus from all honours + medals combined is capped at **+10%** per category of effect (e.g., max +10% combat-related, +10% crafting-related, etc.). Beyond the cap, additional ⚡ awards are cosmetic-only.
- **Diminishing stacking**: multiple sources of the same effect stack *multiplicatively with diminishing returns* (e.g., two +5% crit bonuses = 1 - (0.95)(0.95) = +9.75%, not +10%).
- **Cosmetic is king**: most medals/honours are display-only. The bonuses are seasoning, not the meal.

This mirrors Torn, where honours give tiny permanent stat bumps — enough to matter to min-maxers, not enough to invalidate progression.

---

## 5. Titles

Earned from medals/honours. One **active title** displayed with the character name (e.g., in chat, combat, profile). Players can switch their active title freely from earned titles.

| Title | Source |
|---|---|
| the Pit Fighter | Pit Fighter medal (Gold) |
| Slayer of the Deep | Survivor of the Deep honour |
| Bane of Mangar | Mangar's Bane honour |
| Archmage | Archmage honour |
| the Coin-King / Coin-Queen | Tycoon medal (Platinum) |
| Dragonslayer | Dragonslayer honour |
| Grandmaster | Grandmaster Artisan honour |
| Loremaster | Loremaster medal |
| Shadow / the Unseen | Beggar King's Shadow honour |
| of the Dawn | Champion of the Dawn honour |

Titles are **purely cosmetic** — no mechanical effect. They're the social currency of prestige.

---

## 6. Hall of Fame / Leaderboards

Redis-backed leaderboards (already in the tech stack) power the Hall of Fame:

| Board | Scope | Reset |
|---|---|---|
| Combat ranking | PvP rating | Seasonal (monthly) + all-time |
| Wealth ranking | Net worth | All-time |
| Adventure ranking | Adventures completed (season) | Seasonal |
| Crafting ranking | Items crafted (season) | Seasonal |
| Guild ranking | Guild reputation | Seasonal + all-time |
| Slayer ranking | Slayer tasks (season) | Seasonal |

Top 3 / Top 10 / Top 100 each season earn a **seasonal honour + cosmetic**. All-time leaders are enshrined permanently.

---

## 7. Profile Display

A character's profile (viewable by others, like Torn's profile page) shows:

- **Honours ribbon** — row of rare honour icons (the flex zone)
- **Medal case** — categorized medal badges with earned tiers; unearned show greyed silhouettes (hidden medals show `???`)
- **Active title** — prefix/suffix on the name
- **Hall of Fame badges** — seasonal & all-time rankings
- **Featured medal** — player picks one medal to feature prominently

This creates the Torn-style "let me see how impressive this player is at a glance" profile.

---

## 8. Database Schema (Draft)

```sql
-- Medal definitions (static game data, in skara-brae-common)
-- (could be JSON/TOML in common repo; shown as SQL for schema context)
CREATE TABLE medal_definitions (
    id          VARCHAR(64) PRIMARY KEY,        -- 'pit_fighter'
    category    VARCHAR(32) NOT NULL,
    name        VARCHAR(64) NOT NULL,
    description TEXT NOT NULL,
    is_hidden   BOOLEAN NOT NULL DEFAULT FALSE,
    -- tier thresholds as JSON array: [10,100,1000,10000,50000]
    thresholds  JSONB NOT NULL
);

-- Character medal progress (highest tier earned + current count)
CREATE TABLE character_medals (
    character_id UUID NOT NULL REFERENCES characters(id),
    medal_id     VARCHAR(64) NOT NULL REFERENCES medal_definitions(id),
    count        BIGINT NOT NULL DEFAULT 0,
    highest_tier SMALLINT NOT NULL DEFAULT 0,   -- 0..5
    PRIMARY KEY (character_id, medal_id)
);

-- Honour definitions
CREATE TABLE honour_definitions (
    id          VARCHAR(64) PRIMARY KEY,
    name        VARCHAR(64) NOT NULL,
    description TEXT NOT NULL,
    bonus_json  JSONB,                         -- null if cosmetic
    title       VARCHAR(64)                    -- granted title, if any
);

-- Character honours earned
CREATE TABLE character_honours (
    character_id UUID NOT NULL REFERENCES characters(id),
    honour_id    VARCHAR(64) NOT NULL REFERENCES honour_definitions(id),
    earned_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    PRIMARY KEY (character_id, honour_id)
);

-- Earned titles
CREATE TABLE character_titles (
    character_id UUID NOT NULL REFERENCES characters(id),
    title        VARCHAR(64) NOT NULL,
    source       VARCHAR(64) NOT NULL,          -- honour_id or medal_id
    earned_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    PRIMARY KEY (character_id, title)
);

ALTER TABLE characters ADD COLUMN active_title VARCHAR(64);
ALTER TABLE characters ADD COLUMN featured_medal VARCHAR(64);
```

Counters that feed medals (arena wins, crits, gold earned, etc.) are best stored as **existing gameplay columns** or a lightweight `character_counters` key-value table to avoid schema bloat:

```sql
CREATE TABLE character_counters (
    character_id UUID NOT NULL REFERENCES characters(id),
    counter_key  VARCHAR(48) NOT NULL,          -- 'arena_wins', 'crits_landed', ...
    value        BIGINT NOT NULL DEFAULT 0,
    PRIMARY KEY (character_id, counter_key)
);
```

---

## 9. API Additions (Draft)

```
# Profile / medals / honours (public-ish)
GET    /api/profile/:character_id             # overview incl. medals, honours, title
GET    /api/character/medals                  # own medals + progress + hidden (revealed only)
GET    /api/character/honours                 # own honours
PUT    /api/character/active-title            # set active title
PUT    /api/character/featured-medal          # set featured medal

# Hall of Fame
GET    /api/leaderboard/:board                # seasonal or all-time rankings
```

A new WebSocket notification type for medal/honour unlocks:

```json
{ "type": "achievement:unlock", "data": { "kind": "medal", "id": "crit_master", "tier": 3, "name": "Crit Master", "bonus": "+1% crit chance" } }
{ "type": "achievement:unlock", "data": { "kind": "honour", "id": "dragonslayer", "name": "Dragonslayer" } }
```

---

## 10. Integration With Existing Systems

| Existing System | Integration |
|---|---|
| **Cumulative achievements** (existing design) | *Replaced/augmented* by medals. "Mine 10,000 ore" → Miner's Grit medal. |
| **Skill & Magic System** (new) | Skill ranks, spell lists mastered, Archmage, Jack of All Trades all feed medals/honours. |
| **Combat crit tables** | Crit Master medal tracks crits landed. |
| **Crafting quality tiers** | Artisan / Mastercraft / Legendary Forger medals track quality outcomes. |
| **Adventures / crimes** | Pickpocket, Burglar, Fencer, Adventurer medals mirror Torn crime milestones. |
| **Guilds / Clans** | War Hero, Benefactor, Loyalist medals; seasonal guild HOF. |
| **Slayer / Bounty** | Slayer, Bounty Hunter medals. |
| **Economy** | Coinpurse, Tycoon, Merchant medals; wealth HOF. |
| **Seasonal events** | Festival Goer, seasonal HOF "Citizen of the Year" honour. |
| **Redis** (tech stack) | Powers leaderboards + counter aggregation for medal thresholds. |

---

## 11. MVP / Phasing

- **Phase 1 (MVP)**: Medal *counters* + a handful of combat/adventure medals (cosmetic only). Profile shows medal case. Lays the tracking infrastructure.
- **Phase 2**: Full medal categories, ⚡ bonuses (capped), Honours, Titles, profile ribbon.
- **Phase 3**: Hall of Fame leaderboards (seasonal + all-time), hidden medals, seasonal honours.
- **Phase 4**: Community medal wiki integration, medal-of-the-week, special event honours.

---

## 12. Open Design Questions

- [ ] **Bonus cap**: confirm +10% per-effect-category collective cap? Adjust per category?
- [ ] **Tier count**: 5 tiers (Copper→Dragon) or simplify to 4 (drop Dragon)?
- [ ] **World-first honours** (First Light): feasible to award fairly at launch? Use a registration-cohort instead?
- [ ] **Hidden medals**: how many at launch? Risk of players missing them entirely.
- [ ] **Seasonal HOF reset cadence**: monthly? Quarterly?
- [ ] **Bonus stacking math**: confirm multiplicative-diminishing vs. additive-capped.
- [ ] **Counter storage**: dedicated `character_counters` table vs. adding columns — choose before Phase 1.

---

## Related Notes

- [Game Concept Overview](joplin://9cf8a2e701654ffbbd6512cc837c7e2f) — Core loops, cumulative achievements (now medals)
- [Skill & Magic System](joplin://4c295d18c9b04aea947b534834ffaced) — Skills/magic feed medals & honours
- [Mechanics Source Mapping](joplin://87a0f70b45c4453caae0fa2b5b8a96f9) — Torn City source mapping (honours expanded here)
- [Combat System & Stat Scaling Design](joplin://0ef630db4e3e4d6dab18ccaefccaaa5a) — Crit Master medal tracks crits
- [Tech Stack & Architecture](joplin://cecd2ef2690d4d1fba3450342aa63953) — Redis leaderboards, DB schema
- [Lore & World Building](joplin://867bdc9845624908a90928887a71c4c9) — NPCs/districts referenced in honours
- [Project Plan](joplin://d243ae57778343fca997d46b73d0ee3b) — Roadmap, phasing