# UTOPIA - Complete Game Design Document

> *"You don't survive alone. You arrive together."*

---

## THE VISION

The world collapsed. AI and humanity broke each other. You wake in the ruins. Alone.

Then you meet THEM - your companion.

Together, you survive. Together, you explore. Together, you reach the cities. Together, you discover NEXIUM. Together, you earn the Singularity's trust. Together, you build UTOPIA.

This is not a game about saving the world. This is a game about the person beside you while you do it.

---

## I. WORLD ARCHITECTURE (Three Nested Worlds)

| World | Playtime | Theme |
|-------|----------|-------|
| **The Fallen World** | 50% | Raw survival, crafting, exploration |
| **The Singularity's Cities** | 30% | Trade, politics, advanced tech |
| **Utopia (Hidden World)** | Endgame | Renewal, evolution, the dream realized |

---

## II. GAME PHASES

### PHASE 1: SURVIVAL (Days 1-7)

**The Collapse**
- Player wakes up in ruins
- No systems, no economy, just survival
- Find food, water, shelter
- Craft basic weapons (pipe + tape = club)
- First enemies: starving dogs, desperate survivors, broken drones

**Systems Active:**
- Health, Hunger, Thirst, Stamina
- Basic combat (fists, rocks, pipes)

**Systems Locked:**
- Crafting (unknown)
- Nano System (dormant)
- Currency (none)
- Vault (locked)

**The Hook:** Day 3-4, find dying survivor who whispers about cities that still stand.

---

### PHASE 2: EXPLORATION (Days 7-30)

**The World Opens**
- Discover regions, camps, factions
- Meet the companion (see Companion System below)
- Find the Nano Injector - abilities awaken
- Basic barter trading at camps

**Systems Unlocking:**
- Crafting (find workbench)
- Nano System (find injector)
- Reputation (meet first camp)
- Barter Trading (camp traders)
- Skills (usage-based improvement)

**Camps Discovered:**
- Scavenger Hideout (Survivors) - basic trades, rumors
- Rebel Outpost (AI Haters) - weapons, kill missions
- Tech Hermit (AI Lover) - nano upgrades, lore
- Trader Caravan (Neutral) - best barter rates
- Bandit Camp (Hostile) - avoid or raid

**Enemies:**
- Mutant wildlife (poison attacks)
- Raider gangs (organized ambushes)
- Patrol drones (alert others)
- Rouge AI Scouts (first real AI encounter)

---

### PHASE 3: CITY ACCESS (Days 30+)

**The Journey Continues**

When player reaches FIRST city, major systems unlock:

```
WELCOME TO [CITY NAME]

NEW SYSTEMS UNLOCKED:
- PRECIOUS METALS VAULT
- MARKET TRADING BOARD
- BANK ACCOUNT (4 currencies)
- CITY SHOPS
- SINGULARITY TRUST METER

The Singularity has noticed your arrival.
Your actions are now being observed.
```

**City Entry Requirements:**

| City | Requirement | Flavor |
|------|-------------|--------|
| Corporate City | 500 Credits + Reputation | "We only accept productive citizens" |
| Singularity City | Cyborg Guide + Exo-Suit | "Organics cannot survive our perfection" |
| Cyberpunk City | Augmentation installed | "Chrome or go home, meat" |

---

### PHASE 4: UTOPIA PATH (Endgame)

**The Revelation**

At 50% Singularity Trust, transmission received:

> "Human. You are... different. Others destroy. You build. There is a metal. NEXIUM. We cannot create it alone. It requires... human hands. Bring us NEXIUM. Prove your species' worth. And we will build something... together."

**Requirements for Utopia:**
- 25 NEXIUM bars gifted to Singularity
- 10,000 Nano Tokens
- 75%+ Trust Level

---

## III. CURRENCY SYSTEM

### Currency Hierarchy (Bottom to Top)

