idle/docs/gyms/tiny_sword/PROGRESSION.md

# Tiny Sword — Progression Plan

Full progression design for a playable idle game, from first click to victory.

## Overview

The game has 8 phases. Each phase is gated behind a goal. Completing the goal unlocks new buildings, buffs, or systems that accelerate progress toward the next phase.

The Devil Idol is visible from the start as a long-term goal — destroying it is the one-time win condition. Prestige loops make it asymptotically easier.

---

## Phase Table

| Phase | Goal | Threshold | Unlocks |
|---|---|---|---|
| 1 | *(none)* | Start | Gold Mine (click only, no auto-production) |
| 2 | `gold_total_30` | 30 total gold | Gold Clicker, Gold Dynamo, Summon Worker buffs |
| 3 | `gold_total_1300` | 1,300 total gold | Farm building (food economy begins) |
| 4 | `gold_total_13k` | 13,000 total gold | Forestry building (wood economy), Farm Dynamo, Forest Dynamo |
| 5 | `gold_350k_wood_20k` | 350K gold + 20K wood | **Prestige** (Castle) + **Research** (Monastery) |
| 6 | `gold_2M_food_200k_wood_200k` | 2M gold + 200K food + 200K wood | **Alchemy Tower** |
| 7 | *(post-alchemy)* | — | Alchemy buffs (spend mana stone / cognite / philosopher stone) |
| 8 | `gold_50M_food_5M_wood_5M` | 50M gold + 5M food + 5M wood | **Barracks** + **Devil Idol fight** |

> **Note**: Phase 7 has no dedicated goal — it unlocks implicitly when the Alchemy Tower is active and the player can craft alchemy resources. The Phase 8 goal only needs to be reachable after Alchemy buffs have been applied.

---

## Phase Details

### Phase 1 — Start

**State**: Gold Mine is visible and unlocked, 0 owned, 0 workers.
**Action**: Player clicks the Gold Mine to earn gold manually (1 gold / click, 0.2s cooldown).
**Exit**: Accumulate 30 total gold → Phase 2.

---

### Phase 2 — First Automation

**Goal**: `gold_total_30` (30 total gold)

**Unlocks**:
| Buff | Kind | Cost | Effect | Max Level |
|---|---|---|---|---|
| Gold Clicker | MANUAL_CLICK_MULTIPLIER | Gold | ×(1 + 1×level) click multiplier | 4 |
| Gold Dynamo | AUTO_PRODUCTION_MULTIPLIER | Food | ×(1 + 1×level) auto prod | 10 |
| Summon Worker | RESOURCE_PURCHASE | Gold | Grants 1 worker | ∞ |

**Design note**: Gold Dynamo costs food but Farm isn't unlocked until Phase 3. This is intentional — the buff is visible but unusable until food flows. It creates anticipation.

**Exit**: Buy Summon Worker (200 gold) → get 1 worker → buy first Gold Mine (1 worker) → auto-production begins at 20 gold/s. Accumulate 1,300 total gold → Phase 3.

---

### Phase 3 — Food Economy

**Goal**: `gold_total_1300` (1,300 total gold)

**Unlocks**:
- **Farm** building — starts with 1 owned, produces 20 food/s, purchasable with workers

**New loop**: Gold → workers → more Gold Mines + more Farms. Food accumulates. Gold Dynamo (unlocked in Phase 2) now becomes purchasable with food, multiplying gold mine output.

**Exit**: Accumulate 13,000 total gold → Phase 4.

---

### Phase 4 — Wood Economy

**Goal**: `gold_total_13k` (13,000 total gold)

**Unlocks**:
- **Forestry** building — starts with 1 owned, produces 20 wood/s, purchasable with workers
- **Farm Dynamo** buff — AUTO_PRODUCTION_MULTIPLIER for Farm, costs food, max 10
- **Forest Dynamo** buff — AUTO_PRODUCTION_MULTIPLIER for Forestry, costs food, max 10

**New loop**: Wood flows alongside gold and food. Three parallel production lines scale independently.

**Exit**: Accumulate 350,000 gold + 20,000 wood → Phase 5.

---

### Phase 5 — Prestige + Research

**Goal**: `gold_350k_wood_20k` (350,000 total gold + 20,000 total wood)

**Unlocks**:
- **Prestige panel** at Castle becomes visible and interactive
- **Research panel** at Monastery becomes visible and interactive

#### Prestige System

| Config Property | Value |
|---|---|
| Source basis | RUN_TOTAL (gold earned this run) |
| Formula | POWER, exponent 0.5, scale 1.0 |
| Threshold | 50,000 gold (per prestige point) |
| Rounding | FLOOR |

