docs(wiki): add technical design specs

2026-06-10 15:18:39 -05:00
parent 1621004f3f
commit 6a50129ece
2 changed files with 781 additions and 0 deletions
@@ -29,6 +29,7 @@ The core fantasy is simple:
 ## Wiki Sections
 - [[Gameplay]] — core loop, resources, petitioners, daily seed, world map, consequences, visual style, and design pillars
 - [[Technical-Design-Specs]] — MVP screens, data schemas, resource formulas, save structure, failure states, example day, and build phases
 - [[Lore]] — world-building, factions, and characters
 - [[Story]] — narrative structure, acts, cutscenes, and themes
 - [[Music]] — soundtrack, composers, themes, and audio direction
@@ -0,0 +1,780 @@
 # Technical Design Specs
 ## MVP Overview
 The MVP should prove the core loop:
 1. Player starts a new day.
 2. Three petitioners appear in the throne room.
 3. Player makes one ruling per petitioner.
 4. Rulings change resources, faction trust, settlement stability, or future event tags.
 5. Player takes one world map action.
 6. Day ends with a summary.
 7. Next day seed is generated from current game state.
 The MVP does not need full AI generation at first. It should work with hand-written petitioner data, deterministic seed logic, and simple map state.
 AI-generated content can be added later as a content-expansion layer.
 ---
 ## Core MVP Screens
 ### 1. Home Screen
 Purpose:
 - Start game
 - Continue game
 - Open wiki/lore
 - Open settings
 Elements:
 - Game title
 - BLB throne image or logo
 - Start/continue buttons
 - Cosmic purple-blue background
 ### 2. Throne Room Screen
 Purpose:
 Main gameplay hub for daily petitioners.
 Elements:
 - BLB on throne
 - Current petitioner
 - Petitioner text
 - Ruling choices
 - Resource HUD
 - Day counter
 - Faction/status icons
 - Button to continue after ruling
 ### 3. Petitioner Modal / Case Panel
 Purpose:
 Focused decision interface.
 Elements:
 - Petitioner name
 - Petitioner faction or settlement
 - Problem description
 - 2-4 ruling choices
 - Preview style, depending on design:
  - Full preview
  - Partial preview
  - Hidden consequence
  - Advisor hint
 ### 4. Resource HUD
 Purpose:
 Always show current economic state.
 Elements:
 - Bone total
 - Minion total
 - Cases of milk
 - Optional later:
  - Stability
  - Faction trust
  - Day
  - Warnings
 ### 5. World Map Screen
 Purpose:
 Allow player to spend resources and assign minions after throne rulings.
 Elements:
 - BLB territory
 - NPC cities
 - Towns
 - Homesteads
 - Settlement status
 - Available map actions
 - Resource cost preview
 - Expected effect preview
 ### 6. Daily Summary Screen
 Purpose:
 Show what happened today and what consequences were created.
 Elements:
 - Resource changes
 - Faction changes
 - Settlement changes
 - New flags/tags
 - Warnings for tomorrow
 - Button to start next day
 ---
 ## Petitioner Data Schema
 Recommended format for MVP: JSON.
 Example:
 ```json
 {
  "id": "petitioner_marrowgate_bad_bones_001",
  "name": "Foreman Clatter",
  "type": "settlement_request",
  "faction": "bone_guild",
  "settlementId": "marrowgate",
  "tags": ["bones", "production", "early_game"],
  "minDay": 1,
  "maxDay": 10,
  "weight": 10,
  "requiresFlags": [],
  "blocksFlags": ["marrowgate_resolved_bad_bones"],
  "title": "Bad Bones at Marrowgate",
  "body": "Foreman Clatter reports that Marrowgate's latest bone shipments are brittle, chalky, and emotionally disappointing.",
  "choices": [
    "send_milk_inspection",
    "blame_the_guild",
    "ignore_the_problem"
  ],
  "onSeenFlags": ["seen_bad_bones_case"]
 }
 ```
 ---
 ## Ruling / Choice Schema
 Each ruling should be a separate reusable object or embedded inside the petitioner.
 Recommended choice object:
 ```json
 {
  "id": "send_milk_inspection",
  "label": "Send three cases of milk and a minion inspector.",
  "tone": "practical",
  "costs": {
    "bones": 0,
    "minions": 1,
    "milk": 3
  },
  "effects": {
    "resources": {
      "bones": 0,
      "minions": -1,
      "milk": -3
    },
    "settlements": {
      "marrowgate": {
        "stability": 5,
        "boneProduction": 2
      }
    },
    "factions": {
      "bone_guild": {
        "trust": 3
      },
      "milken_order": {
        "trust": 1
      }
    },
    "flagsAdd": ["marrowgate_milk_audit_started"],
    "flagsRemove": [],
    "futureEventWeights": {
      "petitioner_marrowgate_recovery_001": 5
    }
  },
  "resultText": "The milk inspection begins immediately. The bones do not become less weird, but they do become more useful."
 }
 ```
 ---
 ## Resource Formula Rules
 MVP should start simple and readable.
 ### Daily Resource Production
 Each settlement may produce resources at the end of each day.
 Example:
 ```text
 dailyBones = sum(settlement.boneProduction)
 dailyMilk = sum(settlement.milkProduction)
 dailyMinionUpkeep = floor(minionTotal / 10)
 ```
 Suggested MVP daily update:
 ```text
 bones += totalBoneProduction
 milk += totalMilkProduction
 milk -= floor(minions / 10)
 ```
 Optional:
 Minions require milk upkeep. If milk cannot cover upkeep, minion morale or count drops.
 ---
 ## Resource Triangle Rules
 ### Bones -> Minions
 Bones create minions.
 MVP formula:
 ```text
 1 minion costs 5 bones
 ```
 Better minions can come later.
 Optional future formula:
 ```text
 minionQuality = averageBoneQuality
 ```
 ### Minions -> Milk
 Minions can be assigned to produce milk.
 MVP formula:
 ```text
 1 assigned minion produces 1 milk per day
 ```
 Optional improvement:
 ```text
 milkProduced = assignedMinions * settlement.milkMultiplier
 ```
 ### Milk -> Bones
 Milk improves bone production and bone quality.
 MVP formula:
 ```text
 Sending 3 milk to a bone settlement increases boneProduction by +1 for 3 days.
 ```
 Alternative:
 ```text
 boneQuality += milkSent * 0.1
 boneProduction += floor(milkSent / 3)
 ```
 Keep the MVP simple. Use the first version unless deeper simulation is needed.
 ---
 ## Settlement / World Map Schema
 Recommended settlement object:
 ```json
 {
  "id": "marrowgate",
  "name": "Marrowgate",
  "type": "city",
  "owner": "blb",
  "factionInfluence": ["bone_guild"],
  "resources": {
    "boneProduction": 5,
    "milkProduction": 0,
    "minionCapacity": 2
  },
  "stats": {
    "stability": 60,
    "loyalty": 50,
    "need": 30,
    "danger": 10
  },
  "tags": ["bone_city", "industrial", "early_game"],
  "statusEffects": [
    {
      "id": "milk_boost",
      "durationDays": 3,
      "effects": {
        "boneProduction": 1
      }
    }
  ]
 }
 ```
 ---
 ## Faction Schema
 Recommended faction object:
 ```json
 {
  "id": "bone_guild",
  "name": "The Bone Guild",
  "trust": 50,
  "power": 40,
  "agenda": "Control bone standards and production rights.",
  "likes": ["bone_investment", "predictable_law", "industrial_expansion"],
  "dislikes": ["milk_theology", "resource_waste", "minion_labor_rights"],
  "tags": ["economic", "bones", "industrial"]
 }
 ```
 ---
 ## Trust and Stability Ranges
 Use 0-100 ranges.
 ### Faction Trust
 ```text
 0-20: hostile
 21-40: suspicious
 41-60: neutral
 61-80: supportive
 81-100: loyal
 ```
 ### Settlement Stability
 ```text
 0-20: collapsing
 21-40: unstable
 41-60: strained
 61-80: stable
 81-100: thriving
 ```
 ### Settlement Need
 ```text
 0-20: comfortable
 21-40: minor need
 41-60: serious need
 61-80: crisis
 81-100: emergency
 ```
 ---
 ## Minion Assignment Rules
 MVP minions can be assigned during the world map phase.
 Possible assignments:
 - Produce milk
 - Harvest bones
 - Stabilize settlement
 - Guard settlement
 - Repair damage
 - Support faction project
 MVP rule:
 ```text
 Each available minion can be assigned to one task per day.
 Assigned minions return at the end of the day unless the action says otherwise.
 ```
 Example map action:
 ```json
 {
  "id": "assign_minions_to_lacthollow",
  "label": "Assign minions to Lacthollow dairies",
  "costs": {
    "minions": 3
  },
  "durationDays": 1,
  "effects": {
    "milk": 3,
    "settlement": {
      "lacthollow": {
        "stability": 2
      }
    }
  }
 }
 ```
 ---
 ## Daily Seed Algorithm
 The daily seed should combine randomness with world state.
 MVP daily flow:
 ```text
 1. Start day.
 2. Build eligible petitioner pool.
 3. Filter by minDay, maxDay, required flags, blocked flags.
 4. Increase weights based on current resource shortages.
 5. Increase weights based on unstable settlements.
 6. Increase weights based on low faction trust.
 7. Select 3 petitioners.
 8. Prevent duplicate petitioner IDs in same day.
 9. Save selected petitioner IDs into day history.
 ```
 Example weighting rules:
 ```text
 If bones < 20, add +5 weight to bone-related petitioners.
 If milk < 10, add +5 weight to milk-related petitioners.
 If minions < 5, add +5 weight to minion-related petitioners.
 If settlement stability < 40, add +8 weight to that settlement's crisis events.
 If faction trust < 30, add +6 weight to that faction's complaint events.
 ```
 AI rotation can later generate or modify eligible cases, but the MVP should first prove deterministic seeded selection.
 ---
 ## Save Game Structure
 Recommended save structure:
 ```json
 {
  "saveVersion": "0.1.0",
  "gameId": "run_001",
  "day": 4,
  "resources": {
    "bones": 32,
    "minions": 9,
    "milk": 12
  },
  "kingdom": {
    "stability": 58
  },
  "settlements": {},
  "factions": {},
  "flags": [
    "seen_bad_bones_case",
    "marrowgate_milk_audit_started"
  ],
  "history": {
    "seenPetitioners": [],
    "rulings": [],
    "dailySummaries": []
  },
  "rng": {
    "seed": "BLB_RUN_001_DAY_004"
  }
 }
 ```
 ---
 ## Failure States
 MVP failure states:
 ```text
 bones <= 0 = Bone Collapse
 minions <= 0 = Workforce Collapse
 milk <= 0 = Milk Famine
 kingdomStability <= 0 = Dominion Collapse
 three settlements collapsed = Map Collapse
 one faction trust <= 0 and faction power >= 70 = Faction Coup
 ```
 Each failure state should have a unique summary screen.
 ---
 ## Example Day
 ### Starting Resources
 ```text
 Bones: 25
 Minions: 8
 Milk: 10
 Kingdom Stability: 55
 ```
 ### Petitioner 1
 **Foreman Clatter of Marrowgate**
 Problem:
 Marrowgate's bones are brittle and production is dropping.
 Choices:
 1. Send 3 milk and 1 minion inspector.
 2. Punish the Bone Guild.
 3. Ignore the problem.
 Chosen:
 Send milk and inspector.
 Result:
 ```text
 Milk -3
 Minions -1 for the day
 Marrowgate Stability +5
 Marrowgate Bone Production +1 for 3 days
 Bone Guild Trust +3
 ```
 ### Petitioner 2
 **Gerald the Minion Clerk**
 Problem:
 Minions are complaining that milk duty is sticky, humiliating, and "beneath skeleton-adjacent workers of their station."
 Choices:
 1. Promise hats.
 2. Ignore them.
 3. Spend bones to improve minion tools.
 Chosen:
 Promise hats.
 Result:
 ```text
 Minion morale flag added: promised_hats
 No immediate resource cost
 Future event unlocked: hat_accountability
 ```
 ### Petitioner 3
 **Mayor Pella of Ribcage Crossing**
 Problem:
 Merchants want lower tariffs in exchange for emergency milk barrels.
 Choices:
 1. Accept the trade.
 2. Refuse and protect Dominion markets.
 3. Demand bones instead.
 Chosen:
 Accept trade.
 Result:
 ```text
 Milk +5
 Ribcage Crossing Loyalty +4
 Bone Guild Trust -2
 Future trade event weight +5
 ```
 ### World Map Action
 Action:
 Assign 3 minions to Lacthollow dairies.
 Result:
 ```text
 Milk +3 at end of day
 Lacthollow Stability +2
 3 minions unavailable until next day
 ```
 ### End of Day Summary
 ```text
 Bones: 25
 Minions: 8
 Milk: 15
 Marrowgate is recovering.
 The Bone Guild is slightly annoyed by trade concessions.
 The minions remember the promised hats.
 Tomorrow's petitioner pool now includes possible hat-related consequences.
 ```
 ---
 ## Content Format
 Recommended MVP content format:
 ```text
 Hand-authored JSON for game logic.
 Markdown for lore/wiki pages.
 Cached AI-generated petitioners later.
 Database only after the schema stabilizes.
 ```
 ### MVP Recommendation
 Use:
 - `/content/petitioners/*.json`
 - `/content/choices/*.json`
 - `/content/settlements/*.json`
 - `/content/factions/*.json`
 - `/wiki/*.md`
 Do not start with a database unless the game already needs live editing, user-generated content, or server-side persistence.
 ---
 ## AI-Generated Content Rule
 AI-generated petitioners should not directly mutate the game state without validation.
 Recommended flow:
 ```text
 AI generates petitioner draft.
 System validates schema.
 System assigns approved tags/effects only from allowed list.
 Generated content is cached.
 Player sees cached petitioner.
 Ruling applies deterministic effects.
 ```
 The AI may write flavor.
 The game engine must control consequences.
 ---
 ## UI Wireframe Notes
 ### Throne Screen
 ```text
 [Resource HUD]
 [BLB on Throne]
 [Petitioner Portrait]
 [Petitioner Text]
 [Choice 1]
 [Choice 2]
 [Choice 3]
 [Day / Map / Summary Buttons]
 ```
 ### Resource HUD
 ```text
 Bones: 25 Minions: 8 Milk: 10
 Stability: 55 Day: 4
 ```
 ### Map Screen
 ```text
 [Resource HUD]
 [World Map]
 Marrowgate: Stable, Bone +5
 Lacthollow: Strained, Milk +3
 Ribcage Crossing: Neutral, Trade Active
 Homesteads: Need Rising
 [Available Actions Panel]
 ```
 ### Daily Summary
 ```text
 Day 4 Complete
 Resource Changes:
 Bones +0
 Minions +0
 Milk +5
 Settlement Changes:
 Marrowgate recovering
 Lacthollow stabilized
 New Flags:
 promised_hats
 marrowgate_milk_audit_started
 [Begin Day 5]
 ```
 ---
 ## Build Priority
 ### Phase 1: Static MVP
 - Home screen
 - Throne room screen
 - Resource HUD
 - Three hard-coded petitioners
 - Choice effects
 - Daily summary
 - Basic save state
 ### Phase 2: Seeded Days
 - Petitioner pool
 - Weighted selection
 - Flags
 - Settlement/faction state
 - Map action screen
 ### Phase 3: Reactive World
 - Settlement consequences
 - Faction trust
 - Recurring petitioners
 - Failure states
 - Endings
 ### Phase 4: AI Layer
 - AI-generated petitioner drafts
 - Schema validation
 - Cached event rotation
 - Flavor expansion
 - Dynamic but controlled content
 ---
 *See also: [[Home]] | [[Gameplay]] | [[Lore]] | [[Story]] | [[References]]*