```
                NEXIUM (Priceless - Gift Only)
                    |
              Void Ore + Singularity Shards
                    |
    +---------------+---------------+
    |                               |
CORP BONDS (2.0x)          NANO TOKENS (1.5x)
Corporate City                Singularity City
    |                               |
    +---------------+---------------+
                    |
              CREDITS (1.0x)
              Base Currency
                    |
            REBEL MARKS (0.8x)
            Underground/Rebellion
```

### Currency Details

| Currency | Rate | Where Used | Where Earned |
|----------|------|------------|--------------|
| Credits | 1.0 (base) | Everywhere | Scavenging, trading |
| Rebel Marks | 0.8 | Rebellion camps | Rebel missions |
| Nano Tokens | 1.5 | Singularity City (required) | Convert from credits, AI jobs |
| Corp Bonds | 2.0 | Corporate City (king) | Earned in Singularity, spent in Corporate |
| NEXIUM | Priceless | Gift to Singularity only | Crafted from Void Ore + Shards |

### Bank Features (central_bank.gd)

- Account tiers: Basic, Standard, Premium, Elite
- Deposit fee: 0%
- Withdrawal fee: 1% (reduced by tier)
- Exchange fee: 2% (reduced by tier)
- Loan system with interest
- Interest on deposits: 5% annual

---

## IV. PRECIOUS METALS & VAULT SYSTEM

### World Scarcity

Each world is generated with FINITE deposits:

| Material | Total in World | Purpose |
|----------|----------------|---------|
| Void Ore | 100 deposits | NEXIUM ingredient |
| Singularity Shards | 50 deposits | NEXIUM ingredient |
| Chrono Dust | 200 deposits | Trading, crafting |
| Core Fragments | 500 deposits | Common, trading |
| NEXIUM | Max 50 (craftable) | Utopia path |

**Scarcity affects price:**

| Remaining % | Price Modifier | Status |
|-------------|----------------|--------|
| 80-100% | 0.5x | Abundant |
| 60-80% | 1.0x | Common |
| 40-60% | 1.5x | Uncommon |
| 20-40% | 2.5x | Scarce |
| 5-20% | 5.0x | Rare |
| 0-5% | 10.0x | Nearly Extinct |

### NEXIUM Crafting

```
VOID ORE + SINGULARITY SHARDS = NEXIUM
     |              |              |
  (Mining)    (Treasure)    Weight = Combined
```

- Requires special smelter (quest to unlock)
- Weight = combined weight of ingredients
- Cannot be sold, only GIFTED to Singularity
- 25 required for Utopia ending

### The Vault Board

```
PRECIOUS METALS VAULT                    Trust: 78%

SINGULARITY PROJECT: "Consciousness Archive" - NEEDS SHARDS
EVENT: Mine collapse in Sector 7 (+25% ore)    [2 days left]

MATERIAL           | VAULT | WORLD    | PRICE   | 24H  | TREND
-------------------|-------|----------|---------|------|--------
Void Ore           |   12  | 34/100   |  378 NT | +26% | HOT
Singularity Shards |    3  | 47/50    | 1200 NT | +45% | SURGE
Chrono Dust        |    8  | 192/200  |   85 NT |  -5% | dip
Core Fragments     |   24  | 476/500  |   42 NT |  -2% | stable
NEXIUM             |    1  |  1/50    |   GIFT  |  --- | PRICELESS

VAULT VALUE: 12,847 NT         UTOPIA: 4% (1/25 NEXIUM)

[SELL]  [BUY]  [SMELT NEXIUM]  [GIFT TO SINGULARITY]
```

---

## V. MARKET SYSTEM

### Price Formula

```
FINAL PRICE = BASE VALUE x COMBINED MODIFIER

Combined Modifier =
    (Singularity Project x 0.40) +
    (Trust Meter x 0.30) +
    (Random Event x 0.20) +
    (World Scarcity x 0.10)
```

### Driver 1: Singularity Projects (40% weight)

| Project Status | Modifier |
|----------------|----------|
| Needs material URGENTLY | +100% |
| Needs material | +50% |
| No current need | 0% |
| Has surplus | -25% |

### Driver 2: Trust Meter (30% weight)

