docs(game): migrate game-design canon notes from Joplin into docs/game/

Eight canon notes (Game Concept Overview, Mechanics Source Mapping,
Combat System & Stat Scaling Design, Skill & Magic System, Medals &
Honours System, Lore & World Building, Idle Fantasy Inspirations,
Tech Stack & Architecture) as markdown, note title as H1, with source
line citing the Joplin note ID. Joplin keeps status notes.

docs/game/mechanics-source-mapping.md

@@ -0,0 +1,298 @@
+# Skara Brae — Mechanics Source Mapping
+
+Source: Joplin note 87a0f70b45c4453caae0fa2b5b8a96f9, migrated 2026-10-03
+
+How elements from each inspiration source map to Skara Brae mechanics.
+
+---
+
+## Sources
+
+| Source | Type | Key Contribution |
+|---|---|---|
+| **The Bard's Tale I** (1985) | Dungeon crawl RPG | Setting, city structure, review board, party system, spell learning, dungeon progression |
+| **RoleMaster / MERP** (1980+) | Tabletop RPG | Combat engine (d100 open-ended, crit tables), 10-stats, skill ranks, spell realms, brutality |
+| **Idle Fantasy** (2024) | Mobile idle RPG | Offline sessions, hireable workers, pets, guild ranks, blessings, slayer tasks, quest diversity |
+| **Torn City** (2004) | Text-based MMORPG | Crime→adventure loop, economy, factions, properties, education, PvP, billions-scale stats, casino, travel |
+
+---
+
+## The Mapping
+
+### Leveling & Progression
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **Review Board** | Bard's Tale I | The **Adventurers' Guild** in Skara Brae. Unmarked building (must be discovered). Only place to level up, learn new spells, and change spell schools. Pay gold + meet XP threshold. Magical exam for spellcasters (lore check). |
+| **Experience points** | All | BIGINT XP. Earned from adventures, combat, crafting, quests. Level thresholds scale exponentially. |
+| **Stat growth to billions** | Torn City | BIGINT stats, tiered display (K/M/B/T). Stats only go up. Training, equipment, education, and crafting all feed into stats. |
+| **Skill ranks via development points** | RoleMaster | Skills leveled through use (not point-buy). Each skill has its own XP bar. Higher ranks = logarithmic cost increase. |
+| **Education courses** | Torn City | Schools (Fighters' Academy, College of Magic, Thieves' Den, Merchants' Guild). Real-time courses, permanent bonuses. Some adventures require prerequisites. |
+
+### Spell System
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **Spell schools as classes** | Bard's Tale I | Magician (offensive), Conjurer (summoning), Sorcerer (debilitating), Wizard (utility). Mages can switch schools at the Review Board. Master all four = Archmage title (cosmetic + achievement). |
+| **Spell learning at Review Board** | Bard's Tale I | Must visit the Adventurers' Guild to learn new spells after leveling. Each spell costs gold + requires minimum skill level. Spell codes replaced by meaningful names. |
+| **Three realms of magic** | RoleMaster | **Essence** (wizards — raw magical energy), **Channeling** (clerics — divine power from Old Gods), **Mentalism** (bards/psionics — mind power). Each realm has open lists (available to all) and closed lists (class-restricted). |
+| **Bard songs as spells** | Bard's Tale I | Bard songs function as long-duration buffs. Strengthen armor, increase attack speed, heal over time, boost skill XP. Certain puzzles/adventures require specific songs. |
+| **85 spells** | Bard's Tale I | Target: 60-80 spells at launch across all realms and schools. Expandable via updates. |
+
+### Combat
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **d100 open-ended roll** | RoleMaster | All attacks roll d100 open-ended (96-100: roll again and add). Creates rare but exciting high rolls. |
+| **Critical tables by weapon type** | RoleMaster | Slash, crush, puncture, unarmed crit tables. Each maps roll range to damage multiplier + status effect (bleed, stun, disarm, cripple, blind). Tables stored in `skara-brae-common/crit-tables/`. |
+| **Crit damage capped by level difference** | Original design | Equal level = full crit. +50 levels = 15% cap. +100 = 5% cap. Status effects always apply. Low levels can disrupt, not kill. |
+| **Armor type vs. weapon cross-reference** | RoleMaster | Attack tables cross-index weapon type against armor type (unarmored, leather, chain, plate). Heavy armor reduces crit severity. |
+| **Concussion hits** | RoleMaster | Normal hits (non-crit) = concussion damage. Accumulates, can knock unconscious. Natural recovery over time. |
+| **Body part damage** | RoleMaster | Crit rolls determine hit location (head, torso, arms, legs). Location affects which status effects apply. Head crits = stun. Arm crits = disarm. Leg crits = cripple. |
+| **Resistance rolls (RR)** | RoleMaster | Magic attacks require resistance roll: d100 + Will stat vs. spell difficulty. Failed RR = full effect. Partial success = reduced effect. Success = resisted. |
+| **Turn-based combat** | Bard's Tale I | Combat is turn-based/text-based. Choose actions each round. Manage stamina, mana, positioning (front/back rank). |
+| **Party combat (6 characters)** | Bard's Tale I | See Party System below. |
+
+### Adventures & Dungeons
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **Crime tiers** | Torn City | Adventures in risk/reward tiers: Safe (pick pockets) → Moderate (burglary) → Dangerous (dungeon raid) → Extreme (Undercity deep). Higher tiers = better rewards, more energy cost, higher failure chance. |
+| **Dungeon progression** | Bard's Tale I | Sequential dungeons with prerequisites: Wine Cellar → Sewers → Catacombs → Harkyn's Castle → Kylearan's Tower → Mangar's Tower. Each unlocks the next. Later dungeons require items/keys from earlier ones. |
+| **Random encounters on city streets** | Bard's Tale I | Moving between districts at night triggers random encounters. Higher danger districts = harder encounters. Daytime = mostly safe. |
+| **Dungeon puzzles and riddles** | Bard's Tale I | Dungeons include locked doors (lockpicking check), riddles (lore check), magical barriers (spell requirement), and boss mechanics. |
+| **Racing → Idle adventuring** | Torn City + Idle Fantasy | **Expeditions**: Send your character (or a hired worker) on a timed expedition to a dungeon or adventure zone. Takes 15 min to 1 hour. Returns with loot. Reduced rewards (60%) compared to active play. Energy consumed while on expedition. Comparable to Torn's racing (timed event with wager → payout). |
+| **Organized crime → Guild raids** | Torn City | **Guild raids**: Cooperative dungeon runs requiring 4-6 guild members. Each member contributes. Rewards split. Guild treasury gets a cut. Weekly cooldown. |
+
+### City & Navigation
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **30×30 city grid** | Bard's Tale I | **Decision needed**: Full MUD-style room-by-room map, or district-based navigation? See Map Question below. |
+| **Named streets and buildings** | Bard's Tale I | Key locations are named (Rakhir Street, The Singing Tavern, Garth's Equipment Shoppe). Even with district navigation, these names persist as flavor. |
+| **Locked gates / guardian statues** | Bard's Tale I | Certain districts require keys, quest completion, or level thresholds to access. The Undercity requires a password from a quest. The Noble Quarter requires property ownership or guild rank. |
+| **District-based navigation** | Torn City | Click on a district, see available actions. Fast, mobile-friendly, no spatial navigation needed. |
+| **Christmas Town** | Torn City | **Seasonal locations**: Temporary areas that appear during seasonal events. Festival of Lights → Frozen Lake (ice fishing, ice dungeon). Mangar's Eve → Shadow Realm (special dungeon). The Great Market → Bazaar of Wonders (rare vendors). These locations disappear after the event. |
+| **Travel (off-shore)** | Torn City | **Travel system**: Take a ship from the Harbor to offshore locations. Each trip costs gold + takes real time (1-4 hours). Destinations: The Iron Islands (mining colony, rare ores), Stormwatch Keep (military outpost, PvP zone), The Lost Tombs (ancient ruins, high-level dungeon), The Free Ports (neutral trade hub, no PvP). Travel time = opportunity for ambush by pirates or sea monsters. |
+
+#### Map Question: MUD-Style vs. District Navigation
+
+**Option A: MUD-Style Room Map**
+- 30×30 grid (like BT1), each tile is a "room" with description, exits, and possible encounters
+- Players navigate with cardinal directions (N/S/E/W)
+- Feels immersive, authentic to BT1 roots
+- Problem: Tedious on mobile. Hard to make feel good in a web UI. Most players would find it annoying.
+- Works if we want a true MUD feel
+
+**Option B: District-Based Navigation (Recommended)**
+- City has 10 districts (already defined). Click a district → see available locations and actions.
+- Within districts, specific locations (The Singing Tavern, Garth's Shoppe) are clickable destinations.
+- Dungeons are separate instances (enter → turn-based combat + exploration).
+- Problem: Less immersive. Loses the BT1 city-as-maze feel.
+- Works best for web/mobile, fast navigation, Torn-like UX
+
+**Option C: Hybrid**
+- District navigation for the main city (fast, mobile-friendly)
+- Dungeons use room-by-room exploration with a minimap (MUD/MUD2 style)
+- City streets at night can trigger random encounters when traveling between districts (without full room navigation)
+- Best of both worlds: fast city navigation, immersive dungeon crawling
+- The BT1 city-as-maze can be a special dungeon instance ("Skara Brae: The Eternal Winter" — a flashback to Mangar's original attack)
+
+**Recommendation**: Option C (Hybrid). District nav for city, room-by-room for dungeons. Night travel has encounter chance.
+
+### Economy
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **Bazaar / Item market** | Torn City | Player-driven marketplace. List items for sale. Search, filter, buy. Transaction fee (gold sink). |
+| **Garth's Equipment Shoppe** | Bard's Tale I | NPC shop with basic equipment. Always available. Sells low-to-mid tier gear. Buys items at 40% value. |
+| **Auction House** | Torn City | Rare items, timed auctions. 24-72 hour listings. Buyout option. |
+| **Bank of Skara Brae** | Torn City | Deposit gold, earn interest (0.5%/day). Loans available (collateral required). |
+| **Casino → Inn games** | Torn City | **The Singing Tavern** offers gambling: Dice (craps variant), Cards (fantasy poker), Arm Wrestling (strength check), Shell Game (perception check). Wager gold, win or lose. House edge ensures long-term gold sink. High-stakes table in the back room (Noble Quarter access). |
+| **Stock market → Merchant ventures** | Torn City | Invest in trading caravans departing from the Harbor. Returns depend on random events (pirates, storms, bandits, rare finds). Check results after 24 hours. |
+| **Player shops/stalls** | Torn City | Set up a stall in the Market Square. List items at custom prices. Stall rent = gold sink. Higher rent = better location (more traffic). |
+| **Fencing stolen goods** | Torn City | **Old Grist** at the Harbor buys stolen goods. Lower prices than market but no questions asked. Thievery skill affects quality of goods you can fence. |
+
+### Guilds & Clans
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **Factions** | Torn City | **Guilds** (already designed). Player organizations with hierarchy, guild hall, territory, treasury, taxation, wars. Guild rank progression (10 ranks). |
+| **Companies** | Torn City | **Clans** — a separate system from guilds. Clans are player-run businesses/cooperatives. |
+| **Clan types** | Original design | Clan types: Trading Company (market bonuses), Mercenary Band (PvP bonuses), Crafting Cooperative (crafting bonuses), Exploration Society (adventure bonuses). A player can be in one guild AND one clan simultaneously. Guilds are about power/territory. Clans are about economic specialization. |
+| **Guild wars** | Torn City | Territory control through raids. Formal war declaration. Surrender terms. Winner takes territory + treasury portion. |
+| **Alliances** | Torn City | Guild-to-guild treaties. Non-aggression pacts, trade agreements, mutual defense. Alliance chat channel. |
+| **Guild Adventures** | Torn City | Cooperative activities requiring multiple members (→ Torn's organized crimes). Weekly cooldown. |
+
+### Party System & Grouping
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **Party of 6 characters** | Bard's Tale I | **Parties of 2-4 players** (not 6 characters per player). Group up for adventures and dungeons. Party leader chooses destination. Loot distributed by configured rules (need/greed, round-robin, leader assigns). |
+| **Front/back rank** | Bard's Tale I | Combat positions: Front rank (melee, takes hits first) and back rank (ranged/magic, protected). Party leader assigns positions. |
+| **Adventurer's Guild party board** | Bard's Tale I | **Looking for Group board** at the Adventurers' Guild. Post: "Looking for healer for Catacombs run" or "Need tank for guild raid." Players apply, leader accepts. |
+| **Group bonuses** | MMORPGs | Party of 2: +10% XP. Party of 3: +20% XP. Party of 4: +30% XP. Encourages grouping without making it mandatory. |
+| **NPC party members** | Bard's Tale I | Hire **mercenaries** from the inn to fill empty party slots. Cost gold per adventure. Lower stats than players, no special abilities. Better than nothing for solo players attempting hard content. |
+| **Raid content** | MMORPGs | **Guild raids**: 6-12 players in an instanced dungeon. Boss mechanics require coordination. Weekly lockout. Best loot in the game. |
+
+### Races (Conservative)
+
+Drawing from all fantasy settings but keeping it traditional:
+
+| Race | Bonus | Penalty | Lore |
+|---|---|---|---|
+| **Human** | +Charisma, adaptable | None (jack of all trades) | Most numerous. Run the City Watch, merchant houses, and government. |
+| **Dwarf** | +Constitution, +Smithing | -Agility | Clan-based hill-dwellers. Run the best forges in the Crafters' Quarter. |
+| **Elf** | +Intelligence, +Perception | -Strength | Ancient, declining race. Tied to the Old Kingdom's magic. Run the Academy. |
+| **Halfling** | +Agility, +Thievery | -Strength | Nimble, underestimated. Run the smuggling routes at the Harbor. |
+| **Half-Orc** | +Strength, +Intimidation | -Intelligence | Marginalized. Often found in the Arena or as mercenaries. |
+| **Half-Elf** | +Charisma, +Magic | -Constitution | Bridge between human and elven societies. Often diplomats or bards. |
+
+**Decision**: Keep the 6 races from the current design. Conservative, well-understood, no weird ones.
+
+### Classes (Conservative)
+
+| Class | Role | Key Abilities | Source Inspiration |
+|---|---|---|---|
+| **Warrior** | Tank / Melee DPS | Heavy armor, weapon mastery, shield skills | BT1 Warrior, RM Fighter |
+| **Rogue** | DPS / Utility | Stealth, lockpicking, poison, backstab (high crit chance) | BT1 Rogue, RM Thief |
+| **Mage** | Ranged DPS | 4 spell schools (Magician, Conjurer, Sorcerer, Wizard). Switch schools at Review Board. | BT1 Magician/Conjurer/Sorcerer/Wizard, RM Essence user |
+| **Bard** | Support / Buffs | Bard songs (long-duration buffs), lore skills, social bonuses, minor healing | BT1 Bard, RM Bard |
+| **Cleric** | Healer / Support | Channeling spells (healing, protection, undead turning), blessings | RM Channeling user, D&D Cleric |
+| **Ranger** | Ranged DPS / Survival | Bow mastery, tracking, wilderness survival, minor nature magic | BT1 Hunter, RM Ranger |
+| **Paladin** | Tank / Healer hybrid | Heavy armor + minor healing, undead bonuses, aura buffs | BT1 Paladin, D&D Paladin |
+| **Monk** | Melee DPS / Evasion | Unarmed combat, high dodge, stunning blows, meditation (mana recovery) | BT1 Monk, RM Monk |
+
+**Decision**: 8 classes. The original 6 + Paladin and Monk (both in BT1). Conservative, recognizable archetypes. Each class has a clear role.
+
+### Properties & Housing
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **Properties** | Torn City | Buy/rent dwellings: Straw bed at inn → Room at boarding house → Apartment → House → Tower. Properties provide: energy recovery rate, storage capacity, crafting station quality, pet stable size. |
+| **Upgrades** | Torn City | Upgrade properties: Add a forge (blacksmithing bonus), library (education speed bonus), garden (herbalism yield), wine cellar (entertaining bonus). |
+| **Rent** | Torn City | Properties have weekly rent. Fail to pay = locked out (items in storage). Pay back rent to regain access. Permanent ownership available for high gold cost. |
+
+### Pets & Companions
+
+(Fully designed in Idle Fantasy Inspirations note)
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **Collectible pets** | Idle Fantasy | Rare drops from enemies. Provide passive bonuses. |
+| **Pet breeding** | Idle Fantasy | Combine pets for rare offspring. |
+| **Pet death in PvP** | Original design | Pets can be killed, resurrected at temple. Creates stakes. |
+
+### Crafting
+
+(Fully designed in Game Concept Overview note)
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **23 skills** | Idle Fantasy | Mapped to 5 gathering + 7 crafting + combat + support skills. |
+| **Quality rolls** | Original design | Common → Legendary quality tiers with crafting crits (RM-inspired). |
+| **Crafting professions** | Idle Fantasy / RM | 12 professions with mastery levels (Novice → Grandmaster). |
+
+### Quest System
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **Main storyline (5 acts)** | Bard's Tale I | Mangar the Dark as antagonist. 5-act progression mirroring BT1's dungeon sequence. |
+| **Daily quests** | Idle Fantasy | 3-5 daily quests from NPCs. Quick goals, moderate rewards. |
+| **Weekly quests** | Torn City | Larger goals, better rewards. |
+| **Cumulative achievements** | Idle Fantasy | "Mine 10,000 ore total" → permanent bonus. Long-term engagement. |
+| **Slayer tasks** | Idle Fantasy | Kill-specific-enemy assignments from Captain Rennick or The Beggar King. |
+| **Bounty board** | Torn City | Player-posted and NPC-posted bounties on other players. |
+| **Riddles and puzzles** | Bard's Tale I | Dungeon-specific puzzles requiring lore knowledge, bard songs, or specific items. |
+
+### World & Events
+
+| Mechanic | Source | Skara Brae Adaptation |
+|---|---|---|
+| **Day/night cycle** | Original design | Compressed clock (1 game day = 4 real hours). Night = stealth bonuses, danger increases. |
+| **Calendar events** | Original design | Moonday (magic bonus), Market Day (reduced fees), Arena Day (tournaments). |
+| **Seasonal events** | Torn City | Festival of Lights, The Hunt, Mangar's Eve, The Great Market. Each with temporary locations (like Torn's Christmas Town). |
+| **Dynamic world events** | Original design | Plague, invasion, festival. City-wide events affecting all players. |
+| **Weather** | RoleMaster | Affects combat (rain = ranged penalty, fog = stealth bonus) and gathering (rain = herbalism bonus). |
+
+---
+
+## Summary: What Each Source Primarily Contributes
+
+### Bard's Tale I — Setting & Structure
+- The city of Skara Brae (setting, districts, key locations)
+- Review Board (leveling, spell learning)
+- Adventurer's Guild (character management, LFG board)
+- Party-based combat with front/back rank
+- Dungeon progression with prerequisites
+- Mangar as antagonist
+- Named locations (Garth's Shoppe, Rakhir Street)
+- Spell schools (Magician, Conjurer, Sorcerer, Wizard → Archmage)
+- Bard songs as buffs
+- Paladin and Monk classes
+
+### RoleMaster / MERP — Combat Engine
+- d100 open-ended roll system
+- Critical tables by weapon type (slash, crush, puncture, unarmed)
+- Attack vs. armor cross-reference tables
+- Body part damage with status effects
+- Resistance rolls for magic
+- Concussion hits vs. critical hits
+- Three realms of magic (Essence, Channeling, Mentalism)
+- 10 stats (expanded to fit our 6-stat system)
+- Skill rank progression
+- Brutality: any level can critically affect any level (adapted with caps)
+
+### Idle Fantasy — Idle & Progression Mechanics
+- Offline sessions (1-hour cap)
+- Hireable NPC workers (inn system)
+- Pet collection and passive bonuses
+- Guild rank progression (10 ranks with daily tasks)
+- Blessings/church system
+- Slayer tasks
+- Daily + cumulative quest system
+- 23-skill framework (adapted to our profession system)
+- Quality tiers in crafting
+- Provision buying in bulk
+
+### Torn City — Economy & Long-Term Engagement
+- Crime → adventure loop with energy system
+- Billions-scale stat growth (BIGINT)
+- Player-driven economy (bazaar, auctions, bank, market)
+- Properties and housing with rent
+- Education system (real-time courses)
+- Casino → inn gambling games
+- Racing → expeditions (timed adventures)
+- Travel to offshore locations
+- Factions → guilds (with territory wars)
+- Companies → clans (economic specialization)
+- Stock market → merchant ventures
+- Bounty system
+- PvP (arena + ambush)
+- Patron subscription (ethical F2P)
+- Community API from day one
+- Seasonal events with temporary locations (Christmas Town)
+
+---
+
+## Open Design Questions
+
+- [ ] **Map system**: Hybrid recommended (district nav for city, room-by-room for dungeons). Confirm?
+- [ ] **Clan system**: Separate from guilds? One guild + one clan per player?
+- [ ] **Party size**: 2-4 players? Up to 4+2 (4 players + 2 NPCs)?
+- [ ] **Raid size**: 6? 12? For guild raid content.
+- [ ] **Travel time**: 1-4 hours real time for offshore locations? Too long? Too short?
+- [ ] **Spell school switching**: Allow mages to switch schools freely at Review Board, or restrict (cooldown, cost)?
+- [ ] **Archmage**: Cosmetic title + achievement for mastering all spell schools? Or gameplay bonus?
+- [ ] **Mercenary NPCs**: How strong? Flat % of player stats? Fixed stat range by hire cost?
+
+---
+
+## Related Notes
+
+- [Game Concept Overview](joplin://9cf8a2e701654ffbbd6512cc837c7e2f) — Full game design
+- [Combat System & Stat Scaling Design](joplin://0ef630db4e3e4d6dab18ccaefccaaa5a) — Crit tables, BIGINT stats
+- [Idle Fantasy Inspirations](joplin://48b3a3c76f734c8dafbbf9e8b3b5f80a) — Idle mechanics
+- [Lore & World Building](joplin://867bdc9845624908a90928887a71c4c9) — Districts, NPCs, storyline
+- [Tech Stack & Architecture](joplin://cecd2ef2690d4d1fba3450342aa63953) — Rust workspace, DB schema
+- [Project Plan](joplin://d243ae57778343fca997d46b73d0ee3b) — Roadmap, MVP, repo structure