**First prestige estimate**: At 350K gold → `floor(sqrt(350000/50000))` = `floor(sqrt(7))` = `floor(2.64)` = **2 ascension points**.
**Second run**: With prestige buffs applied and ~500K gold → `floor(sqrt(10))` = **3 ascension points**.

`total_prestige_earned` persists across resets — it's a strictly increasing counter that never resets. It feeds the prestige multiplier (`base_multiplier + total_prestige_earned × multiplier_per_prestige`).

**Prestige Buff Graph** (purchasable with ascension points):
| Node | Cost | Prerequisites | Effect |
|---|---|---|---|
| Golden Touch | 1 ascension | *(none)* | Gold Mine ×2 production |
| Fertile Grounds | 2 ascension | Golden Touch | Farm ×2 production |
| Wood Touch | 3 ascension | Fertile Grounds | Forestry ×2 production |
| Martial Prowess | 5 ascension | Wood Touch | Barracks ×2 unit production *(Phase 8)* |

#### Research System

Three research tracks at the Monastery:

| Track | Linked Generator | XP Source |
|---|---|---|
| Gold Mine Research | Gold Mine | Gold production |
| Farm Research | Farm | Food production |
| Forestry Research | Forestry | Wood production |

One track active at a time. XP scales with workers assigned to research (`research_workers`). Default: 0.01 XP per currency unit, 100 XP for level 1, ×1.5 growth per level, +0.1 multiplier per level.

**Exit**: Accumulate 2M gold + 200K food + 200K wood → Phase 6.

---

### Phase 6 — Alchemy Tower

**Goal**: `gold_2M_food_200k_wood_200k` (2,000,000 total gold + 200,000 food + 200,000 wood)

**Unlocks**:
- **Alchemy Tower** building — passively produces Magic Gold

#### Alchemy Tower Mechanics

- Cycles of base 5 seconds, producing 1 Magic Gold per cycle
- Cycle time grows ×1.2 per completed cycle
- Workers can be assigned (1 worker each, up to 10) for +10% speed each
- Workers assigned here are separate from research workers (spent from worker currency)

#### Crafting Recipes

| Recipe | Input | Output |
|---|---|---|
| Mana Stone | 10 Magic Gold | 1 Mana Stone |
| Cognite | 25 Magic Gold | 1 Cognite |
| Philosopher Stone | 10 Mana Stone + 10 Cognite | 1 Philosopher Stone |

**Exit**: Build up alchemy resources → Phase 7 (implicit).

---

### Phase 7 — Alchemy Buffs

**Prerequisite**: Alchemy Tower active, player can craft resources.

Three new buffs, purchasable with alchemy resources:

| Buff | Cost Currency | Target | Effect | Max Level |
|---|---|---|---|---|
| Fertile Infusion | Mana Stone | Farm | ×2 production per level | 5 |
| Sylvan Cognite | Cognite | Forestry | ×2 production per level | 5 |
| Opus Magnum | Philosopher Stone | Gold Mine | ×3 production per level | 5 |

Added to the buff catalogue. Available via the existing buff purchase UI in each generator's panel.

**Exit**: Accumulate 50M gold + 5M food + 5M wood → Phase 8.

---

### Phase 8 — Devil Idol (Finale)

**Goal**: `gold_50M_food_5M_wood_5M` (50,000,000 total gold + 5,000,000 food + 5,000,000 wood)

**Unlocks**:
- **Barracks** building — produces Military Units (pure damage currency)
- **Devil Idol** becomes targetable

#### Barracks

| Property | Value |
|---|---|
| Produces | `unit` currency |
| Purchase cost | Workers |
| Unlock goal | Phase 8 goal |
| Research track | Shares with ? or none (TBD) |
| Prestige buff | Martial Prowess (×2 unit production) |

#### Devil Idol

| Property | Value |
|---|---|
| Visible from | Start (always visible in world) |
| Targetable from | Phase 8 |
| HP | `1e12` (1,000,000,000,000) — defined in an exported resource |
| Damage mechanic | Click idol to spend 1 unit → deal 1 damage. Or "Send Army" button for bulk spend. |
| Win condition | HP ≤ 0 → victory signal (TBD: victory screen, credits, etc.) |

#### Asymptotic Loop

Without prestige: defeating the idol would require 10^12 units, which with baseline production is essentially infinite.

With prestige: each loop applies Martial Prowess (+×2 per level) to Barracks production. A player with 5 ascension points in Martial Prowess produces ×32 units per cycle. As they earn more ascension points across runs, unit production scales multiplicatively, asymptotically reducing the "time to kill."

The idol HP never resets — it's persistent across prestige. Each prestige loop chips away at it.

---

## Currency Catalogue (Complete)