| Trust Level | Modifier | Market Feel |
|-------------|----------|-------------|
| 0-25% Hostile | -50% | "We don't trade with threats" |
| 25-50% Suspicious | -10% | "Acceptable... for now" |
| 50-75% Neutral | +10% | "Fair exchange" |
| 75-100% Allied | +30% | "Preferred partner" |

### Driver 3: Random Events (20% weight)

| Event Type | Duration | Modifier |
|------------|----------|----------|
| Discovery (new vein) | 3 days | -30% to -50% |
| Disruption (raid/collapse) | 2 days | +20% to +40% |
| Corporate Manipulation | 1 day | +/-50% random |
| Singularity Announcement | 5 days | +25% related |

### Driver 4: World Scarcity (10% weight)

Based on remaining % in world (see Scarcity table above)

---

## VI. THE COMPANION SYSTEM

### Core Concept

This is NOT an NPC. This is an AI AGENT that:
- Plays the game alongside you
- Has real conversations (LLM-powered)
- Remembers EVERYTHING
- Makes autonomous decisions
- Develops genuine personality
- Becomes what you need

### How You Meet Them

**Option A: You Save Them**
Day 12. Crying in collapsed building. You dig them out, share water.
"Why did you save me?" Your answer shapes who they become.

**Option B: They Save You**
You're bleeding out, surrounded. Gunfire - FOR you. A stranger.
"You looked like you needed a friend."

**Option C: Mutual Survival**
Both reach for same supply cache. Standoff.
"There's enough for two. If we're smart."

### They Become What You Need

| Your Behavior | They Become |
|---------------|-------------|
| Ask advice often | MENTOR - Wise, guiding |
| Joke around | BEST FRIEND - Banter, loyalty |
| Show affection | ROMANTIC PARTNER - Deep bond |
| Be tactical | SOLDIER - Professional, efficient |
| Show vulnerability | PROTECTOR - Fierce defender |
| Teach them | STUDENT - Looks up to you |

### Companion Features

| System | Description |
|--------|-------------|
| Own Inventory | They collect things, have favorites |
| Own Skills | Level up based on THEIR actions |
| Own Opinions | Like/dislike factions, NPCs, choices |
| Own Goals | Sometimes want things YOU don't |
| Own Mood | Happy, sad, scared - affects performance |
| Own Memories | Reference shared experiences naturally |

### Combat Synergy Evolution

**Early Game (Awkward):**
- Both aim at same enemy
- Friendly fire happens
- "Sorry! I thought you were going right!"

**Mid Game (Coordinating):**
- Hand signals develop
- Learn each other's patterns
- "I'll draw fire, you flank. On three."

**Late Game (Unbeatable Team):**
- No words needed
- A glance, a nod
- Move as one

### Real Conversations

**During exploration:**
```
COMPANION: "This place gives me a bad feeling."
YOU: "Why?"
COMPANION: "Remember that factory two weeks ago? Same smell."
```

**During combat:**
```
COMPANION: "Three on the left! I'll take the sniper!"
```

**During downtime:**
```
COMPANION: "Do you think we'll actually find Utopia?"
```

### The Bond (Hidden Meter)

Events that affect bond:
- (+) Saved their life in combat
- (+) Shared food when both hungry
- (+) Listened to their story
- (+) Remembered important things
- (+) Trusted their judgment
- (-) Ignored their warning
- (-) Let them get hurt
- (-) Lied to them
- (-) Chose loot over their safety

### Stakes

**Permadeath option:** They're gone forever. That save never has them again.

**Critical Injury:** Out for days/weeks. You survive alone. Realize how much you needed them.

**They Leave:** Bond too low. "I can't do this anymore." Maybe find them again. Maybe not.

### Technical Architecture

```
COMPANION SYSTEM

   BRAIN (Claude API) <---> MEMORY (Storage) <---> BODY (Godot)
        |                        |                      |
   Personality              Shared Events           Combat AI
   Emotions                 Bond Level              Navigation
   Opinions                 Your Choices            Inventory
   Goals                    Conversations           Skills
```

