docs(wiki): add technical design specs
Aaron Pressey
+1
@@ -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]]*
|
||||
Reference in New Issue
Block a user