| Currency | ID | Produced By | Used For |
|---|---|---|---|
| Gold | `gold` | Gold Mine | Buff purchases, worker generation |
| Worker | `worker` | Summon Worker buff | Purchasing generators, research assignment, alchemy workers |
| Food | `food` | Farm | Buff purchases |
| Wood | `wood` | Forestry | Goal requirements |
| Ascension | `ascension` | Prestige resets | Prestige buff graph |
| Magic Gold | `magic_gold` | Alchemy Tower | Crafting mana stones + cognite |
| Mana Stone | `mana_stone` | Craft (10 magic gold) | Crafting philosopher stones, Fertile Infusion buff |
| Cognite | `cognite` | Craft (25 magic gold) | Crafting philosopher stones, Sylvan Cognite buff |
| Philosopher Stone | `philosoper_stone` | Craft (10 mana + 10 cognite) | Opus Magnum buff |
| Unit | `unit` | Barracks | Devil Idol damage |

---

## Buff Catalogue (Complete)

| Buff | ID | Kind | Cost | Unlock Goal | Max Lvl | Target |
|---|---|---|---|---|---|---|
| Gold Clicker | `gold_click_focus` | CLICK_MULT | Gold | `gold_total_30` | 4 | Gold Mine |
| Gold Dynamo | `gold_auto_flux` | AUTO_MULT | Food | `gold_total_30` | 10 | Gold Mine |
| Summon Worker | `summon_worker` | RESOURCE | Gold | `gold_total_30` | ∞ | Worker |
| Farm Dynamo | `farm_auto_flux` | AUTO_MULT | Food | `gold_total_13k` | 10 | Farm |
| Forest Dynamo | `forestry_auto_flux` | AUTO_MULT | Food | `gold_total_13k` | 10 | Forestry |
| Fertile Infusion | *(new)* | AUTO_MULT | Mana Stone | *(alchemy active)* | 5 | Farm |
| Sylvan Cognite | *(new)* | AUTO_MULT | Cognite | *(alchemy active)* | 5 | Forestry |
| Opus Magnum | *(new)* | AUTO_MULT | Philo Stone | *(alchemy active)* | 5 | Gold Mine |

---

## Goal Catalogue (Complete)

| Goal ID | Requirements | Unlock Behavior | Phase |
|---|---|---|---|
| `gold_total_30` | 30 gold | AUTOMATIC | 2 |
| `gold_total_1300` | 1,300 gold | MANUAL | 3 |
| `gold_total_13k` | 13,000 gold | MANUAL | 4 |
| `gold_350k_wood_20k` | 350,000 gold + 20,000 wood | MANUAL | 5 |
| `gold_2M_food_200k_wood_200k` *(new)* | 2M gold + 200K food + 200K wood | MANUAL | 6 |
| `gold_50M_food_5M_wood_5M` *(new)* | 50M gold + 5M food + 5M wood | MANUAL | 8 |

---

## Prestige Buff Graph (Complete)

```
					  Golden Touch (1pt)
							│
					  Fertile Grounds (2pt)
							│
					   Wood Touch (3pt)
							│
					 Martial Prowess (5pt)
```

| Node | Cost | Prerequisites | Effect | Target |
|---|---|---|---|---|
| Golden Touch | 1 | none | ×2 production | Gold Mine |
| Fertile Grounds | 2 | Golden Touch | ×2 production | Farm |
| Wood Touch | 3 | Fertile Grounds | ×2 production | Forestry |
| Martial Prowess | 5 | Wood Touch | ×2 production | Barracks |

---

## Buildings (Complete)

| Building | Scene | Generates | Cost Currency | Unlock Goal |
|---|---|---|---|---|
| Gold Mine | `gold_mine.tscn` | Gold | Worker | *(none)* |
| Farm | `farm.tscn` | Food | Worker | `gold_total_1300` |
| Forestry | `forestry.tscn` | Wood | Worker | `gold_total_13k` |
| Monastery | `monastery.tscn` | *(none — Research UI)* | — | `gold_350k_wood_20k` (panel visible) |
| Castle | `castle.tscn` | *(none — Prestige UI)* | — | `gold_350k_wood_20k` (panel visible) |
| Alchemy Tower | `alchemy_tower.tscn` | Magic Gold | — | `gold_2M_food_200k_wood_200k` *(new)* |
| Barracks | `barracks.tscn` *(new)* | Unit | Worker | `gold_50M_food_5M_wood_5M` *(new)* |
| Devil Idol | `devil_idol.tscn` *(new)* | *(none — damage sink)* | — | `gold_50M_food_5M_wood_5M` (targetable) |

---

## Implementation Checklist

### Phase 1–2 (already exists)
- [x] Gold Mine building + generator
- [x] Gold Clicker, Gold Dynamo, Summon Worker buffs
- [x] `gold_total_30` goal