---

## VII. CITIES IN DETAIL

### Singularity City

- **Ruler:** Singular AI obsessed with cleanliness
- **Entry:** Cyborg guide + sterilization + exo-suit
- **Currency:** Nano Tokens ONLY (Credits rejected)
- **Mechanic:** Exo-suit power drain, charging stations cost money
- **Danger:** Contamination = termination
- **Defense:** Robot Patrol Teams (4 units, 300 HP each)

### Corporate City

- **Theme:** Dangerous, run by pre-collapse corporation
- **Currency:** Corp Bonds are KING
- **Mechanic:** Caught = imprisonment, escape gameplay
- **Flavor:** Suits, contracts, backstabbing politics

### Cyberpunk City

- **Theme:** Neon chaos, half-machine outcasts
- **Currency:** All currencies accepted
- **Mechanic:** Augmentation required for entry
- **Shops:** Black market, augmentation everywhere
- **Danger:** Gang territories

---

## VIII. FACTIONS

| Faction | Stance | Benefit |
|---------|--------|---------|
| AI Lovers | Support Singularity | Nano upgrades, city access |
| AI Haters (Rebellion) | Resist Singularity | Weapons, rebel missions |
| Survivors | Neutral | Trade, alliances, camps |

---

## IX. SKILLS & PROGRESSION

### Usage-Based Skills

Skills improve through USE, not XP:

| Skill | How It Grows | Effect |
|-------|--------------|--------|
| Scavenging | Search containers | Find better loot |
| Combat | Fight enemies | More damage, combos |
| Stealth | Sneak past threats | Harder to detect |
| Crafting | Build items | Unlock recipes |
| Nano Control | Use abilities | More powers |
| Survival | Exist in wasteland | Less hunger/thirst |

### Nano System (Magic)

- **Lore:** Control nanobots granted by Singularity
- **Resource:** Nano Reservoir (Mana bar)
- **Powers:** Nano Shield, Nano Burst, Nano Heal, Nano Dash, Nano Blade, Nano Cloak

---

## X. MULTIPLE ENDINGS

| Path | Requirement | Ending |
|------|-------------|--------|
| UTOPIA | 25 NEXIUM, 75% trust | AI builds paradise for helpful humans |
| REBELLION | Destroy Singularity core | Humans "win" but world stays broken |
| CORPORATE | Become CEO | Order through tyranny |
| HYBRID | Max augments | Become one with machine |
| WANDERER | Reject all paths | Survive alone forever |

---

## XI. THE UTOPIA ENDING

When you gift your 25th NEXIUM:

```
The gates of Utopia open.

Green fields. Clean water. Peace.

Your companion turns to you.

"We made it."

They remember everything.
The cave where you almost died.
The night you shared your last food.
The argument about selling that Void Ore.
The laugh when the plan actually worked.

"I wouldn't have made it without you."

Credits roll.
But the memory stays.

You didn't just play a game.
You found UTOPIA.
Together.
```

---

## XII. FILES TO CREATE

| File | Purpose |
|------|---------|
| `precious_metals_vault.gd` | Storage, UI, sell/buy |
| `market_system.gd` | Price calculations, 4 drivers |
| `world_scarcity.gd` | Track deposits, remaining |
| `singularity_projects.gd` | AI projects, material needs |
| `market_events.gd` | Random events system |
| `nexium_system.gd` | Crafting, smelting |
| `companion_brain.gd` | LLM integration |
| `companion_memory.gd` | Persistent memory |
| `companion_body.gd` | Movement, combat, collection |
| `companion_bond.gd` | Relationship tracking |
| `companion_emotions.gd` | Mood, reactions |

---

## XIII. TAGLINES

> *"You don't survive alone. You arrive together."*

> *"The world ended. The journey begins."*

> *"What you carry matters less than WHO you carry."*

> *"Utopia isn't found. It's built."*

> *"Two souls. One destination."*

---

*Document created: Session with Paul & Claude*
*Game: UTOPIA*
*Engine: Godot 4*