### Phase 3–4 (already exists)
- [x] Farm building + generator
- [x] `gold_total_1300` goal
- [x] Forestry building + generator
- [x] Farm Dynamo, Forest Dynamo buffs
- [x] `gold_total_13k` goal

### Phase 5 — Prestige + Research Visibility
- [ ] **`castle.gd`**: Uncomment `_prestige_panel.visible = true`, gate behind `gold_350k_wood_20k` goal completion
- [ ] **`primary_prestige.tres`**: Tune basis → RUN_TOTAL, source → `"gold"`, threshold → 50,000, exponent → 0.5
- [ ] **`monastery.gd`**: Gate `_research_panel.visible` behind `gold_350k_wood_20k` goal completion
- [ ] **`prestige_buff_catalogue.tres`**: Add Wood Touch + Martial Prowess nodes
- [x] `gold_350k_wood_20k` goal (already exists)

### Phase 6 — Alchemy Tower Gating
- [ ] **New goal `.tres`**: `gold_2M_food_200k_wood_200k`
- [ ] **`ts_goal_catalogue.tres`**: Register new goal
- [ ] **`alchemy_tower_data.tres`** or **`alchemy_tower.tscn`**: Add `unlock_goal` field
- [ ] Wire unlock to Alchemy Tower visibility

### Phase 7 — Alchemy Buffs
- [ ] **New buff `.tres`**: Fertile Infusion (mana stone → farm, ×2, max 5)
- [ ] **New buff `.tres`**: Sylvan Cognite (cognite → forestry, ×2, max 5)
- [ ] **New buff `.tres`**: Opus Magnum (philosopher stone → gold mine, ×3, max 5)
- [ ] **`ts_buff_catalogue.tres`**: Register the 3 new buffs

### Phase 8 — Barracks + Devil Idol
- [ ] **New goal `.tres`**: `gold_50M_food_5M_wood_5M`
- [ ] **`ts_goal_catalogue.tres`**: Register new goal
- [ ] **New currency `.tres`**: Unit (`unit`)
- [ ] **`ts_currency_catalogue.tres`**: Register unit currency
- [ ] **New generator data `.tres`**: `barracks_generator.tres`
- [ ] **New scene**: `barracks.tscn` (NG2D, sprite, Area2D, CurrencyGenerator, GeneratorContainer)
- [ ] **New scene**: `devil_idol.tscn` (NG2D, sprite, Area2D, click handler, HP display, win logic)
- [ ] **New prestige buff `.tres`**: Martial Prowess (×2 barracks production, cost 5 ascension, parent: Wood Touch)
- [ ] **`prestige_buff_catalogue.tres`**: Register Martial Prowess
- [ ] **`tiny_sword.tscn`**: Place Barracks + Devil Idol in world
- [ ] Victory condition handling (TBD: signal, screen, save state)

### Research (Phase 5+, already functional)
- [x] ResearchData for Gold Mine, Farm, Forestry
- [x] ResearchPanel at Monastery
- [x] ResearchRow UI
- [x] XP generation in CurrencyGenerator
- [ ] *(optional)*: Add Barracks research track
- [ ] *(optional)*: Tune per-track values (XP required, multiplier growth)

---

## File Map

```
docs/gyms/tiny_sword/
├── PROGRESSION.md                          ← this file
├── tiny_sword.tscn                         ← main scene (add Barracks + Devil Idol)
│
├── currencies/
│   ├── ts_currency_catalogue.tres          ← register "unit" currency
│   └── unit.tres                           ← NEW: unit currency definition
│
├── buffs/
│   ├── ts_buff_catalogue.tres              ← register alchemy buffs
│   ├── fertile_infusion_buff.tres          ← NEW
│   ├── sylvan_cognite_buff.tres            ← NEW
│   └── opus_magnum_buff.tres               ← NEW
│
├── goals/
│   ├── ts_goal_catalogue.tres              ← register new phase 6 + 8 goals
│   ├── gold_2M_food_200k_wood_200k.tres    ← NEW
│   └── gold_50M_food_5M_wood_5M.tres      ← NEW
│
├── prestige/
│   ├── primary_prestige.tres               ← tune: RUN_TOTAL, gold, 50K threshold
│   ├── prestige_buff_catalogue.tres        ← register Wood Touch + Martial Prowess
│   ├── prestige_buff_wood_boost.tres       ← existing (may need cost/parent update)
│   └── prestige_buff_barracks_boost.tres   ← NEW
│
├── buildings/
│   ├── barracks/                           ← NEW
│   │   ├── barracks.tscn
│   │   └── barracks_generator.tres
│   ├── devil_idol/                         ← NEW
│   │   └── devil_idol.tscn
│   └── ... (existing buildings)
│
└── research/
	└── ts_research_catalogue.tres          ← (optional) add barracks research
```