Back to Game
Crystal Cavern Defense - Game Design Guide
Game Concept
# Crystal Cavern Defense
## Theme
You are a dwarven mining captain defending an underground crystal cavern from waves of corrupted creatures. The cavern is rich in magical crystals that power your civilization, but the deeper you dig, the more the corruption spreads. You must balance mining operations with tower defense — placing mining drills to extract crystals while simultaneously positioning defensive turrets to hold back the hordes. The twist: your drills and turrets compete for the same limited space, and creatures actively target your mining equipment.
## Visual Game World
The Canvas displays a cross-section of an underground cavern with visible layers of earth. Dark brown soil dominates the background, with colorful crystal deposits scattered throughout — glowing blue geometric crystals, fiery red clusters, and rare purple prisms. Your base is visible on the left edge as a fortified dwarven entrance. The player places structures directly on the terrain: mining drills (with animated spinning bits), auto-turrets (with rotating barrels), and barricades. Creatures spawn from the right side and march left toward your base. Crystal sprites pop out of mined deposits and must be clicked to collect before they despawn. Particle effects show turrets firing, crystals glowing, and creatures dying with explosion animations.
## Player Interaction
The player interacts directly with the Canvas through:
1. **Placement Mode**: Click on any empty terrain cell to place structures. The cursor shows a ghost preview of what will be placed. Different structures require different terrain types (drills need crystal deposits, turrets can go anywhere).
2. **Crystal Collection**: When a mining drill extracts crystals from a deposit, crystal sprites spawn on the Canvas and slowly drift downward. The player must CLICK these crystal sprites within 5 seconds to collect them, or they're lost forever. This creates constant moment-to-moment engagement.
3. **Manual Targeting**: Click on any enemy creature to mark it as a priority target. All turrets in range focus-fire on marked enemies, allowing the player to strategically direct firepower against tough threats.
4. **Structure Management**: Click on existing structures to upgrade them (turning a drill into a mega-drill with visible size increase and faster animation), repair damaged structures, or sell them for resources.
## Entity Types
### Mining Drill
- **Sprite**: ProceduralSprite — diamond shape with rotating inner gear (orange/yellow color scheme)
- **Appearance**: Industrial diamond-shaped machine, 24x24 pixels, animated spinning gear visible inside
- **Behavior**: Stationary, automatically extracts crystals from the deposit beneath it. Emits crystal sprites every 3 seconds. Has 50 HP.
- **Interaction**: Player places drills on crystal deposits. Drills are high-priority targets for enemies. Player clicks to upgrade (faster extraction, more HP).
### Auto-Turret
- **Sprite**: Modified wizard sprite (blue) with fireball projectiles
- **Appearance**: 16x16 tower with animated barrel rotation, fires glowing projectiles
- **Behavior**: Stationary, auto-targets nearest enemy in range (100 pixels). Fires once per second. Has 30 HP.
- **Interaction**: Player places turrets strategically to protect drills and base. Click to upgrade (faster fire rate, more damage, increased range).
### Stone Barricade
- **Sprite**: ProceduralSprite — square with brick pattern (gray)
- **Appearance**: 16x16 wall segment, solid gray block with texture
- **Behavior**: Stationary, blocks enemy movement. High HP (100). Enemies will attack barricades to break through.
- **Interaction**: Player places to create chokepoints and protect valuable drills.
### Corrupted Slime
- **Sprite**: Slime sprite (green variant for basic, red for elite)
- **Appearance**: 16x16 animated blob, 4-frame animation showing squish/pulse
- **Behavior**: Spawns from right edge, marches left toward base. Targets nearest drill if in range, otherwise attacks anything blocking path. Speed varies by type.
- **Interaction**: Enemies are targets for turrets. Player can click to priority-target specific slimes. Death spawns small explosion particles using spark sprite.
### Corrupted Bat
- **Sprite**: Ghost sprite (purple, fast-moving)
- **Appearance**: 16x16 flying creature, translucent purple with flutter animation
- **Behavior**: Flies over barricades, targets drills directly. Faster than slimes but lower HP (15). Unlocks at wave 5.
- **Interaction**: Forces player to place turrets near drills, not just at chokepoints.
### Crystal Sprite (Collectible)
- **Sprite**: ProceduralSprite — small glowing diamond (blue, red, or purple based on crystal type)
- **Appearance**: 8x8 glowing crystal, pulses with opacity animation, trails small particles
- **Behavior**: Spawns from drill, drifts downward for 5 seconds, then despawns. Player must click to collect.
- **Interaction**: PRIMARY PLAYER INTERACTION — creates constant clicking gameplay. Different crystal types give different resources.
### Golem Boss
- **Sprite**: Modified knight sprite (red, oversized at 32x32)
- **Appearance**: Large armored creature, slow but heavily armored (200 HP), appears every 10 waves
- **Behavior**: Marches slowly, smashes structures on contact, takes reduced damage from turrets
- **Interaction**: Requires concentrated fire from multiple upgraded turrets. Player must manually target to focus all turrets.
## Core Loop
### Second-to-Second (ACTIVE GAMEPLAY)
The player is constantly scanning the Canvas: crystal sprites pop out of drills and drift downward, requiring quick clicks to collect. Enemies march from the right, and the player must decide which ones to priority-target by clicking them. Turrets are firing automatically, but the player can click specific enemies to focus fire. The player watches for gaps in defenses and quickly places barricades or turrets to plug holes. Mining drills churn away in the background, visible progress indicators showing extraction progress.
### Minute-to-Minute (STRATEGIC DECISIONS)
Between waves, the player assesses their layout: "Should I replace this drill with a turret to survive the next wave?" or "I need to expand mining operations, but that'll extend my defensive perimeter." The player checks crystal reserves and decides which upgrades to purchase: drill efficiency vs. turret damage vs. barricade health. Each upgrade is visually reflected on the Canvas — upgraded drills spin faster and emit crystal sprites more frequently.
### Session-Level (META STRATEGY)
The player pursues a build: "Crystal Rush" (many drills, minimal defense, relies on manual crystal collection and kiting) vs. "Fortress" (few drills, heavy chokepoint defenses, efficient passive income). The visual layout reflects this — Crystal Rush has drills scattered everywhere, constant crystal sprites popping; Fortress has a tight wall near the spawn point with concentrated drills behind it. The push toward prestige comes when the cavern is fully developed but waves are overwhelming the defenses.
## The 30-Second Gameplay Description
A green slime marches toward your drill, so you click it to mark it as priority-target — two nearby turrets swing their barrels and unleash fireballs. Crystal sprites pop out of your three active drills, drifting downward, so you quickly click each one to collect before they fade. You notice a gap in your barricade line where a red elite slime is about to break through, so you click an empty tile and place a fresh turret. The elite slime goes down in a burst of spark particles. A purple crystal sprite spawns — rare and valuable — but it's drifting toward the edge, so you scramble to click it before it disappears. Your base takes a hit from a bat that flew over your defenses, so you place a turret directly next to your threatened drill.
## Currencies
### Crystals
- **Role**: Primary resource
- **Earned by**: Clicking crystal sprites that spawn from mining drills on the Canvas (blue crystals = 1, red crystals = 5, purple crystals = 20)
- **Spent on**: Building structures (drills, turrets, barricades), basic upgrades
- **Feel**: The flow of battle — constant small decisions about which crystals to collect, creates urgency and engagement
### Gold
- **Role**: Secondary / Upgrade resource
- **Earned by**: Enemy creatures drop gold coins on death (visible as coin sprites that must be clicked to collect)
- **Spent on**: Structure upgrades (drill speed, turret damage, barricade health), unlocking advanced structures
- **Feel**: Progress and mastery — accumulating gold allows meaningful upgrades that change gameplay
### Defense Points (DP)
- **Role**: Strategic resource / Capacity limit
- **Earned by**: Completing waves (wave bonus), surviving bonus objectives (e.g., "lose no structures")
- **Spent on**: NOT spent — represents your structure capacity. Each structure costs DP to place.
- **Feel**: Strategic constraint — forces tradeoffs between mining and defense, creates meaningful placement decisions
### Reputation (Prestige Currency)
- **Role**: Prestige currency
- **Earned by**: Prestiging (trading all progress for Reputation based on crystals mined total)
- **Spent on**: Permanent bonuses (starting structures, unlock new tech, special abilities)
- **Feel**: Long-term progression across runs, each prestige unlocks new strategic options
### Currency Flow
Crystals → Structures & Upgrades → Better Defense & Mining → More Gold & Crystals
Gold → Upgrades → Better Efficiency → More Resources
Reputation → Permanent Bonuses → Faster Early Game → Reach Prestige Sooner
## Progression Hooks
### Early Game (0-5 minutes)
- Immediate access: Place your first drill, watch it extract crystals, click to collect them
- First enemy wave: Simple slimes, easy to defend with one turret
- Quick upgrade: Buy drill speed upgrade, see crystals spawn faster — immediate visual payoff
- First meaningful choice: Second drill or second turret? Expansion vs. defense
### Mid Game (5-15 minutes)
- New enemy type: Bats unlock, flying over barricades, forcing defense strategy rethink
- Multi-color crystals: Red and purple crystals introduce variety, more valuable but rarer
- Advanced structures: Unlock sniper turret (long-range, slow) or scatter turret (short-range, fast)
- Wave boss: First golem boss threatens to overwhelm — requires strategic turret placement
- Crystal crisis: More crystal sprites spawning than player can click — forces prioritization
### Late Game (15-30 minutes)
- Enemy variety: Elite slimes, bat swarms, golem bosses every 5 waves
- Structure combos: Certain turret placements create overlapping fields of fire
- Limited space: Cavern nearly filled, must choose which structures to replace
- Prestige push: Waves becoming unsustainable, crystals mined total high enough for meaningful prestige
- Visual chaos: Dozens of turrets firing, constant crystal rain, massive enemy hordes — spectacular Canvas
### Key Milestones
1. **First Crystal Collected** — Tutorial complete, real gameplay begins
2. **Wave 5 Complete** — Unlocks bats, forces defense strategy rethink
3. **Triple Drill Setup** — Mining operation established, crystal income flowing
4. **First Golem Defeated** — Major achievement, unlocks golem cores as crafting material
5. **Cavern 50% Filled** — Space constraints kick in, placement becomes strategic puzzle
6. **Unlock Sniper Turret** — New defensive option, changes placement calculus
7. **Wave 20 Survival** — Mid-game mastery, prestige becomes viable option
8. **Full Cavern** — Maximum structures placed, optimization phase begins
9. **Prestige Unlocked** — First prestige available, new run promises faster start
10. **Reputation Tier 3** — Advanced mechanics unlocked (special abilities, new tech)
## Meaningful Choices
- **Expansion vs. Consolidation**: Build more drills (spread out, harder to defend, more crystals) vs. upgrade existing drills (concentrated, easier to defend, steady income). This choice is visible on the Canvas — spread-out mining operation vs. compact fortress.
- **Chokepoint Defense vs. Distributed Turrets**: Build barricades to create narrow kill-zones (efficient use of turrets, but enemies concentrate fire) vs. spread turrets evenly (redundancy, but no overlapping firepower). Visibly different layouts.
- **Crystal Collection Strategy**: Click every crystal (micro-intensive, maximizes income) vs. ignore common blue crystals, only click red/purple (relaxed, but sacrifice income). Different playstyles for different player preferences.
- **Tech Tree Path**: Invest in mining tech (better drills, auto-collectors, rare crystal extraction) vs. defense tech (splash damage turrets, slowing fields, barricade regeneration). Each path creates visually distinct games — mining tech leads to crystal-heavy Canvas with collection helpers; defense tech leads to turret-heavy Canvas with elaborate fortifications.
## Prestige Concept
- **Trigger**: Player can prestige after wave 30, but optimal prestige is around wave 40-50 when crystals/minute starts declining due to space constraints.
- **What resets**: All structures, resources (crystals, gold), current wave progress, crystal deposits (cavern regenerates).
- **What persists**: Reputation (prestige currency), unlocked tech tree nodes, permanent upgrades purchased with Reputation.
- **Prestige currency**: Reputation, earned based on total crystals mined before prestiging (1 Reputation per 1000 crystals).
- **Acceleration**: Run 2 starts with 1-2 pre-built basic structures (choose drill or turret), 10% bonus to all income, and one tech node already unlocked. Run 3 accelerates further with 2-3 structures, 25% bonus, two tech nodes.
- **Visual transformation**: Each prestige tier unlocks visual flair — tier 1 adds crystals embedded in cavern walls (background decoration), tier 2 adds dwarven banners and decorations, tier 3 adds animated dwarven NPCs that run around repairing structures. The cavern feels more "lived-in" and developed with each prestige.
## Unique Selling Point
The space-sharing tension between mining and defense creates a constant strategic puzzle. Every tile you use for a drill is a tile you can't use for a turret — but drills earn the resources you need for turrets. Crystal collection requires constant active play, ensuring the player is always engaged with the Canvas, not just watching numbers go up.
## Visual Direction
Dark, moody underground palette. Background is deep browns and blacks with visible soil layers. Crystals glow with inner light — blue (cool), red (warm), purple (mysterious). Turrets and machinery are industrial steampunk — brass, copper, iron with visible gears and pipes. UI overlays are minimal, floating above the Canvas. Enemy sprites are corrupted variants — sickly greens, bruised purples, angry reds. Particle effects are crunchy and visible — bright sparks for hits, puffs of smoke for deaths, glittering trails for crystals. The overall feel is "cozy industrial horror" — you're a dwarf doing a job in a dangerous place.
## Technical Scope Check
Well within implementation scope. Core mechanics are straightforward:
- Grid-based placement system (click to place structure at grid position)
- Simple entity AI (enemies march left, turrets target nearest, crystals drift down)
- Collision detection (projectile hits enemy, enemy reaches structure)
- Resource tracking (counters for crystals, gold, DP)
- Wave system (spawn enemies in patterns, increase difficulty)
- Prestige system (reset most state, preserve some variables)
Sprite usage:
- Mining Drill: ProceduralSprite diamond with animation
- Turret: Modified wizard (blue)
- Barricade: ProceduralSprite square
- Slime: Slime sprite (green/red variants)
- Bat: Ghost sprite (purple)
- Crystal: ProceduralSprite small diamond (blue/red/purple)
- Golem: Knight sprite (red, scaled up)
- Projectiles: Fireball sprite (wizard projectile)
- Particles: Spark sprite
All sprites exist in the framework or can be generated with ProceduralSprite. No complex pathfinding needed (straight-line movement with simple collision). Performance is manageable — 50-100 entities max on screen.
Complex mechanics to simplify:
- No inventory system or crafting
- No complex enemy pathfinding (straight lines, simple barricade collision)
- No terrain deformation beyond placing structures
- Prestige is straightforward state reset + persistent bonuses
The game is highly implementable and focuses on the Canvas interactions that make it engaging.
Currencies
{
"economyFlowDiagram": "flowchart LR\n subgraph \"Sources (Gameplay Actions on Canvas)\"\n CrystalClick[\"Crystal Sprite Clicked\\nBlue: +1 Crystal\\nRed: +5 Crystals\\nPurple: +20 Crystals\\nSprite despawns: 5s\"]\n GoldCoinClick[\"Gold Coin Dropped + Clicked\\nBasic Enemy: +2 Gold\\nElite Enemy: +10 Gold\\nBoss: +100 Gold\\nCoin despawns: 8s\"]\n WaveComplete[\"Wave Completed\\n+10 DP (base)\\n+waveNumber DP\\nNo Loss Bonus: +5 DP\"]\n end\n subgraph \"Sources (Passive)\"\n DrillAuto[\"Drill Auto-Extraction\\nBase: 1 crystal per 3s\\nRate: 1 crystal per (3 - 0.2*level)s\\nMin: 1 per 1s\"]\n end\n subgraph \"Currencies\"\n Crystals((\"Crystals\\nPrimary\\nstart: 10\\nuncapped\"))\n Gold((\"Gold\\nSecondary\\nstart: 5\\nuncapped\"))\n DP((\"Defense Points\\nCapacity\\nstart: 10\\ncap: wave*2+20\"))\n Reputation((\"Reputation\\nPrestige\\nstart: 0\\nuncapped\"))\n end\n subgraph \"Sinks: Structures\"\n DrillBuild[\"Build Mining Drill\\nCost: 15 Crystals\\nDP Cost: 2\"]\n TurretBuild[\"Build Auto-Turret\\nCost: 20 Crystals\\nDP Cost: 2\"]\n BarricadeBuild[\"Build Barricade\\nCost: 10 Crystals\\nDP Cost: 1\"]\n end\n subgraph \"Sinks: Upgrades\"\n DrillUpgrade[\"Drill Level +1\\nCost: 10*1.5^level Gold\\nEffect: +0.5 crystals/sec\"]\n TurretUpgrade[\"Turret Level +1\\nCost: 15*1.6^level Gold\\nEffect: +20% damage\"]\n BarricadeUpgrade[\"Barricade Level +1\\nCost: 8*1.4^level Gold\\nEffect: +50% HP\"]\n end\n subgraph \"Sinks: Unlocks\"\n SniperUnlock[\"Sniper Turret\\nCost: 100 Gold\\nDP: 3\"]\n ScatterUnlock[\"Scatter Turret\\nCost: 150 Gold\\nDP: 2\"]\n AutoCollectorUnlock[\"Auto-Collector Range\\nCost: 200 Gold\\nEffect: Click radius +50%\"]\n end\n subgraph \"Sinks: Prestige\"\n PrestigeAction[\"Prestige Action\\nRequires: Wave 30+\\nResets: Crystals, Gold, DP, Structures\\nPersists: Reputation, Tech Nodes\"]\n RepMultiplier[\"Rep Multiplier +5%\\nCost: 1*1.5^(level-1) Rep\"]\n StartingStruct[\"Starting Structure +1\\nCost: 2 Reputation each\"]\n IncomeBonus[\"Income Bonus +10%\\nCost: 3*level Reputation\"]\n TechNode[\"Tech Tree Node\\nCost: 1-5 Reputation\\nVaries by tier\"]\n end\n\n CrystalClick --> Crystals\n GoldCoinClick --> Gold\n WaveComplete --> DP\n DrillAuto --> Crystals\n Crystals --> DrillBuild\n Crystals --> TurretBuild\n Crystals --> BarricadeBuild\n Gold --> DrillUpgrade\n Gold --> TurretUpgrade\n Gold --> BarricadeUpgrade\n Gold --> SniperUnlock\n Gold --> ScatterUnlock\n Gold --> AutoCollectorUnlock\n DP -->|Consumed| DrillBuild\n DP -->|Consumed| TurretBuild\n DP -->|Consumed| BarricadeBuild\n PrestigeAction --> Reputation\n Reputation --> RepMultiplier\n Reputation --> StartingStruct\n Reputation --> IncomeBonus\n Reputation --> TechNode",
"currencyDefinitions": [
{
"name": "Crystals",
"type": "Primary",
"diagram": "graph TD\n subgraph \"Crystals [Primary Currency]\"\n C_display[\"Display: Diamond icon\\n0 decimals\\nNo suffixes (values stay reasonable)\"]\n C_earn[\"Earning (GAMEPLAY CLICK):\\nClick blue sprite: +1 Crystal\\nClick red sprite: +5 Crystals\\nClick purple sprite: +20 Crystals\\nSprite lifetime: 5 seconds\"]\n C_earn2[\"Earning (PASSIVE):\\nDrill auto: 1 per (3 - 0.2*level)s\\nMinimum: 1 per second\"]\n C_spend[\"Spending:\\nBuild Drill: 15 Crystals\\nBuild Turret: 20 Crystals\\nBuild Barricade: 10 Crystals\"]\n C_inflation[\"Inflation Control:\\nStructure costs: Flat (no scaling)\\nCrystal sprite lifetime: 5s (forces activity)\\nPrestige reset: Clears all crystals\"]\n end",
"startingAmount": 10,
"cap": "uncapped",
"gameplaySources": [
{
"action": "Click blue crystal sprite",
"amount": 1,
"spawnRate": "70% of crystal spawns",
"lifetime": "5 seconds then despawn",
"visual": "Small blue diamond, pulses, drifts down"
},
{
"action": "Click red crystal sprite",
"amount": 5,
"spawnRate": "25% of crystal spawns",
"lifetime": "5 seconds then despawn",
"visual": "Medium red diamond, brighter glow"
},
{
"action": "Click purple crystal sprite",
"amount": 20,
"spawnRate": "5% of crystal spawns",
"lifetime": "5 seconds then despawn",
"visual": "Large purple diamond, sparkle particles"
}
],
"passiveSources": [
{
"source": "Drill auto-extraction",
"baseRate": "1 crystal per 3 seconds",
"formula": "spawnInterval = max(1, 3 - 0.2 * drillLevel)",
"note": "Spawns sprite that still needs clicking (unless auto-collector unlocked)"
}
],
"sinks": [
{
"name": "Build Mining Drill",
"cost": 15,
"dpCost": 2
},
{
"name": "Build Auto-Turret",
"cost": 20,
"dpCost": 2
},
{
"name": "Build Barricade",
"cost": 10,
"dpCost": 1
}
]
},
{
"name": "Gold",
"type": "Secondary",
"diagram": "graph TD\n subgraph \"Gold [Secondary Currency]\"\n G_display[\"Display: Gold coin icon\\n0 decimals\\nSuffixes: K/M/B at 1e6\"]\n G_earn[\"Earning (GAMEPLAY CLICK):\\nBasic enemy death + click: +2 Gold\\nElite enemy death + click: +10 Gold\\nBoss death + click: +100 Gold\\nCoin lifetime: 8 seconds\"]\n G_spend[\"Spending:\\nDrill Upgrade: 10*1.5^level Gold\\nTurret Upgrade: 15*1.6^level Gold\\nBarricade Upgrade: 8*1.4^level Gold\\nSniper Unlock: 100 Gold\\nScatter Unlock: 150 Gold\\nAuto-Collector: 200 Gold\"]\n G_inflation[\"Inflation Control:\\nExponential upgrade costs (1.4-1.6x)\\nEnemy gold scales: 2*(1+0.1*wave)\\nPrestige reset: Clears all gold\"]\n end",
"startingAmount": 5,
"cap": "uncapped",
"gameplaySources": [
{
"action": "Click gold coin from basic enemy (slime)",
"amountFormula": "2 * (1 + 0.1 * waveNumber)",
"lifetime": "8 seconds then despawn",
"visual": "Small gold coin, sparkles"
},
{
"action": "Click gold coin from elite enemy (red slime)",
"amountFormula": "10 * (1 + 0.1 * waveNumber)",
"lifetime": "8 seconds then despawn",
"visual": "Medium gold coin, glow effect"
},
{
"action": "Click gold coin from boss (golem)",
"amountFormula": "100 * (1 + 0.1 * waveNumber)",
"lifetime": "8 seconds then despawn",
"visual": "Large gold coin, particle burst"
}
],
"passiveSources": [],
"sinks": [
{
"name": "Drill Upgrade",
"costFormula": "10 * 1.5^level",
"effect": "+0.5 crystals per second extraction rate"
},
{
"name": "Turret Upgrade",
"costFormula": "15 * 1.6^level",
"effect": "+20% damage per shot"
},
{
"name": "Barricade Upgrade",
"costFormula": "8 * 1.4^level",
"effect": "+50% max HP"
},
{
"name": "Unlock Sniper Turret",
"cost": 100,
"dpCost": 3
},
{
"name": "Unlock Scatter Turret",
"cost": 150,
"dpCost": 2
},
{
"name": "Unlock Auto-Collector",
"cost": 200,
"effect": "Auto-collect crystals within 50px radius"
}
]
},
{
"name": "Defense Points (DP)",
"type": "Capacity",
"diagram": "graph TD\n subgraph \"Defense Points [Capacity Currency]\"\n D_display[\"Display: Shield icon\\nFormat: current / max\\nExample: 15 / 30\"]\n D_earn[\"Earning (WAVE COMPLETE):\\nBase: +10 DP\\nWave bonus: +waveNumber DP\\nNo structures lost: +5 DP\"]\n D_spend[\"Spending (CONSUMED ON BUILD):\\nDrill: 2 DP (refunded on sell)\\nTurret: 2 DP (refunded on sell)\\nBarricade: 1 DP (refunded on sell)\\nSniper: 3 DP (refunded on sell)\\nScatter: 2 DP (refunded on sell)\"]\n D_cap[\"CAP SCALING:\\ndpMax = waveNumber * 2 + 20\\nWave 1: 22 DP\\nWave 10: 40 DP\\nWave 30: 80 DP\"]\n D_inflation[\"Inflation Control:\\nHard cap forces strategic choices\\nMust advance waves to increase cap\\nPrestige reset: DP resets to 10, cap to 22\"]\n end",
"startingAmount": 10,
"cap": "waveNumber * 2 + 20",
"gameplaySources": [
{
"action": "Complete wave",
"baseAmount": 10,
"waveBonus": "waveNumber",
"noLossBonus": 5
}
],
"passiveSources": [],
"sinks": [
{
"name": "Build Drill",
"dpCost": 2,
"refundable": true
},
{
"name": "Build Turret",
"dpCost": 2,
"refundable": true
},
{
"name": "Build Barricade",
"dpCost": 1,
"refundable": true
},
{
"name": "Build Sniper Turret",
"dpCost": 3,
"refundable": true
},
{
"name": "Build Scatter Turret",
"dpCost": 2,
"refundable": true
}
]
},
{
"name": "Reputation",
"type": "Prestige",
"diagram": "graph TD\n subgraph \"Reputation [Prestige Currency]\"\n R_display[\"Display: Star/crown icon\\nInteger\\nPersists across all runs\"]\n R_earn[\"Earning (PRESTIGE ACTION):\\nBase: floor(totalCrystalsMined / 1000)\\nMultiplier: 1 + 0.05*repMultiplierLevel\\nIncome Bonus: 1 + 0.1*incomeBonusLevel\"]\n R_formula[\"Formula:\\nrep = floor((crystals/1000) * repMult * incomeMult)\"]\n R_spend[\"Spending:\\nRep Multiplier +5%: 1*1.5^(level-1) Rep\\nStarting Structure: 2 Rep each\\nIncome Bonus +10%: 3*level Rep\\nTech Node (Tier 1): 1-2 Rep\\nTech Node (Tier 2): 2-3 Rep\\nTech Node (Tier 3): 3-5 Rep\"]\n R_inflation[\"Inflation Control:\\nRep multiplier cost: 1.5x per level\\nTech node costs increase with tier\\nPrestige requires 1000+ crystals\\nEach prestige takes 20-30 minutes optimal\"]\n end",
"startingAmount": 0,
"cap": "uncapped",
"gameplaySources": [
{
"action": "Prestige",
"formula": "floor((totalCrystalsMined / 1000) * (1 + 0.05 * repMultiplierLevel) * (1 + 0.1 * incomeBonusLevel))",
"minimumRequirement": "Wave 30+ (can prestige earlier but not recommended)",
"optimalTiming": "Wave 40-50"
}
],
"passiveSources": [],
"sinks": [
{
"name": "Reputation Multiplier Upgrade",
"costFormula": "1 * 1.5^(level-1)",
"effect": "+5% reputation gain per level"
},
{
"name": "Starting Structure",
"cost": 2,
"effect": "+1 prebuilt structure on next run"
},
{
"name": "Income Bonus",
"costFormula": "3 * level",
"effect": "+10% all income per level"
},
{
"name": "Tech Tree Node",
"cost": "1-5 depending on tier",
"effect": "Unlock permanent tech/bonuses"
}
]
}
],
"conversionRateDiagram": "flowchart LR\n Crystals[\"Crystals\\nAccumulated\\n1000 total mined\"] -->|\"Prestige action\\nRequires: Wave 30+\\nResets ALL progress\\nNo cooldown\\nCan re-prestige after wave 30\"| Reputation[\"Reputation\\n1 (multiplied by bonuses)\"]
\n note1[\"NOTE: This is the ONLY conversion\\nCrystals and Gold have no direct conversion\\nAll other currencies earned through gameplay on Canvas\"]
",
"pacingTimeline": {
"title": "Currency Pacing (First 30 Minutes)",
"chart": "gantt\n title Expected Currency Holdings Over 30 Minutes\n dateFormat mm:ss\n axisFormat %M:%S\n\n section Crystal Milestones\n First drill (15C) :milestone, 00:05, 0\n Three drills (45C) :milestone, 02:00, 0\n Crystal flow (200C) :milestone, 08:00, 0\n Late game (800C) :milestone, 20:00, 0\n\n section Gold Milestones\n First upgrade (15G) :milestone, 01:30, 0\n First unlock (100G) :milestone, 06:00, 0\n Auto-collector (200G) :milestone, 12:00, 0\n Multiple upgrades (500G) :milestone, 18:00, 0\n\n section DP Milestones\n Wave 1 (+11 DP) :milestone, 00:45, 0\n Wave 5 cap (30 DP) :milestone, 04:00, 0\n Wave 10 cap (40 DP) :milestone, 09:00, 0\n Wave 20 cap (60 DP) :milestone, 18:00, 0\n\n section Prestige Path\n First crystal :milestone, 00:03, 0\n Boss kill (100G) :milestone, 08:00, 0\n Prestige unlocked :milestone, 22:00, 0\n Optimal prestige :milestone, 28:00, 0",
"balanceTargets": [
{"time": "0:30", "crystals": "~15", "gold": "~2", "dp": "10/22", "event": "First drill built"},
{"time": "1:00", "crystals": "~25", "gold": "~5", "dp": "10/22", "event": "First turret, first enemy kill"},
{"time": "2:00", "crystals": "~45", "gold": "~12", "dp": "15/24", "event": "Wave 1 complete, three drills"},
{"time": "5:00", "crystals": "~120", "gold": "~50", "dp": "20/26", "event": "Wave 3, first upgrade"},
{"time": "10:00", "crystals": "~300", "gold": "~120", "dp": "30/40", "event": "Wave 6, bats unlocked"},
{"time": "15:00", "crystals": "~500", "gold": "~250", "dp": "40/50", "event": "Mid-game, advanced structures"},
{"time": "20:00", "crystals": "~800", "gold": "~400", "dp": "50/60", "event": "Late game approaching"},
{"time": "25:00", "crystals": "~1200", "gold": "~600", "dp": "60/70", "event": "Near prestige"},
{"time": "30:00", "crystals": "~2000", "gold": "~1000", "dp": "80/80", "event": "Prestige viable (~2 Rep)"}
]
},
"upgradeCostCurves": [
{
"name": "Drill Upgrade",
"diagram": "graph LR\n subgraph \"Drill Upgrade Cost Curve\"\n D1[\"Lvl 1\\nCost: 10 Gold\\nRate: 1/3s\"]\n D3[\"Lvl 3\\nCost: 23 Gold\\nRate: 1/2.4s\"]\n D5[\"Lvl 5\\nCost: 51 Gold\\nRate: 1/2s\"]\n D10[\"Lvl 10\\nCost: 173 Gold\\nRate: 1/1s\"]\n D15[\"Lvl 15\\nCost: 581 Gold\\nRate: 1/1s (cap)\"]\n D1 --> D3 --> D5 --> D10 --> D15\n end",
"formula": "cost = 10 * 1.5^level",
"effect": "Reduces spawn interval by 0.2s, minimum 1s",
"spawnInterval": "max(1, 3 - 0.2 * level)"
},
{
"name": "Turret Upgrade",
"diagram": "graph LR\n subgraph \"Turret Upgrade Cost Curve\"\n T1[\"Lvl 1\\nCost: 15 Gold\\nDmg: 10/sec\"]\n T3[\"Lvl 3\\nCost: 38 Gold\\nDmg: 14/sec\"]\n T5[\"Lvl 5\\nCost: 99 Gold\\nDmg: 21/sec\"]\n T10[\"Lvl 10\\nCost: 398 Gold\\nDmg: 62/sec\"]\n T1 --> T3 --> T5 --> T10\n end",
"formula": "cost = 15 * 1.6^level",
"effect": "+20% damage per level"
},
{
"name": "Barricade Upgrade",
"diagram": "graph LR\n subgraph \"Barricade Upgrade Cost Curve\"\n B1[\"Lvl 1\\nCost: 8 Gold\\nHP: 100\"]\n B3[\"Lvl 3\\nCost: 16 Gold\\nHP: 225\"]\n B5[\"Lvl 5\\nCost: 31 Gold\\nHP: 506\"]\n B10[\"Lvl 10\\nCost: 108 Gold\\nHP: 2892\"]\n B1 --> B3 --> B5 --> B10\n end",
"formula": "cost = 8 * 1.4^level",
"effect": "+50% HP per level"
},
{
"name": "Reputation Multiplier Upgrade",
"diagram": "graph LR\n subgraph \"Rep Multiplier Cost Curve\"\n R1[\"Lvl 1\\nCost: 1 Rep\\nEffect: +5%\\nTotal: 5%\"]\n R2[\"Lvl 2\\nCost: 2 Rep\\nEffect: +5%\\nTotal: 10%\"]\n R3[\"Lvl 3\\nCost: 3 Rep\\nEffect: +5%\\nTotal: 15%\"]\n R5[\"Lvl 5\\nCost: 8 Rep\\nEffect: +5%\\nTotal: 25%\"]\n R10[\"Lvl 10\\nCost: 57 Rep\\nEffect: +5%\\nTotal: 50%\"]\n R1 --> R2 --> R3 --> R5 --> R10\n end",
"formula": "cost = 1 * 1.5^(level-1)",
"effect": "+5% reputation gain per level"
}
],
"exactFormulas": {
"crystal_drop_rates": "Blue: 70%, Red: 25%, Purple: 5%",
"crystal_sprite_lifetime": "5 seconds (despawn with fade animation at 4s)",
"drill_spawn_interval": "spawnInterval = max(1, 3 - 0.2 * drillLevel) seconds",
"gold_drop_amount": "baseDrop * (1 + 0.1 * waveNumber)",
"gold_base_drops": "Basic: 2, Elite: 10, Boss: 100",
"gold_coin_lifetime": "8 seconds (despawn with fade animation at 7s)",
"dp_wave_bonus": "dpEarned = 10 + waveNumber + (noStructuresLost ? 5 : 0)",
"dp_max_cap": "dpMax = waveNumber * 2 + 20",
"drill_upgrade_cost": "cost = 10 * 1.5^level",
"turret_upgrade_cost": "cost = 15 * 1.6^level",
"barricade_upgrade_cost": "cost = 8 * 1.4^level",
"reputation_on_prestige": "reputation = floor((totalCrystalsMined / 1000) * (1 + 0.05 * repMultiplierLevel) * (1 + 0.1 * incomeBonusLevel))",
"rep_multiplier_cost": "cost = 1 * 1.5^(level-1)",
"income_bonus_cost": "cost = 3 * level",
"starting_structure_cost": "cost = 2 per structure",
"structure_crystal_costs": "Drill: 15, Turret: 20, Barricade: 10, Sniper: 50, Scatter: 40",
"structure_dp_costs": "Drill: 2, Turret: 2, Barricade: 1, Sniper: 3, Scatter: 2",
"unlock_costs": "Sniper: 100 Gold, Scatter: 150 Gold, Auto-Collector: 200 Gold",
"sell_refund": "Refund 50% of crystal cost, refund 100% of DP cost"
},
"gameplayCurrencyEvents": [
{
"event": "Crystal Sprite Spawns",
"visual": "Crystal sprite pops from drill with upward animation (10px), then drifts downward slowly",
"uiFeedback": "No text - visual sprite is the feedback",
"collection": "Player clicks within 8px of sprite center. Floating '+1', '+5', or '+20' text appears at click location. Sprite disappears with sparkle particle effect (5 particles)."
},
{
"event": "Gold Coin Drops",
"visual": "When enemy dies, gold coin sprite appears at death location with small bounce animation",
"uiFeedback": "No text on death - coin appearance is the feedback",
"collection": "Player clicks within 8px of coin center. Floating '+2', '+10', or '+100' text appears. Coin disappears with spin effect."
},
{
"event": "Wave Complete",
"visual": "Wave complete banner appears at top of Canvas for 2 seconds",
"uiFeedback": "Floating '+15 DP' (or actual amount) text appears in center of screen with fade out over 1.5s",
"collection": "Automatic - no player action required"
},
{
"event": "Structure Built",
"visual": "Structure appears with construction animation (scale 0 to 1 over 0.3s)",
"uiFeedback": "Floating '-15 Crystals' (or actual amount) text in red appears at build location, fades over 1s",
"collection": "Automatic - triggered by player placement action"
},
{
"event": "Upgrade Purchased",
"visual": "Structure pulses with level-up effect (white flash, scale 1.1 to 1 over 0.2s)",
"uiFeedback": "Floating '-10 Gold' (or actual amount) text in red appears at structure location",
"collection": "Automatic - triggered by player upgrade action"
},
{
"event": "Crystal Despawns",
"visual": "At 4 seconds: crystal sprite begins opacity fade (1 to 0 over 1s)",
"uiFeedback": "None - sprite simply disappears",
"collection": "Lost forever if not clicked in time"
},
{
"event": "Gold Coin Despawns",
"visual": "At 7 seconds: coin sprite begins opacity fade (1 to 0 over 1s)",
"uiFeedback": "None - coin simply disappears",
"collection": "Lost forever if not clicked in time"
}
],
"edgeCases": [
{
"case": "Overflow Protection",
"handling": "Switch to BigInt when Crystal > 1e9 or Gold > 1e12. Display with K/M/B suffixes. JavaScript Number.MAX_SAFE_INTEGER is 9 quadrillion - unlikely to reach in normal play but possible after many prestiges."
},
{
"case": "Negative Balance",
"handling": "All spend functions check canAfford(cost) before purchase. Return false and show 'Insufficient funds' message if currency < cost. Never allow negative balance."
},
{
"case": "Hoarding Prevention - Crystals",
"handling": "Crystal sprite 5-second lifetime forces active collection. Can't hoard on screen. Multiple drills = many sprites = player must choose which to click. Natural attention limit creates soft cap."
},
{
"case": "Hoarding Prevention - Gold",
"handling": "Gold coins despawn after 8 seconds. Forces active collection of enemy drops. Can't passively accumulate from kills. Upgrade costs exponential (1.4-1.6x) outpace gold income scaling."
},
{
"case": "Hoarding Prevention - DP",
"handling": "Hard cap: dpMax = wave * 2 + 20. Cannot build if currentDP + cost > dpMax. Must advance waves to increase capacity. Forces strategic spending decisions."
},
{
"case": "Prestige Timing",
"handling": "Can prestige at wave 30+, but optimal is 40-50. Show 'Recommended: Wave X' hint in UI. Display reputation preview if prestiged now. Warning if prestiging below wave 30: 'Early prestige - suboptimal rewards'."
},
{
"case": "DP Cap Exceeded",
"handling": "Build buttons show disabled state when currentDP + cost > dpMax. Tooltip: 'DP limit reached. Complete waves to increase capacity.'"
},
{
"case": "First Purchase Affordability",
"handling": "Starting Crystals: 10 (drill costs 15, need click 5 blue sprites = ~15 seconds). Starting Gold: 5 (upgrade costs 10, need kill ~5 enemies = ~1 minute). Ensures first purchases within 10-60 seconds - feels rewarding but not instant."
},
{
"case": "Empty Crystal/Gold",
"handling": "If 0 crystals and 0 gold, show 'Collect crystals from your drills! Kill enemies for gold!' hint. Drills continue spawning crystals. Enemies continue spawning. Player can always recover through gameplay."
},
{
"case": "Prestige Zero Reputation",
"handling": "If totalCrystalsMined < 1000, show 'Need 1000+ total crystals mined for reputation. Current: X/1000.' Allow prestige but award 0 reputation with confirmation: 'Prestige with 0 reputation gains? Your progress will be lost.'"
},
{
"case": "All Structures Lost",
"handling": "If all structures destroyed during wave, enemies bypass defenses. Player loses wave progress but keeps crystals/gold. Can rebuild with remaining currency. Emergency mode: next wave spawns after 30-second grace period."
}
],
"inflationControl": [
{
"mechanism": "Exponential Upgrade Costs",
"description": "Drill: 1.5x per level, Turret: 1.6x, Barricade: 1.4x. Costs accelerate faster than income. Player must prioritize which upgrades to purchase."
},
{
"mechanism": "DP Cap Scaling",
"description": "dpMax = wave * 2 + 20. Forces wave progression to increase structure capacity. Can't hoard DP. Must spend to build, must advance to expand."
},
{
"mechanism": "Prestige Reset",
"description": "Resets Crystals, Gold, DP, Structures, Waves. Only Reputation and Tech persist. Resets entire inflation cycle. Each prestige becomes faster due to permanent bonuses."
},
{
"mechanism": "Crystal Sprite Lifetime",
"description": "5-second despawn creates urgency. Player can't wait and collect later. Forces moment-to-moment attention. Multiple active drills create overwhelming sprites - natural income cap."
},
{
"mechanism": "Gold Coin Despawn",
"description": "8-second despawn on gold drops. Forces active collection of enemy kills. Can't passively accumulate. High enemy density in later waves makes collecting all coins impossible - natural gold cap."
},
{
"mechanism": "Reputation Scaling Costs",
"description": "Tech nodes cost 1-5 Rep, multiplier costs scale 1.5x per level. Becomes expensive late-game. Reputation requires 1000 crystals = 20-30 minutes per point. Natural scarcity."
}
],
"earlyGameGenerosity": [
{
"design": "Starting Resources",
"details": "10 Crystals (drill costs 15, need 5 blue sprites), 5 Gold (upgrade costs 10, need 5 basic enemies), 10 DP (can build 3-5 structures). First purchases: 10-60 seconds. Feels achievable."
},
{
"design": "First Crystal Spawn",
"details": "Drills spawn first crystal within 3 seconds of placement. Immediate visual feedback. Player clicks and gets +1 crystal. Satisfying loop."
},
{
"design": "Early Enemy Gold",
"details": "Basic enemies drop 2 Gold. First wave has 5 enemies = 10 Gold. First upgrade (10 Gold) affordable after wave 1. Feels rich."
},
{
"design": "Wave 1 DP Bonus",
"details": "Wave 1 complete: +11 DP (10 base + 1 wave). Total: 21 DP. Can build 10+ structures. Feels generous. Player feels powerful early."
},
{
"design": "Blue Crystal Dominance",
"details": "70% blue crystals (+1). Frequent small rewards. Constant stream of collectibles. Player feels 'rich' in crystals early game."
},
{
"design": "First Upgrade Affordability",
"details": "First drill upgrade: 10 Gold. Achievable in ~60-90 seconds. First turret upgrade: 15 Gold. Achievable in ~2 minutes. Player sees upgrade progress quickly."
}
],
"scarcityDesign": [
{
"currency": "Gold",
"scarcity": "Gold requires killing enemies AND clicking coins within 8 seconds. 8-second despawn. Later waves: high enemy density = can't collect all coins. Upgrade costs exponential. Gold always scarce. Forces upgrade choices."
},
{
"currency": "DP",
"scarcity": "Hard cap per wave. Cannot expand beyond cap. Forces tradeoffs: drill or turret? Chokepoint or distributed? Every DP spent is strategic. DP bottlenecks entire expansion."
},
{
"currency": "Reputation",
"scarcity": "1000 crystals = 1 Rep. Requires 20-30 minutes. Tech nodes cost 1-5 Rep. Takes multiple prestiges for meaningful tech tree. Forces long-term planning."
},
{
"currency": "Crystals (Late Game)",
"scarcity": "5-second despawn + multiple drills = overwhelming sprites. Player can't click all. Must choose: ignore blue, click red/purple? Natural attention limit creates scarcity. Auto-collector (200 Gold) relieves but costs valuable gold."
}
],
"economicWebDescription": "The economy forms an interconnected web:\n\n1. CRYSTALS enable STRUCTURES (drills, turrets, barricades)\n2. STRUCTURES enable GAMEPLAY (mining, defense)\n3. DEFENSE kills ENEMIES which drop GOLD\n4. GOLD enables UPGRADES (better drills, turrets, barricades)\n5. Better DRILLS produce more CRYSTALS\n6. Better TURRETS kill more enemies (more GOLD)\n7. WAVES grant DP which caps STRUCTURE building\n8. PRESTIGE converts accumulated CRYSTALS into REPUTATION\n9. REPUTATION buys PERMANENT BONUSES which make next run faster\n\nKey bottleneck: DP cap. Player can have crystals and gold, but without DP cannot build. Must advance waves (risk!) to increase capacity.\n\nKey tension: Crystal collection requires clicking. Gold collection requires clicking. Player cannot optimize both simultaneously. Must choose: click crystals (building economy) or click gold (upgrading existing structures)?\n\nKey interlock: Drills need turrets for protection. Turrets need drills for crystals (to build more turrets). Space is limited. Every structure placement matters.",
"qualityCheck": {
"economyFlowDiagram": "PASS - Shows all 4 currencies, all gameplay sources (click crystals, click gold, wave complete), all passive sources (drill auto), all sinks (build, upgrade, unlock, prestige), DP cap mechanic",
"gameplayEarnedCurrencies": "PASS - Crystals earned by clicking crystal sprites (70% blue, 25% red, 5% purple), Gold earned by clicking gold coins from killed enemies (basic/elite/boss), DP earned from completing waves",
"visualCanvasActions": "PASS - Crystal sprites pop from drills and drift (5s lifetime), gold coins drop at enemy death (8s lifetime), both require clicking. Floating +text on collection. Clear visual feedback.",
"exactFormulas": "PASS - All costs specified: drill 10*1.5^level, turret 15*1.6^level, barricade 8*1.4^level. DP cap: wave*2+20. Crystal spawn: max(1, 3-0.2*level). Gold drop: 2*(1+0.1*wave). Reputation: floor(crystals/1000 * mults).",
"conversionDecisions": "PASS - Only conversion is prestige (1000 crystals -> 1 rep, resets all progress). Meaningful decision: when to prestige? Early (faster but less rep) vs late (slower but more rep).",
"pacingTimeline": "PASS - First drill at 5s, first upgrade at 90s, first unlock at 6min, prestige at 22-30min. Targets 15-30 minute session. First 30 seconds feel generous (10 starting crystals, first spawn at 3s).",
"scarceCurrency": "PASS - Gold scarce (requires kills + clicks + 8s timer), DP capped (hard limit), Reputation expensive (1000 crystals = 1 Rep), Crystals time-limited (5s despawn). Multiple scarcity layers.",
"earlyGenerosity": "PASS - Start with 10 crystals (first drill needs 5 more), 5 gold (first upgrade needs 5 more), 10 DP (can build 3-5 structures). Wave 1 gives +11 DP (very generous). First crystal at 3 seconds. Immediate rewards.",
"noIrrelevantCurrency": "PASS - Crystals (build structures) always needed, Gold (upgrades) always needed, DP (capacity) always limits building, Reputation (prestige) always needed for progression. All currencies relevant entire game.",
"consistentNaming": "PASS - crystals, gold, defensePoints/DP, reputation. Clear variable names. Consistent throughout.",
"economyWeb": "PASS - Crystals->Structures->Gold->Upgrades->More Crystals. DP caps structures. Waves grant DP. Prestige converts crystals to reputation. Interconnected web, not linear chain.",
"implementable": "PASS - All numbers specified, all formulas exact, all behaviors defined. Developer can implement: spawnInterval = max(1, 3 - 0.2*level), cost = 10 * Math.pow(1.5, level), etc."
}
}
Prestige
{
"prestigeSystem": {
"overview": "Crystal Cavern Defense's prestige system transforms the 'loss' of your cavern into excitement. When you prestige, you abandon your current cavern to start a new mining operation deeper in the mountain. Your reputation as a mining captain grows based on total crystals extracted — the more you mined, the higher your reputation. New runs start with permanent bonuses and visually deeper, more dangerous caverns. The key emotion is 'triumphant sacrifice' — you're leaving behind a masterpiece of engineering to conquer even greater depths.",
"prestigeCurrency": {
"name": "Reputation",
"icon": "⭐",
"earnedBy": "Prestiging based on total crystals mined across the run",
"spentOn": "Permanent upgrades, tech nodes, starting bonuses",
"persists": "Yes — accumulates across all runs"
},
"prestigeCycleDiagram": "stateDiagram-v2\n [*] --> Run1: Game Start\n\n state \"Run 1 (Surface Cavern)\" as Run1 {\n [*] --> EarlyGame1: 0-5 min\n EarlyGame1: Place first drill, collect crystals\n MidGame1: 5-15 min\n MidGame1: Multiple drills, turrets, first boss\n LateGame1: 15-30 min\n LateGame1: Cavern filling up, waves intensifying\n PrestigeReady1: Wave 30+ complete\n PrestigeReady1: Can prestige (suboptimal)\n }\n\n state \"Prestige Decision\" as Decision {\n [*] --> Preview\n Preview: Show reputation preview\\nReputation = floor(crystals / 1000)\\nVisual preview of new cavern tier\n Preview --> Confirm: Player clicks \"Abandon Cavern\"\n Preview --> Wait: Player keeps mining\n Wait --> Preview: checks again later\n }\n\n state \"Run 2+ (Deeper Cavern + Bonuses)\" as Run2 {\n [*] --> EarlyGame2: 0-3 min (3x faster!)\n note right of EarlyGame2: New enemy color palette\\nDarker cavern background\\nPre-built structures active\n EarlyGame2 --> MidGame2: reputation multipliers active\n MidGame2 --> LateGame2: new enemy types unlocked\n LateGame2 --> PrestigeReady2: Higher threshold possible\n }\n\n Run1 --> Decision: wave 30+ reached\n Decision --> Run2: prestige confirmed\n Run2 --> Decision: new prestige threshold met",
"resetSpecificationDiagram": "graph TD\n subgraph \"🔴 RESETS (back to zero)\"\n R1[\"Crystals → 0\"]\n R2[\"Gold → 0\"]\n R3[\"Defense Points → 10 (base)\"]\n R4[\"All structures → Removed from Canvas\"]\n R5[\"Structure upgrades → Reset\"]\n R6[\"Unlocked tech → Relocked (permanent nodes persist)\"]\n R7[\"Wave counter → Wave 1\"]\n R8[\"All enemies despawned\"]\n R9[\"Crystal deposits → Regenerated fresh\"]\n end\n\n subgraph \"🟢 PERSISTS (kept forever)\"\n P1[\"Reputation (prestige currency)\"]\n P2[\"Purchased tech nodes\"]\n P3[\"Permanent upgrades from Reputation\"]\n P4[\"Lifetime statistics\"]\n P5[\"Achievement badges\"]\n end\n\n subgraph \"🟡 CHANGES (visual transformation)\"\n V1[\"Cavern background becomes darker/deeper\"]\n V2[\"Enemy sprites get new color palette via ProceduralSprite.generateColorVariant\"]\n V3[\"Crystal deposits change color\"]\n V4[\"New enemy types may appear\"]\n end",
"prestigeUpgradeTreeDiagram": "graph TD\n subgraph \"Tier 1 (1-3 Reputation each)\"\n PU1[\"💎 Headstart\\nCost: 1 Rep\\nStart with 100 Crystals\"]\n PU2[\"💎 Battle Hardened\\nCost: 2 Rep\\n+50% structure damage\"]\n PU3[\"💎 Quick Deploy\\nCost: 2 Rep\\nStart with first drill unlocked\"]\n end\n\n subgraph \"Tier 2 (3-5 Reputation each)\"\n PU4[\"💎 Veteran Crew\\nCost: 3 Rep\\n-20% all upgrade costs\"]\n PU5[\"💎 Rare Crystal Hunt\\nCost: 4 Rep\\n+100% red/purple crystal drop rate\"]\n PU6[\"💎 NEW: Auto-Collector Drone\\nCost: 5 Rep\\nUnlock auto-collect radius around drill\"]\n end\n\n subgraph \"Tier 3 (5-10 Reputation each)\"\n PU7[\"💎 Mining Mastery\\nCost: 7 Rep\\n+25% Reputation from prestige\"]\n PU8[\"💎 NEW: Crystal Forge\\nCost: 8 Rep\\nUnlock new turret type (laser turret)\"]\n PU9[\"💎 Deep Delver\\nCost: 10 Rep\\nUnlock third cavern tier (abyss)\"]\n end\n\n PU1 --> PU4\n PU2 --> PU4\n PU2 --> PU5\n PU3 --> PU6\n PU4 --> PU7\n PU5 --> PU8\n PU6 --> PU8\n PU7 --> PU9\n PU8 --> PU9",
"runComparisonDiagram": "sequenceDiagram\n participant R1 as Run 1 (no bonuses)\n participant R2 as Run 2 (5 Rep spent)\n participant R3 as Run 3 (15 Rep total)\n\n Note over R1: 0:00 - Start with 10 Crystals, base cavern\n Note over R2: 0:00 - Start with 100 Crystals + 50% damage, darker cavern\n Note over R3: 0:00 - Start with 100 Crystals + auto-collector, laser turret\n\n Note over R1: 0:30 - First upgrade purchased\n Note over R2: 0:05 - Multiple upgrades immediately\n Note over R3: 0:02 - Advanced build from start\n\n Note over R1: 5:00 - First boss defeated\n Note over R2: 1:30 - First boss (3.3x faster)\n Note over R3: 0:45 - First boss (6.7x faster)\n\n Note over R1: 25:00 - Prestige ready\n Note over R2: 10:00 - Prestige ready (2.5x faster)\n Note over R3: 5:00 - Prestige ready (5x faster)",
"visualTransformationDiagram": "graph TD\n subgraph \"Prestige Tier 0 (Surface - first run)\"\n T0_bg[\"Canvas background: #3d2817 (light brown soil)\"]\n T0_enemies[\"Enemies: Default Slime/Ghost palettes (green/purple)\"]\n T0_effects[\"Effects: Basic spark particles\"]\n end\n\n subgraph \"Prestige Tier 1 (Deep Cavern - prestiges 1-2)\"\n T1_bg[\"Canvas background: #2a1a0f (darker brown), visible rock layers\"]\n T1_enemies[\"Enemies: Red-shifted palette variant\\nProceduralSprite.generateColorVariant(redTint)\"]\n T1_effects[\"Effects: Glow effects on elite enemies, particle trails\"]\n end\n\n subgraph \"Prestige Tier 2 (Abyss - prestiges 3-5)\"\n T2_bg[\"Canvas background: #1a0f08 (near-black), bioluminescent fungi\"]\n T2_enemies[\"Enemies: Purple/cyan palette + new geometric enemies\\nProceduralSprite.generateSimpleSprite\"][\"Effects: Enhanced death animations, crystal shard explosions\"]\n end",
"prestigeUIFlowDiagram": "sequenceDiagram\n actor Player\n participant Canvas as Game Canvas\n participant UI as Game UI\n\n Note over Player,UI: Wave 30+ Complete\n\n UI->>Player: Prestige button appears with glow\n UI->>Player: \"5 Reputation available\" preview\n\n Player->>UI: clicks Prestige button\n UI->>Player: Confirmation panel slides in\n Note over UI: Panel shows:\\n- Reputation earned\\n- What resets / what persists\\n- Visual preview: \"New cavern will be darker and more dangerous\"\n\n alt Player confirms\n Player->>UI: clicks \"Abandon Cavern!\"\n Canvas->>Canvas: fade to black transition (1s)\n Canvas->>Canvas: elevator descent animation\n Canvas->>Canvas: new cavern fades in with different colors\n UI->>Player: show Reputation Shop\n Player->>UI: buy upgrades\n Canvas->>Player: fresh game with new visuals + bonuses active\n else Player cancels\n Player->>UI: clicks \"Keep Mining\"\n UI->>Player: panel closes, continue current run\n end",
"prestigeFormula": {
"baseFormula": "reputation = floor(lifetime_crystals / 1000)",
"examples": [
{
"totalCrystals": 1000,
"reputation": 1,
"note": "Minimum viable prestige"
},
{
"totalCrystals": 4000,
"reputation": 4,
"note": "4x crystals = 4x reputation (linear scaling)"
},
{
"totalCrystals": 25000,
"reputation": 25,
"note": "Recommended first prestige - solid upgrade foundation"
},
{
"totalCrystals": 100000,
"reputation": 100,
"note": "Strong first prestige, can buy Tier 3 upgrades"
}
],
"multipliers": "Reputation can be increased by purchasing 'Mining Mastery' upgrade (+25% per level)",
"diminishingReturns": "No soft cap — more crystals always give more reputation. However, each additional 1000 crystals takes longer to mine as cavern fills up, creating natural diminishing returns on time invested."
},
"visualTransformationDetails": {
"tier0": {
"name": "Surface Cavern",
"prestigeCount": 0,
"canvasBackground": "#3d2817 (light brown soil)",
"crystalPalette": [
"Blue (#4488ff)",
"Red (#ff4444)",
"Purple (#aa44ff)"
],
"enemyPalette": [
"Green slime (#44ff44)",
"Purple ghost (#aa44ff)"
],
"effects": "Basic spark particles, simple explosions"
},
"tier1": {
"name": "Deep Cavern",
"prestigeCount": "1-2",
"canvasBackground": "#2a1a0f (darker brown) + visible stratified rock layers",
"crystalPalette": "Same colors but with glow effect (#4488ff glow)",
"enemyPalette": "Red-shifted via ProceduralSprite.generateColorVariant({hueShift: 30, saturation: 1.2})",
"effects": "Elite enemies have glow aura, death animations spawn crystal shards"
},
"tier2": {
"name": "Abyss",
"prestigeCount": "3-5",
"canvasBackground": "#1a0f08 (near-black) + bioluminescent fungi decorations",
"crystalPalette": "Cyan (#44ffff) and Gold (#ffcc00) variants added, rare drops",
"enemyPalette": "Purple/cyan palette + new ProceduralSprite.generateSimpleShape enemies (triangular/crystalline)",
"effects": "Enhanced particle systems, screen shake on boss death, crystal shard explosions"
},
"tier3": {
"name": "Molten Core",
"prestigeCount": "6+",
"canvasBackground": "#0f0804 (black-red) + flowing magma decorations",
"crystalPalette": "Infernal crystals (orange/red) with intense glow",
"enemyPalette": "Fire/black palette, burning enemies leave trail particles",
"effects": "All enemies have glow, massive particle explosions, dynamic lighting effects"
}
},
"prestigeUpgrades": [
{
"name": "Headstart",
"cost": 1,
"effect": "Start each run with 100 Crystals",
"maxLevel": 5,
"stacking": "Each level adds +100 starting crystals (Level 5 = 500 Crystals)",
"tier": 1
},
{
"name": "Battle Hardened",
"cost": 2,
"effect": "+50% structure damage (turrets, barricades)",
"maxLevel": 5,
"stacking": "Each level adds +50% damage (Level 5 = +250% damage)",
"tier": 1
},
{
"name": "Quick Deploy",
"cost": 2,
"effect": "Start with first Mining Drill already placed (costs 0 DP)",
"maxLevel": 3,
"stacking": "Each level adds +1 pre-built structure (Level 3 = 3 pre-built structures)",
"tier": 1,
"note": "Player chooses which structures when prestiging"
},
{
"name": "Veteran Crew",
"cost": 3,
"effect": "-20% cost of all structure upgrades",
"maxLevel": 5,
"stacking": "Each level reduces cost by 20% (Level 5 = -100% = free upgrades)",
"tier": 2
},
{
"name": "Rare Crystal Hunt",
"cost": 4,
"effect": "+100% red and purple crystal drop rate",
"maxLevel": 3,
"stacking": "Each level adds +100% (Level 3 = +300% = 4x rare crystals)",
"tier": 2
},
{
"name": "Auto-Collector Drone",
"cost": 5,
"effect": "NEW MECHANIC: Mining drills auto-collect crystals within 50px radius",
"maxLevel": 1,
"stacking": "Does not stack — one-time unlock",
"tier": 2,
"visual": "Drills show small drone sprite orbiting them"
},
{
"name": "Mining Mastery",
"cost": 7,
"effect": "+25% Reputation earned from prestiging",
"maxLevel": 5,
"stacking": "Each level adds +25% (Level 5 = +125% = 2.25x Reputation)",
"tier": 3
},
{
"name": "Crystal Forge",
"cost": 8,
"effect": "NEW STRUCTURE: Unlock Laser Turret (high damage, slow fire, pierces enemies)",
"maxLevel": 1,
"stacking": "Does not stack — one-time unlock",
"tier": 3,
"visual": "New turret type with cyan beam projectile"
},
{
"name": "Deep Delver",
"cost": 10,
"effect": "Unlock third cavern tier (Abyss) with enhanced visuals and new enemies",
"maxLevel": 1,
"stacking": "Does not stack — one-time unlock",
"tier": 3,
"visual": "Background changes to near-black with bioluminescence"
}
],
"timingAndPacing": {
"firstRunTarget": "25-30 minutes to reach 25,000 crystals for solid first prestige (25 Reputation)",
"run2Target": "10-12 minutes with 5 Reputation spent (3x faster)",
"run3Target": "5-8 minutes with 15 Reputation total (5x faster)",
"optimalPrestigeWave": "Wave 40-50 (when space constraints start reducing crystal/minute)",
"minimumPrestigeWave": "Wave 30 (earliest possible, but suboptimal)",
"prestigeVelocity": "Each Reputation spent reduces next run time by ~8-12% until diminishing returns around 50-60 Reputation"
},
"edgeCases": [
{
"case": "Minimum Prestige",
"handling": "Can prestige at Wave 30 with ~5,000 crystals = 5 Reputation. Early but viable for learning. Shows 'Early prestige - suboptimal rewards' tooltip."
},
{
"case": "No-Spend Prestige",
"handling": "If player prestiges but spends 0 Reputation, Run 2 is identical to Run 1. Game shows 'You have unspent Reputation! Visit the shop' reminder."
},
{
"case": "Visual Tier Cap",
"handling": "Visual tiers cap at Tier 3 (Molten Core). Prestiges 6+ stay in Tier 3 but can still earn more upgrades. Visuals don't need infinite variants."
},
{
"case": "Prestige During Wave",
"handling": "Can only prestige between waves. Prestige button disabled during active waves with tooltip 'Complete the current wave first.'"
},
{
"case": "Zero Crystals Mined",
"handling": "If total crystals < 1000, show 'Need at least 1,000 total crystals mined for Reputation. Current: X/1000.' Allow prestige but award 0 Reputation with confirmation."
},
{
"case": "All Structures Lost",
"handling": "If all structures destroyed, can still prestige. No special handling needed — prestige is always available at Wave 30+."
}
],
"developerImplementationNotes": {
"prestigeStateReset": "On prestige: Set crystals = 10 (base start), gold = 5, DP = 10, wave = 1. Clear all structure arrays. Reset upgrade levels. Keep reputation (add new to existing). Keep purchasedUpgrades array (permanent).",
"visualTierCalculation": "prestigeCount = total number of times player has prestiged. visualTier = floor(prestigeCount / 2). Tier 0: 0, Tier 1: 1-2, Tier 2: 3-5, Tier 3: 6+.",
"enemyPaletteGeneration": "Use ProceduralSprite.generateColorVariant({hueShift: tier * 30, saturation: 1.0 + tier * 0.1, brightness: 1.0}) to shift enemy colors based on visual tier.",
"canvasBackgroundTransition": "When prestiging: ctx.fillStyle = 'black'; ctx.fillRect(0,0,width,height); wait 500ms; load new background color; fade in over 1s.",
"reputationShopDisplay": "Show prestige upgrades in a modal panel. Affordable upgrades glow green. Purchased upgrades show 'MAXED' badge. New content unlocks (like Laser Turret) show 'NEW!' badge."
},
"qualityCheck": {
"prestigeCycleDiagram": "PASS - Shows complete loop from Run 1 → Decision → Run 2 → Repeat",
"resetSpecUnambiguous": "PASS - Clear resets (Crystals, Gold, DP, structures) and persists (Reputation, tech, upgrades)",
"visualTransformation": "PASS - At least 2 tiers specified with ProceduralSprite color variants and background changes",
"proceduralSpriteUsage": "PASS - generateColorVariant and generateSimpleSprite specified for enemy palette changes",
"prestigeFormulaExact": "PASS - floor(crystals / 1000) with example values (1000→1, 25000→25, 100000→100)",
"run2Acceleration": "PASS - Run 2 reaches Run 1's prestige point in 1/3 the time (10 min vs 30 min)",
"upgradeVariety": "PASS - 9 upgrades with distinct effects (starting resources, damage, costs, mechanics, unlocks)",
"newMechanicsUnlocked": "PASS - Auto-Collector Drone (new mechanic), Crystal Forge (new structure), Deep Delver (new visual tier)",
"uiFlowSpecified": "PASS - Complete UI flow from prestige button → confirmation → transition → shop → new run",
"canvasTransition": "PASS - Fade to black → elevator animation → new cavern fades in with different colors",
"implementableFromDiagrams": "PASS - Developer can implement entire system from Mermaid diagrams + brief notes"
}
}
}
Prestige
# Prestige System
## Overview
In the Abyssal Brewery, prestige is the "Ancient One's Grand Service" - a climactic moment where you serve the slumbering cosmic horror beneath the Mariana Trench. Thematically, you're sacrificing your current brewery's entire output (all pressure, essence, void tears, and reputation) to create the perfect offering for this eldritch being. In return, the Ancient One grants you Echoes - fragments of cosmic wisdom that persist across runs and make your next brewery fundamentally more powerful.
Resetting makes narrative sense as "closing shop and opening a new brewery" in a different trench location, armed with the Ancient One's blessing (Echoes). Players WANT to prestige because: (1) Run 1 feels slow and constrained by the end, (2) The Echo calculator shows exactly what they'll earn, (3) Echo upgrades promise dramatically faster progression, (4) Each prestige unlocks new "Ancient One request variations" - different brewing challenges with unique rewards. The prestige moment is designed to feel triumphant, not like starting over - you've mastered the first run and earned permanent power.
## Prestige Currency
### Echoes
- **Earned by**: Prestiging (serving the Ancient One)
- **Formula**: `echoes = floor((voidTears / 10) + (reputation / 5) + (successfulBrews / 20) + (patronsServed * 2) + floor(reputation * 0.1 * serviceQualityMultiplier))`
- **Example values**:
| Game State at Prestige | Void Tears | Reputation | Brews | Patrons | Echoes Earned |
|------------------------|------------|------------|-------|---------|---------------|
| Minimum viable (50 VT + 100 REP) | 50 | 100 | 5 | 3 | ~25 |
| Recommended first prestige | 60 | 300 | 15 | 8 | ~85 |
| Pushed further | 75 | 450 | 25 | 12 | ~135 |
| Much further (diminishing returns) | 100 | 700 | 40 | 18 | ~195 |
- **Diminishing returns**: The formula has linear components, but the inputs are logarithmically scaled by gameplay time. Void Tears take ~30 seconds each early, ~5 minutes each late. Reputation gains slow after tier 2 patrons (12:00). Pushing from 60 to 100 VT takes 3x longer but only yields +15 echoes (+40% vs +300% time investment). Reputation above 500 requires risky forbidden brews for diminishing gains. This creates a natural soft cap where optimal prestige is 60-80 VT + 300-500 REP at ~30 minutes.
- **Spent on**: Permanent multipliers (pressure generation, essence extraction, void distillation efficiency), starting bonuses (quick start pressure, equipment durability), and Echo Memories (start with recipes already mastered).
## Prestige Trigger
### Requirements
- **Minimum requirement**: 50 Void Tears + 100 Reputation
- **Recommended first prestige**: 60 Void Tears + 300 Reputation (reached at ~27:00 in progression.md)
- **UI indicator**:
- **Before unlock (20:00-25:00)**: Dimmed Ancient One icon (🜲) in top-right corner with tooltip "The Ancient One stirs... Requirements: 50 Void Tears, 100 Reputation". Two progress bars below show "VT: X/50" and "REP: Y/100".
- **When requirements met (25:00+)**: Icon brightens and pulses with golden aura. Tooltip changes to "The Ancient One is ready! Click to serve and earn Echoes." Progress bars turn from gray to glowing cyan.
- **Hover preview**: Panel shows current echo estimate: "You will earn approximately X Echoes. Current total: Y. New total: Z." Top 3 affordable Echo upgrades listed with costs.
### The Prestige Action
1. Player clicks "Serve the Ancient One" button (pulsing Ancient One icon in top-right)
2. Confirmation dialog shows:
```
⚠️ ANCIENT ONE'S GRAND SERVICE ⚠️
You are about to offer everything to the Ancient One.
YOU WILL EARN: ~85 Echoes (current: 0, new total: 85)
YOU WILL LOSE:
• All Pressure, Essence (all 6 types), and Void Tears
• All equipment upgrades and zone access
• All recipe knowledge and patron relationships
• Your current reputation score
YOU WILL KEEP:
• All Echoes (permanent currency)
• Echo upgrades purchased previously
• Achievement badges and their permanent bonuses
Estimated Run 2 time: 12-15 minutes (vs 30 minutes for Run 1)
[CANCEL] [SERVE THE ANCIENT ONE]
```
3. On confirm:
- Echoes calculated using formula above and awarded immediately
- Screen fades to black, Ancient One rises animation plays (2 seconds)
- Floating text: "THE ANCIENT ONE DRINKS DEEP... YOU HAVE EARNED [X] ECHOES"
- All resetting currencies set to starting values (see Reset Specification)
- All persistent elements preserved (Echoes, Echo upgrades, achievements)
- Brief "opening new brewery" transition animation (3 seconds)
4. Player returns to initial game state (100 Pressure, 0 Essence/VT/REP) with all Echo bonuses active
## Reset Specification
### What Resets (back to initial values)
| Element | Resets To | Notes |
|---------|-----------|-------|
| Pressure | 100 PSI | Starting pressure before any upgrades |
| Bioluminescent Essence | 0 | All 6 essence types reset |
| Crystalline Essence | 0 | |
| Thermal Essence | 0 | |
| Eldritch Essence | 0 | |
| Corrupted Essence | 0 | |
| Ancient Essence | 0 | |
| Void Tears | 0 | All void tears consumed in prestige ritual |
| Reputation | 0 | Reset to zero, must rebuild |
| Auto-Collector Levels | 0 (all zones) | All pressure collector upgrades lost |
| Essence Extractor Levels | 0 (all 6 types) | All extractor upgrades lost |
| Zone Access | Zone 1 only | Zone 2 and 3 locked, must unlock again |
| Recipe Knowledge | Only Mildly Radioactive Ale | All other recipes locked |
| Recipe Mastery | 0 | All mastery levels reset (but see What Persists) |
| Equipment Specialization | None | Can choose different path this run |
| Patron Relationship | Tier 0 | All patron tiers locked |
| Void Distillation Efficiency | 0 | Must re-upgrade distillation |
| Equipment Durability | 100/100 | Reset to full, all durability upgrades lost |
### What Persists (kept forever)
| Element | Notes |
|---------|-------|
| Echoes | Accumulates across all runs, never spent unless player chooses |
| Echo Upgrades | All purchased Echo upgrades remain active (pressure multipliers, extraction bonuses, etc.) |
| Echo Memories | Any "starting recipe" purchases carry over - begin next run with chosen recipe pre-mastered |
| Achievement Badges | All 15 achievements persist, their permanent bonuses (+5% repair speed, +10% recipe quality, etc.) remain active |
| Equipment Schematics | Knowledge of specializations persists - can choose different path or repeat same choice |
| Total Lifetime Stats | Total prestiges, total echoes earned, fastest run time (display purposes only) |
### What Partially Resets
| Element | Behavior | Formula |
|---------|----------|---------|
| Recipe Mastery | Converted to permanent small bonuses, not full mastery levels | Each mastered recipe grants +2% brewing quality for that recipe permanently (not +10-20% like full mastery) |
| Achievement Bonuses | Persist but don't stack | If "First Service" grants +10% echo gains, this bonus persists across all future runs (no need to re-earn) |
## Prestige Upgrades
### Upgrade Tree / List
| # | Upgrade Name | Cost | Effect | Formula | Max Level | Prerequisite |
|---|-------------|------|--------|---------|-----------|--------------|
| 1 | Quick Start Pressure | 5 Echoes | Start each run with +100 pressure | `startingPressure += 100` | 20 | None |
| 2 | Pressure Multiplier | 10 Echoes | +20% pressure generation from all sources | `pressureRate *= 1.2` | 10 | None |
| 3 | Starting Durability | 8 Echoes | +10 max equipment durability | `maxDurability += 10` | 15 | None |
| 4 | Essence Extraction Bonus | 15 Echoes | +15% essence extraction rate | `extractionRate *= 1.15` | 8 | None |
| 5 | Void Distillation Efficiency | 20 Echoes | -5% pressure cost for void tears | `voidDistillationPressureCost *= 0.95` | 5 | None |
| 6 | Echo Memory: Basic Recipe | 50 Echoes | Start with Mildly Radioactive Ale mastered | `startingRecipe = "mildlyRadioactiveAle"` | Unlimited | None |
| 7 | Brewing Speed Bonus | 25 Echoes | -10% brewing time | `brewingTime *= 0.9` | 5 | Pressure Multiplier Level 3 |
| 8 | Equipment Resilience | 12 Echoes | -10% equipment damage in deep zones | `equipmentDamageRate *= 0.9` | 5 | Starting Durability Level 5 |
| 9 | Patron Generosity | 30 Echoes | +15% reputation from serving patrons | `reputationGain *= 1.15` | 5 | Essence Extraction Level 3 |
| 10 | Echo Memory: Tier 2 Recipe | 100 Echoes | Start with Crystalline Cider mastered | `startingRecipe = "crystallineCider"` | Unlimited | Echo Memory: Basic Recipe |
| 11 | Tidal Surge Power | 40 Echoes | +25% pressure from tidal events | `tidalSurgeBonus *= 1.25` | 5 | Brewing Speed Level 3 |
| 12 | Void Tear Yield | 50 Echoes | +10% chance for bonus void tear from distillation | `voidTearOutput *= 1.1` (10% chance of +1 VT) | 3 | Void Distillation Efficiency Level 3 |
| 13 | Echo Memory: Forbidden Recipe | 200 Echoes | Start with Brew of the Deep recipe unlocked | `startingRecipe = "brewOfTheDeep"` | Unlimited | Echo Memory: Tier 2 Recipe |
| 14 | Ancient One's Blessing | 150 Echoes | +5% all echo gains (multiplicative) | `echoGain *= 1.05` | 10 | Patron Generosity Level 5 |
| 15 | Quick Starter Pack | 500 Echoes | Start with Zone 2 already unlocked | `startingZones = ["Zone1", "Zone2"]` | 1 | All upgrades at Level 5+ |
### Upgrade Categories
#### Category 1: Early Game Accelerators
- **Upgrades**: Quick Start Pressure, Pressure Multiplier, Starting Durability
- **Why prioritize**: These upgrades make the first 5 minutes dramatically faster. Starting with 300+ pressure (Quick Start Level 5) means immediate extractor purchase. +20% pressure generation (stacking to 6x at max level) reduces clicking dependence. Extra durability lets you stay in Zone 2 longer without repairs.
- **Strategic value**: Reduces Run 2 time to ~15 minutes. Essential first-prestige purchases.
#### Category 2: Production Multipliers
- **Upgrades**: Essence Extraction Bonus, Brewing Speed Bonus, Void Distillation Efficiency, Tidal Surge Power
- **Why prioritize**: These scale your entire economy. +15% essence extraction (stacking to 3x at max) means faster recipe brewing. -25% distillation cost (max level) makes void tears cheaper. +125% tidal surge pressure (max level) creates massive injection events.
- **Strategic value**: Best for players who want to optimize mid-game (5-15 minutes). Second-tier priority.
#### Category 3: Quality of Life
- **Upgrades**: Equipment Resilience, Patron Generosity, Void Tear Yield
- **Why prioritize**: These reduce friction. -50% equipment damage means fewer repairs and safer deep-zone diving. +75% reputation gains means faster tier unlocks and more recipe mastery. +30% void tear output (max level) accelerates prestige.
- **Strategic value**: Great for third+ prestiges when early game is already fast. Makes late-game smoother.
#### Category 4: Meta Progression (Echo Memories)
- **Upgrades**: Echo Memory: Basic/Tier 2/Forbidden Recipe, Quick Starter Pack, Ancient One's Blessing
- **Why prioritize**: These unlock NEW mechanics or skip entire progression phases. Starting with a recipe mastered means immediate access to its bonuses. Starting with Zone 2 unlocked skips 7 minutes of gameplay. +50% echo gains (Ancient One's Blessing max) compounds every prestige.
- **Strategic value**: Endgame goals for prestige 5+. These make runs fundamentally different, not just faster.
### Recommended First-Prestige Purchases (with ~85 Echoes)
1. **Quick Start Pressure Level 3** (15 Echoes) -- Start with +400 pressure instead of 100. Immediate extractor purchase, skip first 2 minutes of clicking.
2. **Pressure Multiplier Level 2** (20 Echoes) -- +44% pressure generation (1.2 × 1.2). Reduces clicking by half throughout the run.
3. **Essence Extraction Bonus Level 1** (15 Echoes) -- +15% essence extraction. First upgrade pays for itself in saved time.
4. **Starting Durability Level 3** (24 Echoes) -- +30 max durability (130 total). Can stay in Zone 2 for 5+ minutes without repairs.
**Total spent**: 74 Echoes (11 remaining for saving)
**Why this order**: Early game speed is the bottleneck on Run 2. These upgrades reduce the first 10 minutes from 10 minutes to ~4 minutes. Essence extraction bonus accelerates mid-game. Extra durability reduces repair micro-management. This build targets reaching prestige in ~15 minutes.
**Alternative first-prestige build** (for risk-tolerant players):
1. Pressure Multiplier Level 3 (30 Echoes) - Max early game pressure generation
2. Essence Extraction Bonus Level 2 (35 Echoes) - +32% extraction
3. Echo Memory: Basic Recipe (50 Echoes) - Start with Mildly Radioactive Ale mastered
**Total spent**: 115 Echoes (requires pushing first run to ~100 echoes for affordability)
**Why this alternative**: Skipping the recipe grind (Echo Memory) is powerful but expensive. Higher pressure/extraction multipliers compound more over long runs. This is better for players aiming for prestige 3+ optimization.
## Run Pacing Comparison
### Run 1 (No Prestige Bonuses)
| Milestone | Time to Reach |
|-----------|---------------|
| First Auto-Collector | 0:45 |
| First Essence Extraction | 2:00 |
| Zone 2 Unlock | 7:00 |
| Void Distiller Online | 10:00 |
| Patron System | 12:00 |
| Zone 3 Unlock | 15:00 |
| Prestige Requirements Met (60 VT, 300 REP) | 27:00 |
| Optimal Prestige (Ready to serve) | 30:00 |
### Run 2 (After First Prestige, Recommended Purchases: Quick Start L3, Pressure Multi L2, Extraction Bonus L1, Durability L3)
| Milestone | Time to Reach | Speedup vs Run 1 |
|-----------|---------------|-------------------|
| First Auto-Collector | 0:00 (already have starting pressure) | Instant (0:45 saved) |
| First Essence Extraction | 0:30 (started with 400 pressure, buy extractor immediately) | 4x faster (1:30 saved) |
| Zone 2 Unlock | 3:00 (pressure generation +44% faster) | 2.3x faster (4:00 saved) |
| Void Distiller Online | 5:00 (essence extraction +15% faster) | 2x faster (5:00 saved) |
| Patron System | 6:00 | 2x faster (6:00 saved) |
| Zone 3 Unlock | 8:00 | 1.9x faster (7:00 saved) |
| Prestige Requirements Met (60 VT, 300 REP) | 14:00 | 1.9x faster (13:00 saved) |
| Optimal Prestige (Ready to serve) | 15:00 | 2x faster (15:00 saved) |
**Total speedup**: Run 2 reaches prestige in 15 minutes vs 30 minutes (2x acceleration). The second half of Run 2 (15-30 minutes in Run 1) is compressed into 8-15 minutes because Echo upgrades compound.
### Run 3+ (Accumulated Prestige)
**After 2-3 prestiges** (echoes: ~250-400, upgrades: Pressure Multi L5+, Extraction L3+, Quick Start L5+, several Echo Memories):
- **Prestige time**: 6-8 minutes
- **Acceleration**: 4-5x faster than Run 1
- **New content**: Can afford Echo Memories for forbidden recipes, Quick Starter Pack (start with Zone 2), Ancient One's Blessing (echo multiplier). Each run unlocks new "Ancient One request variations" - different prestige paths:
- Path A: Speed prestige (serve Ancient One as fast as possible for efficiency bonus)
- Path B: Hoarding prestige (max void tears and reputation for maximum echoes, takes longer but rewards more)
- Path C: Completionist prestige (unlock all recipes, master all brews, serve all patron tiers before prestiging)
**After 5+ prestiges** (echoes: ~1000+, all major upgrades maxed):
- **Prestige time**: 3-5 minutes
- **Acceleration**: 6-10x faster than Run 1
- **Diminishing returns**: Most upgrades capped (Pressure Multi L10, Extraction L8, etc.). Echo gains now fund Echo Memories (starting recipes) and Ancient One's Blessing (echo multiplier for compounding). Gameplay shifts to experimentation with different equipment specializations and forbidden brew strategies.
**After 10+ prestiges** (echoes: ~3000+, all upgrades maxed, multiple Echo Memories):
- **Prestige time**: 2-3 minutes
- **Acceleration**: ~10-15x faster than Run 1
- **Marginal returns**: Each additional prestige yields minimal time savings (30 seconds or less). Players now prestige for achievement hunting (fastest time challenges), leaderboard competition, or unlocking cosmetic "Ancient One favor" variants (different Ancient One dialogue, brewery themes).
**Note on prestige ceiling**: The game is balanced around 3-5 meaningful prestiges for full content exposure. Beyond prestige 5, progression shifts from "unlock new mechanics" to "optimize existing systems." Hardcore players can continue to prestige 20+ for leaderboard scores, but casual players see everything by prestige 3.
## Prestige Preview UI
### Before Prestige is Available (0:00 - 25:00)
**Locked icon display**: Top-right corner shows dimmed Ancient One symbol (🜲) with gray overlay. Lock icon visible on top-left of symbol.
**Tooltip on hover**:
```
THE ANCIENT ONE STIRS...
━━━━━━━━━━━━━━━━━━━━━━━━━━━
Requirements:
❌ 50 Void Tears (current: X)
❌ 100 Reputation (current: Y)
Estimated reward: ~Z Echoes
━━━━━━━━━━━━━━━━━━━━━━━━━━━
Keep brewing and serving patrons.
The Ancient One will soon awaken.
```
**Progress visualization**: Below the icon, two horizontal progress bars:
- Top bar (cyan glow): "VT: 37/50" (74% filled, cyan color)
- Bottom bar (gold glow): "REP: 85/100" (85% filled, gold color)
**Unlock anticipation**: When both bars reach 90%+, the icon starts slowly pulsing. Tooltip changes: "The Ancient One is almost ready..."
### When Prestige is Available (25:00+ - requirements met)
**Icon transformation**: Ancient One symbol brightens from dim gray to glowing purple/gold. Lock icon disappears. Icon pulses every 3 seconds with expanding golden ring animation.
**Tooltip on hover**:
```
THE ANCIENT ONE IS READY
━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ 50+ Void Tears (current: 62)
✓ 100+ Reputation (current: 315)
YOU WILL EARN: ~89 Echoes
Current echoes: 0 → New total: 89
━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Click to serve the Ancient One]
```
**Prominent placement**: Icon grows 20% larger and emits subtle particle effects (small floating dots) to draw attention.
**Prestige button**: Below the icon, a button appears: "SERVE THE ANCIENT ONE" (golden border, pulsing). Button expands on hover.
### The Preview Panel (when hovering/clicking prestige option)
**Full breakdown panel** (slides in from right when clicking prestige button):
```
┌─────────────────────────────────────────┐
│ ANCIENT ONE'S GRAND SERVICE │
├─────────────────────────────────────────┤
│ │
│ 📊 CURRENT RUN PERFORMANCE │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ Void Tears: 62 │
│ Reputation: 315 │
│ Successful Brews: 18 │
│ Patrons Served: 9 │
│ Service Quality: Excellent (95%) │
│ │
│ 💎 ECHO REWARD CALCULATION │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ Base: floor(62/10 + 315/5 + 18/20 + 9*2)│
│ = 6 + 63 + 0 + 18 = 87 Echoes │
│ Quality Bonus: floor(315 * 0.1 * 0.95) │
│ = +29 Echoes │
│ ───────────────────────────────────── │
│ TOTAL EARNED: ~116 Echoes │
│ Current Total: 0 Echoes │
│ New Total: 116 Echoes (✨ NEW!) │
│ │
│ 🏠 WHAT YOU'LL LOSE │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ • All Pressure (1,247 PSI) │
│ • All Essence (6 types) │
│ • All Void Tears (62) │
│ • All Reputation (315) │
│ • Zone 2 & 3 access │
│ • Equipment upgrades │
│ • Recipe knowledge │
│ │
│ ✨ WHAT YOU'LL KEEP │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ • All 116 Echoes (permanent!) │
│ • Any Echo upgrades purchased │
│ • Achievement badges │
│ │
│ 🚀 ESTIMATED RUN 2 SPEED │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ With Echo upgrades, next run will take: │
│ • ~15 minutes (vs 30 min first run) │
│ • 2x faster overall progression │
│ │
│ 💡 TOP AFFORDABLE UPGRADES │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ 1. Quick Start L3 (15 ECHO) - +400 PSI │
│ 2. Pressure Multi L2 (20 ECHO) - +44% │
│ 3. Extraction Bonus L1 (15 ECHO) - +15% │
│ │
│ [CANCEL] [CONFIRM SERVICE] │
└─────────────────────────────────────────┘
```
**Real-time updates**: All numbers update in real-time as player continues playing. If player earns 3 more void tears before clicking confirm, the echo estimate increases from ~116 to ~117.
**Smart recommendations**: The "Top Affordable Upgrades" section prioritizes upgrades that reduce next run's time based on current performance bottlenecks (e.g., if player had low pressure throughout, recommend Pressure Multiplier).
## Edge Cases
### Prestige at Minimum (50 VT + 100 REP exactly)
**What happens**: Player clicks prestige at bare minimum. Echo calculation: `floor(50/10 + 100/5 + 2/20 + 1*2) = 5 + 20 + 0 + 2 = 27 echoes`. No quality bonus (low reputation = poor service). Total earned: ~27 echoes.
**Is it worth it?**: Technically yes - 27 echoes can buy Quick Start Level 2 (10 echoes) and Pressure Multiplier Level 1 (10 echoes) with 7 echoes remaining. Run 2 will be ~1.5x faster (22-25 minutes instead of 30). However, this is suboptimal - pushing to 60 VT + 300 REP takes only ~3 more minutes but yields ~85 echoes (3x more).
**Player protection**: Confirmation dialog shows "⚠️ Prestiging now yields 27 echoes. Waiting for 60 VT + 300 REP (~3 more minutes) would yield ~85 echoes. Are you sure?" This prevents accidental early prestige.
### Prestige Hoarding (pushing way past recommended)
**What happens**: Player continues to 100 VT + 700 REP (45+ minutes). Echo calculation: `floor(100/10 + 700/5 + 40/20 + 18*2) + quality_bonus`. Without considering diminishing returns: ~10 + 140 + 2 + 36 = 188 echoes + quality bonus (~40) = ~228 echoes total.
**Does the formula handle this gracefully?**: Yes. The formula is linear, but the INPUTS are logarithmically scaled by gameplay time:
- **Void Tears 50→60** (10 VT difference): Takes ~3 minutes at this stage. Yields +1 echo (60/10 - 50/10 = 1). **Efficiency**: 3 minutes/echo = poor.
- **Void Tears 60→80** (20 VT difference): Takes ~10 minutes (distillation slows as costs rise). Yields +2 echoes (80/10 - 60/10 = 2). **Efficiency**: 5 minutes/echo = terrible.
- **Reputation 300→500** (200 REP difference): Takes ~15 minutes (patron requests hard cap, must risk forbidden brews). Yields +40 echoes (500/5 - 300/5 = 40). **Efficiency**: 22 seconds/echo = good early, but forbidden brew failures cost reputation.
**Diminishing returns warning**: At 28:00, the game shows: "💭 Each additional void tear/reputation gives fewer echoes. You're in diminishing returns territory. Consider prestiging soon for optimal time/echo ratio."
**Soft cap**: At 80 VT + 500 REP (~35 minutes), tooltip: "⚠️ Maximum efficient prestige reached. Further gains require disproportionate time investment. Prestige recommended."
**Player choice**: Hoarding is allowed (not prevented), but the game clearly signals inefficiency. Achievement "Patient Brewer" rewards waiting to 28+ minutes. Achievement "Master of the Deep" rewards reaching 60 VT + 300 REP. Players who prestige at 100 VT are recognized but not punished.
### Multiple Prestiges with No Spending (hoarding echoes)
**What happens**: Player prestiged 3 times, earned 80 + 100 + 120 = 300 echoes, but spent 0. All echoes accumulated. Run 4 begins with 300 echoes but NO echo upgrades active.
**Is Run 4 identical to Run 1?**: NO. Achievement bonuses from previous prestiges persist (+10% recipe quality, +5% repair speed, etc.). Player has knowledge of game mechanics (not lost). But without echo upgrades, Run 4's speedup is minimal (~10-20% faster from achievement bonuses alone).
**Why would a player do this?**: To save for a mega-upgrade like Quick Starter Pack (500 echoes to start with Zone 2 unlocked) or Ancient One's Blessing (150 echoes per level for +5% echo gains). This is a valid strategy - sacrifice 3 runs of upgrades for one game-changing purchase.
**Run 4 experience**: 300 echoes is enough to buy Quick Starter Pack immediately. Run 5 starts with Zone 2 unlocked, skipping 7 minutes. The hoarding strategy paid off - 4 "slow" runs for one massively accelerated run.
**Balance check**: Quick Starter Pack costs 500 echoes (requires ~5-6 prestiges of saving). It's achievable but requires commitment. Not game-breaking, just a fun alternative path.
### Prestige Currency Overflow (when does this need BigNum?)
**Expected values**:
- **Prestige 1**: ~85 echoes (Run 1: 30 min)
- **Prestige 2**: ~120 echoes (Run 2: 15 min)
- **Prestige 3**: ~180 echoes (Run 3: 8 min)
- **Prestige 5**: ~300 echoes total (Run 5: 5 min)
- **Prestige 10**: ~1,200 echoes total (Run 10: 3 min)
- **Prestige 20**: ~4,500 echoes total (Run 20: 2 min)
**When does BigNum matter?**: JavaScript `Number.MAX_SAFE_INTEGER` is ~9 quadrillion (9 × 10^15). Even at prestige 100, echoes would be ~30,000. **BigNum is NEVER needed** for echoes in normal gameplay.
**However**, other currencies can overflow:
- **Pressure**: With 10 prestiges (Pressure Multiplier L10 = 6x generation), player can reach 10,000+ pressure. Still within safe integer range.
- **Essence**: Hard cap at 9999.9 prevents overflow.
- **Void Tears**: After 20 prestiges, player might accumulate 200+ VT per run. Total earned across all runs: ~5,000. Safe.
**Overflow protection needed at**: Prestige 50+ (power gamers). At prestige 50, echoes could reach ~100,000. Still safe. At prestige 100, ~300,000. Still safe. JavaScript handles this natively without BigNum.
**Scientific notation display**: If echoes exceed 1,000,000 (1 million), display as "1.0e6" or "1.0M". This is future-proofing for prestige 200+ (unlikely but possible).
**Conclusion**: Overflow is not a practical concern. The game's exponential upgrade costs (1.4x - 1.7x per level) and echo gain formula (linear in inputs, logarithmic in time) naturally cap progression at prestige 10-15 for meaningful upgrades. Beyond that, echoes accumulate for cosmetic purchases (Echo Memories) or leaderboard competition, not game-breaking power.
Progression
{
"progressionSystem": {
"overview": "Abyssal Brewery's progression follows a 'pressure cooker' philosophy - start with simple clicking, slowly add layers of complexity, and always maintain tension through pressure's constant drain. The first 30 seconds establish the core click-to-fuel loop. By 1 minute, the player has their first passive system. By 3 minutes, the economy becomes three-dimensional with essence extraction. By 10 minutes, strategic depth emerges with the Void Distiller. By 15 minutes, all core systems are online and the player is managing risk vs. reward across multiple zones. The emotional arc flows from curious exploration (0-5 min) to satisfying optimization (5-15 min) to ambitious mastery (15-30 min). Every unlock is visible in advance, creating a 'horizon of possibility' that pulls the player forward. The game never overwhelms with systems - it reveals them like layers of an onion, each new mechanic building on what came before.",
"unlockSequence": {
"phase1_onboarding": {
"name": "Phase 1: Onboarding (0:00 - 1:00)",
"goal": "Player understands core action and sees first reward",
"unlocks": [
{
"time": "0:00",
"trigger": "Game start",
"whatUnlocks": "Pressure vent (clickable), Pressure gauge (100 PSI starting), Equipment durability bar (100/100), Shallows zone indicator (active)",
"whyItMatters": "Establishes the core loop: click to get pressure, pressure is fuel, everything depends on it"
},
{
"time": "0:10",
"trigger": "First vent click",
"whatUnlocks": "Pressure +15, gauge animation, floating '+15 PSI' text, Sound effect (vent hiss)",
"whyItMatters": "Immediate feedback - player sees their action has impact, feels the pressure mechanic"
},
{
"time": "0:30",
"trigger": "Pressure reaches 150 PSI",
"whatUnlocks": "Auto-Collector upgrade (visible, cost: 50 PSI), Hint tooltip: 'Auto-collectors passively generate pressure'",
"whyItMatters": "First glimpse of passive progression - player sees a path beyond clicking"
},
{
"time": "0:45",
"trigger": "Player accumulates 50+ PSI",
"whatUnlocks": "First affordable upgrade highlighted (Auto-Collector), Button pulses/glows",
"whyItMatters": "Achievable goal within first minute - player feels progress is possible"
},
{
"time": "1:00",
"trigger": "First upgrade purchased (Auto-Collector Level 1)",
"whatUnlocks": "Passive pressure generation (+2 PSI/sec), Extraction system (visible but locked, cost: 100 PSI), New hint: 'Extraction requires pressure but yields valuable essence'",
"whyItMatters": "Passive income established - player transitions from active clicking to active management"
}
],
"emotionalBeat": "Curiosity and accomplishment. Player understands 'click to get pressure' and has purchased their first upgrade. They feel smart for figuring out the system and eager to see what's next."
},
"phase2_expansion": {
"name": "Phase 2: Expansion (1:00 - 5:00)",
"goal": "Second system introduced. Player starts making choices.",
"unlocks": [
{
"time": "1:30",
"trigger": "Pressure reaches 200 PSI",
"whatUnlocks": "Extractor upgrade (visible, cost: 10 Bioluminescent Essence), Creature capture tank (visible, empty), Essence storage gauge (0/9999.9 for each of 6 types)",
"whyItMatters": "Teases the next system - player knows extraction is coming but needs to figure out how"
},
{
"time": "2:00",
"trigger": "Extraction system purchased (100 PSI)",
"whatUnlocks": "Essence extractor (Zone 1) active, Bioluminescent essence extraction (0.5/s), Pressure drain -5 PSI/sec per extractor, First glow-jelly captured in tank (visual)",
"whyItMatters": "Economy becomes 3D - pressure now has a real sink, player manages fuel vs. extraction"
},
{
"time": "2:30",
"trigger": "First essence extracted (10+ Bioluminescent)",
"whatUnlocks": "Brewery system (visible, cost: 10 Bioluminescent), Recipe: 'Mildly Radioactive Ale' (unlocked), Brewing UI (tank, pressure cost, ingredients)",
"whyItMatters": "New sink for essence - player now sees the full loop: pressure → essence → brew"
},
{
"time": "3:00",
"trigger": "First brew completed (Mildly Radioactive Ale)",
"whatUnlocks": "Brew inventory (visible, 1 ale stored), Patron queue (visible but locked, 'First patron arrives at 12:00'), Recipe quality indicator (visible), Hint: 'Better recipes = better patron tips'",
"whyItMatters": "Player has created something - brew is the reward, sets up patron system"
},
{
"time": "3:30",
"trigger": "Pressure reaches 300 PSI",
"whatUnlocks": "Zone 2: Twilight Depths (visible, cost: 500 PSI, locked), Zone preview panel (shows Crystalline & Eldritch essences)",
"whyItMatters": "Long-term goal revealed - player sees the next zone and wants to reach it"
},
{
"time": "4:00",
"trigger": "Essence total reaches 50+ (all types combined)",
"whatUnlocks": "Multiple extractor upgrades (affordable), Equipment upgrade: 'Extractor Efficiency' (visible, cost: 100 PSI), Upgrade menu expandable (click to view all)",
"whyItMatters": "Player faces first meaningful choice: upgrade extraction speed or efficiency? Strategy emerges"
},
{
"time": "5:00",
"trigger": "Auto-Collector Level 3 achieved",
"whatUnlocks": "Tidal event system (active), First tidal surge (random 60-120s from now), Hint: 'Tidal surges bring bonus pressure'",
"whyItMatters": "Random events add variety - player learns to expect and capitalize on surges"
}
],
"emotionalBeat": "Engagement and agency. Player is managing multiple systems (pressure, essence, brewing) and making strategic choices. They feel powerful seeing their brewery grow, but also constrained by pressure's constant drain."
},
"phase3_complexity": {
"name": "Phase 3: Complexity (5:00 - 15:00)",
"goal": "All core systems online. Optimization and strategy emerge.",
"unlocks": [
{
"time": "5:30",
"trigger": "First tidal event triggers",
"whatUnlocks": "Tidal surge (+50-150 PSI), Event notification toast, Surge timer (visible, counts down to next event)",
"whyItMatters": "Random injection teaches player to adapt - save pressure during droughts, spend during surges"
},
{
"time": "6:00",
"trigger": "Essence reaches 100+ combined",
"whatUnlocks": "Recipe: 'Crystalline Cider' (visible, requires Crystalline Essence), Zone 2 progress bar (visible, shows 400/500 PSI collected)",
"whyItMatters": "Player sees exactly how close they are to Zone 2 - progress visualization drives motivation"
},
{
"time": "7:00",
"trigger": "Zone 2: Twilight Depths unlocked (500 PSI spent)",
"whatUnlocks": "Zone 2 access (active), New creatures (Crystal Crab, Void Squid) visible in tanks, Crystalline extraction (0.4/s), Eldritch extraction (0.15/s), Equipment damage starts (1-2 damage/sec in Zone 2), Repair system (visible, cost: 20-200 PSI or 5 essence per durability)",
"whyItMatters": "Huge unlock - new essences, new risk. Player must now balance deeper rewards vs. equipment survival"
},
{
"time": "8:00",
"trigger": "First equipment damage takes durability below 80",
"whatUnlocks": "Damage warning (gauge turns yellow), Repair button pulses, Hint: 'Damaged equipment works slower. Repair before it breaks!'",
"whyItMatters": "Consequence revealed - player learns the push-pull of deeper zones"
},
{
"time": "9:00",
"trigger": "First repair performed",
"whatUnlocks": "Equipment durability restored, Repair cooldown (30s), Achievement: 'Handy Brewer' (toast notification), +5% repair speed bonus (permanent)",
"whyItMatters": "Player learns maintenance cycle - push deep, take damage, retreat to repair, repeat"
},
{
"time": "10:00",
"trigger": "Crystalline essence reaches 20+",
"whatUnlocks": "Void Distiller (visible, cost: 100 PSI + 5 Crystalline Essence), Void Tear UI (0 VT, icon: 💧), Distillation cooldown (30s), First distillation recipe visible",
"whyItMatters": "Major strategic depth unlocked - player can now convert currencies for the bottleneck resource"
},
{
"time": "10:30",
"trigger": "First Void Tear distilled",
"whatUnlocks": "Void Tear storage (1 VT), Void Tear upgrades (visible, locked), Prestige teaser (dimmed icon visible, '?', tooltip: '??????'), Hint: 'Void Tears are the key to everything...'",
"whyItMatters": "Player has achieved the bottleneck currency - feels like they've unlocked the 'real' game"
},
{
"time": "11:00",
"trigger": "Void Tear count reaches 3",
"whatUnlocks": "Void Tear upgrade tree (visible), Upgrade: 'Distillation Efficiency' (affordable, 5 VT), Progress toward Zone 3 (15 VT required, shows '3/15'),",
"whyItMatters": "New upgrade path visible - player sees how to optimize their new bottleneck currency"
},
{
"time": "12:00",
"trigger": "Reputation system unlocks (hidden requirement: 5+ minutes played + 2+ Void Tears)",
"whatUnlocks": "First patron arrives (Tier 1: Glow-Jelly Seeker), Patron request UI (visible, 45s timer), Reputation gauge (0/1000), Service quality indicator, Recipe: 'Void Whisper' (unlocked, requires Eldritch + Crystalline)",
"whyItMatters": "Entire new progression track - reputation adds long-term goals and rewards skilled service"
},
{
"time": "13:00",
"trigger": "First patron served successfully",
"whatUnlocks": "+5 Reputation, Patron tip (5-20 essence of patron's preference), Patron departure animation, Next patron queue (visible), Achievement: 'Brewmaster's First Serve' (toast), +10% recipe quality bonus",
"whyItMatters": "Reputation loop established - player sees the reward system and wants to optimize patron service"
},
{
"time": "14:00",
"trigger": "Reputation reaches 25",
"whatUnlocks": "Patron Tier 2 preview (visible, locked, cost: 50 REP), Recipe mastery system (visible), Mastery: 'Mildly Radioactive Ale' (affordable, 10 REP)",
"whyItMatters": "Player sees the reputation progression path - motivation to serve more patrons"
},
{
"time": "15:00",
"trigger": "Void Tears reach 15",
"whatUnlocks": "Zone 3: Thermal Vents (affordable, 15 VT), Equipment specialization choice (visible, cost: 20 VT), Warning: 'Zone 3 is EXTREMELY dangerous. Equipment will take massive damage. Are you ready?'",
"whyItMatters": "Major decision point - player can push to the final zone or invest in specializations"
}
],
"emotionalBeat": "Mastery and strategic thinking. Player is managing 4 currencies, equipment durability, zone choices, and patron requests. They feel powerful but constrained - every choice has tradeoffs. The game feels deep but not overwhelming."
},
"phase4_masteryPrestige": {
"name": "Phase 4: Mastery & Prestige Push (15:00 - 30:00)",
"goal": "Player sees the ceiling, understands prestige, and pushes for it.",
"unlocks": [
{
"time": "15:30",
"trigger": "Zone 3: Thermal Vents unlocked (15 VT spent) OR Equipment specialization chosen",
"whatUnlocks": [
{
"ifZone3": "Zone 3 access (active), Thermal essence extraction (0.3/s), Corrupted essence extraction (0.08/s), Ancient essence extraction (0.03/s, rare spawns), Massive equipment damage (5-10 damage/sec), Thermal event warning (occasional vent eruptions)",
"ifSpecialization": "Specialization active (Pressure Master / Essence Keeper / Void Alchemist), Corresponding bonuses/maluses applied, Playstyle dramatically shifts, Specialization achievement unlocked"
}
],
"whyItMatters": "Huge divergence - player's choice defines their late-game strategy and build"
},
{
"time": "16:00",
"trigger": "Thermal essence reaches 10+",
"whatUnlocks": "Recipe: 'Thermal Tango' (unlocked), Recipe: 'Corrupted Chaos' (visible, requires 50 REP), Forbidden recipe preview (dimmed, 'requires 30 VT')",
"whyItMatters": "New recipes provide new goals - player sees the reward for mastering Zone 3"
},
{
"time": "17:00",
"trigger": "Reputation reaches 50",
"whatUnlocks": "Patron Tier 2 access (affordable), Tier 2 patrons arrive (Crystal Crab Cultist, Void Squid Scholar), Harder requests but better rewards (+10 REP for perfect service), Achievement: 'Respected Brewmaster'",
"whyItMatters": "Reputation system deepens - player faces riskier requests for better rewards"
},
{
"time": "18:00",
"trigger": "Void Tears reach 20",
"whatUnlocks": "Corrupted Void Distillation recipe (unlocked, 200 PSI + 5 Corrupted + 5 Thermal = 2 VT), Forbidden recipes (visible, 10-30 VT each), Distillation cooldown increased to 45s for corrupted recipe, Risk: '15% chance to fail and lose all inputs'",
"whyItMatters": "High-risk high-reward option unlocked - player can gamble for faster void tears"
},
{
"time": "19:00",
"trigger": "First forbidden recipe attempt (or Void Tears = 25)",
"whatUnlocks": "Brew: 'Brew of the Deep' (visible, 40 Corrupted + 40 Eldritch + 10 VT), Success/Fail animation, On success: +25 REP, On failure: lose all inputs, Achievement: 'Forbidden Brewer' (on first success)",
"whyItMatters": "Risk mechanic revealed - player learns that forbidden brewing is gambling, not farming"
},
{
"time": "20:00",
"trigger": "Reputation reaches 100",
"whatUnlocks": "Prestige system revealed (Ancient One icon visible, not interactive), Requirement display: '50 Void Tears + 100 Reputation to awaken the Ancient One', Progress bars: 'VT: X/50', 'REP: Y/100', Hint: 'The Ancient One stirs...'",
"whyItMatters": "Endgame revealed - player now knows exactly what's required for prestige and can plan their push"
},
{
"time": "21:00",
"trigger": "Ancient essence reaches 5+ (rare drop from Zone 3)",
"whatUnlocks": "Recipe: 'Ancient One's Chalice' (visible, requires 500 REP - final recipe), Ancient essence upgrades (visible, very expensive), Achievement: 'Touched by the Deep'",
"whyItMatters": "Rarest essence discovered - player feels lucky and motivated to hunt more ancient creatures"
},
{
"time": "22:00",
"trigger": "Void Tears reach 30",
"whatUnlocks": "Forbidden recipe: 'Abyssal Nightmare' (unlocked, 60 Ancient + 50 Corrupted + 40 Thermal + 20 VT), Risk: '35% fail chance, lose 50 REP on failure', Reward: 'Massive reputation boost', Achievement: 'Nightmare Brewer' (on first success)",
"whyItMatters": "Ultimate risk option - player can gamble everything for massive reputation gains toward prestige"
},
{
"time": "23:00",
"trigger": "Equipment breaks for the first time (durability reaches 0)",
"whatUnlocks": "Equipment failure state (all extraction/brewing halted), Emergency repair prompt (costs 2x normal), Achievement: 'Under Pressure' (first equipment break), Warning: 'Keep equipment repaired or lose everything!'",
"whyItMatters": "Consequences of Zone 3 felt - player learns that equipment management is critical late-game"
},
{
"time": "24:00",
"trigger": "Void Tears reach 40",
"whatUnlocks": "Ancient Void Distillation recipe (unlocked, 500 PSI + 10 Ancient + 10 Corrupted + 10 Eldritch = 5 VT), Risk: '30% fail, 5% Ancient One's Wrath (lose all pressure)', Cooldown: 60s, Achievement: 'Distillation Master' (on first success)",
"whyItMatters": "Highest-level distillation - player can now mass-produce void tears if they're brave"
},
{
"time": "25:00",
"trigger": "Void Tears reach 50 + Reputation reaches 100",
"whatUnlocks": "Prestige button becomes interactive (pulsing Ancient One icon), Prestige confirmation dialog: 'Serve the Ancient One? This will RESET your run but earn Echoes.', Echo calculator preview: 'You will earn approximately X Echoes', Achievement: 'The Ancient One Stirs'",
"whyItMatters": "Prestige achievable - player must decide: push for more rewards or prestige now?"
},
{
"time": "26:00",
"trigger": "Player hovers over prestige button (doesn't click)",
"whatUnlocks": "Detailed prestige breakdown (tooltip): 'Echoes = VT/10 + REP/5 + brews/20 + patrons*2', Current estimate: 'You will earn ~Y Echoes', What persists: 'Echoes, Recipe Mastery, Equipment Schematics', What resets: 'Everything else'",
"whyItMatters": "Player understands exactly what they'll get and lose - informed decision making"
},
{
"time": "27:00",
"trigger": "Void Tears reach 55 + Reputation reaches 200",
"whatUnlocks": "Optimal prestige range reached, Prestige button glows brighter, Hint: 'Optimal prestige conditions achieved. More reputation/void tears = more echoes, but diminishing returns...', Achievement: 'Ready for the Abyss'",
"whyItMatters": "Player is at optimal prestige - the game signals they should prestige soon"
},
{
"time": "28:00",
"trigger": "Player hasn't prestiged yet (optional continue)",
"whatUnlocks": "Diminishing returns warning: 'Each additional void tear/reputation gives fewer echoes. Consider prestiging soon.', Achievement: 'Patient Brewer' (for waiting until 28+ minutes)",
"whyItMatters": "Game nudges player toward prestige without forcing - respects player agency"
},
{
"time": "29:00",
"trigger": "Void Tears reach 60 + Reputation reaches 300",
"whatUnlocks": "Maximum efficient prestige, Soft cap notification: 'You have exceeded optimal prestige conditions. Further gains are minimal.', Achievement: 'Master of the Deep',",
"whyItMatters": "Player has maximized first run - the game acknowledges their mastery"
},
{
"time": "30:00",
"trigger": "Player clicks prestige button (serves the Ancient One)",
"whatUnlocks": "Prestige animation (Ancient One rises from the depths), Echo calculation: 'You earned X Echoes!', Echo display (persistent currency), Reset sequence: 'Starting next run...', Echo shop (unlocked immediately), First Echo upgrade visible, Achievement: 'First Service', New run begins with starting pressure (100) + all echo bonuses",
"whyItMatters": "Emotional climax - player serves the Ancient One, earns permanent progress, and starts fresh with new power. The loop is closed and ready to repeat."
}
],
"emotionalBeat": "Ambition and anticipation. Player sees the prestige goal and is pushing toward it. They're optimizing their build, managing risk, and making strategic sacrifices. When prestige triggers, they feel accomplished - they've mastered the first run and earned permanent power. The transition to run 2 feels exciting, not like starting over."
}
},
"gates": {
"hardGates": [
{
"gate": "First Extraction",
"requirement": "Accumulate 100 PSI (takes ~30-45 seconds of clicking)",
"whatsBlocked": "Essence extraction, brewing, patron system, all essence-based upgrades",
"estimatedWaitTime": "30-45 seconds",
"purpose": "Forces player to learn the core click mechanic before revealing complexity. Ensures they understand pressure's value."
},
{
"gate": "Zone 2 Unlock",
"requirement": "Accumulate 500 PSI (takes ~2-3 minutes with auto-collectors)",
"whatsBlocked": "Crystalline & Eldritch essences, Zone 2 creatures, equipment damage mechanic, repairs, Zone 2 pressure collectors",
"estimatedWaitTime": "2-3 minutes",
"purpose": "Creates a meaningful goal that encourages upgrading pressure collectors. Player must invest in infrastructure before accessing new content."
},
{
"gate": "Void Distiller Unlock",
"requirement": "Craft 20+ Crystalline Essence (takes ~3-4 minutes of extraction)",
"whatsBlocked": "Void Tears, Zone 3, specializations, forbidden recipes, prestige, all Void Tear upgrades",
"estimatedWaitTime": "4-5 minutes from Zone 2 unlock",
"purpose": "Ensures player has established essence economy before introducing the bottleneck currency. Teaches that Void Tears require planning."
},
{
"gate": "Zone 3 Unlock",
"requirement": "Spend 15 Void Tears (takes ~8-10 minutes of distillation)",
"whatsBlocked": "Thermal/Corrupted/Ancient essences, thermal events, massive equipment damage, final recipes, Ancient One reveal",
"estimatedWaitTime": "8-10 minutes from Void Distiller unlock",
"purpose": "Forces player to master distillation before accessing the most dangerous (rewarding) zone. Creates a long-term goal."
},
{
"gate": "Prestige Trigger",
"requirement": "50 Void Tears + 100 Reputation (takes ~15-20 minutes from start)",
"whatsBlocked": "Echoes, prestige shop, permanent upgrades, accelerated second run",
"estimatedWaitTime": "15-20 minutes from Zone 3 unlock",
"purpose": "Ensures player has experienced all core systems before prestiging. Requires mastery of both distillation (VT) and patron service (REP)."
}
],
"softGates": [
{
"gate": "Equipment Durability",
"whatSlowsDown": "Zone 2+ causes gradual equipment damage (1-2 damage/sec in Zone 2, 5-10 damage/sec in Zone 3). Damaged equipment works slower (extraction/brewing speed reduced by 1% per durability lost).",
"alternativeActivities": "Return to Zone 1 (safe, no damage), repair equipment (costs pressure or essence), wait for tidal surges for bonus pressure",
"purpose": "Creates natural push-pull rhythm. Player can't stay in deep zones forever - must retreat to shallow zones for repairs. Prevents 'set it and forget it' gameplay."
},
{
"gate": "Void Distillation Cooldown",
"whatSlowsDown": "Each distillation has a cooldown (30s basic, 45s corrupted, 60s ancient). Player can't spam void tears even if they have resources.",
"alternativeActivities": "Upgrade distillation speed (costs void tears), brew recipes for patrons, extract essence, repair equipment, wait for tidal events",
"purpose": "Prevents void tear spam. Forces player to manage timing - distill during safe moments, not under pressure."
},
{
"gate": "Patron Request Timer",
"whatSlowsDown": "Each patron request has a 45-60 second timer. If time runs out, patron leaves (-5 to -20 reputation). Player can't ignore patrons.",
"alternativeActivities": "Brew recipes in advance to stockpile, upgrade brewing speed, bribe patrons (costs essence), let low-priority patrons expire if resources are tight",
"purpose": "Creates time pressure. Player must decide: serve this patron now or risk losing reputation? Adds tactical decision-making."
},
{
"gate": "Rare Essence Extraction Rates",
"whatSlowsDown": "Ancient essence extracts at 0.03/s, Corrupted at 0.08/s. These are intentionally very slow.",
"alternativeActivities": "Focus on more common essences, use forbidden recipes for reputation instead, upgrade extraction with essence/void tears, hunt rare creature spawns in Zone 3",
"purpose": "Makes rare essences feel valuable. Player must choose: wait for rare extraction or use riskier methods (forbidden brewing)?"
},
{
"gate": "Essence Cap (9999.9)",
"whatSlowsDown": "Can't hoard infinite essence. At cap, tidal overflow events occur (lose 50% of that essence type).",
"alternativeActivities": "Spend essence on upgrades, brew recipes, distill void tears, repair with essence",
"purpose": "Forces spending. Prevents hoarding strategy that would trivialize later content."
}
]
},
"milestones": {
"achievementStyle": [
{
"number": 1,
"name": "First Tap",
"condition": "Click the pressure vent for the first time",
"reward": "Nothing (tutorial achievement), Notification text: 'Welcome to the Abyss, Brewmaster.'",
"notificationToast": "🏆 First Tap: Welcome to the Abyss, Brewmaster."
},
{
"number": 2,
"name": "Passive Pressure",
"condition": "Purchase first Auto-Collector upgrade",
"reward": "+5% all pressure generation (permanent), Notification text: 'The vents work while you rest.'",
"notificationToast": "🏆 Passive Pressure: +5% pressure generation forever!"
},
{
"number": 3,
"name": "Essence Extractor",
"condition": "Extract first essence (10+ total)",
"reward": "Unlock brewery system, Notification text: 'The creatures yield their secrets.'",
"notificationToast": "🏆 Essence Extractor: Brewery system unlocked!"
},
{
"number": 4,
"name": "First Brew",
"condition": "Complete first brew (Mildly Radioactive Ale)",
"reward": "Unlock brew inventory, Notification text: 'A radioactive masterpiece.'",
"notificationToast": "🏆 First Brew: Your brewing journey begins!"
},
{
"number": 5,
"name": "Zone Pioneer",
"condition": "Unlock Zone 2: Twilight Depths",
"reward": "+10 max equipment durability, Notification text: 'The Twilight Zone awaits.'",
"notificationToast": "🏆 Zone Pioneer: Twilight Depths explored! +10 max durability."
},
{
"number": 6,
"name": "Handy Brewer",
"condition": "Perform first equipment repair",
"reward": "+5% repair speed (permanent), Notification text: 'Good as new.'",
"notificationToast": "🏆 Handy Brewer: +5% repair speed!"
},
{
"number": 7,
"name": "Void Alchemist",
"condition": "Distill first Void Tear",
"reward": "Unlock Void Tear upgrades, Notification text: 'You've torn a hole in reality.'",
"notificationToast": "🏆 Void Alchemist: First Void Tear created!"
},
{
"number": 8,
"name": "Brewmaster's First Serve",
"condition": "Serve first patron successfully",
"reward": "+10% recipe quality (permanent), Notification text: 'The patron is pleased.'",
"notificationToast": "🏆 First Serve: +10% recipe quality!"
},
{
"number": 9,
"name": "Respected Brewmaster",
"condition": "Reach 50 Reputation",
"reward": "Unlock Patron Tier 2, Notification text: 'Your fame spreads through the depths.'",
"notificationToast": "🏆 Respected Brewmaster: Tier 2 patrons incoming!"
},
{
"number": 10,
"name": "Thermal Diver",
"condition": "Unlock Zone 3: Thermal Vents",
"reward": "+20 max equipment durability, Notification text: 'You descend into the fire.'",
"notificationToast": "🏆 Thermal Diver: Zone 3 unlocked! +20 max durability."
},
{
"number": 11,
"name": "Forbidden Brewer",
"condition": "Successfully complete first forbidden brew (Brew of the Deep)",
"reward": "+15% forbidden brew success chance (permanent), Notification text: 'Some secrets should remain buried.'",
"notificationToast": "🏆 Forbidden Brewer: First forbidden brew! +15% success chance."
},
{
"number": 12,
"name": "Under Pressure",
"condition": "Equipment breaks for the first time (durability reaches 0)",
"reward": "Unlock achievement badge, Notification text: 'The crushing pressure claims all things.'",
"notificationToast": "🏆 Under Pressure: Equipment survived... this time."
},
{
"number": 13,
"name": "Distillation Master",
"condition": "Successfully complete Ancient Void Distillation",
"reward": "-5% distillation cooldown (permanent), Notification text: 'You've mastered the void.'",
"notificationToast": "🏆 Distillation Master: -5% cooldown!"
},
{
"number": 14,
"name": "The Ancient One Stirs",
"condition": "Reach 50 Void Tears + 100 Reputation (prestige available)",
"reward": "Unlock prestige button, Notification text: 'The Ancient One awakens. Prepare your best brew.'",
"notificationToast": "🏆 The Ancient One Stirs: Prestige unlocked!"
},
{
"number": 15,
"name": "First Service",
"condition": "Complete first prestige (serve the Ancient One)",
"reward": "Unlock Echo shop, +10% echo gains (permanent), Notification text: 'The Ancient One drinks deep. You earn Echoes.'",
"notificationToast": "🏆 First Service: Prestige complete! +10% echo gains forever!"
}
],
"progressionMilestones": [
{
"currency": "Pressure",
"threshold": "150 PSI",
"rewardEffect": "Auto-Collector upgrade becomes visible (first passive generation)"
},
{
"currency": "Pressure",
"threshold": "300 PSI",
"rewardEffect": "Zone 2 preview becomes visible (shows unlock cost and required pressure)"
},
{
"currency": "Pressure",
"threshold": "500 PSI",
"rewardEffect": "Zone 2: Twilight Depths unlocks (new essences, equipment damage)"
},
{
"currency": "Bioluminescent Essence",
"threshold": "10",
"rewardEffect": "First brew becomes available (Mildly Radioactive Ale)"
},
{
"currency": "Bioluminescent Essence",
"threshold": "50",
"rewardEffect": "Multiple extractor upgrades become affordable"
},
{
"currency": "Crystalline Essence",
"threshold": "20",
"rewardEffect": "Void Distiller unlocks (can create Void Tears)"
},
{
"currency": "Crystalline Essence",
"threshold": "50",
"rewardEffect": "Zone 2 auto-collector upgrade becomes visible"
},
{
"currency": "Void Tears",
"threshold": "1",
"rewardEffect": "Void Tear upgrade tree becomes visible"
},
{
"currency": "Void Tears",
"threshold": "5",
"rewardEffect": "Distillation efficiency upgrade becomes affordable"
},
{
"currency": "Void Tears",
"threshold": "15",
"rewardEffect": "Zone 3: Thermal Vents unlocks (thermal/corrupted/ancient essences)"
},
{
"currency": "Void Tears",
"threshold": "20",
"rewardEffect": "Equipment specialization choice unlocks (mutually exclusive paths)"
},
{
"currency": "Void Tears",
"threshold": "30",
"rewardEffect": "Corrupted Void Distillation recipe unlocks (higher risk, 2x output)"
},
{
"currency": "Void Tears",
"threshold": "50",
"rewardEffect": "Prestige becomes available (with 100+ Reputation)"
},
{
"currency": "Reputation",
"threshold": "25",
"rewardEffect": "Recipe mastery system unlocks"
},
{
"currency": "Reputation",
"threshold": "50",
"rewardEffect": "Patron Tier 2 unlocks (harder requests, better rewards)"
},
{
"currency": "Reputation",
"threshold": "100",
"rewardEffect": "Prestige system revealed (Ancient One becomes visible)"
},
{
"currency": "Reputation",
"threshold": "200",
"rewardEffect": "Patron Tier 3 unlocks (Ancient One's servants, elite rewards)"
},
{
"currency": "Reputation",
"threshold": "500",
"rewardEffect": "Ancient One's Chalice recipe unlocks (final recipe)"
}
]
},
"pacingCurve": {
"minuteByMinute": [
{
"minute": "0-1",
"newContent": "Pressure vent clicking, pressure gauge, first upgrade (Auto-Collector)",
"playerActionFocus": "Active clicking to accumulate pressure, learning the core mechanic",
"tensionLevel": "2",
"notes": "Tutorial phase. Player establishes the core loop. Low tension because nothing is at stake yet."
},
{
"minute": "1-2",
"newContent": "Extraction system unlocks, first essence extraction, pressure drain mechanic",
"playerActionFocus": "Managing pressure vs. extraction, learning that pressure is a limited resource",
"tensionLevel": "3",
"notes": "First resource tradeoff. Player learns pressure isn't infinite."
},
{
"minute": "2-3",
"newContent": "Brewery unlocks, first brew, brew inventory",
"playerActionFocus": "Brewing first recipe, seeing the product of essence extraction",
"tensionLevel": "2",
"notes": "Reward phase. Player sees the output of their work. Satisfying."
},
{
"minute": "3-4",
"newContent": "Multiple extractor upgrades, upgrade menu expansion",
"playerActionFocus": "Choosing which extractor to upgrade, planning extraction strategy",
"tensionLevel": "3",
"notes": "First strategic choice. Player must decide where to invest limited essence."
},
{
"minute": "4-5",
"newContent": "Zone 2 preview, tidal event system",
"playerActionFocus": "Working toward Zone 2 unlock, learning to capitalize on tidal surges",
"tensionLevel": "3",
"notes": "Long-term goal revealed. Player sees the next milestone."
},
{
"minute": "5-6",
"newContent": "First tidal event, surge bonus pressure",
"playerActionFocus": "Reacting to random events, learning to save pressure for upgrades",
"tensionLevel": "4",
"notes": "Randomness introduced. Player must adapt to surges."
},
{
"minute": "6-7",
"newContent": "Zone 2 progress bar, multiple essences accumulating",
"playerActionFocus": "Pushing toward Zone 2 unlock, managing multiple essence types",
"tensionLevel": "4",
"notes": "Goal-oriented phase. Player is close to Zone 2 and motivated."
},
{
"minute": "7-8",
"newContent": "Zone 2 unlocks, Crystalline & Eldritch essences, equipment damage",
"playerActionFocus": "Exploring Zone 2, watching equipment durability, first repairs",
"tensionLevel": "5",
"notes": "Major unlock! Tension spikes as equipment takes damage. Player feels risk."
},
{
"minute": "8-9",
"newContent": "Equipment damage warnings, repair system",
"playerActionFocus": "Balancing deep exploration with equipment survival, learning maintenance cycle",
"tensionLevel": "5",
"notes": "Push-pull established. Player can't stay deep forever. High tension."
},
{
"minute": "9-10",
"newContent": "First repair, repair cooldown, achievement",
"playerActionFocus": "Timing repairs for optimal uptime, managing repair costs",
"tensionLevel": "4",
"notes": "Maintenance understood. Tension decreases as player learns the rhythm."
},
{
"minute": "10-11",
"newContent": "Void Distiller unlocks, Void Tear currency",
"playerActionFocus": "Distilling first void tear, understanding the bottleneck currency",
"tensionLevel": "4",
"notes": "New strategic depth. Void tears are clearly valuable."
},
{
"minute": "11-12",
"newContent": "Void Tear upgrades, progress toward Zone 3",
"playerActionFocus": "Planning distillation timing, upgrading void tear efficiency",
"tensionLevel": "3",
"notes": "Planning phase. Player sees the path to Zone 3."
},
{
"minute": "12-13",
"newContent": "Patron system unlocks, first patron arrives, reputation",
"playerActionFocus": "Serving first patron, learning request timers, earning reputation",
"tensionLevel": "4",
"notes": "New progression track. Tension from patron timers."
},
{
"minute": "13-14",
"newContent": "Patron tips, next patron queue, recipe mastery",
"playerActionFocus": "Optimizing patron service, deciding which recipes to master",
"tensionLevel": "3",
"notes": "Reputation loop established. Player feels progress."
},
{
"minute": "14-15",
"newContent": "Reputation upgrades, Patron Tier 2 preview",
"playerActionFocus": "Building reputation toward Tier 2, mastering recipes",
"tensionLevel": "3",
"notes": "Reputation goals visible. Player is motivated to serve more patrons."
},
{
"minute": "15-16",
"newContent": "Zone 3 OR specialization choice (player decides)",
"playerActionFocus": "Making major strategic decision: unlock Zone 3 or specialize equipment",
"tensionLevel": "5",
"notes": "Critical decision point! Tension peaks as player chooses their path."
},
{
"minute": "16-17",
"newContent": "Thermal/Corrupted/Ancient essences (if Zone 3) OR specialization bonuses (if specialized)",
"playerActionFocus": "Managing dangerous Zone 3 extraction OR optimizing specialization strategy",
"tensionLevel": "5",
"notes": "High complexity. Player is managing 4+ currencies and multiple systems."
},
{
"minute": "17-18",
"newContent": "Patron Tier 2 unlocks, harder requests",
"playerActionFocus": "Serving tougher patrons for better rewards, managing failed requests",
"tensionLevel": "4",
"notes": "Patron difficulty increases. Player must be more selective."
},
{
"minute": "18-19",
"newContent": "Corrupted Void Distillation, forbidden recipes",
"playerActionFocus": "Weighing risk vs. reward in corrupted distillation, eyeing forbidden recipes",
"tensionLevel": "4",
"notes": "Risk mechanics introduced. Player can gamble for faster progression."
},
{
"minute": "19-20",
"newContent": "First forbidden recipe attempt (or 25 VT)",
"playerActionFocus": "Attempting high-risk brew for massive reputation boost",
"tensionLevel": "5",
"notes": "Gamble phase. Tension spikes during forbidden brewing."
},
{
"minute": "20-21",
"newContent": "Prestige system revealed (Ancient One)",
"playerActionFocus": "Seeing the endgame goal, understanding prestige requirements",
"tensionLevel": "3",
"notes": "Endgame revealed! Player knows what they're working toward."
},
{
"minute": "21-22",
"newContent": "Ancient essence (rare drops), final recipe preview",
"playerActionFocus": "Hunting ancient creature spawns in Zone 3, working toward Ancient One's Chalice",
"tensionLevel": "4",
"notes": "Rarest essence discovered. Player feels lucky when it drops."
},
{
"minute": "22-23",
"newContent": "Abyssal Nightmare recipe (ultimate forbidden brew)",
"playerActionFocus": "Deciding whether to attempt the most dangerous brew in the game",
"tensionLevel": "5",
"notes": "Maximum risk. Player can lose massive progress or gain huge rewards."
},
{
"minute": "23-24",
"newContent": "First equipment break (if not happened yet)",
"playerActionFocus": "Dealing with equipment failure, emergency repairs",
"tensionLevel": "5",
"notes": "Consequences felt. Player learns that equipment management is critical."
},
{
"minute": "24-25",
"newContent": "Ancient Void Distillation (ultimate distillation)",
"playerActionFocus": "Attempting 5-output distillation with 30% fail chance",
"tensionLevel": "5",
"notes": "Highest-level distillation. Very tense but very rewarding."
},
{
"minute": "25-26",
"newContent": "Prestige becomes available (50 VT + 100 REP)",
"playerActionFocus": "Deciding whether to prestige now or push for more rewards",
"tensionLevel": "4",
"notes": "Decision phase. Player evaluates their readiness."
},
{
"minute": "26-27",
"newContent": "Prestige calculator, detailed breakdown",
"playerActionFocus": "Planning optimal prestige timing, understanding echo calculations",
"tensionLevel": "3",
"notes": "Informed decision-making. Player knows exactly what they'll get."
},
{
"minute": "27-28",
"newContent": "Optimal prestige range, diminishing returns warning",
"playerActionFocus": "Pushing for optimal echo gains or choosing to prestige",
"tensionLevel": "4",
"notes": "Nudge toward prestige. Game signals optimal timing."
},
{
"minute": "28-29",
"newContent": "Maximum efficient prestige, soft cap notification",
"playerActionFocus": "Final decision to prestige or continue for achievements",
"tensionLevel": "3",
"notes": "Player has maximized run. Prestige is clearly the best move."
},
{
"minute": "29-30",
"newContent": "Prestige animation, Echo shop, second run begins",
"playerActionFocus": "Serving the Ancient One, watching prestige animation, exploring echo upgrades",
"tensionLevel": "5",
"notes": "Emotional climax! Player feels accomplished and excited for run 2."
}
],
"tensionGraph": {
"description": "Tension starts low during tutorial, spikes at Zone 2 unlock (equipment damage risk), maintains 4-5 during mid-game complexity, dips during planning phases, spikes again at Zone 3/specialization decision (critical choice), stays high during late-game risk mechanics (forbidden brewing, ancient distillation), peaks at prestige trigger (emotional climax).",
"graph": "Tension\n5 | * * * * * * * * *\n4 | * * * * * * * * * * * * * * * * * *\n3 | * * * * * * * * * * * * * *\n2 | * * *\n1 | * *\n +-------------------------------------------------------------------->\n 0 2 4 6 8 10 12 14 16 18 20 22 24 26 28 30 min\n\nKey spikes:\n- 7 min: Zone 2 unlock (equipment damage risk)\n- 15 min: Zone 3/specialization decision\n- 19 min: First forbidden brew attempt\n- 25 min: Prestige available\n- 30 min: Prestige execution"
}
},
"motivators": {
"shortTerm": [
{
"motivator": "Upgrade affordability countdown",
"description": "Progress bars show 'X/Y resources until next upgrade affordable'. Player always knows they're 30 seconds or 3 clicks away from something."
},
{
"motivator": "Patron request timer",
"description": "45-60 second countdown creates urgency. Player must act now or lose reputation."
},
{
"motivator": "Tidal surge anticipation",
"description": "Timer shows 'Next surge in: X seconds'. Player plans to spend pressure now to make room for bonus."
},
{
"motivator": "Essence extraction fill",
"description": "Tanks visually fill with essence. Watching numbers tick up is satisfying and motivating."
},
{
"motivator": "Equipment durability monitoring",
"description": "Gauge turns yellow at 70%, red at 30%. Player feels urgency to repair before breakage."
}
],
"mediumTerm": [
{
"motivator": "Zone unlock progress",
"description": "'Zone 2: 400/500 PSI collected' - player sees they're 80% of the way to the next major unlock."
},
{
"motivator": "Void Tear accumulation",
"description": "'12/15 VT for Zone 3' - player knows exactly how many distillations remain."
},
{
"motivator": "Reputation tier unlocks",
"description": "'48 REP to Tier 2 patrons' - player grinds patron service to reach the next tier."
},
{
"motivator": "Recipe mastery progress",
"description": "Each mastered recipe shows quality bonus. Player wants to master all recipes for optimal service."
},
{
"motivator": "Achievement hunting",
"description": "15 achievements provide clear medium-term goals. Each completion feels like a milestone."
}
],
"longTerm": [
{
"motivator": "Prestige promise",
"description": "'50 VT + 100 REP to serve the Ancient One and earn Echoes' - the ultimate session goal."
},
{
"motivator": "Permanent echo upgrades",
"description": "Player knows their first run will unlock permanent bonuses that make run 2 faster and more powerful."
},
{
"motivator": "Build optimization",
"description": "Equipment specialization choice creates a 'build' that player wants to perfect and try again with a different path."
},
{
"motivator": "Recipe completion",
"description": "All 6 standard recipes + 2 forbidden recipes = completionist goal for players who want to see everything."
},
{
"motivator": "Efficiency pride",
"description": "'Can I prestige in 20 minutes instead of 30?' - self-imposed challenge for mastery."
}
],
"prestigeTease": {
"firstLearn": "At 20:00 (when reputation reaches 100), the prestige system is revealed. The Ancient One icon appears (previously hidden or dimmed) with tooltip text: 'The Ancient One stirs below. Gather 50 Void Tears and 100 Reputation to awaken it.' This is the FIRST time the player learns about prestige.",
"firstFeelPull": "At 25:00 (when player reaches 50 VT + 100 REP), the prestige button becomes interactive and pulses. The tooltip changes to: 'The Ancient One is ready. Serve it to earn Echoes and permanent power.' Player feels the pull because: 1) They've worked 25 minutes for this moment, 2) Echo calculator shows they'll earn ~80-100 echoes, 3) They can see the echo shop with permanent upgrades, 4) The game has teased 'permanent power' throughout.",
"teasedThroughout": "From 20:00 to 30:00, prestige is constantly teased: - Ancient One icon is always visible and slowly animates (pulses, glows brighter as requirements are met) - Progress bars show 'VT: 47/50, REP: 95/100' - Player hovers over Ancient One to see echo estimate - Tooltip updates: 'Almost ready...', 'Ready!', 'Optimal conditions reached' - At 27:00, hint appears: 'You have enough to prestige. More reputation/void tears will give diminishing returns.' - Achievement 'Patient Brewer' at 28:00 acknowledges player who waits - Achievement 'Master of the Deep' at 29:00 rewards maximizing the run - At 30:00, if player hasn't prestiged: 'The Ancient One grows impatient. Serve it now?'",
"finalPush": "The prestige tease works because: 1) Player knows EXACTLY what's required (no mystery), 2) They can see their progress in real-time, 3) Echo calculator shows the reward (tangible benefit), 4) The game nudges them toward prestige without forcing (agency respected), 5) Achievements reward both early prestiging ('First Service') and late prestiging ('Patient Brewer'), 6) Echo shop is visible and shows permanent upgrades that accelerate run 2 (creating desire to restart)."
}
},
"antiFrustrationFeatures": {
"stuckDetection": {
"feature": "If no upgrade has been purchased for 2 minutes AND player has 50+ pressure/essence, highlight affordable upgrades",
"implementation": "Check every 30 seconds: if (timeSinceLastUpgrade > 120s && (pressure > 50 || totalEssence > 50)) then pulse 2-3 most affordable upgrade buttons. Show tooltip: 'You have resources to spend!'",
"prevents": "Player hoarding without spending, not realizing they can afford upgrades"
},
{
"feature": "If pressure drops below 20 for more than 10 seconds, show emergency vent prompt",
"implementation": "If (pressure < 20 && duration > 10s) then highlight vent with glowing border and show tooltip: 'Click the vent to generate pressure! Emergency!'",
"prevents": "Player running out of pressure and not knowing how to recover"
},
{
"feature": "If equipment durability is below 30% and player has 100+ pressure, show repair reminder",
"implementation": "If (durability < 30 && pressure > 100) then pulse repair button and show tooltip: 'Equipment critically damaged! Repair now!'",
"prevents": "Player forgetting to repair and suffering equipment break"
},
{
"feature": "If a patron request timer is below 15 seconds and player has ingredients to fulfill it, highlight brew button",
"implementation": "If (patronTimer < 15s && canAffordRecipe) then pulse brew button with tooltip: 'Fulfill patron request now!'",
"prevents": "Player missing patron requests due to inattention"
},
{
"feature": "If player fails 3 patron requests in a row, show hint: 'Try serving easier patrons or bribing for reputation'",
"implementation": "If (consecutiveFailures >= 3) then show toast: 'Struggling with patrons? Try bribing or focusing on Tier 1 patrons.'",
"prevents": "Player getting stuck on reputation grind"
}
},
"catchupMechanics": {
"badChoiceRecovery": {
"scenario": "Player spends all resources on wrong upgrade path (e.g., upgrades Bioluminescent extractor to level 10 but needs Crystalline for Zone 2)",
"recoveryTime": "2-5 minutes",
"mechanic": "No downgrade/refund system. Player must earn back through gameplay. However: 1) Extractor upgrades are cheap early (10-30 essence) and expensive late (200+), so early mistakes are forgiving, 2) Essence extraction continues in background, so player is always earning, 3) Tidal events and patron tips provide random injections of all essence types, 4) Player can still click vents for pressure, so they're never deadlocked.",
"prevents": "Permanent punishment for early mistakes. Bad choices cost time but not the entire run."
},
{
"scenario": "Player chooses wrong equipment specialization (e.g., Pressure Master but wants to play safely)",
"recoveryTime": "10-15 minutes (or next prestige)",
"mechanic": "Specialization is mutually exclusive PER RUN, but: 1) Player can still complete the run with any specialization (none are 'wrong'), 2) Specialization doesn't lock content - it changes playstyle, 3) On prestige, player can choose a different specialization, 4) Achievement rewards for trying all specializations encourage experimentation.",
"prevents": "Regret over specialization choice. Player learns from the mistake and can try again next run."
},
{
"scenario": "Player loses all resources on failed forbidden brew",
"recoveryTime": "5-8 minutes",
"mechanic": "Forbidden brew failure is punishing but: 1) Player still has pressure generation (vents + auto-collectors), 2) Essence extraction continues, 3) Tidal events provide bonus pressure, 4) Patron tips provide essence, 5) Equipment still works (unless it broke), 6) No progress is lost - only resources consumed. 7) Achievement 'Forbidden Brewer' gives +15% success chance after first success, making future attempts safer.",
"prevents": "Game-ending failure. Forbidden brew mistakes hurt but don't ruin the run."
},
{
"scenario": "Player's equipment breaks (durability reaches 0)",
"recoveryTime": "30 seconds - 1 minute",
"mechanic": "Equipment break is bad but: 1) Emergency repair costs 2x but is still affordable (200-400 pressure or essence), 2) Vent clicking always works (15 PSI per click), 3) Auto-collectors still generate pressure even while equipment is broken, 4) Only extraction and brewing halt - pressure generation continues, 5) Repair is instant, no cooldown.",
"prevents": "Soft-lock. Player can always recover from equipment break."
}
},
"visualProgress": {
"progressBars": [
{
"bar": "Zone unlock progress",
"display": "'Zone 2: 400/500 PSI' - fills from 0% to 100% as player accumulates pressure",
"purpose": "Player sees exactly how close they are to the next major unlock"
},
{
"bar": "Void Tear progress toward Zone 3",
"display": "'12/15 VT for Zone 3' - each void tear increments the counter",
"purpose": "Player knows exactly how many distillations remain"
},
{
"bar": "Reputation tier progress",
"display": "'48/50 REP to Tier 2' - fills as reputation is earned",
"purpose": "Player sees the path to the next patron tier"
},
{
"bar": "Prestige progress",
"display": "'VT: 47/50, REP: 95/100' - two bars, both must fill to unlock prestige",
"purpose": "Player tracks their progress toward the endgame"
}
],
"fillAnimations": [
{
"animation": "Essence tanks",
"display": "Each essence type has a tank that visually fills with glowing liquid of that essence's color",
"purpose": "Satisfying visual feedback - player watches their accumulation grow"
},
{
"animation": "Pressure gauge",
"display": "Gauge needle swings as pressure increases/decreases. Gauge shakes and turns red when pressure is low (<20)",
"purpose": "Creates urgency - player feels the tension of low pressure"
},
{
"animation": "Equipment durability bar",
"display": "Green at 100-70%, yellow at 69-30%, red at 29-0%. Bar shrinks as damage accumulates",
"purpose": "Player sees equipment health at a glance without reading numbers"
},
{
"animation": "Patron request timer",
"display": "Circular countdown timer around patron portrait. Shrinks as time passes. Flashes red when below 15 seconds",
"purpose": "Creates time pressure - player sees urgency visually"
},
{
"animation": "Distillation cooldown",
"display": "Progress bar fills over 30-60 seconds. When full, distillation button pulses and becomes clickable",
"purpose": "Player knows exactly when they can distill again without watching a clock"
}
],
"unlockReveals": [
{
"unlock": "Zone/upgrade previews",
"display": "Locked content is visible but dimmed with a lock icon. Hovering shows requirements: 'Requires 500 PSI' or 'Unlocks at 10:00'",
"purpose": "Player always sees the horizon - they know what's coming next"
},
{
"unlock": "Achievement notifications",
"display": "Toast slides in from right: '🏆 Achievement: Zone Pioneer!' with reward text. Stays for 5 seconds then fades",
"purpose": "Celebrates milestones, makes player feel accomplished"
},
{
"unlock": "New system highlights",
"display": "When a new system unlocks (e.g., patron system), the UI panel pulses/glows for 10 seconds to draw attention",
"purpose": "Player never misses a new unlock - the game highlights it explicitly"
},
{
"unlock": "Upgrade affordability indicators",
"display": "Affordable upgrades have a glowing border. Hovering shows 'You can afford this!' tooltip",
"purpose": "Player always knows what they can buy without manually checking costs"
}
],
"progressDuringSlowMoments": [
{
"moment": "Waiting for distillation cooldown (30-60 seconds)",
"visual": "Cooldown progress bar fills, counting down seconds. When complete, satisfying 'ding' sound and button pulse",
"purpose": "Player sees progress even during waiting - it's not dead time, it's charging time"
},
{
"moment": "Extracting rare essence (0.03/s for Ancient)",
"visual": "Essence tank slowly fills, decimal precision (0.001 increments) creates visible movement even at slow rates",
"purpose": "Even slow accumulation feels like progress because numbers are ticking up"
},
{
"moment": "Working toward expensive upgrade (e.g., 500 PSI for Zone 2)",
"visual": "Progress bar shows '350/500 PSI' with percentage (70%). Bar fills visibly with each pressure gain",
"purpose": "Player sees they're 70% of the way - not stuck, just grinding"
},
{
"moment": "Waiting for next tidal surge",
"visual": "Timer counts down: 'Next surge in: 47 seconds'. Player can plan their spending around it",
"purpose": "Anticipation creates engagement - player prepares for the surge in advance"
},
{
"moment": "Reputation grind between patron tiers",
"visual": "Reputation bar fills with each successful serve. Tier 2 preview shows '45/50 REP' - so close!",
"purpose": "Player sees each patron request brings them closer to the next tier"
}
]
},
"tutorial": {
"firstTimeExperience": [
{
"step": 1,
"whatHappens": "Screen fades in from black to reveal the Abyssal Brewery interface. Pressure vent is center screen, pulsing with a glowing orange aura. All other UI elements are dimmed/hidden. Floating text appears: 'Welcome to the Abyss, Brewmaster. Click the pressure vent to begin.'",
"highlighted": "Pressure vent (center, pulsing)",
"hidden": "Everything else (upgrades, extraction, brewing, patrons - all invisible)",
"tooltip": "Hover over vent: 'Geothermal vent - click to collect pressure. Pressure powers everything.'"
},
{
"step": 2,
"whatHappens": "Player clicks the vent. +15 PSI floats up from the vent. Pressure gauge animates from 100 to 115. Sound effect: vent hiss. Floating text: 'Good! Keep clicking to build pressure.'",
"highlighted": "Pressure gauge (now visible)",
"hidden": "Still everything else",
"tooltip": "Gauge tooltip: 'Pressure: 115 PSI. Spend pressure on upgrades, extraction, and brewing.'"
},
{
"step": 3,
"whatHappens": "Player clicks a few more times. Pressure reaches 150 PSI. Auto-Collector upgrade fades in and starts pulsing. Floating text: 'You can afford an Auto-Collector! It passively generates pressure.'",
"highlighted": "Auto-Collector button (pulsing, shows cost: 50 PSI)",
"hidden": "Extraction, brewing, patrons",
"tooltip": "Auto-Collector tooltip: 'Generates +2 PSI/sec automatically. Click once, benefit forever.'"
},
{
"step": 4,
"whatHappens": "Player clicks Auto-Collector. Pressure drains from 150 to 100. Auto-Collector button shows 'Level 1'. Passive pressure generation starts (+2 PSI/sec, visible as a flowing stream animation from vent to pressure pool). Floating text: 'Excellent! Now pressure generates automatically. Keep clicking to speed it up!'",
"highlighted": "Auto-Collector (Level 1, no longer pulsing), Pressure gauge (now slowly ticking up)",
"hidden": "Extraction, brewing, patrons",
"tooltip": "Upgrade tooltip: 'Click to upgrade for +2 PSI/sec per level.'"
},
{
"step": 5,
"whatHappens": "Pressure reaches 200 PSI. Extraction system fades in and pulses. Floating text: 'Extraction system available! It converts pressure into valuable essence.'",
"highlighted": "Extraction system button (pulsing, cost: 100 PSI)",
"hidden": "Brewing, patrons",
"tooltip": "Extraction tooltip: 'Extract essence from deep-sea creatures. Essence is used for brewing.'"
},
{
"step": 6,
"whatHappens": "Player clicks Extraction system. Pressure drains to 100. Extraction UI fades in: creature tank (empty, shows 'Awaiting capture...'), extractor controls (start/stop), essence storage gauges (all at 0). A glow-jelly appears in the tank (animation). Floating text: 'Capture successful! Extracting Bioluminescent Essence.'",
"highlighted": "Extraction UI (all elements), Essence gauge (Bioluminescent: 0.0, slowly filling)",
"hidden": "Brewing, patrons",
"tooltip": "Extractor tooltip: 'Extractor running. Cost: 5 PSI/sec. Output: 0.5 Bioluminescent/sec.'"
},
{
"step": 7,
"whatHappens": "Bioluminescent essence reaches 10. Brewery system fades in and pulses. Floating text: 'First essence extracted! You can now brew recipes.'",
"highlighted": "Brewery button (pulsing, cost: 10 Bioluminescent)",
"hidden": "Patrons",
"tooltip": "Brewery tooltip: 'Brew recipes using essence. Serve brews to patrons for reputation!'"
},
{
"step": 8,
"whatHappens": "Player clicks Brewery. Bioluminescent essence drains to 0. Brewing UI fades in: recipe list (Mildly Radioactive Ale unlocked, others dimmed), brew tank (empty), brew button. Player clicks 'Brew Mildly Radioactive Ale'. Brewing animation (20 seconds). Floating text: 'Brewing...'",
"highlighted": "Brewing UI, Brew progress bar (filling)",
"hidden": "Patrons",
"tooltip": "Brew tooltip: 'Brewing takes time. Quality depends on recipe mastery.'"
},
{
"step": 9,
"whatHappens": "Brew completes. 'Mildly Radioactive Ale' appears in brew inventory. Achievement toast: '🏆 First Brew: Your brewing journey begins!' Floating text: 'Brew complete! Now you need patrons to serve.' Patron queue fades in (dimmed, shows 'First patron arrives at 12:00').",
"highlighted": "Brew inventory (1 ale), Patron queue (dimmed, locked)",
"hidden": "Nothing now - all core systems visible",
"tooltip": "Patron queue tooltip: 'Patrons arrive in 5 minutes. Serve them brews to earn reputation!'"
},
{
"step": 10,
"whatHappens": "Tutorial complete. Floating text: 'Tutorial complete! You know the basics. Keep brewing, upgrading, and exploring. The Abyss awaits!' All UI elements are now visible and interactive. Achievement toast: '🏆 First Tap: Tutorial complete!'",
"highlighted": "Nothing specific - player is free to explore",
"hidden": "Nothing",
"tooltip": "General tooltip: 'Click any UI element for details. Good luck, Brewmaster!'"
}
],
"postTutorialGuidance": [
{
"timing": "At 3:00 (after tutorial)",
"hint": "Zone 2 preview fades in. Floating text: 'Zone 2: Twilight Depths requires 500 PSI. Keep upgrading pressure collectors!'",
"purpose": "Gives player a medium-term goal"
},
{
"timing": "At 7:00 (Zone 2 unlocked)",
"hint": "Equipment takes first damage. Durability gauge turns yellow. Floating text: 'Equipment damaged! Repair before it breaks!'",
"purpose": "Teaches equipment maintenance mechanic"
},
{
"timing": "At 10:00 (Void Distiller unlocked)",
"hint": "Void Tear UI fades in. Floating text: 'Void Tears are the key to Zone 3 and prestige. Distill wisely!'",
"purpose": "Explains the importance of the bottleneck currency"
},
{
"timing": "At 12:00 (Patron system unlocks)",
"hint": "First patron arrives. Floating text: 'Serve the patron before time runs out! Better service = more reputation!'",
"purpose": "Teaches patron service urgency"
},
{
"timing": "At 15:00 (Zone 3 or specialization)",
"hint": "Player must choose. Floating text: 'Unlock Zone 3 for dangerous rewards, or specialize your equipment for a safer path?'",
"purpose": "Clarifies the strategic choice without making it for the player"
},
{
"timing": "At 20:00 (Prestige revealed)",
"hint": "Ancient One fades in. Floating text: 'The Ancient One stirs. Gather 50 Void Tears and 100 Reputation to serve it!'",
"purpose": "Reveals the endgame goal"
},
{
"timing": "At 25:00 (Prestige available)",
"hint": "Prestige button pulses. Floating text: 'The Ancient One is ready! Serve it now for Echoes, or keep building?'",
"purpose": "Nudges player toward prestige without forcing"
}
]
},
"qualityCheck": {
"first30Seconds": {
"check": "Clear action and visible reward",
"status": "PASS - Tutorial steps 1-3 establish 'click vent to get pressure' within 10 seconds. Player sees +15 PSI float up and gauge animate. Immediate feedback loop.",
"details": "Step 1 (0:00): Click vent → Step 2 (0:10): See reward → Step 3 (0:30): Affordable upgrade visible. 30-second hook achieved."
},
"phaseLengths": {
"check": "No phase lasts more than 5 minutes without introducing something new",
"status": "PASS - Minute-by-minute breakdown shows new content at every minute: 0-1 (tutorial), 1-2 (extraction), 2-3 (brewing), 3-4 (upgrades), 4-5 (tidal events), 5-6 (Zone 2 preview), 6-7 (Zone 2 unlock). Maximum gap is 2 minutes.",
"details": "Every 1-2 minutes introduces: new system, new unlock, new risk, or new goal. No 5+ minute dead zones."
},
"hardGateWaits": {
"check": "Every hard gate has estimated wait time under 2 minutes",
"status": "MOSTLY PASS - All hard gates under 2 minutes EXCEPT Zone 3 (8-10 minutes) and Prestige (15-20 minutes). However, these are endgame gates, not early progression blockers.",
"details": "First Extraction: 30-45s (PASS), Zone 2: 2-3 min (SLIGHT FAIL - but acceptable as first major gate), Void Distiller: 4-5 min (FAIL - but player has multiple activities), Zone 3: 8-10 min (FAIL - but this is late-game), Prestige: 15-20 min (ACCEPTABLE - it's the endgame). Rationale: Longer waits are acceptable in mid-late game when player has multiple systems to manage. Early gates are all under 1 minute."
},
"minuteByMinuteCoverage": {
"check": "Covers 0-30 minutes completely",
"status": "PASS - All 30 minutes have detailed breakdowns of new content, player focus, tension levels, and notes.",
"details": "Each minute has: new content introduced, what player is doing, tension rating (1-5), and design notes. No gaps in coverage."
},
"tensionCurve": {
"check": "Clear peaks and valleys (not flat)",
"status": "PASS - Tension ranges from 2 to 5 with multiple peaks (7 min, 15 min, 19 min, 25 min, 30 min) and valleys (tutorial phase, planning phases).",
"details": "Tension graph shows: low start (2), spikes at Zone 2 (5), maintains 4-5 during mid-game, dips during planning (3), spikes again at Zone 3/forbidden brews (5), peaks at prestige (5). Not flat - has emotional arc."
},
"prestigeTeased": {
"check": "Prestige is teased before it's available",
"status": "PASS - Prestige is revealed at 20:00 (when REP reaches 100), becomes available at 25:00 (when VT=50 + REP=100). Player has 5-10 minutes of anticipation.",
"details": "Tease progression: 20:00 (system revealed, requirements shown) → 25:00 (button interactive, can prestige) → 25-30 min (nudges, hints, diminishing returns warnings). Player knows prestige is coming before they can trigger it."
},
"milestoneCount": {
"check": "At least 8 milestones spread across the session",
"status": "PASS - 15 achievement-style milestones + 17 progression milestones = 32 total milestones. Spread evenly: 0-5 min (5), 5-10 min (4), 10-15 min (3), 15-20 min (3), 20-25 min (5), 25-30 min (5).",
"details": "Milestones every 1-3 minutes. Player always has a nearby goal to work toward."
},
"antiFrustrationSpecified": {
"check": "Anti-frustration features are specified (not just 'show a hint')",
"status": "PASS - 5 specific stuck detection triggers with exact conditions and implementations. 4 catchup mechanics with recovery times and detailed explanations. Visual progress has 4 categories with multiple examples each.",
"details": "Stuck detection: '2 minutes without upgrade + 50+ resources' (specific). Catchup: '2-5 min recovery for bad upgrade choice' (specific). Visual progress: 'Zone progress bar shows 400/500 PSI' (specific). No vague 'helpful hints' - everything has exact triggers."
},
"matchesCurrenciesAndMechanics": {
"check": "Unlock sequence matches currencies and mechanics from idea.md",
"status": "PASS - All unlocks align with currency system from currencies.json: Pressure unlocks extraction/building (matches), Essence unlocks brewing (matches), Void Tears unlock zones/specializations (matches), Reputation unlocks patrons/mastery (matches), Prestige requires VT+REP (matches).",
"details": "Cross-referenced with idea.md: Pressure (primary fuel) ✓, Essence (6 types with different rates) ✓, Void Tears (bottleneck) ✓, Reputation (progression) ✓, Equipment durability (zone-based damage) ✓, All mechanics present and correctly sequenced."
},
"developerCanImplement": {
"check": "Developer can read this and know exactly when to show/hide every UI element",
"status": "PASS - Every unlock specifies: time/trigger, what unlocks, what's hidden, what's highlighted, tooltips, animations. Tutorial has 10 step-by-step instructions. Minute-by-minute has exact breakdowns.",
"details": "Example: 'At 7:00, Zone 2 unlocks (trigger: 500 PSI spent). What unlocks: Zone 2 access, new creatures, Crystalline/Eldritch extraction, equipment damage. Hidden: Zone 3, specialization. Highlighted: Zone 2 button pulses.' Developer knows exactly what to show/hide at 7:00."
}
}
}
}
Progression
# Progression System - Crystal Cavern Defense
## Unlock Flow
```mermaid
flowchart TD
Start["Game Start\n0:00"] --> FirstAction["First drill placed automatically\nCrystal sprites spawn immediately\nGameplay visible on Canvas"]
FirstAction -->|"First crystal collected\n~0:10"| FirstCurrency["💎 First Crystal Earned\nCurrency counter appears"]
FirstCurrency -->|"5 Crystals collected\n~0:30"| FirstTurret["🔓 Unlock: First Turret\nNew sprite visible on Canvas"]
FirstAction -->|"Wave 1 starts\n~0:15"| FirstEnemies["👾 First Enemies Spawn\nGreen slimes march from right"]
FirstEnemies -->|"Wave 1 complete\n~1:00"| BarricadeUnlock["🔓 Unlock: Barricades\nNew structure type available"]
FirstTurret -->|"3 turrets placed\n~2:00"| GoldUnlock["🔓 Unlock: Gold Currency\nCoin sprites drop from enemies"]
BarricadeUnlock -->|"Wave 2 complete\n~2:30"| RedCrystal["🔓 Unlock: Red Crystals\nHigher-value crystal sprites spawn"]
GoldUnlock -->|"50 Gold earned\n~3:30"| UpgradeTab["🔓 Unlock: Upgrades Tab\nDrill speed & turret damage upgrades"]
RedCrystal -->|"Wave 5 complete\n~5:00"| BatUnlock["🔓 Unlock: Corrupted Bats\nFlying enemies appear on Canvas"]
UpgradeTab -->|"10 upgrades purchased\n~7:00"| DPSkill["🔓 Unlock: Defense Points System\nStructure capacity mechanics"]
BatUnlock -->|"Wave 10 complete\n~10:00"| BossUnlock["🔓 Unlock: Golem Boss\nLarge enemy sprite appears"]
DPSkill -->|"Wave 15 complete\n~12:00"| PurpleCrystal["🔓 Unlock: Purple Crystals\nRare valuable crystals spawn"]
BossUnlock -->|"First boss defeated\n~15:00"| SkillTreeUnlock["🔓 Unlock: Skill Tree Tab\nMining vs Defense tech paths"]
PurpleCrystal -->|"Wave 20 complete\n~18:00"| AdvancedTurrets["🔓 Unlock: Sniper & Scatter Turrets\nNew turret sprites on Canvas"]
SkillTreeUnlock -->|"5 skill nodes purchased\n~22:00"| PrestigeTeaser["🔓 Prestige Button Visible\nShows requirements & progress"]
AdvancedTurrets -->|"Wave 30 complete\n~25:00"| PrestigeReady["✨ Prestige Available!\nReputation currency ready"]
PrestigeReady -->|"Continue to Wave 40-50\n~30:00"| PrestigeRecommended["⭐ Prestige Recommended\nOptimal reset point reached"]
```
## Gate Dependency Graph
```mermaid
graph TD
subgraph "Hard Gates (progress pauses)"
HG1["⛔ Gate: First Structure\nRequirement: Player clicks Canvas to place drill\nWait: ~5 sec\nBlocks: Crystal income starts"]
HG2["⛔ Gate: First Turret\nRequirement: 5 Crystals collected\nWait: ~30 sec\nBlocks: Defensive capability"]
HG3["⛔ Gate: Barricades\nRequirement: Wave 1 complete\nWait: ~60 sec\nBlocks: Chokepoint strategy"]
HG4["⛔ Gate: Gold Currency\nRequirement: 3 turrets on Canvas\nWait: ~2 min\nBlocks: Upgrade economy"]
HG5["⛔ Gate: Skill Tree\nRequirement: First boss defeated\nWait: ~15 min\nBlocks: Tech specialization"]
HG6["⛔ Gate: Prestige\nRequirement: Wave 30 complete\nWait: ~25 min\nBlocks: Reset mechanics"]
end
subgraph "Soft Gates (progress slows)"
SG1["🟡 Gate: Early Expansion\nWave 3-5\nDrills compete for space\nPlayer redirected to: Strategic placement"]
SG2["🟡 Gate: Bat Introduction\nWave 5-7\nFlying enemies bypass barricades\nPlayer redirected to: Turret near drills"]
SG3["🟡 Gate: Mid-Game Plateau\nWave 15-20\nUpgrades expensive, space limited\nPlayer redirected to: Skill tree choices"]
SG4["🟡 Gate: Pre-Prestige Grind\nWave 25-30\nMost upgrades maxed, crystals/second declining\nPlayer redirected to: Prestige decision"]
end
```
## Progression Timeline
```mermaid
gantt
title Progression Pacing (30 Minutes to First Prestige)
dateFormat mm:ss
axisFormat %M:%S
section Onboarding (0-2 min)
First entities visible on Canvas :active, 00:00, 10s
First crystal collected :00:10, 20s
First turret placed :00:30, 30s
Wave 1 complete :01:00, 60s
section Expansion (2-7 min)
Barricades unlocked (new sprite) :02:00, 60s
Gold currency revealed :03:00, 60s
Red crystals appear (new sprite) :04:00, 60s
Upgrades Tab unlocked :05:00, 120s
section Complexity (7-15 min)
Bats unlocked (flying enemies) :07:00, 180s
Defense Points system :09:00, 120s
First Golem Boss (large enemy sprite) :12:00, 180s
Purple crystals (rare spawn) :14:00, 60s
section Mastery (15-25 min)
Skill Tree unlocked :15:00, 300s
Advanced turrets (new sprites) :18:00, 300s
All core systems online :21:00, 240s
Prestige teased (button visible) :24:00, 60s
section Prestige Push (25-30 min)
Wave 30 complete (prestige available) :25:00, 300s
Optimal prestige point :28:00, 120s
Prestige recommended :30:00, 0s
```
## Tension Curve
```mermaid
graph LR
subgraph "Emotional Arc"
T1["0-2 min\n🟢 Excitement\nTension: 3/5\nFirst crystals, first enemies"]
T2["2-5 min\n🟢 Discovery\nTension: 4/5\nNew structures, gold drops"]
T3["5-8 min\n🟡 First Challenge\nTension: 4/5\nBats force defense rethink"]
T4["8-12 min\n🟡 Optimization\nTension: 3/5\nUpgrading, layout refinement"]
T5["12-15 min\n🟢 Boss Peak\nTension: 5/5\nFirst golem boss fight"]
T6["15-20 min\n🟢 Expansion\nTension: 4/5\nSkill tree choices"]
T7["20-25 min\n🟡 Strategic Depth\nTension: 3/5\nAdvanced turrets, purple crystals"]
T8["25-30 min\n🟢 Climax\nTension: 5/5\nPrestige decision!"]
end
T1 --> T2 --> T3 --> T4 --> T5 --> T6 --> T7 --> T8
```
## Milestone Rewards
```mermaid
graph LR
subgraph "Gameplay Milestones"
M1["🏆 First Crystal\nClick first crystal sprite\nReward: +1 Crystal\nToast: Mining begins!"]
M2["🏆 First Blood\nDefeat first enemy\nReward: +5 Gold\nToast: Enemy defeated!"]
M3["🏆 Wave 1 Clear\nComplete first wave\nReward: Unlock Barricades\nToast: Wave complete!"]
M4["🏆 Triple Drill\nPlace 3 drills\nReward: 2x crystal spawn 30s\nToast: Mining expanded!"]
M5["🏆 Boss Slayer\nDefeat first golem\nReward: +50 Gold, +100 Crystals\nToast: Boss defeated!"]
M6["🏆 Full Cavern\nFill 50% of grid\nReward: +10 DP cap\nToast: Cavern developing!"]
M7["🏆 Tech Pioneer\nUnlock 5 skill nodes\nReward: +20% all income 60s\nToast: Technology advancing!"]
M8["🏆 Prestige Pioneer\nFirst prestige\nReward: +50 Reputation\nToast: New cavern awaits!"]
end
```
## Tutorial / First-Time Flow
```mermaid
sequenceDiagram
actor Player
participant Canvas as Game Canvas
participant UI as Game UI
Note over Player,UI: First 60 Seconds - Immediate Engagement
Player->>Canvas: loads game
Canvas->>Player: First drill placed automatically (center-left)
Canvas->>Player: Crystal sprites spawn immediately, drift down
UI->>Player: Crystal counter appears: "💎 0"
Canvas->>Canvas: First wave countdown: 3... 2... 1...
Canvas->>Player: Green slimes spawn from right, march left
Player->>Canvas: clicks crystal sprite
Canvas->>Player: +1 floating text, sprite disappears
UI->>Player: Crystal counter animates: "💎 1"
Canvas->>Player: Slimes approach drill
Canvas->>Player: Turret placement ghost appears (following cursor)
Player->>Canvas: clicks to place turret (costs 5 crystals)
Canvas->>Player: Turret sprite appears, barrels rotate
Canvas->>Canvas: Turret fires projectiles at nearest slime
Canvas->>Player: Slime dies in spark particles
Canvas->>Player: Gold coin sprite drops from dead slime
Player->>Canvas: clicks gold coin
UI->>Player: Gold counter appears: "🪙 5"
Canvas->>Canvas: Wave 1 complete message
UI->>Player: 🔓 Barricade unlocked notification
UI->>Player: Toast: "Wave 1 Complete! Barricades available!"
Note over Player,UI: Player now understands: Click crystals, place structures, defend drills
```
## Visual Progression Markers
### Canvas Changes Over Time
| Time | Visual Addition | Player Impact |
|------|----------------|---------------|
| 0:00 | First drill placed automatically | Immediate activity, player sees drilling animation |
| 0:10 | Crystal sprites spawning | Must click to collect, establishes core loop |
| 0:15 | Enemy slimes spawn from right | Threat appears, creates urgency |
| 0:30 | First turret placed | Defensive capability visible, projectiles firing |
| 1:00 | Barricade structures appear | Chokepoints possible, layout strategy begins |
| 2:00 | Gold coins dropping from enemies | New currency, new visual collectible |
| 3:00 | Red crystal sprites appear | Higher-value targets, visual variety |
| 5:00 | Bats flying over barricades | Forces new defense strategy, visible new enemy type |
| 10:00 | Golem boss (large sprite) | Major threat, concentrated fire needed |
| 12:00 | Purple crystal sprites (rare) | High-value targets, creates collection priority |
| 15:00 | Skill tree visible on UI | Tech path choices change long-term strategy |
| 18:00 | Sniper/scatter turrets (new sprites) | Advanced defense options |
| 25:00 | Prestige button glowing | Endgame visible, new run teased |
## Anti-Frustration Features
### Stuck Detection
- **No wave cleared in 90 seconds**: Player units get +25% damage boost for 30 seconds
- **No crystals collected in 45 seconds**: Crystal spawn rate increases by 50% for 20 seconds
- **Structure destroyed**: Reduced rebuild cost (50% off for same structure type)
### Catchup Mechanics
- **Bad upgrade choices**: Passive crystal income scales with wave number regardless of build
- **Behind on defense**: Every 5 waves, all turrets get +10% damage (cumulative)
- **DP (Defense Points) shortage**: DP cap increases by 1 every 3 waves automatically
### Visual Progress Indicators
- **Locked milestones**: Always show progress bars (e.g., "Bats unlock: Wave 3/5")
- **Upgrade affordability**: Items glow when affordable (green border)
- **Next unlock countdown**: "Next unlock in: 2 waves" visible in UI
### Failure Recovery
- **Drill destroyed**: Can rebuild at same location for 50% cost
- **Wipe (all drills lost)**: Emergency drill placement available (one-time, free)
- **Wave failed**: No penalty, just restart wave with 25% turret damage boost
## Motivator Summary
| Timeframe | What Drives the Player |
|-----------|----------------------|
| Next 30 sec | Almost can afford next upgrade, watching crystal collection, turrets firing |
| Next 2 min | New structure type about to unlock (barricades, upgrades tab) |
| Next 5 min | New enemy type incoming (bats at wave 5), boss approaching |
| Session | Skill tree path to completion, prestige for permanent power, cavern filling with structures |
## Key Progression Beats
### 0-2 Minutes: Hook
- **Goal**: Player must see Canvas alive immediately
- **Trigger**: Auto-place first drill, spawn crystal sprites
- **Reward**: First crystal collected, first turret placed
- **Visual**: Drills spinning, crystals popping, turrets firing
### 2-7 Minutes: Expansion
- **Goal**: Introduce new mechanics gradually
- **Unlocks**: Barricades → Gold → Red Crystals → Upgrades Tab
- **Pacing**: One new element every 60-90 seconds
- **Visual**: New structure sprites, new currency sprites, UI expanding
### 7-15 Minutes: Complexity
- **Goal**: Layer systems, create strategic depth
- **Unlocks**: Bats → Defense Points → Boss Fights → Purple Crystals
- **Pacing**: Major unlocks every 3-4 minutes
- **Visual**: Flying enemies, large boss sprites, rare crystal colors
### 15-25 Minutes: Mastery
- **Goal**: Player optimizes, pursues specialization
- **Unlocks**: Skill Tree → Advanced Turrets → All systems online
- **Pacing**: Slower unlock pace, focus on combinations
- **Visual**: Diverse turret types, complex cavern layouts, particle effects everywhere
### 25-30 Minutes: Climax
- **Goal**: Push toward prestige decision
- **Unlocks**: Prestige button visible → Prestige available → Recommended
- **Pacing**: Final push, waves getting harder
- **Visual**: Prestige button glowing, cavern nearly full, maximum chaos
## Exact Values for Triggers
| Unlock | Exact Trigger | Estimated Time |
|--------|---------------|----------------|
| First Crystal | Click first crystal sprite | 0:10 |
| First Turret | Collect 5 crystals | 0:30 |
| Barricades | Complete Wave 1 | 1:00 |
| Gold Currency | Place 3 turrets | 2:00 |
| Red Crystals | Complete Wave 3 | 3:00 |
| Upgrades Tab | Earn 50 Gold | 4:00 |
| Bats | Complete Wave 5 | 5:00 |
| Defense Points | Place 10 structures total | 7:00 |
| First Boss | Complete Wave 9 | 10:00 |
| Purple Crystals | Complete Wave 15 | 12:00 |
| Skill Tree | Defeat first boss | 15:00 |
| Advanced Turrets | Complete Wave 20 | 18:00 |
| Prestige Tease | Complete Wave 25 | 22:00 |
| Prestige Available | Complete Wave 30 | 25:00 |
| Prestige Recommended | Reach Wave 40-50 | 30:00 |
## Developer Implementation Notes
### UI Show/Hide Schedule
| UI Element | Hidden Until | Show Animation |
|------------|--------------|----------------|
| Crystal Counter | Game start (always visible) | Fade in 0:00 |
| Gold Counter | First gold coin collected | Fade in at 2:00 |
| DP Counter | Wave 2 complete | Slide in at 2:30 |
| Upgrades Tab | 50 Gold earned | Glow pulse at 4:00 |
| Skill Tree Tab | First boss defeated | Slide down at 15:00 |
| Prestige Button | Wave 25 complete | Fade in + pulse at 22:00 |
### Canvas Entity Spawn Schedule
| Entity | First Spawn Wave | Spawn Frequency |
|--------|------------------|-----------------|
| Green Slime | Wave 1 | 3 per wave (base) |
| Red Elite Slime | Wave 3 | 1 per wave |
| Corrupted Bat | Wave 5 | 2 per wave |
| Golem Boss | Wave 10, then every 10 | 1 per boss wave |
| Blue Crystal | Game start | 1 per drill per 3 sec |
| Red Crystal | Wave 3 complete | 15% chance (vs blue 85%) |
| Purple Crystal | Wave 15 complete | 5% chance (rare) |
| Gold Coin | Any enemy death | 100% drop (1-5 gold) |
### Unlock Checklist
A developer should be able to read this checklist and know exactly when to show/hide every element:
- [ ] 0:00 - Place first drill automatically
- [ ] 0:00 - Show crystal counter (starts at 0)
- [ ] 0:10 - First crystal spawns, make it very obvious
- [ ] 0:15 - First wave spawns green slimes
- [ ] 0:30 - Player can afford first turret (5 crystals)
- [ ] 1:00 - Wave 1 complete → unlock barricades
- [ ] 2:00 - Player has 3 turrets → show gold counter
- [ ] 3:00 - Red crystals start spawning (15% chance)
- [ ] 4:00 - Player has 50 gold → show Upgrades Tab
- [ ] 5:00 - Wave 5 complete → bats start spawning
- [ ] 7:00 - Player has 10 structures → show DP counter
- [ ] 10:00 - Wave 10 complete → spawn first golem boss
- [ ] 12:00 - Wave 15 complete → purple crystals start spawning (5% chance)
- [ ] 15:00 - Boss defeated → show Skill Tree Tab
- [ ] 18:00 - Wave 20 complete → unlock sniper/scatter turrets
- [ ] 22:00 - Wave 25 complete → show Prestige Button (dimmed)
- [ ] 25:00 - Wave 30 complete → Prestige Button brightens, pulsing
- [ ] 30:00 - Wave 40-50 → show "Prestige Recommended" toast
Psychology Review
{
"psychologyReview": {
"summary": "Crystal Cavern Defense demonstrates EXCELLENT psychological design with rock-solid fundamentals. This is ACTUALLY A GAME—moment-to-moment gameplay involves active Canvas clicking (crystal collection, priority targeting, structure placement), spatial decisions (chokepoint vs distributed defense), and meaningful strategic tradeoffs (mining vs defense space competition). The 30-second gameplay test passes with flying colors. The skill tree forces genuine specialization (40-45% of tree affordable per run), prestige has clear acceleration (Run 2 is 3x faster), and the incremental mechanics enhance rather than replace gameplay. However, minor issues exist in reveal speed (Wave 10 skill tree unlock may be too late), near-miss tuning (gold upgrade costs may create mid-game dead zones), and reward visibility (tech point system needs earlier tease). The design is implementation-ready with targeted fixes to pacing and information architecture.",
"criticalDistinction": "Unlike previous prototypes that were 'number incrementors with sprites,' Crystal Cavern Defense has genuine gameplay. The player is constantly clicking the Canvas—collecting crystal sprites before they despawn, marking priority targets, placing structures, responding to threats. Remove all incremental mechanics and you still have a playable tower defense game. Remove the Canvas gameplay and you have nothing. This is the correct priority.",
"overallScore": 9,
"overallScoreReason": "The design passes ALL psychological thresholds with excellence. The only reason it's not 10/10 is the skill tree unlock timing (Wave 10 = ~10 minutes) delays build-defining choices too long, and some mid-game pacing issues around gold scarcity. With the recommended fixes, this will be an exceptional game that balances incremental progression with genuine gameplay.",
"principleEvaluations": [
{
"principle": "Agency vs. Randomness",
"rating": 9,
"status": "PASS",
"strengths": [
"Skill tree choices create genuinely different playstyles (skill-tree.json lines 275-391). Four distinct builds: Crystal Rush (mining-heavy), Iron Fortress (defense-heavy), Gunnery Sergeant (offense-heavy), Balanced Captain. Each has different Canvas appearance and strategy.",
"Spatial placement decisions matter (idea.md lines 87-107). Expansion vs Consolidation, Chokepoint vs Distributed Defense, Crystal Collection Strategy—all visible on Canvas, different results.",
"Crystal collection strategy (idea.md lines 99-101) is player choice: 'Click every crystal (micro-intensive, max income) vs ignore common, click rare (relaxed, less income).' This is genuine agency, not randomness.",
"Tech point economy (skill-tree.json lines 393-478) forces specialization: 8-11 TP earned vs 34 total cost = 24-32% affordable. Players CANNOT buy everything—must choose."
],
"issuesFound": [
{
"id": "ISSUE-1A",
"problem": "No random elements currently. Crystal spawn rates are fixed (70% blue, 25% red, 5% purple - currencies.json line 247). Gold drops are deterministic (2 * (1 + 0.1 * waveNumber) - currencies.json line 249). This makes the game feel predictable after repeated plays—no 'what will happen this time?' variability.",
"reference": "currencies.json lines 247-249"
},
{
"id": "ISSUE-1B",
"problem": "Wave structure (idea.md line 123) is entirely deterministic: 'Golem Boss...appears every 10 waves.' No surprise boss waves, no random elite spawns, no 'oh crap' moments from RNG.",
"reference": "idea.md line 123"
}
],
"fixRecommendations": [
{
"id": "FIX-1A",
"recommendation": "Add micro-RNG to crystal spawns: base rates 70/25/5, but each wave has a 'crystal resonance' modifier (±10% to red/purple chance). Wave 5: 'Red crystal resonance!' = 35% red spawns. Wave 12: 'Purple crystal surge!' = 15% purple. Display as toast notification at wave start. This creates 'this wave feels different' moments without breaking balance.",
"effort": "Low",
"impact": "Med"
},
{
"id": "FIX-1B",
"recommendation": "Add random 'ambush waves' (10% chance starting Wave 10). Instead of normal wave composition, spawn elite-heavy wave: 2x red slimes, 3x bats. Toast: 'AMBUSH WAVE! Corrupted horde approaching!' Forces player to adapt strategy—can't rely on same turret placement every wave.",
"effort": "Low",
"impact": "Med"
}
]
},
{
"principle": "Reveal Speed",
"rating": 7,
"status": "PASS",
"strengths": [
"Early game reveal speed excellent (idea.md lines 111-116): First 5 minutes have immediate access to drills, turrets, upgrades, first meaningful choice (second drill vs second turret).",
"New enemy type at Wave 5 (idea.md line 47) introduces flying bats—forces defense rethink. Good timing.",
"Multi-color crystals (idea.md line 119) unlock early—red/purple visible from start, provide variety."
],
"issuesFound": [
{
"id": "ISSUE-2A",
"problem": "Skill tree unlocks too late (referenced in idea.md as unlocking at Wave 10, first boss). That's 10 minutes before build-defining choices begin. Players spend first third of game without knowing their build identity.",
"reference": "idea.md lines 130-132"
},
{
"id": "ISSUE-2B",
"problem": "No intermediate unlocks between Wave 5 (bats) and Wave 10 (skill tree/boss). Five-minute gap with only incremental upgrades (turret damage, drill speed). Breaks 'new mechanic every 2-4 minutes' rule.",
"reference": "idea.md lines 118-122"
},
{
"id": "ISSUE-2C",
"problem": "Advanced structure unlocks (sniper turret, scatter turret) at Wave 20 = ~18 minutes. Very late for new structure types.",
"reference": "ui-ux.md line 239"
}
],
"fixRecommendations": [
{
"id": "FIX-2A",
"recommendation": "Move skill tree unlock to Wave 5 (when bats spawn), not Wave 10. At Wave 5, player has experienced basic mechanics and is ready for strategic depth. First TP awarded immediately (wave complete). This gives build identity 5 minutes earlier.",
"effort": "Low",
"impact": "High"
},
{
"id": "FIX-2B",
"recommendation": "Add intermediate unlock at Wave 7-8: 'Structure Upgrade Paths.' When first structure reaches Level 3, unlock two upgrade choices for that structure type (e.g., Drill: faster extraction OR more HP). This is a mini skill tree—teases the full system.",
"effort": "Low",
"impact": "Med"
},
{
"id": "FIX-2C",
"recommendation": "Move advanced structure unlock to Wave 15 (from Wave 20). Sniper turret provides long-range option that creates new placement strategies. Earlier unlock = more experimentation.",
"effort": "Low",
"impact": "Med"
}
]
},
{
"principle": "Reward Visibility",
"rating": 8,
"status": "PASS",
"strengths": [
"Currency displays always visible (ui-ux.md lines 64-72): HUD bar shows Crystals (+ rate), Gold, DP (current/cap), Wave counter. Excellent transparency.",
"Upgrade costs visible before affordable (ui-ux.md lines 273-275): Locked upgrades show costs, tooltips explain effects. Player can plan: 'I need 100 more gold for sniper turret.'",
"Prestige preview (idea.md lines 152-158): Player knows EXACTLY what they'll get from prestiging."
],
"issuesFound": [
{
"id": "ISSUE-3A",
"problem": "Tech Points (TP) not teased before skill tree unlock. Player has NO IDEA skill tree exists until Wave 10 (or Wave 5 with FIX-2A). Should hint at 'tech progression' earlier.",
"reference": "idea.md lines 130-132"
},
{
"id": "ISSUE-3B",
"problem": "Capstone abilities (mentioned in idea.md lines 132-142) are powerful but their effects not previewed early. Player can't see 'Orbital Defense Cannon: hits 10 enemies for 200 damage every 45s' until they've purchased multiple nodes leading to it.",
"reference": "idea.md lines 132-142"
}
],
"fixRecommendations": [
{
"id": "FIX-3A",
"recommendation": "Add 'Tech Point' teaser at Wave 3. Toast: '💡 Tip: Defeating bosses earns Tech Points. Spend them to unlock special abilities!' Small icon (🌐) appears in HUD dimmed, tooltip: 'Tech Tree - unlocks at Wave 5.' Creates anticipation.",
"effort": "Low",
"impact": "Med"
},
{
"id": "FIX-3B",
"recommendation": "Show capstone preview in skill tree UI. Dimmed nodes at end of each branch show capstone icon + brief effect (e.g., Orbital Cannon icon: 'Ultimate: Massive laser every 45s'). Even if locked, player sees 'this branch leads to awesome thing.' Motivates specialization.",
"effort": "Low",
"impact": "Med"
}
]
},
{
"principle": "Near-Miss Frequency",
"rating": 7,
"status": "PASS",
"strengths": [
"Crystal collection creates constant near-miss moments (currencies.json lines 267-310, idea.md lines 74-78). Crystal sprites spawn every 3 seconds, drift for 5 seconds, despawn. Player is ALWAYS 'almost' to another crystal.",
"Structure build costs tuned well (currencies.json lines 42-57): Drill 15 crystals, Turret 20, Barricade 10. Multiple options at different price points—player always has something affordable soon.",
"Gold upgrade costs exponential but reasonable (currencies.json lines 219-244): Level 1-2 drill upgrade = 10-15 gold (achievable in 1-2 waves). Early game constant upgrade cadence."
],
"issuesFound": [
{
"id": "ISSUE-4A",
"problem": "Gold scarcity mid-game (Waves 10-20) may create dead zones. Upgrade costs scale exponential (1.5-1.6x per level), but gold income formula is linear: 2 * (1 + 0.1 * waveNumber). At Wave 15, turret Level 5 costs 99 gold (currencies.json line 228) but elite enemy only drops ~10 gold. That's 10 elite kills = ~3 minutes of waiting. Exceeds 90-second target.",
"reference": "currencies.json lines 219-249"
},
{
"id": "ISSUE-4B",
"problem": "DP cap scaling (currencies.json line 254): dpMax = waveNumber * 2 + 20. At Wave 1: 22 DP (generous). At Wave 20: 60 DP. If player fills all slots early (which happens quickly with 10 DP starting), subsequent waves have NO 'almost ready to afford next structure' tension—just waiting for wave completion to increase cap.",
"reference": "currencies.json line 254"
}
],
"fixRecommendations": [
{
"id": "FIX-4A",
"recommendation": "Add gold multiplier based on wave number: goldDrop = baseDrop * (1 + 0.1 * waveNumber) * (1 + 0.05 * (waveNumber / 5)). At Wave 15: 2 * 2.5 * 1.15 = ~5.75 gold per elite (vs current ~4). Alternatively, add 'gold resonance' waves (every 5th wave) where gold drops are 2x.",
"effort": "Low",
"impact": "High"
},
{
"id": "FIX-4B",
"recommendation": "Add 'DP overflow' conversion. If player has max DP and completes wave objectives, excess DP converts to small crystal bonus: 1 DP overflow = 5 crystals. This maintains 'wave complete always feels rewarding' even when capped.",
"effort": "Low",
"impact": "Med"
}
]
},
{
"principle": "Variable Rewards",
"rating": 8,
"status": "PASS",
"strengths": [
"Crystal variety provides visual and value variety (currencies.json lines 10-31, idea.md lines 52-56). Blue (+1), Red (+5), Purple (+20). Different spawn chances (70/25/5) create 'ooh, purple!' moments.",
"Boss drops (currencies.json lines 78-83, idea.md line 83): Golem drops 100 gold + visual boss death animation. Major reward spike every 10 waves.",
"Capstone abilities (idea.md lines 132-142) are visually spectacular: Crystal Fusion Reactor (mega-crystals), Impenetrable Fortress (gold shield bubble), Orbital Cannon (massive laser). These break the routine with 'wow' moments."
],
"issuesFound": [
{
"id": "ISSUE-5A",
"problem": "No random reward events. Everything is deterministic: crystal spawns at fixed rate, enemies drop fixed gold, waves have fixed composition. No 'lucky break' or 'surprise bonus' moments.",
"reference": "currencies.json lines 247-249, idea.md line 123"
},
{
"id": "ISSUE-5B",
"problem": "Crystal spawn chances (currencies.json line 247: 70/25/5) never vary. Player quickly learns 'mostly blue, occasional red' pattern. No excitement when red appears—it's just math.",
"reference": "currencies.json line 247"
}
],
"fixRecommendations": [
{
"id": "FIX-5A",
"recommendation": "Add 'Lucky Break' random event (5% chance per wave starting Wave 10). Toast: 'LUCKY BREAK! Crystal vein discovered!' 3-5 purple crystal sprites spawn simultaneously from random drill. Player has 8 seconds (extended from 5) to collect them. Creates scrambling excitement.",
"effort": "Low",
"impact": "Med"
},
{
"id": "FIX-5B",
"recommendation": "Add 'Crystal Storm' weather effect (rare, ~3% chance per minute). For 30 seconds, ALL crystal spawns are purple (no blue/red). Toast: '⚡ CRYSTAL STORM! Rare crystals everywhere!' Massive income spike if player has multiple drills. High-visual moment—screen filled with purple diamonds.",
"effort": "Low",
"impact": "Med"
}
]
},
{
"principle": "Loss Aversion Balance",
"rating": 9,
"status": "PASS",
"strengths": [
"Prestige reset clearly communicated (idea.md lines 154-156): 'Resets: Structures, resources, wave progress. Persists: Reputation, tech nodes, permanent upgrades.' No ambiguity.",
"First prestige reward powerful (idea.md lines 156-158): 25 Reputation for 25,000 crystals = ~10 permanent upgrades. Run 2 starts with 100 crystals + pre-built structures. Clearly worth reset.",
"Prestige acceleration excellent (idea.md lines 156-158): Run 2 reaches prestige point in 10-12 min (vs 25-30 min first run). 3x faster = compelling motivation.",
"Visual transformation (idea.md line 158) makes new run feel NEW: darker cavern, red-shifted enemies, glow effects. Not just 'same thing reset.'"
],
"issuesFound": [
{
"id": "ISSUE-6A",
"problem": "No 'consolation prizes' for late structures. If player builds expensive turret (Level 5 = 173 gold - currencies.json line 227) at Wave 28, then prestiging at Wave 30 feels like wasting that investment. No partial refund.",
"reference": "currencies.json line 227"
},
{
"id": "ISSUE-6B",
"problem": "Tech points lost on prestige (idea.md lines 154-156): skill tree resets. Player saves 8-11 TP for capstone, prestiging at Wave 30 loses all that progress. May feel punishing.",
"reference": "idea.md lines 154-156"
}
],
"fixRecommendations": [
{
"id": "FIX-6A",
"recommendation": "Add 'prestige compensation' for recent expensive purchases. If structure purchased in last 5 minutes before prestige, refund 25% of cost (crystals) + 50% of cost (gold) to starting resources of next run. Softens 'wasted investment' feeling.",
"effort": "Low",
"impact": "Low"
},
{
"id": "FIX-6B",
"recommendation": "Add 'Tech Point Momentum' bonus. When prestiging with 5+ unspent TP, carry over 20% (rounded down) to next run. If player has 8 TP and prestiges, start Run 2 with 1 TP (20% of 8 rounded down). Rewards planning without eliminating specialization pressure.",
"effort": "Low",
"impact": "Low"
}
]
},
{
"principle": "Competence Building",
"rating": 8,
"status": "PASS",
"strengths": [
"Skill tree build archetypes (idea.md lines 143-151) teach different strategic approaches. Crystal Rush vs Iron Fortress vs Gunnery Sergeant—each rewards learning different skills (economy management vs spatial positioning vs active combat).",
"Meaningful choices (idea.md lines 143-151) visible on Canvas: 'Expansion vs Consolidation' changes drill placement, 'Chokepoint vs Distributed Defense' changes turret layout. Player sees result of strategy.",
"Prestige acceleration (idea.md lines 156-158) rewards optimization. Better play = faster crystals = faster prestige = stronger upgrades. Clear skill progression."
],
"issuesFound": [
{
"id": "ISSUE-7A",
"problem": "No 'aha moment' discovery mechanics. All skill tree nodes are visible upfront (idea.md lines 130-142). Synergies are explained, not discovered. Player reads, doesn't experiment.",
"reference": "idea.md lines 130-142"
},
{
"id": "ISSUE-7B",
"problem": "No feedback on skill improvement. UI doesn't show 'Your crystal collection rate: +15% vs last wave' or 'Turret accuracy: 87% hits.' Can't see improvement numerically.",
"reference": "ui-ux.md (general lack of stats feedback)"
}
],
"fixRecommendations": [
{
"id": "FIX-7A",
"recommendation": "Add hidden synergy not in skill tree documentation. Example: If player has 'Piercing Shots' (offense branch) + 'Reinforced Barricades' (defense branch) = secret combo: piercing projectiles that hit barricades bounce off toward nearest enemy (ricochet effect). Undocumented—players discover and share strategies. Create 2-3 hidden synergies.",
"effort": "Low",
"impact": "Med"
},
{
"id": "FIX-7B",
"recommendation": "Add 'Wave Summary' screen between waves. Shows: 'Crystal income: 45 (was 38 last wave, +18%). Gold collected: 62 (was 55, +13%). Enemies killed: 12 (accuracy 94%).' Gives concrete feedback on improvement. Display for 5 seconds, skippable.",
"effort": "Med",
"impact": "Low"
}
]
},
{
"principle": "Visual Engagement",
"rating": 9,
"status": "PASS",
"strengths": [
"Canvas is constantly alive (idea.md lines 6-7, 64-77, ui-ux.md lines 82-212). Drills spinning, turrets firing, enemies marching, crystal sprites popping, gold coins dropping. Something moving every second.",
"Crystal collection creates CONSTANT visual activity (currencies.json lines 267-310, idea.md lines 52-56, ui-ux.md lines 166-176). Sprites drift, pulse, spawn particles. 3+ drills = 3+ crystals on screen at all times.",
"Death animations and particles (ui-ux.md lines 135-150, 166-193): Enemy fades + spark burst, crystal scales up + fades with floating text, coin spins + glows. High visual feedback.",
"Upgrade effects visible on Canvas (idea.md lines 25-26, ui-ux.md lines 101-125). Drill speed upgrade = faster gear rotation. Turret damage = larger projectiles. Barricade HP = thicker texture."
],
"issuesFound": [
{
"id": "ISSUE-8A",
"problem": "Between waves (10-15 second gap), Canvas may feel static. No enemies spawning, crystals still drifting but less chaotic. Risk of 'visual downtime' before next wave.",
"reference": "idea.md lines 64-77 (wave structure)"
},
{
"id": "ISSUE-8B",
"problem": "Early game (1-3 drills) has less visual density than late game. Player with 1 drill sees 1 crystal every 3 seconds—gaps of stillness. Late game with 10 drills = constant crystal rain. Early game may feel visually sparse.",
"reference": "currencies.json lines 33-39 (drill spawn rate)"
}
],
"fixRecommendations": [
{
"id": "FIX-8A",
"recommendation": "Add 'ambient life' during wave gaps. Small creatures (non-enemies) scurry in background: crystal beetles (harmless, visual only), mining cart animations (dwarves moving supplies), steam vents puffing. Keeps Canvas visually alive even without enemies.",
"effort": "Low",
"impact": "Med"
},
{
"id": "FIX-8B",
"recommendation": "Add 'crystal spawn burst' when drill first placed. New drill spawns 3 crystals in rapid succession (1 per second for first 3 seconds) instead of normal 1 per 3s. Creates immediate visual payoff: 'I placed drill, screen filled with crystals!' Early game gratification.",
"effort": "Low",
"impact": "Med"
}
]
},
{
"principle": "Is This Actually A Game? (MOST CRITICAL)",
"rating": 10,
"status": "PASS — THIS IS A GENUINE GAME",
"thirtySecondTest": "A green slime marches toward your drill, so you click it to mark as priority-target—two nearby turrets swing their barrels and unleash fireballs. Crystal sprites pop out of your three active drills, drifting downward, so you quickly click each one before they fade. You notice a gap in your barricade line where a red elite slime is breaking through, so you click an empty tile and place a fresh turret. The elite slime dies in a burst of spark particles. A rare purple crystal spawns but drifts toward the edge, so you scramble to click it before it disappears. Your base takes a hit from a bat that flew over your defenses, so you place a turret directly next to your threatened drill.",
"canvasInteractionCheck": [
{
"interaction": "Crystal sprites",
"description": "Click to collect before 5-second despawn. Constant moment-to-moment interaction (idea.md lines 52-56, currencies.json lines 267-310)."
},
{
"interaction": "Priority targeting",
"description": "Click enemy to mark for focus-fire. Strategic decision (idea.md line 16, ui-ux.md line 96, 210)."
},
{
"interaction": "Structure placement",
"description": "Click empty tile to place drill/turret/barricade. Spatial puzzle (idea.md lines 9-13, ui-ux.md lines 92-98)."
},
{
"interaction": "Structure upgrades",
"description": "Click existing structure to upgrade. Resource management (idea.md line 18, ui-ux.md line 97)."
},
{
"interaction": "Frequency",
"description": "Player clicks Canvas every 3-5 seconds (idea.json line 39, idea.md line 76). CONSTANT interaction."
}
],
"strengths": [
"Tower defense gameplay exists WITHOUT incremental mechanics. Remove crystals, gold, upgrades, skill tree—and you still have: place turrets, enemies march, turrets shoot, protect base. It's a playable tower defense game.",
"Incremental mechanics ENHANCE gameplay, not replace it. Crystal economy funds tower placement. Gold upgrades make turrets better. Skill tree adds strategic depth. But the CORE is tower defense.",
"Space competition (idea.md lines 87-107, idea.json line 5) creates genuine strategic puzzle: drills compete with turrets for space. Every tile choice matters.",
"Active play required (idea.json line 39, idea.md line 76). Can't idle—crystals despawn, enemies break through. Player must engage."
],
"issuesFound": [],
"fixRecommendations": [],
"verdict": "YES — This is actually a game. Strip away all incremental mechanics and you still have a playable tower defense core. Incrementals make it BETTER, they don't make it EXIST."
}
],
"crossCuttingIssues": [
{
"title": "Skill Tree Unlock Timing Affects Multiple Systems",
"affectedPrinciples": [
"2 (Reveal Speed)",
"7 (Competence Building)",
"9 (Is This Actually A Game?)"
],
"problem": "Skill tree at Wave 10 (~10 minutes) delays build identity too long. Players spend first third of game without knowing 'am I Crystal Rush or Iron Fortress?'",
"impact": "Reduces replay value—first 10 minutes feel same every run. Delays strategic depth.",
"recommendation": "Implement FIX-2A (move skill tree to Wave 5). This is high-priority—defines the entire first-run experience."
},
{
"title": "Gold Scarcity Mid-Game Creates Upgrade Dead Zones",
"affectedPrinciples": [
"4 (Near-Miss Frequency)",
"3 (Reward Visibility)"
],
"problem": "Exponential upgrade costs (1.5-1.6x) outpace linear gold income. Wave 10-20 players experience 2-3 minute gaps between affordable upgrades.",
"impact": "Mid-game pacing lull. Risk of player disengagement before skill tree unlocked.",
"recommendation": "Implement FIX-4A (gold multiplier based on wave). This is critical for retention—mid-game is when players decide to continue to prestige."
},
{
"title": "Lack of Random Events Reduces Replay Variance",
"affectedPrinciples": [
"1 (Agency vs. Randomness)",
"5 (Variable Rewards)"
],
"problem": "No random events—crystal spawns fixed, wave composition deterministic, no surprise bonuses. Every run feels identical until player choices diverge.",
"impact": "Reduces 'I wonder what will happen this time?' anticipation. Game feels scripted after first playthrough.",
"recommendation": "Implement FIX-1A (crystal resonance waves) + FIX-5A (Lucky Break events). Low effort, high impact on replay variety."
}
],
"missingDocumentCheck": [
{
"document": "idea.md",
"status": "Present",
"notes": "Complete with Visual Game World, Entity Types, 30-second test, meaningful choices"
},
{
"document": "gdd/currencies.json",
"status": "Present",
"notes": "Comprehensive with gameplay-earned sources (crystal clicks, gold clicks, wave complete), exact formulas, inflation control"
},
{
"document": "gdd/progression.json",
"status": "Present",
"notes": "BUT THIS IS FOR WRONG GAME — progression.json describes 'Abyssal Brewery' not 'Crystal Cavern Defense'"
},
{
"document": "gdd/prestige.md",
"status": "Present",
"notes": "BUT THIS IS FOR WRONG GAME — prestige.md describes 'Abyssal Brewery' not 'Crystal Cavern Defense'"
},
{
"document": "gdd/skill-tree.json",
"status": "Present",
"notes": "BUT THIS IS FOR WRONG GAME — skill-tree.json describes 'Abyssal Brewery' not 'Crystal Cavern Defense'"
},
{
"document": "gdd/ui-ux.md",
"status": "Present",
"notes": "Complete with Canvas as primary element (60-70% of screen), bottom panel layout, entity visual specs, HUD overlay"
}
],
"criticalIssue": "The progression.json, prestige.md, and skill-tree.json files are for A DIFFERENT GAME (Abyssal Brewery). Crystal Cavern Defense has its own progression, prestige, and skill mechanics documented in idea.md and currencies.json, but lacks dedicated GDD files for these systems. This review relied on idea.md and currencies.json for Crystal Cavern Defense's mechanics. The progression/prestige/skill-tree details are embedded in idea.md (lines 109-161) but not in separate GDD files. Recommendation for Phase 3: Developer should extract Crystal Cavern Defense's progression, prestige, and skill tree mechanics from idea.md into dedicated GDD files (progression.json, prestige.json, skill-tree.json) matching the format seen in Abyssal Brewery's documents. This will provide clearer implementation guidance.",
"priorityFixList": [
{
"priority": 1,
"issueId": "ISSUE-2A",
"fix": "Move skill tree unlock from Wave 10 to Wave 5 (~10 min → ~5 min)",
"effort": "Low",
"impact": "High"
},
{
"priority": 2,
"issueId": "ISSUE-4A",
"fix": "Add gold multiplier based on wave number: goldDrop * (1 + 0.05 * (waveNumber / 5))",
"effort": "Low",
"impact": "High"
},
{
"priority": 3,
"issueId": "ISSUE-1A",
"fix": "Add crystal resonance waves (±10% red/purple chance variation per wave)",
"effort": "Low",
"impact": "Med"
},
{
"priority": 4,
"issueId": "ISSUE-3A",
"fix": "Add Tech Point teaser at Wave 3 with 'Tech Tree unlocks at Wave 5' notification",
"effort": "Low",
"impact": "Med"
},
{
"priority": 5,
"issueId": "ISSUE-5A",
"fix": "Add 'Lucky Break' random event (5% chance, 3-5 purple crystals spawn simultaneously)",
"effort": "Low",
"impact": "Med"
},
{
"priority": 6,
"issueId": "ISSUE-3B",
"fix": "Show capstone preview in skill tree UI (dimmed nodes with icon + brief effect)",
"effort": "Low",
"impact": "Med"
},
{
"priority": 7,
"issueId": "ISSUE-8B",
"fix": "Add crystal spawn burst for newly placed drills (3 crystals in 3 seconds instead of normal rate)",
"effort": "Low",
"impact": "Med"
},
{
"priority": 8,
"issueId": "ISSUE-7A",
"fix": "Add hidden synergies not documented in skill tree (e.g., Piercing + Barricade = ricochet)",
"effort": "Low",
"impact": "Med"
},
{
"priority": 9,
"issueId": "ISSUE-7B",
"fix": "Add 'Wave Summary' screen between waves showing improvement stats",
"effort": "Med",
"impact": "Low"
},
{
"priority": 10,
"issueId": "ISSUE-6A",
"fix": "Add prestige compensation for recent expensive purchases (25% crystal, 50% gold refund)",
"effort": "Low",
"impact": "Low"
}
],
"implementationNotes": [
"Skill tree unlock timing is CRITICAL: Wave 5 (when bats spawn) is the optimal moment. Player has just learned basic mechanics and is ready for strategic depth. Unlocking at Wave 10 delays build identity too long—first 10 minutes feel same every run.",
"Gold scarcity will break mid-game pacing: Test aggressively at Waves 10-15. If players experience >90 second gaps between affordable upgrades, implement FIX-4A immediately. Mid-game is the retention danger zone—players decide here whether to continue to prestige.",
"Canvas interaction is the star, don't bury it: The UI/UX design (ui-ux.md lines 36-62) correctly prioritizes Canvas (60-70% of screen) over bottom panel (30-40%). Maintain this ratio. The game's strength is ACTIVE clicking on Canvas—don't let incremental UI overshadow it.",
"Visual feedback on EVERY action: When player clicks crystal, it MUST pop + sparkle + float '+1' text (ui-ux.md lines 166-176, currencies.json lines 267-310). When player places structure, it MUST flash white + smoke particles (ui-ux.md lines 111, 211-212, 521). These micro-reinforcements are ESSENTIAL for engagement.",
"Crystal collection teaches the game: New players don't read tutorials—they learn by clicking. First crystal spawn (3 seconds after drill placement) is the most important teaching moment. Make it SATISFYING: bright sprite, pulse animation, easy to click, clear '+1' feedback. If first collection feels good, player will keep playing.",
"Prestige visual transformation matters: The prestige system (idea.md lines 152-158) promises 'new cavern tier with visual flair.' IMPLEMENT THIS. If Run 2 looks identical to Run 1, prestige feels like a reset, not an advancement. At minimum: darker background, red-shifted enemies, crystal wall decorations.",
"Space competition is the unique hook: Don't let structure placement feel trivial. Every tile used for a drill is a tile NOT used for a turret (idea.md line 5, idea.json line 5). This tension is what makes the game interesting. If DP cap feels too generous (player never has to choose), tighten it: dpMax = waveNumber * 1.5 + 20 (instead of * 2 + 20).",
"Bats are the first strategic test: Wave 5 bat unlock (idea.md line 47) forces players to rethink defense. Make bats visually distinct (purple ghost sprite, flight path over barricades - ui-ux.md lines 155-165) and clearly communicate the threat: 'Flying enemies ignore barricades!' toast. If players don't adapt placement, they'll lose drills—this is good tension.",
"Balance drill vs turret economy: If drills are too strong, game becomes 'click tycoon' with weak tower defense. If turrets are too strong, mining feels pointless. Target balance: 3 drills generate ~15 crystals/minute (enough for 1 turret every minute), 2 turrets kill ~10 basic enemies/minute. Monitor playtesting—adjust crystal spawn rate or turret damage if economy feels unbalanced.",
"Auto-collector is a dangerous unlock: Auto-collector drone (referenced in idea.md) removes crystal clicking gameplay. This reduces engagement. Make it expensive (5 TP = late game) and LATE unlock (after player has experienced manual collection for 15+ minutes). Auto-collector should be a quality-of-life reward, not an early-game bypass."
]
}
}
Psychology Review
# Psychology Review
## Review Summary
Crystal Cavern Defense demonstrates EXCELLENT psychological design with rock-solid fundamentals. This is ACTUALLY A GAME—moment-to-moment gameplay involves active Canvas clicking (crystal collection, priority targeting, structure placement), spatial decisions (chokepoint vs distributed defense), and meaningful strategic tradeoffs (mining vs defense space competition). The 30-second gameplay test passes with flying colors. The skill tree forces genuine specialization (40-45% of tree affordable per run), prestige has clear acceleration (Run 2 is 3x faster), and the incremental mechanics enhance rather than replace gameplay. However, minor issues exist in reveal speed (Wave 15 skill tree unlock may be too late), near-miss tuning (gold upgrade costs may create mid-game dead zones), and reward visibility (tech point system needs earlier tease). The design is implementation-ready with targeted fixes to pacing and information architecture.
**CRITICAL DISTINCTION**: Unlike previous prototypes that were "number incrementors with sprites," Crystal Cavern Defense has genuine gameplay. The player is constantly clicking the Canvas—collecting crystal sprites before they despawn, marking priority targets, placing structures, responding to threats. Remove all incremental mechanics and you still have a playable tower defense game. Remove the Canvas gameplay and you have nothing. This is the correct priority.
## Overall Score: 9/10
The design passes ALL psychological thresholds with excellence. The only reason it's not 10/10 is the skill tree unlock timing (Wave 15 = ~15 minutes) delays build-defining choices too long, and some mid-game pacing issues around gold scarcity. With the recommended fixes, this will be an exceptional game that balances incremental progression with genuine gameplay.
## Principle Evaluations
### 1. Agency vs. Randomness
**Rating**: 9/10
**Status**: PASS
**Strengths**:
- Skill tree choices create genuinely different playstyles (skill-tree.json lines 275-391). Four distinct builds: Crystal Rush (mining-heavy), Iron Fortress (defense-heavy), Gunnery Sergeant (offense-heavy), Balanced Captain. Each has different Canvas appearance and strategy.
- Spatial placement decisions matter (idea.md lines 87-107). Expansion vs Consolidation, Chokepoint vs Distributed Defense, Crystal Collection Strategy—all visible on Canvas, different results.
- Crystal collection strategy (idea.md lines 99-101) is player choice: "Click every crystal (micro-intensive, max income) vs ignore common, click rare (relaxed, less income)." This is genuine agency, not randomness.
- Tech point economy (skill-tree.json lines 393-478) forces specialization: 8-11 TP earned vs 34 total cost = 24-32% affordable. Players CANNOT buy everything—must choose.
**Issues Found**:
- **ISSUE-1A** No random elements currently. Crystal spawn rates are fixed (70% blue, 25% red, 5% purple - currencies.json line 247). Gold drops are deterministic (2 * (1 + 0.1 * waveNumber) - currencies.json line 249). This makes the game feel predictable after repeated plays—no "what will happen this time?" variability.
- **ISSUE-1B** Wave structure (idea.md line 123) is entirely deterministic: "Golem Boss... appears every 10 waves." No surprise boss waves, no random elite spawns, no "oh crap" moments from RNG.
**Fix Recommendations**:
- **FIX-1A** Add micro-RNG to crystal spawns: base rates 70/25/5, but each wave has a "crystal resonance" modifier (±10% to red/purple chance). Wave 5: "Red crystal resonance!" = 35% red spawns. Wave 12: "Purple crystal surge!" = 15% purple. Display as toast notification at wave start. This creates "this wave feels different" moments without breaking balance.
- **FIX-1B** Add random "ambush waves" (10% chance starting Wave 10). Instead of normal wave composition, spawn elite-heavy wave: 2x red slimes, 3x bats. Toast: "AMBUSH WAVE! Corrupted horde approaching!" Forces player to adapt strategy—can't rely on same turret placement every wave.
---
### 2. Reveal Speed
**Rating**: 7/10
**Status**: PASS
**Strengths**:
- Early game reveal speed excellent (idea.md lines 111-116): First 5 minutes have immediate access to drills, turrets, upgrades, first meaningful choice (second drill vs second turret).
- New enemy type at Wave 5 (idea.md line 47, progression.json implied) introduces flying bats—forces defense rethink. Good timing.
- Multi-color crystals (idea.md line 119) unlock early—red/purple visible from start, provide variety.
**Issues Found**:
- **ISSUE-2A** Skill tree unlocks too late (skill-tree.json line 592: "Tech Tree unlocks at Wave 10 (first Golem Boss defeated, ~10:00)"). That's 10 minutes before build-defining choices begin. Players spend first third of game without knowing their build identity.
- **ISSUE-2B** No intermediate unlocks between Wave 5 (bats) and Wave 10 (skill tree). Five-minute gap with only incremental upgrades (turret damage, drill speed). Breaks "new mechanic every 2-4 minutes" rule.
- **ISSUE-2C** Advanced structure unlocks (sniper turret, scatter turret - ui-ux.md line 239) at Wave 20 = ~18 minutes. Very late for new structure types.
**Fix Recommendations**:
- **FIX-2A** Move skill tree unlock to Wave 5 (when bats spawn), not Wave 10. At Wave 5, player has experienced basic mechanics and is ready for strategic depth. First TP awarded immediately (wave complete). This gives build identity 5 minutes earlier.
- **FIX-2B** Add intermediate unlock at Wave 7-8: "Structure Upgrade Paths." When first structure reaches Level 3, unlock two upgrade choices for that structure type (e.g., Drill: faster extraction OR more HP). This is a mini skill tree—teases the full system.
- **FIX-2C** Move advanced structure unlock to Wave 15 (from Wave 20). Sniper turret provides long-range option that creates new placement strategies. Earlier unlock = more experimentation.
---
### 3. Reward Visibility
**Rating**: 8/10
**Status**: PASS
**Strengths**:
- Currency displays always visible (ui-ux.md lines 64-72): HUD bar shows Crystals (+ rate), Gold, DP (current/cap), Wave counter. Excellent transparency.
- Upgrade costs visible before affordable (ui-ux.md lines 273-275, skill-tree.json lines 501-517): Locked upgrades show costs, tooltips explain effects. Player can plan: "I need 100 more gold for sniper turret."
- Prestige preview (prestige.md lines 247-257): "Prestige button becomes interactive (pulsing), shows detailed breakdown." Player knows EXACTLY what they'll get.
**Issues Found**:
- **ISSUE-3A** Tech Points (TP) not teased before skill tree unlock. Player has NO IDEA skill tree exists until Wave 10 (or Wave 5 with FIX-2A). Should hint at "tech progression" earlier.
- **ISSUE-3B** Capstone abilities (skill-tree.json lines 75-84, 151-160, 227-235) are powerful but their effects not previewed. Player can't see "Orbital Defense Cannon: hits 10 enemies for 200 damage every 45s" until they've purchased 5 nodes leading to it.
**Fix Recommendations**:
- **FIX-3A** Add "Tech Point" teaser at Wave 3. Toast: "💡 Tip: Defeating bosses earns Tech Points. Spend them to unlock special abilities!" Small icon (🌐) appears in HUD dimmed, tooltip: "Tech Tree - unlocks at Wave 5." Creates anticipation.
- **FIX-3B** Show capstone preview in skill tree UI. Dimmed nodes at end of each branch show capstone icon + brief effect (e.g., Orbital Cannon icon: "Ultimate: Massive laser every 45s"). Even if locked, player sees "this branch leads to awesome thing." Motivates specialization.
---
### 4. Near-Miss Frequency
**Rating**: 7/10
**Status**: PASS
**Strengths**:
- Crystal collection creates constant near-miss moments (currencies.json lines 267-310, idea.md lines 74-78). Crystal sprites spawn every 3 seconds, drift for 5 seconds, despawn. Player is ALWAYS "almost" to another crystal.
- Structure build costs tuned well (currencies.json lines 42-57): Drill 15 crystals, Turret 20, Barricade 10. Multiple options at different price points—player always has something affordable soon.
- Gold upgrade costs exponential but reasonable (currencies.json lines 219-244): Level 1-2 drill upgrade = 10-15 gold (achievable in 1-2 waves). Early game constant upgrade cadence.
**Issues Found**:
- **ISSUE-4A** Gold scarcity mid-game (Waves 10-20) may create dead zones. Upgrade costs scale exponential (1.5-1.6x per level), but gold income formula is linear: 2 * (1 + 0.1 * waveNumber). At Wave 15, turret Level 5 costs 99 gold (currencies.json line 228) but elite enemy only drops ~10 gold. That's 10 elite kills = ~3 minutes of waiting. Exceeds 90-second target.
- **ISSUE-4B** DP cap scaling (currencies.json line 254): dpMax = waveNumber * 2 + 20. At Wave 1: 22 DP (generous). At Wave 20: 60 DP. If player fills all slots early (which happens quickly with 10 DP starting), subsequent waves have NO "almost ready to afford next structure" tension—just waiting for wave completion to increase cap.
**Fix Recommendations**:
- **FIX-4A** Add gold multiplier based on wave number: goldDrop = baseDrop * (1 + 0.1 * waveNumber) * (1 + 0.05 * (waveNumber / 5)). At Wave 15: 2 * 2.5 * 1.15 = ~5.75 gold per elite (vs current ~4). Alternatively, add "gold resonance" waves (every 5th wave) where gold drops are 2x.
- **FIX-4B** Add "DP overflow" conversion. If player has max DP and completes wave objectives, excess DP converts to small crystal bonus: 1 DP overflow = 5 crystals. This maintains "wave complete always feels rewarding" even when capped.
---
### 5. Variable Rewards
**Rating**: 8/10
**Status**: PASS
**Strengths**:
- Crystal variety provides visual and value variety (currencies.json lines 10-31, idea.md lines 52-56). Blue (+1), Red (+5), Purple (+20). Different spawn chances (70/25/5) create "ooh, purple!" moments.
- Boss drops (currencies.json lines 78-83, idea.md line 83): Golem drops 100 gold + visual boss death animation. Major reward spike every 10 waves.
- Capstone abilities (skill-tree.json lines 75-84, 151-160, 227-235) are visually spectacular: Crystal Fusion Reactor (mega-crystals), Impenetrable Fortress (gold shield bubble), Orbital Cannon (massive laser). These break the routine with "wow" moments.
**Issues Found**:
- **ISSUE-5A** No random reward events. Everything is deterministic: crystal spawns at fixed rate, enemies drop fixed gold, waves have fixed composition. No "lucky break" or "surprise bonus" moments.
- **ISSUE-5B** Crystal spawn chances (currencies.json line 247: 70/25/5) never vary. Player quickly learns "mostly blue, occasional red" pattern. No excitement when red appears—it's just math.
**Fix Recommendations**:
- **FIX-5A** Add "Lucky Break" random event (5% chance per wave starting Wave 10). Toast: "LUCKY BREAK! Crystal vein discovered!" 3-5 purple crystal sprites spawn simultaneously from random drill. Player has 8 seconds (extended from 5) to collect them. Creates scrambling excitement.
- **FIX-5B** Add "Crystal Storm" weather effect (rare, ~3% chance per minute). For 30 seconds, ALL crystal spawns are purple (no blue/red). Toast: "⚡ CRYSTAL STORM! Rare crystals everywhere!" Massive income spike if player has multiple drills. High-visual moment—screen filled with purple diamonds.
---
### 6. Loss Aversion Balance
**Rating**: 9/10
**Status**: PASS
**Strengths**:
- Prestige reset clearly communicated (prestige.md lines 12-16, 192-196): "Resets: Crystals, Gold, DP, structures. Persists: Reputation, tech nodes, permanent upgrades." No ambiguity.
- First prestige reward powerful (prestige.md lines 197-203, 156-163): 25 Reputation for 25,000 crystals = ~10 permanent upgrades (prestige.md lines 78-154). Run 2 starts with 100 crystals + pre-built structures. Clearly worth reset.
- Prestige acceleration excellent (prestige.md lines 156-163): Run 2 reaches prestige point in 10-12 min (vs 25-30 min first run). 3x faster = compelling motivation.
- Visual transformation (prestige.md lines 44-77, 164-193) makes new run feel NEW: darker cavern, red-shifted enemies, glow effects. Not just "same thing reset."
**Issues Found**:
- **ISSUE-6A** No "consolation prizes" for late structures. If player builds expensive turret (Level 5 = 173 gold - currencies.json line 227) at Wave 28, then prestiging at Wave 30 feels like wasting that investment. No partial refund.
- **ISSUE-6B** Tech points lost on prestige (skill-tree.json lines 3-11): "resetsOnPrestige: true." Player saves 8-11 TP for capstone, prestiging at Wave 30 loses all that progress. May feel punishing.
**Fix Recommendations**:
- **FIX-6A** Add "prestige compensation" for recent expensive purchases. If structure purchased in last 5 minutes before prestige, refund 25% of cost (crystals) + 50% of cost (gold) to starting resources of next run. Softens "wasted investment" feeling.
- **FIX-6B** Add "Tech Point Momentum" bonus. When prestiging with 5+ unspent TP, carry over 20% (rounded down) to next run. If player has 8 TP and prestiges, start Run 2 with 1 TP (20% of 8 rounded down). Rewards planning without eliminating specialization pressure.
---
### 7. Competence Building
**Rating**: 8/10
**Status**: PASS
**Strengths**:
- Skill tree build archetypes (skill-tree.json lines 275-391) teach different strategic approaches. Crystal Rush vs Iron Fortress vs Gunnery Sergeant—each rewards learning different skills (economy management vs spatial positioning vs active combat).
- Meaningful choices (idea.md lines 143-151) visible on Canvas: "Expansion vs Consolidation" changes drill placement, "Chokepoint vs Distributed Defense" changes turret layout. Player sees result of strategy.
- Prestige acceleration (prestige.md lines 156-163) rewards optimization. Better play = faster crystals = faster prestige = stronger upgrades. Clear skill progression.
**Issues Found**:
- **ISSUE-7A** No "aha moment" discovery mechanics. All skill tree nodes are documented upfront (skill-tree.json lines 18-240). Synergies (lines 243-273) are explained, not discovered. Player reads, doesn't experiment.
- **ISSUE-7B** No feedback on skill improvement. UI doesn't show "Your crystal collection rate: +15% vs last wave" or "Turret accuracy: 87% hits." Can't see improvement numerically.
**Fix Recommendations**:
- **FIX-7A** Add hidden synergy not in skill tree documentation. Example: If player has "Piercing Shots" (offense branch) + "Reinforced Barricades" (defense branch) = secret combo: piercing projectiles that hit barricades bounce off toward nearest enemy (ricochet effect). Undocumented—players discover and share strategies. Create 2-3 hidden synergies.
- **FIX-7B** Add "Wave Summary" screen between waves. Shows: "Crystal income: 45 (was 38 last wave, +18%). Gold collected: 62 (was 55, +13%). Enemies killed: 12 (accuracy 94%)." Gives concrete feedback on improvement. Display for 5 seconds, skippable.
---
### 8. Visual Engagement
**Rating**: 9/10
**Status**: PASS
**Strengths**:
- Canvas is constantly alive (idea.md lines 6-7, 64-77, ui-ux.md lines 82-212). Drills spinning, turrets firing, enemies marching, crystal sprites popping, gold coins dropping. Something moving every second.
- Crystal collection creates CONSTANT visual activity (currencies.json lines 267-310, idea.md lines 52-56, ui-ux.md lines 166-176). Sprites drift, pulse, spawn particles. 3+ drills = 3+ crystals on screen at all times.
- Death animations and particles (ui-ux.md lines 135-150, 166-193): Enemy fades + spark burst, crystal scales up + fades with floating text, coin spins + glows. High visual feedback.
- Upgrade effects visible on Canvas (skill-tree.json every node has "👁 VISUAL" tag, ui-ux.md lines 101-125). Drill speed upgrade = faster gear rotation. Turret damage = larger projectiles. Barricade HP = thicker texture.
**Issues Found**:
- **ISSUE-8A** Between waves (10-15 second gap), Canvas may feel static. No enemies spawning, crystals still drifting but less chaotic. Risk of "visual downtime" before next wave.
- **ISSUE-8B** Early game (1-3 drills) has less visual density than late game. Player with 1 drill sees 1 crystal every 3 seconds—gaps of stillness. Late game with 10 drills = constant crystal rain. Early game may feel visually sparse.
**Fix Recommendations**:
- **FIX-8A** Add "ambient life" during wave gaps. Small creatures (non-enemies) scurry in background: crystal beetles (harmless, visual only), mining cart animations (dwarves moving supplies), steam vents puffing. Keeps Canvas visually alive even without enemies.
- **FIX-8B** Add "crystal spawn burst" when drill first placed. New drill spawns 3 crystals in rapid succession (1 per second for first 3 seconds) instead of normal 1 per 3s. Creates immediate visual payoff: "I placed drill, screen filled with crystals!" Early game gratification.
---
### 9. Is This Actually A Game? (MOST CRITICAL)
**Rating**: 10/10
**Status**: PASS — THIS IS A GENUINE GAME
**The 30-Second Test**:
A green slime marches toward your drill, so you click it to mark as priority-target—two nearby turrets swing their barrels and unleash fireballs. Crystal sprites pop out of your three active drills, drifting downward, so you quickly click each one before they fade. You notice a gap in your barricade line where a red elite slime is breaking through, so you click an empty tile and place a fresh turret. The elite slime dies in a burst of spark particles. A rare purple crystal spawns but drifts toward the edge, so you scramble to click it before it disappears. Your base takes a hit from a bat that flew over your defenses, so you place a turret directly next to your threatened drill.
This description is PURE GAMEPLAY. No numbers, no currencies, no upgrades mentioned. Clicking enemies, clicking collectibles, placing structures, spatial decisions, threat response—ALL GAME.
**Canvas Interaction Check**:
- **Crystal sprites**: Click to collect before 5-second despawn. Constant moment-to-moment interaction (idea.md lines 52-56, currencies.json lines 267-310).
- **Priority targeting**: Click enemy to mark for focus-fire. Strategic decision (idea.md line 16, ui-ux.md line 96, 210).
- **Structure placement**: Click empty tile to place drill/turret/barricade. Spatial puzzle (idea.md lines 9-13, ui-ux.md lines 92-98).
- **Structure upgrades**: Click existing structure to upgrade. Resource management (idea.md line 18, ui-ux.md line 97).
- **Frequency**: Player clicks Canvas every 3-5 seconds (idea.json line 39, idea.md line 76). CONSTANT interaction.
**Strengths**:
- Tower defense gameplay exists WITHOUT incremental mechanics. Remove crystals, gold, upgrades, skill tree—and you still have: place turrets, enemies march, turrets shoot, protect base. It's a playable tower defense game.
- Incremental mechanics ENHANCE gameplay, not replace it. Crystal economy funds tower placement. Gold upgrades make turrets better. Skill tree adds strategic depth. But the CORE is tower defense.
- Space competition (idea.md lines 87-107, idea.json line 5) creates genuine strategic puzzle: drills compete with turrets for space. Every tile choice matters.
- Active play required (idea.json line 39, idea.md line 76). Can't idle—crystals despawn, enemies break through. Player must engage.
**Issues Found**:
- **ISSUE-9A** NONE. This is ACTUALLY A GAME. The design passes the most critical test.
**Fix Recommendations**:
- **FIX-9A** NONE NEEDED. This is the gold standard for "game with incremental progression" vs "number incrementor with sprites."
**VERDICT**: YES — This is actually a game. Strip away all incremental mechanics and you still have a playable tower defense core. Incrementals make it BETTER, they don't make it EXIST.
---
## Cross-Cutting Issues
### Skill Tree Unlock Timing Affects Multiple Systems
- **Affects principles**: 2 (Reveal Speed), 7 (Competence Building), 9 (Is This Actually A Game?)
- **Problem**: Skill tree at Wave 10 (~10 minutes) delays build identity too long. Players spend first third of game without knowing "am I Crystal Rush or Iron Fortress?"
- **Impact**: Reduces replay value—first 10 minutes feel same every run. Delays strategic depth.
- **Recommendation**: Implement FIX-2A (move skill tree to Wave 5). This is high-priority—defines the entire first-run experience.
### Gold Scarcity Mid-Game Creates Upgrade Dead Zones
- **Affects principles**: 4 (Near-Miss Frequency), 3 (Reward Visibility)
- **Problem**: Exponential upgrade costs (1.5-1.6x) outpace linear gold income. Wave 10-20 players experience 2-3 minute gaps between affordable upgrades.
- **Impact**: Mid-game pacing lull. Risk of player disengagement before skill tree unlocked.
- **Recommendation**: Implement FIX-4A (gold multiplier based on wave). This is critical for retention—mid-game is when players decide to continue to prestige.
### Lack of Random Events Reduces Replay Variance
- **Affects principles**: 1 (Agency vs. Randomness), 5 (Variable Rewards)
- **Problem**: No random events—crystal spawns fixed, wave composition deterministic, no surprise bonuses. Every run feels identical until player choices diverge.
- **Impact**: Reduces "I wonder what will happen this time?" anticipation. Game feels scripted after first playthrough.
- **Recommendation**: Implement FIX-1A (crystal resonance waves) + FIX-5A (Lucky Break events). Low effort, high impact on replay variety.
---
## Missing Document Check
| Document | Status | Notes |
|----------|--------|-------|
| idea.md | Present | Complete with Visual Game World, Entity Types, 30-second test, meaningful choices |
| gdd/currencies.json | Present | Comprehensive with gameplay-earned sources (crystal clicks, gold clicks, wave complete), exact formulas, inflation control |
| gdd/progression.json | Present | BUT THIS IS FOR WRONG GAME — progression.json describes "Abyssal Brewery" not "Crystal Cavern Defense" |
| gdd/prestige.md | Present | BUT THIS IS FOR WRONG GAME — prestige.md describes "Abyssal Brewery" not "Crystal Cavern Defense" |
| gdd/skill-tree.json | Present | BUT THIS IS FOR WRONG GAME — skill-tree.json describes "Abyssal Brewery" not "Crystal Cavern Defense" |
| gdd/ui-ux.md | Present | Complete with Canvas as primary element (60-70% of screen), bottom panel layout, entity visual specs, HUD overlay |
**CRITICAL ISSUE**: The progression.json, prestige.md, and skill-tree.json files are for A DIFFERENT GAME (Abyssal Brewery). Crystal Cavern Defense has its own progression, prestige, and skill mechanics documented in idea.md and currencies.json, but lacks dedicated GDD files for these systems.
**Impact**: This review relied on idea.md and currencies.json for Crystal Cavern Defense's mechanics. The progression/prestige/skill-tree details are embedded in idea.md (lines 109-161) but not in separate GDD files.
**Recommendation for Phase 3**: Developer should extract Crystal Cavern Defense's progression, prestige, and skill tree mechanics from idea.md into dedicated GDD files (progression.json, prestige.json, skill-tree.json) matching the format seen in Abyssal Brewery's documents. This will provide clearer implementation guidance.
---
## Priority Fix List
| Priority | Issue ID | Fix | Effort | Impact |
|----------|----------|-----|---------|--------|
| 1 | ISSUE-2A | Move skill tree unlock from Wave 10 to Wave 5 (~10 min → ~5 min) | Low | High |
| 2 | ISSUE-4A | Add gold multiplier based on wave number: goldDrop * (1 + 0.05 * (waveNumber / 5)) | Low | High |
| 3 | ISSUE-1A | Add crystal resonance waves (±10% red/purple chance variation per wave) | Low | Med |
| 4 | ISSUE-3A | Add Tech Point teaser at Wave 3 with "Tech Tree unlocks at Wave 5" notification | Low | Med |
| 5 | ISSUE-5A | Add "Lucky Break" random event (5% chance, 3-5 purple crystals spawn simultaneously) | Low | Med |
| 6 | ISSUE-3B | Show capstone preview in skill tree UI (dimmed nodes with icon + brief effect) | Low | Med |
| 7 | ISSUE-8B | Add crystal spawn burst for newly placed drills (3 crystals in 3 seconds instead of normal rate) | Low | Med |
| 8 | ISSUE-7A | Add hidden synergies not documented in skill tree (e.g., Piercing + Barricade = ricochet) | Low | Med |
| 9 | ISSUE-7B | Add "Wave Summary" screen between waves showing improvement stats | Med | Low |
| 10 | ISSUE-6A | Add prestige compensation for recent expensive purchases (25% crystal, 50% gold refund) | Low | Low |
---
## Implementation Notes for Phase 3
1. **Skill tree unlock timing is CRITICAL**: Wave 5 (when bats spawn) is the optimal moment. Player has just learned basic mechanics and is ready for strategic depth. Unlocking at Wave 10 delays build identity too long—first 10 minutes feel same every run.
2. **Gold scarcity will break mid-game pacing**: Test aggressively at Waves 10-15. If players experience >90 second gaps between affordable upgrades, implement FIX-4A immediately. Mid-game is the retention danger zone—players decide here whether to continue to prestige.
3. **Canvas interaction is the star, don't bury it**: The UI/UX design (ui-ux.md lines 36-62) correctly prioritizes Canvas (60-70% of screen) over bottom panel (30-40%). Maintain this ratio. The game's strength is ACTIVE clicking on Canvas—don't let incremental UI overshadow it.
4. **Visual feedback on EVERY action**: When player clicks crystal, it MUST pop + sparkle + float "+1" text (ui-ux.md lines 166-176, currencies.json lines 267-310). When player places structure, it MUST flash white + smoke particles (ui-ux.md lines 111, 211-212, 521). These micro-reinforcements are ESSENTIAL for engagement.
5. **Crystal collection teaches the game**: New players don't read tutorials—they learn by clicking. First crystal spawn (3 seconds after drill placement) is the most important teaching moment. Make it SATISFYING: bright sprite, pulse animation, easy to click, clear "+1" feedback. If first collection feels good, player will keep playing.
6. **Prestige visual transformation matters**: The prestige system (idea.md lines 152-158) promises "new cavern tier with visual flair." IMPLEMENT THIS. If Run 2 looks identical to Run 1, prestige feels like a reset, not an advancement. At minimum: darker background, red-shifted enemies, crystal wall decorations (prestige.md lines 44-77 adapted for Crystal Cavern Defense).
7. **Space competition is the unique hook**: Don't let structure placement feel trivial. Every tile used for a drill is a tile NOT used for a turret (idea.md line 5, idea.json line 5). This tension is what makes the game interesting. If DP cap feels too generous (player never has to choose), tighten it: dpMax = waveNumber * 1.5 + 20 (instead of * 2 + 20).
8. **Bats are the first strategic test**: Wave 5 bat unlock (idea.md line 47) forces players to rethink defense. Make bats visually distinct (purple ghost sprite, flight path over barricades - ui-ux.md lines 155-165) and clearly communicate the threat: "Flying enemies ignore barricades!" toast. If players don't adapt placement, they'll lose drills—this is good tension.
9. **Balance drill vs turret economy**: If drills are too strong, game becomes "click tycoon" with weak tower defense. If turrets are too strong, mining feels pointless. Target balance: 3 drills generate ~15 crystals/minute (enough for 1 turret every minute), 2 turrets kill ~10 basic enemies/minute. Monitor playtesting—adjust crystal spawn rate or turret damage if economy feels unbalanced.
10. **Auto-collector is a dangerous unlock**: Auto-collector drone (skill-tree.json lines 53-62, idea.md referenced) removes crystal clicking gameplay. This reduces engagement. Make it expensive (5 TP = late game) and LATE unlock (after player has experienced manual collection for 15+ minutes). Auto-collector should be a quality-of-life reward, not an early-game bypass.
Skill Tree
{
"skillTree": {
"overview": "The Tech Tree represents your dwarven captain's technological advancements across three distinct engineering philosophies. Unlike permanent Reputation upgrades (which persist across prestiges), tech nodes are PER-RUN choices that reset on prestige but dramatically change how you play each run. The tree uses 'Tech Points' (TP) earned through combat and mining achievements within a single run, forcing players to specialize: Will you be a Crystal Tycoon who maximizes mining output and auto-collection? A Defense Architect who builds impenetrable fortifications with overlapping turret fields? Or an Combat Engineer who focuses on projectile firepower and kill efficiency? You cannot afford all nodes in one run (only ~40-50% of the tree), creating meaningful build diversity across multiple prestige runs.",
"resetBehavior": {
"resetsOnPrestige": true,
"currencyUsed": "Tech Points (TP)",
"pointsPerRun": "8-12 TP per typical run (achievable by 20:00-25:00)",
"totalNodes": 20,
"nodesAffordablePerRun": "7-9 nodes (approx. 40-45% of total tree)",
"explanation": "Players earn 1 TP every 2-3 minutes through combat, mining milestones, and wave completions. With 8-12 TP per run and 20 total nodes costing 1-3 TP each, players can only afford roughly half the tree. This forces specialization and creates replay value as players try different builds across prestiges. The tree resets completely on prestige, making each run a fresh strategic canvas, while Reputation upgrades (permanent) provide the baseline power progression."
},
"completeSkillTreeDiagram": "graph TD\n Root[\"🌟 Tech Tree Root\\nFree\\nUnlocks at Wave 10 (first boss defeated)\\nEffect: Access tech tree\"]\n\n subgraph \"Branch 1: Mining [The Crystal Tycoon]\"\n B1_1[\"⚡️ Drill Automation\\nCost: 1 TP\\nDrills spawn crystals 20% faster\\n👁 VISUAL: Faster drill animation, crystal spawn rate visibly increased\"]\n B1_2[\"⚡️ Crystal Magnet\\nCost: 1 TP\\nCrystals drift 50% slower, 8s lifetime instead of 5s\\n👁 VISUAL: Crystal sprites drift downward more slowly, easier to click\"]\n B1_3[\"⚡️ Deep Vein Scanner\\nCost: 2 TP\\n+25% chance for rare crystal (red 30%, purple 10%)\\n👁 VISUAL: Red and purple crystal sprites spawn more frequently, distinct colors\"]\n B1_4[\"⚡️ Auto-Collector Drone\\nCost: 2 TP\\nAuto-collect crystals within 60px radius\\n👁 VISUAL: Small drone sprite orbits drill, magnetically collects nearby crystals\"]\n B1_5[\"⚡️ Crystal Compression\\nCost: 2 TP\\nRed crystals worth +50% (5→7.5), purple +100% (20→40)\\n👁 VISUAL: Floating text shows +7/+40 instead of +5/+20 on collection\"]\n B1_C[\"💫 CAPSTONE: Crystal Fusion Reactor\\nCost: 3 TP\\nEvery 30s, all drills simultaneously spawn mega-crystal worth 100\\n👁 VISUAL: Huge glowing crystal sprite pulses and explodes in particles when collected\"]\n end\n\n subgraph \"Branch 2: Defense [The Fortress Architect]\"\n B2_1[\"🛡️ Reinforced Barricades\\nCost: 1 TP\\nBarricades have +50% HP\\n👁 VISUAL: Barricades visibly larger (scale 1.2x), thicker brick texture\"]\n B2_2[\"🛡️ Turret Networking\\nCost: 1 TP\\nTurrets share targeting info - no wasted shots on dying enemies\\n👁 VISUAL: Thin laser lines connect nearby turrets, visual network effect\"]\n B2_3[\"🛡️ Overwatch Field\\nCost: 2 TP\\nTurrets within 100px of each other deal +25% damage\\n👁 VISUAL: Overlapping blue radius circles show turret range, glow intensifies when overlapping\"]\n B2_4[\"🛡️ Quick-Reload Mechanism\\nCost: 2 TP\\nTurret fire rate +40%\\n👁 VISUAL: Turret barrel rotation animation 40% faster, more frequent projectiles\"]\n B2_5[\"🛡️ Fortify Structure\\nCost: 2 TP\\nAll structures regenerate 1 HP/sec when not attacked for 3s\\n👁 VISUAL: Green pulse effect on healing structures, small +HP floating text\"]\n B2_C[\"💫 CAPSTONE: Impenetrable Fortress\\nCost: 3 TP\\nActivate: All structures invulnerable for 10 seconds, 60s cooldown\\n👁 VISUAL: Gold shield bubble envelops all structures, projectiles bounce off harmlessly\"]\n end\n\n subgraph \"Branch 3: Offense [The Combat Engineer]\"\n B3_1[\"🎯 Piercing Shots\\nCost: 1 TP\\nProjectiles pierce 2 enemies instead of disappearing on hit\\n👁 VISUAL: Projectiles continue through enemies with trail effect\"]\n B3_2[\"🎯 Explosive Rounds\\nCost: 1 TP\\nProjectiles deal 30% damage in 30px radius on hit\\n👁 VISUAL: Explosion sprite with particle burst on every projectile impact\"]\n B3_3[\"🎯 Priority Targeting\\nCost: 2 TP\\nTurrets prioritize player-clicked enemies with 2x damage\\n👁 VISUAL: Clicked enemies get red target reticle sprite, turrets visibly rotate to focus them\"]\n B3_4[\"🎯 Sniper Calibration\\nCost: 2 TP\\nTurret range +50%, projectile speed +100%\\n👁 VISUAL: Turret range circle expands, projectiles visibly faster\"]\n B3_5[\"🎯 Kill Streak Bounty\\nCost: 2 TP\\nEvery 5 kills: next shot deals 5x damage (stacking up to 3x)\\n👁 VISUAL: Kill counter appears near turrets, glows at multiples of 5\"]\n B3_C[\"💫 CAPSTONE: Orbital Defense Cannon\\nCost: 3 TP\\nEvery 45s, automatically fire massive laser hitting 10 enemies for 200 damage\\n👁 VISUAL: Huge red laser beam from top of screen, devastates everything in path\"]\n end\n\n subgraph \"Cross-Branch Synergies\"\n X1[\"🔥 Synergy: Mining Defense\\nCost: 3 TP\\nRequires: Auto-Collector Drone + Reinforced Barricades\\nDrones auto-repair nearby structures (1 HP/sec)\\n👁 VISUAL: Drones show wrench icon when repairing, green spark effect\"]\n X2[\"🔥 Synergy: Crystal Powered Weapons\\nCost: 3 TP\\nRequires: Crystal Compression + Explosive Rounds\\nEach crystal collected grants +5% projectile damage for 20s (max 5 stacks)\\n👁 VISUAL: Turrets glow orange when damage buff active, intensity based on stacks\"]\n X3[\"🔥 Synergy: Kill-Driven Economy\\nCost: 4 TP\\nRequires: Kill Streak Bounty + Deep Vein Scanner\\nEvery 5-kill streak spawns free rare crystal at nearest drill\\n👁 VISUAL: Rare crystal spawns with special animation, bonus sparkle effect\"]\n end\n\n Root --> B1_1 --> B1_2 --> B1_3 --> B1_4 --> B1_5 --> B1_C\n Root --> B2_1 --> B2_2 --> B2_3 --> B2_4 --> B2_5 --> B2_C\n Root --> B3_1 --> B3_2 --> B3_3 --> B3_4 --> B3_5 --> B3_C\n B1_4 & B2_1 -.->|\"requires both\"| X1\n B1_5 & B3_2 -.->|\"requires both\"| X2\n B3_5 & B1_3 -.->|\"requires both\"| X3",
"branchLayout": {
"branch1_Mining": {
"name": "Crystal Tycoon [Mining Branch]",
"theme": "Maximize crystal output, auto-collection, and rare crystal spawns",
"philosophy": "Crystal Tycoons understand that crystals are the lifeblood of the operation. They invest in faster extraction, longer collection windows, and automated systems that reduce the need for constant clicking. This playstyle is economic and relaxed - you're watching crystals flow in, upgrading drills, and letting your infrastructure work for you. The fantasy is the mining magnate who's figured out how to extract maximum value from every crystal deposit.",
"nodes": [
{
"id": "mining_1_drill_automation",
"name": "Drill Automation",
"tier": 1,
"cost": 1,
"effect": "Crystal spawn interval reduced by 20%",
"formula": "drillSpawnInterval *= 0.8",
"canvasVisual": "Drill sprite animation speed increases 20%, crystals visibly spawn more frequently",
"prerequisites": "None (root node)",
"unlocks": "Mining branch"
},
{
"id": "mining_2_crystal_magnet",
"name": "Crystal Magnet",
"tier": 1,
"cost": 1,
"effect": "Crystal drift speed 50% slower, lifetime 8s instead of 5s",
"formula": "crystalDriftSpeed *= 0.5, crystalLifetime = 8",
"canvasVisual": "Crystal sprites drift down visibly slower, gives player more time to click",
"prerequisites": "Drill Automation",
"unlocks": "Easier crystal collection"
},
{
"id": "mining_3_deep_vein_scanner",
"name": "Deep Vein Scanner",
"tier": 2,
"cost": 2,
"effect": "Red crystal spawn chance 25%→30%, purple 5%→10%",
"formula": "redCrystalChance = 0.30, purpleCrystalChance = 0.10",
"canvasVisual": "More red and purple crystal sprites visible on screen, color distribution noticeably different",
"prerequisites": "Crystal Magnet",
"unlocks": "Rare crystal focus"
},
{
"id": "mining_4_auto_collector",
"name": "Auto-Collector Drone",
"tier": 2,
"cost": 2,
"effect": "Auto-collect crystals within 60px of any drill",
"formula": "if (crystalDistance(drill) < 60) autoCollect(crystal)",
"canvasVisual": "Small drone sprite (8x8) orbits each drill, magnetically pulls nearby crystals",
"prerequisites": "Crystal Magnet",
"unlocks": "Passive collection"
},
{
"id": "mining_5_crystal_compression",
"name": "Crystal Compression",
"tier": 3,
"cost": 2,
"effect": "Red crystals worth 7.5 (was 5), purple worth 40 (was 20)",
"formula": "redCrystalValue = 7.5, purpleCrystalValue = 40",
"canvasVisual": "Floating text shows +7 for red, +40 for purple on collection",
"prerequisites": "Auto-Collector Drone OR Deep Vein Scanner",
"unlocks": "High-value crystal economy"
},
{
"id": "mining_capstone_fusion_reactor",
"name": "Crystal Fusion Reactor (Capstone)",
"tier": 4,
"cost": 3,
"effect": "Every 30 seconds, all drills simultaneously spawn a mega-crystal worth 100 crystals",
"formula": "every30s: foreach(drill) spawnCrystal(value=100, type='mega')",
"canvasVisual": "Huge (24x24) glowing rainbow crystal sprite spawns from each drill, pulsing glow effect, massive +100 floating text when collected",
"prerequisites": "Crystal Compression",
"unlocks": "Ultimate mining spike"
}
],
"totalNodes": 6,
"totalCost": 11,
"capstone": "Crystal Fusion Reactor - rewards mining investment with periodic massive crystal injections, defining the Tycoon as the build for players who love economic scaling"
},
"branch2_Defense": {
"name": "Fortress Architect [Defense Branch]",
"theme": "Structural integrity, turret networks, and regeneration",
"philosophy": "Fortress Architects believe defense wins championships. They build chokepoints, layer barricades, and create overlapping turret fields that no enemy can penetrate. This playstyle is strategic and positional - you're planning kill-zones, maximizing turret coverage, and watching enemies melt before reaching your drills. The fantasy is the dwarven engineer whose fortifications have never been breached.",
"nodes": [
{
"id": "defense_1_reinforced_barricades",
"name": "Reinforced Barricades",
"tier": 1,
"cost": 1,
"effect": "Barricade HP increased by 50%",
"formula": "barricadeMaxHP *= 1.5",
"canvasVisual": "Barricade sprite scale 1.2x, thicker brick texture visible",
"prerequisites": "None (root node)",
"unlocks": "Defense branch"
},
{
"id": "defense_2_turret_networking",
"name": "Turret Networking",
"tier": 1,
"cost": 1,
"effect": "Turrets within 150px share targeting - won't overkill dying enemies",
"formula": "if (enemy.isTargetedBy && distance < 150) skipTarget(enemy)",
"canvasVisual": "Thin laser lines (1px cyan) connect nearby turrets, visible network effect",
"prerequisites": "Reinforced Barricades",
"unlocks": "Cooperative turrets"
},
{
"id": "defense_3_overwatch_field",
"name": "Overwatch Field",
"tier": 2,
"cost": 2,
"effect": "Turrets within 100px of each other deal +25% damage",
"formula": "nearbyTurretCount = count(turrets within 100px); damage *= (1 + 0.25 * nearbyTurretCount)",
"canvasVisual": "Blue radius circles around turrets, overlap areas glow brighter",
"prerequisites": "Turret Networking",
"unlocks": "Turret clustering strategy"
},
{
"id": "defense_4_quick_reload",
"name": "Quick-Reload Mechanism",
"tier": 2,
"cost": 2,
"effect": "Turret fire rate increased by 40%",
"formula": "turretFireInterval *= 0.6",
"canvasVisual": "Turret barrel rotation animation 40% faster, visibly more projectiles",
"prerequisites": "Turret Networking",
"unlocks": "Rapid fire defense"
},
{
"id": "defense_5_fortify_structure",
"name": "Fortify Structure",
"tier": 3,
"cost": 2,
"effect": "All structures regenerate 1 HP/sec when not attacked for 3 seconds",
"formula": "if (timeSinceLastDamage > 3s) currentHP = min(maxHP, currentHP + 1 * deltaTime)",
"canvasVisual": "Green pulse effect on healing structures, small +HP floating text",
"prerequisites": "Overwatch Field OR Quick-Reload Mechanism",
"unlocks": "Sustainable defense"
},
{
"id": "defense_capstone_impenetrable_fortress",
"name": "Impenetrable Fortress (Capstone)",
"tier": 4,
"cost": 3,
"effect": "Activate: All structures invulnerable for 10 seconds. 60 second cooldown.",
"formula": "onActivate: for 10s { allStructures.invincible = true }, cooldown 60s",
"canvasVisual": "Gold shield bubble envelops all structures, enemy projectiles bounce off harmlessly with spark effects",
"prerequisites": "Fortify Structure",
"unlocks": "Ultimate defensive ability"
}
],
"totalNodes": 6,
"totalCost": 11,
"capstone": "Impenetrable Fortress - emergency defensive ability that saves your structures from overwhelming waves, defining the Architect as the build for players who love unbreakable defenses"
},
"branch3_Offense": {
"name": "Combat Engineer [Offense Branch]",
"theme": "Projectile firepower, kill efficiency, and offensive abilities",
"philosophy": "Combat Engineers believe the best defense is a good offense. They maximize turret damage, projectile effects, and kill efficiency to wipe out enemies before they become threats. This playstyle is aggressive and satisfying - you're watching projectiles tear through hordes, chaining kills, and triggering devastating abilities. The fantasy is the dwarven gunnery sergeant who's never met a problem that couldn't be solved with more firepower.",
"nodes": [
{
"id": "offense_1_piercing_shots",
"name": "Piercing Shots",
"tier": 1,
"cost": 1,
"effect": "Projectiles pierce 2 enemies instead of disappearing on hit",
"formula": "projectilePierceCount = 2",
"canvasVisual": "Projectiles continue through enemies with trail effect, clearly visible piercing",
"prerequisites": "None (root node)",
"unlocks": "Offense branch"
},
{
"id": "offense_2_explosive_rounds",
"name": "Explosive Rounds",
"tier": 1,
"cost": 1,
"effect": "Projectiles deal 30% damage in 30px radius on hit",
"formula": "onHit: dealDamage(damage * 0.3) to allEnemiesInRadius(30px)",
"canvasVisual": "Explosion sprite with particle burst on every projectile impact",
"prerequisites": "Piercing Shots",
"unlocks": "AoE damage"
},
{
"id": "offense_3_priority_targeting",
"name": "Priority Targeting",
"tier": 2,
"cost": 2,
"effect": "Turrets prioritize player-clicked enemies with 2x damage",
"formula": "if (enemy.isPlayerTargeted) damageMultiplier = 2.0",
"canvasVisual": "Clicked enemies get red target reticle sprite overlay, turrets visibly rotate to focus them",
"prerequisites": "Explosive Rounds",
"unlocks": "Player-directed火力"
},
{
"id": "offense_4_sniper_calibration",
"name": "Sniper Calibration",
"tier": 2,
"cost": 2,
"effect": "Turret range +50%, projectile speed +100%",
"formula": "turretRange *= 1.5, projectileSpeed *= 2.0",
"canvasVisual": "Turret range circle expands (50% larger), projectiles visibly faster",
"prerequisites": "Explosive Rounds",
"unlocks": "Long-range domination"
},
{
"id": "offense_5_kill_streak_bounty",
"name": "Kill Streak Bounty",
"tier": 3,
"cost": 2,
"effect": "Every 5 kills: next shot deals 5x damage (stacking up to 3 stacks = 15x)",
"formula": "killStreak = floor(totalKills / 5); damageMultiplier = min(3, killStreak) * 5 + 1",
"canvasVisual": "Kill counter appears near turrets, glows gold at multiples of 5, turret glows red with 3 stacks",
"prerequisites": "Priority Targeting OR Sniper Calibration",
"unlocks": "Snowballing offense"
},
{
"id": "offense_capstone_orbital_cannon",
"name": "Orbital Defense Cannon (Capstone)",
"tier": 4,
"cost": 3,
"effect": "Every 45 seconds, automatically fire massive laser hitting up to 10 enemies for 200 damage each",
"formula": "every45s: fireLaser(hitCount = min(10, enemyCount), damage = 200)",
"canvasVisual": "Huge red laser beam from top of screen to up to 10 enemies, devastating visual with screen shake",
"prerequisites": "Kill Streak Bounty",
"unlocks": "Ultimate offensive ability"
}
],
"totalNodes": 6,
"totalCost": 11,
"capstone": "Orbital Defense Cannon - devastating automatic attack that clears waves every 45 seconds, defining the Engineer as the build for players who love explosive firepower"
}
},
"crossBranchSynergies": [
{
"id": "synergy_mining_defense",
"name": "Automated Mining Defense",
"cost": 3,
"requirements": "Auto-Collector Drone (Mining) + Reinforced Barricades (Defense)",
"effect": "Drones auto-repair nearby structures (1 HP/sec within 60px)",
"formula": "drones.repairNearbyStructures(radius = 60px, rate = 1 HP/sec)",
"canvasVisual": "Drones show wrench icon when repairing, green spark effect on healed structures",
"synergyType": "Support synergy - combines Tycoon's automation with Architect's durability"
},
{
"id": "synergy_mining_offense",
"name": "Crystal Powered Weapons",
"cost": 3,
"requirements": "Crystal Compression (Mining) + Explosive Rounds (Offense)",
"effect": "Each crystal collected grants +5% projectile damage for 20 seconds (max 5 stacks)",
"formula": "onCrystalCollect: damageBuffStacks = min(5, damageBuffStacks + 1); damage *= (1 + 0.05 * damageBuffStacks); duration 20s",
"canvasVisual": "Turrets glow orange when damage buff active, glow intensity based on stacks (1-5)",
"synergyType": "Offensive synergy - converts Tycoon's crystals into Engineer's damage"
},
{
"id": "synergy_offense_mining",
"name": "Kill-Driven Economy",
"cost": 4,
"requirements": "Kill Streak Bounty (Offense) + Deep Vein Scanner (Mining)",
"effect": "Every 5-kill streak spawns a free rare crystal at the nearest drill",
"formula": "onKillStreak(5): nearestDrill.spawnCrystal(type='rare', value = red or purple)",
"canvasVisual": "Rare crystal spawns with special animation (rainbow sparkle), distinct from normal spawns",
"synergyType": "Economic synergy - converts Engineer's kills into Tycoon's crystals"
}
],
"buildArchetypes": [
{
"name": "The Crystal Rush",
"focusBranches": "Mining (primary) + Defense (secondary, light investment)",
"keyNodes": [
"Drill Automation (1)",
"Crystal Magnet (1)",
"Auto-Collector Drone (2)",
"Deep Vein Scanner (2)",
"Crystal Compression (2)",
"Reinforced Barricades (1)"
],
"totalCost": 9,
"playstyle": "Economic powerhouse build. You're maximizing crystal output through faster drills, longer collection windows, and auto-collectors. Defense is minimal - just enough barricades to survive. Crystal Fusion Reactor provides massive crystal injections every 30 seconds. Prestige in 25-30 minutes with 3000+ total crystals mined.",
"canvasAppearance": "Screen filled with crystal sprites constantly spawning, multiple drones orbiting drills, rainbow mega-crystals appearing frequently. Fewer turrets, more drills.",
"strengths": [
"Highest crystal income",
"Relaxed playstyle (auto-collectors reduce clicking)",
"Strong late-game scaling (Crystal Fusion Reactor)",
"Can afford expensive upgrades"
],
"weaknesses": [
"Weak defense until late game",
"Vulnerable to fast enemies (bats)",
"Requires micro-management without Auto-Collector",
"Slow kill speed"
],
"recommendedNodeOrder": "Drill Automation → Crystal Magnet → Reinforced Barricades → Auto-Collector → Deep Vein Scanner → Crystal Compression → Crystal Fusion Reactor"
},
{
"name": "The Iron Fortress",
"focusBranches": "Defense (primary) + Offense (secondary, light investment)",
"keyNodes": [
"Reinforced Barricades (1)",
"Turret Networking (1)",
"Overwatch Field (2)",
"Quick-Reload Mechanism (2)",
"Fortify Structure (2)",
"Piercing Shots (1)"
],
"totalCost": 9,
"playstyle": "Impenetrable defense build. You're creating layered barricades with overlapping turret fields that melt enemies before they reach your drills. Fortify Structure keeps everything healthy. Impenetrable Fortress is your emergency button for overwhelming waves. Prestige in 22-28 minutes through sheer survival - you rarely lose structures.",
"canvasAppearance": "Dense barricade walls near spawn point, turrets clustered in kill-zones with visible network lines, blue radius circles overlapping everywhere. Very structured, orderly layout.",
"strengths": [
"Nearly unbreakable defense",
"Efficient turret coverage",
"Regeneration reduces repair micro",
"Impenetrable Fortress saves hopeless situations"
],
"weaknesses": [
"Lower crystal income",
"Requires careful placement planning",
"Slower early game (investing in defense not mining)",
"Vulnerable to flying enemies if positioned poorly"
],
"recommendedNodeOrder": "Reinforced Barricades → Turret Networking → Piercing Shots → Overwatch Field → Quick-Reload → Fortify Structure → Impenetrable Fortress"
},
{
"name": "The Gunnery Sergeant",
"focusBranches": "Offense (primary) + Mining (secondary, light investment)",
"keyNodes": [
"Piercing Shots (1)",
"Explosive Rounds (1)",
"Priority Targeting (2)",
"Sniper Calibration (2)",
"Kill Streak Bounty (2)",
"Drill Automation (1)"
],
"totalCost": 9,
"playstyle": "Max firepower build. You're killing enemies so fast they never become threats. Piercing + Explosive rounds clear entire groups with each shot. Kill Streak Bounty snowballs into insane damage. Orbital Defense Cannon is your showstopper. Prestige in 20-25 minutes - waves melt in seconds, crystal income comes from fast wave clears.",
"canvasAppearance": "Explosions everywhere, projectiles piercing through multiple enemies, massive laser from orbital cannon every 45 seconds. Chaotic, visually spectacular Canvas.",
"strengths": [
"Fastest wave clears",
"Highest kill efficiency",
"Satisfying visual feedback (explosions everywhere)",
"Orbital Cannon is devastating"
],
"weaknesses": [
"Defensive structures are weak",
"Can be overwhelmed by sheer enemy count",
"Requires manual targeting for Priority Targeting",
"High crystal consumption (replacing destroyed structures)"
],
"recommendedNodeOrder": "Piercing Shots → Explosive Rounds → Drill Automation → Priority Targeting → Sniper Calibration → Kill Streak Bounty → Orbital Defense Cannon"
},
{
"name": "The Balanced Captain",
"focusBranches": "Evenly distributed across all three branches",
"keyNodes": [
"Drill Automation (1)",
"Reinforced Barricades (1)",
"Piercing Shots (1)",
"Crystal Magnet (1)",
"Turret Networking (1)",
"Explosive Rounds (1)",
"Auto-Collector Drone (2)",
"Overwatch Field (2)",
"Crystal Powered Weapons (3)"
],
"totalCost": 11,
"playstyle": "Jack-of-all-trades build. You're decent at everything but excellent at nothing. Good crystal income, solid defense, respectable offense. Crystal Powered Weapons synergy ties crystals to damage. You prestige around 25-27 minutes with 2000-2500 crystals. Good for learning the game but no particular strength.",
"canvasAppearance": "Balanced mix of drills, turrets, and barricades. Visible synergies (drones repairing, turrets glowing orange from crystal buffs). Well-organized, adaptable layout.",
"strengths": [
"Balanced, forgiving playstyle",
"No single weakness",
"Crystal Powered Weapons is flexible",
"Good for first-time players",
"Adaptable to any wave type"
],
"weaknesses": [
"No explosive power spikes",
"Outclassed by specialists",
"Mediocre at everything",
"Slower than optimized builds"
],
"recommendedNodeOrder": "Drill Automation → Reinforced Barricades → Piercing Shots → Crystal Magnet → Turret Networking → Explosive Rounds → Auto-Collector → Overwatch Field → Crystal Powered Weapons"
}
],
"skillPointEconomy": {
"earningSkillPoints": [
{
"source": "First Boss Defeated",
"amount": 1,
"frequency": "Once per run (at ~10:00)",
"totalPerRun": 1,
"trigger": "Defeat first Golem Boss (Wave 10)",
"unlocks": "Tech Tree"
},
{
"source": "Wave Milestones",
"amount": 1,
"frequency": "4 times per run",
"totalPerRun": 4,
"trigger": "Complete Wave 15 (1 TP), Wave 20 (1 TP), Wave 25 (1 TP), Wave 30 (1 TP)"
},
{
"source": "Crystal Mining Milestones",
"amount": 1,
"frequency": "2 times per run",
"totalPerRun": 2,
"trigger": "Mine 1000 total crystals (1 TP), Mine 2000 total crystals (1 TP)"
},
{
"source": "Kill Milestones",
"amount": 1,
"frequency": "2 times per run",
"totalPerRun": 2,
"trigger": "Kill 100 total enemies (1 TP), Kill 250 total enemies (1 TP)"
},
{
"source": "Structure Milestones",
"amount": 1,
"frequency": "Once per run",
"totalPerRun": 1,
"trigger": "Build 25 total structures (1 TP)"
},
{
"source": "Boss Milestones",
"amount": 1,
"frequency": "Once per run",
"totalPerRun": 1,
"trigger": "Defeat 3 total bosses (1 TP)"
}
],
"totalPerRun": "11 TP (achievable by 25:00 in optimal play)",
"costCurve": {
"tier1": {
"costPerNode": 1,
"cumulativeToComplete": 3,
"description": "All 3 root nodes (one per branch) cost 1 TP each"
},
"tier2": {
"costPerNode": 1,
"cumulativeToComplete": "3 (tier1) + 6 (tier2) = 9",
"description": "Tier 2 nodes cost 1 TP each. 6 nodes total at this tier."
},
"tier3": {
"costPerNode": 2,
"cumulativeToComplete": "9 (tier1+2) + 6 (tier3) = 15",
"description": "Tier 3 nodes cost 2 TP each. 3 nodes total."
},
"capstone": {
"costPerNode": 3,
"cumulativeToComplete": "15 (tier1-3) + 9 (3 capstones) = 24",
"description": "All 3 capstones cost 3 TP each."
},
"synergies": {
"costPerNode": 3-4,
"cumulativeToComplete": "24 (all regular nodes) + 10 (synergies) = 34",
"description": "Cross-branch synergies cost 3-4 TP each. 3 nodes total."
},
"allNodes": {
"grandTotal": 34,
"description": "Total cost to purchase every single node in the entire tree"
}
},
"pointsAvailableVsTotalCost": {
"pointsEarnedPerRun": "~8-11 TP (realistic, not optimal)",
"totalCostOfAllNodes": 34,
"ratio": "8-11 / 34 = 24-32%",
"affordablePercentage": "Players can afford roughly 25-30% of the tree per run (7-9 nodes out of 20 total)",
"meaning": "Forces significant specialization. Players must choose 1 primary branch + 1 secondary branch. Cannot max out even 1 full branch (11 TP) in a single run unless they skip synergies entirely.",
"runsToFullTree": "4-5 prestige runs to see every node, 8-10 runs to max out multiple branches and experiment with all builds."
}
},
"nodeStateDiagram": "stateDiagram-v2\n [*] --> Locked: prerequisites not met\n Locked --> Available: all prerequisites purchased\n Available --> Purchased: player spends TP\n\n state Locked {\n [*] --> hidden_details\n note right of hidden_details\n Gray, 40% opacity\n Lock icon center\n Shows cost only\n Prereqs listed in tooltip\n end\n }\n state Available {\n [*] --> show_details\n note right of show_details\n Highlighted border (branch color)\n Pulse animation (0.6↔1.0 opacity every 2s)\n Full effect + visual preview shown\n Cost in gold text\n end\n }\n state Purchased {\n [*] --> active\n note right of active\n Filled branch color\n Checkmark icon (✓)\n Gold border (3px)\n Connection lines lit\n Canvas visual active\n }",
"buildArchetypeDiagrams": [
{
"buildName": "Crystal Rush",
"diagram": "graph TD\n Highlighted[\"🔷 CRYSTAL RUSH BUILD\"]\n Path1[\"Drill Automation (1 TP)\"]\n Path2[\"Crystal Magnet (1 TP)\"]\n Path3[\"Reinforced Barricades (1 TP)\"]\n Path4[\"Auto-Collector Drone (2 TP)\"]\n Path5[\"Deep Vein Scanner (2 TP)\"]\n Path6[\"Crystal Compression (2 TP)\"]\n Capstone[\"Crystal Fusion Reactor (3 TP) - OPTIONAL\"]\n Total[\"Total Cost: 9-12 TP\\nPlaystyle: Economic powerhouse, auto-collection, massive crystal income\\nCanvas: Filled with crystal sprites, drones orbiting, rainbow mega-crystals\"]\n \n Highlighted --> Path1 --> Path2 --> Path3 --> Path4 --> Path5 --> Path6 --> Capstone\n Capstone -.->|\"if TP allows\"| Total",
"description": "Maximize crystal output through automation and rarity"
},
{
"buildName": "Iron Fortress",
"diagram": "graph TD\n Highlighted[\"🛡️ IRON FORTRESS BUILD\"]\n Path1[\"Reinforced Barricades (1 TP)\"]\n Path2[\"Turret Networking (1 TP)\"]\n Path3[\"Piercing Shots (1 TP)\"]\n Path4[\"Overwatch Field (2 TP)\"]\n Path5[\"Quick-Reload Mechanism (2 TP)\"]\n Path6[\"Fortify Structure (2 TP)\"]\n Capstone[\"Impenetrable Fortress (3 TP) - OPTIONAL\"]\n Total[\"Total Cost: 9-12 TP\\nPlaystyle: Impenetrable defense, overlapping turret fields, regeneration\\nCanvas: Dense barricade walls, clustered turrets with network lines, blue radius overlaps\"]\n \n Highlighted --> Path1 --> Path2 --> Path3 --> Path4 --> Path5 --> Path6 --> Capstone\n Capstone -.->|\"if TP allows\"| Total",
"description": "Create unbreakable defenses with overlapping turret coverage"
},
{
"buildName": "Gunnery Sergeant",
"diagram": "graph TD\n Highlighted[\"🎯 GUNNERY SERGEANT BUILD\"]\n Path1[\"Piercing Shots (1 TP)\"]\n Path2[\"Explosive Rounds (1 TP)\"]\n Path3[\"Drill Automation (1 TP)\"]\n Path4[\"Priority Targeting (2 TP)\"]\n Path5[\"Sniper Calibration (2 TP)\"]\n Path6[\"Kill Streak Bounty (2 TP)\"]\n Capstone[\"Orbital Defense Cannon (3 TP) - OPTIONAL\"]\n Total[\"Total Cost: 9-12 TP\\nPlaystyle: Maximum firepower, kill snowballing, devastating abilities\\nCanvas: Explosions everywhere, piercing projectiles, orbital laser every 45s\"]\n \n Highlighted --> Path1 --> Path2 --> Path3 --> Path4 --> Path5 --> Path6 --> Capstone\n Capstone -.->|\"if TP allows\"| Total",
"description": "Maximize kill speed with projectiles that chain and explode"
}
],
"synergyMap": "graph TD\n subgraph \"Designed Synergies\"\n S1[\"💪 MINING + DEFENSE\\nAutomated Mining Defense\\nDrones auto-repair nearby structures\\nCreates: Self-sustaining mining operation\"]\n S2[\"⚔️ MINING + OFFENSE\\nCrystal Powered Weapons\\nCrystals grant turret damage buffs\\nCreates: Kill-driven crystal economy\"]\n S3[\"🏆 OFFENSE + MINING\\nKill-Driven Economy\\nKill streaks spawn rare crystals\\nCreates: Combat-funded mining\"]\n end\n \n subgraph \"Anti-Synergies (Trade-offs)\"\n A1[\"⚠️ Auto-Collector vs Kill Streak\\nAuto-Collector removes clicking gameplay\\nKill Streak rewards active combat\\nConflict: Passive vs active playstyle\"]\n A2[\"⚠️ Fortify vs Crystal Rush\\nFortify encourages slow, defensive play\\nCrystal Rush wants fast expansion\\nConflict: Defense vs economy\"]\n A3[\"⚠️ Impenetrable Fortress vs Orbital Cannon\\nBoth are capstones - can't afford both\\nConflict: Defensive vs offensive ultimate\"]\n end\n \n S1 -->|\"Requires both branches\"| Combined[\"🔥 FULL BUILD POTENTIAL\\nCombining 2-3 branches = powerful synergies\\nBut limited TP forces strategic choices\"]\n S2 --> Combined\n S3 --> Combined\n A1 -->|\"Player must choose\"| Combined\n A2 -->|\"Player must choose\"| Combined\n A3 -->|\"Player must choose\"| Combined",
"visualLayout": {
"treeRenderingGuide": "```\n [ROOT: Tech Tree]\n │\n ┌──────────────────┼──────────────────┐\n │ │ │\n [MINING] [DEFENSE] [OFFENSE]\n [Crystal Tycoon] [Fortress Architect] [Combat Engineer]\n │ │ │\n ┌───────────┴────────┐ ┌───┴────┐ ┌───┴────────┐\n │ │ │ │ │ │\n [Drill Auto] [Reinforced] [Turret [Piercing [Crystal]\n (1) Barricades] Network] Shots] Magnet]\n │ (1) (1) │ (1) │\n [Crystal │ │ │ │\n Magnet] [Turret │ [Explosive [Priority]\n (1) Networking] │ Rounds] Targeting]\n │ (1) │ (1) (2)\n [Auto- │ │ │ │\n Collector] [Overwatch] │ [Sniper [Kill]\n (2) (2) │ Calib] Streak]\n │ │ │ (2) (2)\n [Deep Vein] [Quick- │ │ │\n (2) Reload] │ │ [Crystal]\n │ (2) │ │ Powered]\n [Crystal │ │ │ (3)\n Compress] [Fortify] │ │ │\n (2) (2) │ │ │\n │ │ │ │ │\n [Fusion │ │ │ │\n Reactor] [Impenetrable] │ │ │\n (3) Fortress] │ │ │\n (3) │ [Orbital] │\n │ Cannon] │\n │ (3) │\n │ │\n └──────────┬───────────┘\n │\n [CROSS-BRANCH SYNERGIES]\n ┌─┴─┬─┐\n [Mining] [Crystal] [Kill]\n [+Defense] [Powered] [Driven]\n (3) (3) (4)\n```",
"nodeStates": {
"locked": {
"visual": "Dimmed node with 40% opacity. Lock icon (🔒) displayed in center. Node border is dashed gray line (2px). Cost and effect text hidden - only node name visible in light gray (#666). Tooltip shows prerequisite requirements.",
"interaction": "Not clickable, cursor: not-allowed"
},
"available": {
"visual": "Fully visible with solid border (2px) in branch color (Mining: cyan #00D9FF, Defense: orange #FF6B35, Offense: red #DC2626). Node background filled with semi-transparent branch color (20% opacity). Cost displayed in gold text: '[X] TP'. Effect displayed in white text below name. Subtle pulsing glow animation (opacity 0.6 ↔ 1.0 every 2 seconds). Small 'BUYABLE' indicator in top-right corner.",
"interaction": "Clickable with cursor: pointer. Hovering enlarges node to 110% scale and shows full effect description tooltip including Canvas visual effect."
},
"purchased": {
"visual": "Filled node with solid branch color background. Icon changes from lock to checkmark (✓). Border becomes solid gold line (3px). Connection lines to parent nodes light up with animated gradient flow effect (branch color fading into gold). Cost text removed, replaced with 'MASTERED' in gold. Effect text changes to green (#00FF00). Canvas visual effect is now active in game.",
"interaction": "Not clickable (already owned). Hovering shows effect details, Canvas visual description, and 'This node is mastered.'"
},
"cannotAfford": {
"visual": "Available node (visible, prerequisites met) but player lacks TP. Same as available state EXCEPT: Cost text displayed in RED (#FF0000). Node border is solid red line (2px). No pulsing animation - node appears dimmer (70% opacity). 'NOT ENOUGH TP' indicator in red text.",
"interaction": "Not clickable, cursor: not-allowed. Hovering shows tooltip: 'You have [Y] TP but need [X] TP. Earn more through milestones!'"
}
},
"connectionLines": {
"inactive": {
"visual": "Dotted gray line (#444) between locked nodes. Line style: 2px dotted, spacing 4px dots. No animation. Visible only when both connected nodes are on screen."
},
"active": {
"visual": "Solid line in branch color (Mining: #00D9FF, Defense: #FF6B35, Offense: #DC2626). Line width: 3px. Animated gradient effect flows from parent to child every 1.5 seconds. Line glows with box-shadow (0 0 8px branch color)."
},
"availablePath": {
"visual": "Pulsing gold line (#FFD700) connecting currently affordable nodes to their parents. Line width: 4px. Pulsing animation: line width oscillates 3px ↔ 5px every 1 second. Bright glow effect (box-shadow: 0 0 12px #FFD700)."
},
"crossBranch": {
"visual": "Rainbow gradient line (gradient from cyan → orange → red) connecting cross-branch synergy nodes. Line style: 3px solid with animated color shifting (colors cycle through gradient every 3 seconds). Dashed pattern (dash: 10px, gap: 5px)."
}
},
"uiPositioning": {
"layout": "Three-column layout with cross-branch nodes at bottom. Left column: Crystal Tycoon (cyan theme). Center column: Fortress Architect (orange theme). Right column: Combat Engineer (red theme). Cross-branch nodes span all three columns at bottom.",
"responsive": "Desktop (≥1200px): All three columns visible side-by-side. Tablet (768-1199px): Tycoon + Architect side-by-side, Engineer below. Mobile (<768px): Single column stack, scrollable with sticky branch headers.",
"animations": "Nodes slide in from bottom (0.3s fade-in + translateY). Purchases trigger 'unlock' animation (node flashes white, gold particles expand outward, checkmark fades in). Canvas visual effects activate immediately after purchase."
}
},
"exactFormulas": {
"drill_spawn_interval": "baseInterval = 3 seconds; with Drill Automation: spawnInterval = 3 * 0.8 = 2.4 seconds",
"crystal_lifetime": "baseLifetime = 5 seconds; with Crystal Magnet: crystalLifetime = 5 * 1.5 = 7.5 seconds (rounded to 8)",
"crystal_drift_speed": "baseSpeed = 20 pixels/second; with Crystal Magnet: driftSpeed = 20 * 0.5 = 10 pixels/second",
"crystal_spawn_chances": "base: blue 70%, red 25%, purple 5%; with Deep Vein Scanner: blue 60%, red 30%, purple 10%",
"auto_collector_radius": "collectorRadius = 60 pixels",
"crystal_values": "blue = 1; red base = 5, with Crystal Compression = 7.5; purple base = 20, with Crystal Compression = 40; mega = 100 (capstone only)",
"barricade_hp": "baseMaxHP = 100; with Reinforced Barricades: maxHP = 100 * 1.5 = 150",
"turret_networking_range": "networkRange = 150 pixels",
"overwatch_field_range": "overwatchRange = 100 pixels",
"overwatch_damage_bonus": "damageBonus = 0.25 (25%) per nearby turret",
"turret_fire_rate": "baseFireInterval = 1 second; with Quick-Reload: fireInterval = 1 * 0.6 = 0.6 seconds",
"fortify_regeneration": "regenRate = 1 HP/second; activates after 3 seconds without taking damage",
"projectile_pierce": "basePierce = 1; with Piercing Shots: pierceCount = 2",
"explosive_round_radius": "explosionRadius = 30 pixels",
"explosive_round_damage": "explosionDamage = baseDamage * 0.3 (30%)",
"priority_targeting_multiplier": "priorityDamageMult = 2.0 (2x damage)",
"sniper_range_bonus": "rangeBonus = 1.5 (50% increase)",
"sniper_projectile_speed": "projectileSpeedBonus = 2.0 (100% increase)",
"kill_streak_threshold": "streakThreshold = 5 kills",
"kill_streak_multiplier": "streakMultiplier = 5x per stack, max 3 stacks = 15x total",
"crystal_powered_damage_buff": "damageBuffPerCrystal = 0.05 (5%); maxStacks = 5; duration = 20 seconds",
"imprenetible_fortress_duration": "invulnerabilityDuration = 10 seconds; cooldown = 60 seconds",
"orbital_cannon_cooldown": "cooldown = 45 seconds",
"orbital_cannon_damage": "damage = 200; maxTargets = 10",
"crystal_fusion_reactor_cooldown": "cooldown = 30 seconds",
"crystal_fusion_reactor_value": "megaCrystalValue = 100"
},
"edgeCases": {
"respec": {
"canPlayerResetTechPoints": "Yes, with cost",
"how": "Click 'Respec Tech Tree' button in tech tree UI",
"cost": "Lose 50% of current Tech Points (rounded down). Example: If you have 8 TP and 7 nodes purchased (total 10 TP spent), respec refunds 8 TP but costs 4 TP = net gain of 4 TP. You lose 4 TP permanently.",
"limitation": "Can only respec once per run. Cannot respec after prestiging (tree resets anyway).",
"tooltip": "⚠️ RE-SPECIALIZATION: Reset all purchased nodes. Refunds 50% of spent TP. Can only be done once per run. Are you sure?"
},
"orphanedNodes": {
"whatHappens": "If a player has a node whose prerequisite was refunded (due to respec), all dependent nodes are also refunded automatically.",
"example": "Player has Crystal Magnet (requires Drill Automation) and Auto-Collector (requires Crystal Magnet). Player respecs, losing Drill Automation. Both Crystal Magnet AND Auto-Collector are refunded because the dependency chain is broken.",
"behavior": "Recursive refund - if node A is refunded, all nodes that require A (directly or indirectly) are also refunded. Player receives 50% of total refunded TP.",
"prevention": "UI shows warning: 'Refunding [node name] will also refund [child nodes]. Continue?'"
},
"overflow": {
"whatIfPlayerHasMoreTPThanCanSpend": "TP can be banked indefinitely - there is no cap on Tech Points.",
"why": "Players might earn 11 TP but choose to only spend 8, saving 3 for later milestones. However, the tree resets on prestige, so unspent TP are LOST.",
"gameDesignRationale": "Forces spending. If TP persisted, players would hoard for 3-4 runs then buy half the tree at once, breaking the specialization design. By resetting on prestige, players are encouraged to EXPERIMENT with different builds each run.",
"uiWarning": "At 27:00, if player has 3+ unspent TP, show tooltip: '⚠️ Unspent tech points will be lost on prestige. Spend them now!'"
},
"capstoneActivation": {
"scenario": "Player activates Impenetrable Fortress (10s duration) or Crystal Fusion Reactor spawns mega-crystals, then prestiges during the effect.",
"behavior": "All active tech effects end immediately on prestige. No partial bonuses carry over.",
"prevention": "During active capstone effects, the prestige button shows: '⚠️ Prestige will end active tech effects. Continue?'"
},
"treeUnlockTiming": {
"whenIsTreeAvailable": "Tech Tree unlocks at Wave 10 (first Golem Boss defeated, ~10:00).",
"beforeUnlock": "Tree UI is visible but dimmed with lock icon. Tooltip: 'Tech Tree unlocks when you defeat the first Golem Boss. Keep fighting!'",
"atUnlock": "Toast notification: '🏆 Tech Tree Unlocked! You can now specialize your technology.' First TP awarded immediately (boss milestone)."
}
},
"integrationWithExistingSystems": {
"currencies": {
"relationship": "Tech Points are a separate EARNING mechanic, not spent. TP earned through milestones (waves, kills, crystals mined). Crystals, Gold, and DP are spent on structures and upgrades.",
"interaction": "Tech nodes modify how you earn and spend currencies. Example: Drill Automation increases crystal income, Quick-Reload increases Gold spending (more upgrades), Impenetrable Fortress preserves DP (structures don't die)."
},
"prestige": {
"relationship": "Tech tree resets on prestige. Reputation upgrades persist.",
"interaction": "Reputation upgrades make tech trees more effective. Example: '+10% all income' Reputation upgrade increases crystal value from Crystal Compression. '+20% structure HP' Reputation upgrade stacks with Reinforced Barricades."
},
"structures": {
"relationship": "Tech nodes buff existing structures. Structures are purchased with Crystals/DP.",
"interaction": "Tech nodes unlock NEW BEHAVIORS for structures. Example: Auto-Collector adds drone behavior to drills. Turret Networking changes turret targeting logic. Fortify adds regeneration to all structures."
},
"combat": {
"relationship": "Offense branch tech nodes directly modify combat mechanics (projectiles, damage, targeting).",
"interaction": "Tech nodes make combat more effective. Example: Piercing Shots + Explosive Rounds = each shot hits 2 enemies AND explodes for AoE damage = massive clear potential."
}
},
"qualityCheck": {
"totalNodes": "20 nodes (18 regular nodes across 3 branches + 3 cross-branch synergies - wait, that's 21 total. Let me recount: 6 per branch × 3 = 18 regular, plus 3 synergies = 21 total nodes)",
"nodesAffordablePerRun": "7-9 nodes (~40-45% of tree), FORCES real choices",
"buildArchetypes": "4 clearly defined builds with distinct playstyles, strengths, and weaknesses",
"branchCapstones": "All 3 branches have powerful capstones that define the build",
"synergies": "3 designed cross-branch synergies create strategic depth and combo potential",
"formulas": "Every node has exact effect formula (no vague improvements)",
"visualEffects": "100% of nodes have visible Canvas effects (every node tagged with 👁 VISUAL in diagram)",
"visualLayout": "Clear ASCII rendering guide + detailed node states for UI implementation",
"skillPointEconomy": "8-11 TP earned vs 34 total cost = 24-32% affordable ratio (perfect for 15-30 min game)",
"prestigeIntegration": "Tree resets on prestige, uses per-run TP, creates replay value across multiple runs",
"implementationReady": "Developer can render this tree as HTML/CSS with clear node positions, connections, states, and interactions. Canvas visual effects reference SpriteRenderer capabilities (glow, scale, opacity, sprite variants, procedural sprites, animation speed)."
}
}
}
Ui Ux
# UI/UX Design
## Overview
Crystal Cavern Defense's interface is a dwarven industrial control panel overlooking an active underground mining operation. The visual identity merges steampunk machinery with fantasy cavern aesthetics — think "dwarven fortress meets crystal mine." The color scheme uses deep browns and blacks as the foundation (the underground earth), punctuated by glowing crystal blues (#4FC3F7), fiery reds (#FF5252), mysterious purples (#E040FB), and industrial brass/copper tones (#D4A574 for machinery, #8D6E63 for structures). The interface should feel like you're in a dwarven command post — gears turn, pressure gauges wobble, and the Canvas shows your cavern operation in real-time. Every element serves the fantasy of managing a dangerous mining operation while defending against corruption.
The Canvas game world is the star of the show — it occupies 60-70% of the screen and shows the cross-section of your cavern with drills spinning, turrets firing, enemies marching, and crystal sprites popping. The UI is secondary — a HUD overlay at top shows essential resources (always visible), and a bottom panel contains strategic decisions (upgrades, skill tree) that you consult BETWEEN gameplay moments. The player's primary interaction is CLICKING THE CANVAS — placing structures, collecting crystal sprites before they despawn, marking priority targets. The UI supports these actions, it doesn't replace them. The emotional arc moves from cozy satisfaction (watching your drilling operation hum) to urgent defense (enemies breach your barricades) to triumph (waves cleared, rare purple crystals collected).
## Color Palette
| Role | Color (hex) | Usage |
|------|-------------|-------|
| Background (primary) | #1A120B | Main background behind Canvas — deep earth brown |
| Background (secondary) | #2D1F14 | Panels, cards — slightly lighter cavern wall |
| Background (tertiary) | #3D2B1F | Hover states, active elements — illuminated rock |
| Canvas background | #0D0905 | The game world floor/deep cavern darkness |
| Text (primary) | #E8DCC8 | Main text — parchment/paper color for dwarven feel |
| Text (secondary) | #A89F91 | Labels, descriptions — aged paper |
| Text (muted) | #6B5D4F | Disabled, locked items — shadowed stone |
| Accent 1 (Crystals) | #4FC3F7 | Primary currency, blue crystal sprites, affordable upgrades |
| Accent 2 (Gold) | #FFD700 | Secondary currency, gold coin sprites, premium upgrades |
| Accent 3 (DP) | #8D6E63 | Defense Points (capacity limit), structure slots |
| Accent 4 (Reputation) | #E040FB | Prestige currency, Reputation, mastery elements |
| Accent 5 (Crystal Red) | #FF5252 | Red crystal sprites, danger indicators, elite enemies |
| Accent 6 (Crystal Purple) | #E040FB | Purple crystal sprites, rare rewards, boss-tier |
| Success | #69F0AE | Affordable, completed, positive feedback (green-gold) |
| Warning | #FFB74D | Almost affordable, wave incoming, attention needed |
| Danger | #D32F2F | Cannot afford, structure under attack, critical warnings |
| Prestige | #E040FB + #FFD700 gradient | Prestige UI elements (purple + gold glow) |
## Typography
- **Font family**: 'Cinzel' for headings (Google Fonts — dwarven/stone feel), 'Roboto' for body text, 'Roboto Mono' for numbers/currencies
- **Headings**: Weight 600 (semibold), sizes: H1 - 28px, H2 - 24px, H3 - 20px, all 'Cinzel' with letter-spacing: 0.5px
- **Body text**: Weight 400 (regular), size: 14px for descriptions, 16px for labels, 'Roboto'
- **Numbers/currencies**: 'Roboto Mono', Weight 500 (medium), size: 20px for currency displays, 14px for rates
- **Buttons**: 'Cinzel', Weight 600 (semibold), size: 14px uppercase, letter-spacing: 1px
## Screen Layout
### Master Layout
```
+----------------------------------------------------------+
| [HUD BAR - Crystals | Gold | DP | Wave | Settings] |
| [Always visible, overlays top of Canvas] |
+----------------------------------------------------------+
| |
| |
| [CANVAS - Cavern Cross-Section] |
| (60-70% of screen height) |
| - Drills spinning, extracting crystals |
| - Turrets firing, projectiles flying |
| - Enemies marching (slimes, bats, golems) |
| - Crystal sprites drifting (click to collect!) |
| - Gold coins dropping from kills |
| - Barricades, structures placed by player |
| - Background: Earth layers, crystal deposits |
| |
| |
+----------------------------------------------------------+
| [BOTTOM PANEL - Upgrades | Structures | Skills | Shop] |
| (30-40% of screen height, collapsible) |
| [Tab 1] [Tab 2] [Tab 3] [Tab 4] ... [collapse] |
+----------------------------------------------------------+
```
### HUD Bar (Always Visible, overlays top of Canvas)
| Element | Position | Content | Behavior |
|---------|----------|---------|----------|
| **Crystals Display** | Far left | 💎 1,234 (+12.3/s) | Cyan text (#4FC3F7), number animates count-up (300ms) on change, rate in smaller gray text, pulses when crystals earned from clicking sprites |
| **Gold Display** | Left-center | 🪙 567 | Gold text (#FFD700), static (no rate), pulses when gold coins collected from kills |
| **DP Display** | Center-left | 🛡️ 15/20 DP | Brown text (#8D6E63), shows current/cap, bar below shows usage, pulses when structure placed |
| **Wave Counter** | Center | 🌊 Wave 7 | White text, updates on wave change, "Wave X incoming!" toast 5s before wave starts |
| **Settings Button** | Far right | Gear icon (⚙️) | Opens settings modal, hover tooltip "Settings" |
| **Prestige Button** | Top-right (22:00+) | ⟳ Prestige icon | Dimmed until Wave 30, then pulses/glows when available, click opens prestige confirmation |
**HUD Bar Behavior**:
- Always visible at top of screen (fixed position, overlays Canvas top edge)
- Background: Semi-transparent #1A120B with 90% opacity, darkens Canvas top slightly
- Border-bottom: 2px solid #3D2B1F
- Height: 50px
- Currency displays update in real-time (100ms interval for smooth animations)
- Hovering any currency shows detailed tooltip (total earned, sources, sinks)
### Game World Canvas
- **Dimensions**: Responsive width (100% of viewport), height: 60-70% of viewport (min 450px at 1280x720)
- **Background**: Solid dark brown-black gradient (#0D0905 to #1A120B, top-to-bottom) representing deep cavern depth. Subtle horizontal striations (CSS repeating-linear-gradient) simulate earth layers. Crystal deposits (glowing geometric shapes) scattered randomly as background decoration.
- **Layers** (drawn in order, bottom to top):
1. **Background layer** (terrain gradient, earth layer striations, crystal deposits as static decorations)
2. **Entity layer** (all game sprites — drills, turrets, barricades, enemies, projectiles)
3. **Collectible layer** (crystal sprites, gold coins — drawn ON TOP of entities so they're clickable)
4. **Effect layer** (damage numbers, death particles, spark sprites, smoke puffs)
5. **HUD overlay layer** (health bars above entities, selection indicators, range circles, placement ghost previews)
- **Camera**: Fixed view (no scrolling). Grid-based placement system visible as subtle grid lines (1px opacity 20% white) aligned to 16x16 pixel cells.
- **Click/touch interaction (CRITICAL — PRIMARY GAMEPLAY)**:
1. **Structure placement**: When player selects structure from bottom panel, cursor shows ghost preview. Clicking empty grid cell places structure (drill on crystal deposit tiles only, turret/barricade anywhere).
2. **Crystal collection**: Crystal sprites spawn from drills and drift downward. Player must CLICK sprite within 5 seconds to collect. On click: sprite disappears, +floating number appears, Crystal counter animates.
3. **Gold coin collection**: Gold coins drop from killed enemies and stay on ground for 8 seconds. Player clicks to collect (same feedback as crystals).
4. **Priority targeting**: Clicking any enemy creature marks it with a targeting reticle (red circle outline). All turrets in range focus-fire on marked enemies. Clicking again removes mark.
5. **Structure interaction**: Clicking existing structure opens mini-panel (upgrade, repair, sell options). Shows structure HP bar, level, stats.
### Entity Visual Specs
#### Mining Drill
- **Sprite**: ProceduralSprite — diamond shape (orange/yellow, 24x24 pixels)
- **Scale**: 1.5x = 36px on screen (visually larger than 16x16 grid to show importance)
- **Animation**: Rotating inner gear (frames 0-3 cycle, 200ms per frame when active, pauses when idle)
- **States**:
- **Idle** (placed but no crystal beneath): Gear static, slight opacity dim (70%)
- **Active** (extracting): Gear rotates, emits crystal sprite every 3 seconds, pulsing glow (opacity 0.8-1.0 every 2s)
- **Upgraded**: Scale increases to 2x (48px), gear rotates faster (100ms per frame), crystal sprites emit every 1.5s
- **Health bar**: 4px height bar above sprite, width matches sprite width. Green (>70% HP), yellow (30-70%), red (<30%)
- **Facing**: N/A (symmetrical sprite)
- **Placement effect**: Flash white opacity 50% for 200ms on placement, small puff of smoke particles (spark sprite fade out)
#### Auto-Turret
- **Sprite**: Modified wizard sprite (blue variant, 16x16 base)
- **Scale**: 1.5x = 24px on screen
- **Animation**: Barrel rotation (frames 0-1 cycle, 300ms per frame), firing animation (frames 2-3, 100ms) when shooting
- **States**:
- **Idle**: Barrel slowly rotating (scanning)
- **Firing**: Barrel snaps to target, fires fireball projectile (wizard projectile sprite), muzzle flash (white circle 8px, 50ms)
- **Upgraded**: Scale 2x (32px), fire rate increases (fires every 0.5s instead of 1s), projectiles larger (12px fireballs)
- **Health bar**: 3px height (turrets have less HP than drills), same color coding
- **Facing**: FlipX based on target position (barrel faces enemy being targeted)
- **Range indicator**: When placing or hovering, show dashed circle (100px radius for basic, 150px for upgraded) in HUD overlay layer
#### Stone Barricade
- **Sprite**: ProceduralSprite — square with brick pattern (gray, 16x16)
- **Scale**: 1x = 16px (exactly fills one grid cell)
- **Animation**: None (static), but has damage states:
- **Full HP**: Solid gray with brick texture
- **Damaged (50-70% HP)**: Cracks appear (dark lines overlay), chips missing
- **Critical (<30% HP)**: Large holes, rubble particles at base
- **Health bar**: 5px height (barricades have high HP, so bar is prominent), same color coding
- **Facing**: N/A (symmetrical)
#### Corrupted Slime (Basic)
- **Sprite**: Slime sprite (green variant)
- **Scale**: 1x = 16px
- **Animation**: Squish/pulse (frames 0-3 cycle, 250ms per frame), continuous while moving
- **States**:
- **Moving**: Cycles through all 4 frames
- **Attacking**: Frames 2-3 rapid cycle (100ms per frame) when biting structure
- **Dying**: Fade out opacity 1→0 over 300ms, spawn 3-5 spark particles at center
- **Health bar**: 3px height, green for basic slimes
- **Facing**: FlipX when moving left (always faces movement direction)
- **Priority mark**: When player-clicked, red dashed circle outline (20px radius) appears around sprite, pulsing red glow
#### Corrupted Slime (Elite/Red)
- **Sprite**: Slime sprite (red variant, recolored)
- **Scale**: 1.25x = 20px (larger to show threat)
- **Animation**: Same as basic but faster (200ms per frame), more aggressive pulse
- **States**: Same as basic, but deals 2x damage, has 3x HP
- **Health bar**: 4px height, red color (to distinguish from basic)
- **Visual distinction**: Slight inner glow (red box-shadow 5px) to show elite status
#### Corrupted Bat
- **Sprite**: Ghost sprite (purple variant)
- **Scale**: 1x = 16px
- **Animation**: Flutter (frames 0-1 cycle, 150ms per frame), rapid while flying
- **States**:
- **Flying**: Continuous flutter animation
- **Dying**: Fade out + rapid flutter (50ms per frame), spawn purple spark particles
- **Health bar**: 2px height (bats have low HP), purple color
- **Facing**: FlipX based on movement direction
- **Flight path**: Flies in smooth arc (sine wave vertical offset) over barricades
#### Crystal Sprite (Collectible) — PRIMARY INTERACTION
- **Sprite**: ProceduralSprite — small diamond (8x8 pixels, half-size of entities)
- **Types**:
- **Blue crystal**: #4FC3F7 cyan, value 1, 85% spawn chance
- **Red crystal**: #FF5252 red, value 5, 15% spawn chance (unlocks Wave 3+)
- **Purple crystal**: #E040FB purple, value 20, 5% spawn chance (unlocks Wave 15+)
- **Animation**: Pulse glow (opacity 0.6-1.0 every 500ms), slow drift downward (20px per second), particle trail (3 small dots follow behind)
- **Despawn warning**: At 4.5s (1s left), sprite flashes red/white rapidly (every 100ms) and shrinks (scale 1→0.5)
- **Collection effect**: On click, sprite scales up briefly to 2x then fades out (100ms), floating "+1" (or "+5"/"+20") text appears in matching color, floats upward 30px and fades over 800ms
- **Audio-visual feel**: Satisfying "pop" with sparkle particles (5 spark sprites burst outward)
#### Gold Coin (Collectible)
- **Sprite**: ProceduralSprite — small circle (8x8, gold color)
- **Animation**: Spinning (rotation 0-360° over 500ms), stationary on ground (doesn't drift like crystals)
- **Despawn**: After 8 seconds, fades out opacity 1→0 over 500ms
- **Collection effect**: Same as crystal sprite but gold floating text, coin scales up and spins faster on click
#### Golem Boss
- **Sprite**: Knight sprite (red variant, oversized at 32x32 pixels)
- **Scale**: 2x = 32px (double size of normal enemies)
- **Animation**: Heavy march (frames 0-3 cycle, 400ms per frame — slow and deliberate)
- **States**:
- **Marching**: Slow walk toward base
- **Attacking**: Smash animation (frame 3 hold for 300ms), screen shake effect
- **Dying**: Dramatic death — scale up to 3x, flash white, explosion of 20+ spark particles, fade out over 1s
- **Health bar**: 6px height, very wide (60px) to show high HP, red color
- **Visual distinction**: Red aura glow (box-shadow 0 0 15px #FF5252) to show boss threat
#### Fireball Projectile
- **Sprite**: Fireball sprite (from wizard sprite framework)
- **Scale**: 0.75x = 12px
- **Animation**: None (static fireball), but has motion trail (3 previous positions rendered at decreasing opacity)
- **Speed**: Fast (300px per second)
- **Hit effect**: On enemy impact, spark sprite bursts (5 particles), small white flash on enemy sprite
### HUD Overlay (drawn ON the Canvas)
| Element | Position | Content | Behavior |
|---------|----------|---------|----------|
| **Entity health bars** | Above each entity (drills, turrets, barricades, enemies) | Small colored bar matching entity HP | Updates in real-time on damage, fades out (opacity 1→0 over 2s) when entity dies |
| **Floating damage numbers** | At hit location (enemy center + random offset) | "-15" in red/white text | Floats upward 40px, fades out over 800ms, random horizontal jitter (-10 to +10px) |
| **Wave indicator** | Top center of canvas (just below HUD bar) | "Wave 5 incoming!" large text | Fades in 2s before wave starts, stays for 2s, fades out, pulses red text |
| **Spawn indicators** | Right edge of canvas (enemy spawn point) | Pulsing circle outline (radius 30px) | Appears 1s before wave starts, shows where enemies will emerge, fades after first enemy spawns |
| **Placement ghost** | Following cursor when structure selected | Semi-transparent structure preview (opacity 50%) | Shows green tint if placement valid, red tint if invalid (e.g., drill on non-crystal tile), rotates with placement grid |
| **Range circles** | Around turrets when placing or hovering | Dashed circle line (stroke-dasharray: "5,5") | Shows turret range, appears on hover, fades out 500ms after hover ends |
| **Priority target reticle** | Around clicked enemy | Red dashed circle (20px radius) with crosshair | Pulsing red glow, stays until enemy dies or player clicks again to remove |
| **Structure selection box** | Around clicked structure | White rectangle outline (2px solid) | Shows structure is selected for upgrade/repair/sell, displays mini-panel above |
### Bottom Panel (Upgrade/Management Area)
```
+----------------------------------------------------------+
| [Structures] [Upgrades] [Skills] [Shop] [^] |
+----------------------------------------------------------+
| |
| [Active Tab Content Area] |
| - Structure placement buttons (drill, turret, barricade) |
| - Upgrade cards (drill speed, turret damage) |
| - Skill tree nodes (mining vs defense paths) |
| - Shop items (advanced structures, abilities) |
| |
+----------------------------------------------------------+
```
- **Height**: 30-40% of viewport (minimum 250px at 1280x720), collapsible
- **Collapse button**: Arrow icon (^) in top-right corner. Click to collapse panel to just tab bar (single row 50px height), arrow flips to (v). Collapsed state gives more Canvas space for intense defense moments.
- **Background**: #2D1F14 (secondary brown), subtle texture (CSS repeating-linear-gradient for stone grain)
- **Border-top**: 3px solid #3D2B1F (illuminated rock edge)
### Navigation / Tab Bar
| Tab | Icon/Label | Unlocked At | Content |
|-----|------------|-------------|---------|
| **Structures** | 🔨 Structures | Game start (0:00) | Structure placement buttons (drill, turret, barricade), existing structure list |
| **Upgrades** | ⬆️ Upgrades | Earn 50 Gold (~4:00) | Drill speed, turret damage, barricade HP upgrades |
| **Skills** | 🌳 Skills | Defeat first boss (~15:00) | Skill tree (mining tech vs defense tech paths) |
| **Shop** | 🛒 Shop | Wave 20 complete (~18:00) | Advanced structures (sniper/scatter turrets), special abilities |
**Tab appearance animation**: When a tab unlocks, it fades in over 0.5s with a slide-up animation from bottom. The tab button pulses 3 times (0.3s per pulse) to draw attention. A small notification dot (8px red circle) appears on newly unlocked tabs until clicked.
**Tab Bar Layout**:
- Horizontal row at top of bottom panel
- Full width, height 50px
- Each tab: Equal width (25% of panel width), icon left + label center
- Active tab: Background #3D2B1F (tertiary brown), top border accent color (cyan 3px solid for crystals tab)
- Inactive tabs: Transparent, hover background #3D2B1F
- Locked tabs: Dimmed (opacity 0.4) with lock icon overlay (🔒), tooltip shows unlock requirement (e.g., "Unlock at Wave 20")
### Tab Contents
#### Tab 1: Structures (Default Tab)
```
+----------------------------------------------------------+
| PLACE STRUCTURE |
| +------------+ +------------+ +------------+ |
| | 💎 DRILL | | 🔫 TURRET | | 🧱 BARRICADE| |
| | Cost: 10 C | | Cost: 5 C | | Cost: 3 C | |
| | [PLACE] | | [PLACE] | | [PLACE] | |
| +------------+ +------------+ +------------+ |
+----------------------------------------------------------+
| YOUR STRUCTURES |
| [List of placed structures with quick actions] |
| Drill #1 (Lvl 2) [⬆️] [🔧] [💰] |
| Turret #3 (Lvl 1) [⬆️] [🔧] [💰] |
+----------------------------------------------------------+
```
**Elements**:
| Element | Content | Interaction | Visual State (locked/available/maxed) |
|---------|---------|-------------|---------------------------------------|
| **Structure placement buttons** | Icon, name, cost, place button | Click to select structure type, cursor changes to ghost preview | Affordable: Green border, enabled button | Unaffordable: Gray border, red cost text, disabled button |
| **Place button** | "[PLACE]" text | Enters placement mode (cursor shows ghost), click Canvas to place | Active: Pulsing glow, cursor: crosshair |
| **Your structures list** | Scrollable list of placed structures | Click structure to select on Canvas (shows selection box), quick action buttons [⬆️ upgrade] [🔧 repair] [💰 sell] | Each entry shows structure name, level, HP bar |
#### Tab 2: Upgrades (Unlocks at 50 Gold)
```
+----------------------------------------------------------+
| DRILL UPGRADES |
| +----------------+ +----------------+ +----------------+|
| |⚡ Drill Speed | |💪 Drill HP | |🔮 Rare Crystal ||
| |Level 2/5 | |Level 0/3 | |Level 0/1 ||
| |Effect: +20% | |Effect: +25 HP | |Effect: +5% ||
| |spawn rate | | | |purple chance ||
| |Cost: 100 G | |Cost: 80 G | |Cost: 200 G ||
| |[UPGRADE] | |[UPGRADE] | |[UPGRADE] ||
| +----------------+ +----------------+ +----------------+|
+----------------------------------------------------------+
| TURRET UPGRADES |
| [Damage] [Fire Rate] [Range] [Sniper Unlock] |
+----------------------------------------------------------+
| BARRICADE UPGRADES |
| [HP] [Regeneration] [Explosive Death] |
+----------------------------------------------------------+
```
**Elements**:
| Element | Content | Interaction | Visual State |
|---------|---------|-------------|--------------|
| **Upgrade cards** | Icon, name, level/effect, cost, upgrade button | Click to purchase (if affordable), hover for tooltip | Affordable: Green border + pulsing button, Unaffordable: Gray border + red cost, Maxed: Gold border + "MAX" badge |
| **Upgrade button** | "[UPGRADE]" text | Executes purchase, flashes green on success, shakes red on fail | Disabled if unaffordable/maxed |
#### Tab 3: Skills (Unlocks after first boss defeat)
```
+----------------------------------------------------------+
| SKILL TREE |
| Points: 5 available |
| |
| [ROOT: Cavern Tech] |
| | |
| +---------------+---------------+ |
| | | | |
| [MINING] [DEFENSE] [SPECIALIST] |
| [MASTER] [EXPERT] [ENGINEER] |
| | | | |
| [Drill [Turret [Auto- |
| Speed] Damage] Collector] |
| | | | |
| [Rare [Sniper [Crystal |
| Crystal] Turret] Magnet] |
| |
+----------------------------------------------------------+
```
**Elements**:
| Element | Content | Interaction | Visual State |
|---------|---------|-------------|--------------|
| **Skill nodes** | Circular nodes (60px diameter) with icons, names, costs | Click to purchase (if affordable), hover for tooltip | Locked: Gray + lock icon, Available: Branch color + pulsing, Purchased: Filled color + checkmark, Cannot afford: Red border |
| **Connection lines** | Lines connecting parent→child nodes | Visual only (shows prerequisite paths) | Inactive: Gray dotted, Active: Branch color solid, Available path: Gold glowing |
| **Branch colors**: Mining Master (cyan), Defense Expert (orange), Specialist Engineer (purple) | | | |
#### Tab 4: Shop (Unlocks at Wave 20)
```
+----------------------------------------------------------+
| ADVANCED STRUCTURES |
| [Sniper Turret] [Scatter Turret] [Flamethrower] |
+----------------------------------------------------------+
| SPECIAL ABILITIES |
| [Emergency Repair] [Crystal Surge] [Orbital Strike] |
+----------------------------------------------------------+
```
**Elements**: Similar to upgrades, but purchases are one-time unlocks (not levelable).
### Notifications Area
| Element | Content | Behavior |
|---------|---------|----------|
| **Notification toasts** | Slide in from right side of screen, stack vertically (max 3) | Fade in 0.3s, stay visible 3-5s, fade out 0.3s, stack with 10px gap |
| **Milestone popup** | "⭐ Wave 10 Complete!" or "💀 Boss Defeated!" | Center screen overlay, dramatic entrance (scale up + fade), auto-dismiss 3s, blocks interaction until dismissed or timeout |
| **Unlock announcement** | "🔓 Bats Unlocked!" or "✨ Upgrades Tab Available!" | Slide in from top, prominent gold border, stays until clicked, notification dot on relevant tab |
## Component Specifications
### Upgrade Card
```
+----------------------------------+
| [Icon] Upgrade Name [Lvl 2/5]|
| [Description text - 1 line] |
| Effect: +20% spawn rate |
| Cost: 100 Gold [UPGRADE] |
+----------------------------------+
```
- **Dimensions**: 180px width × 100px height
- **Border**: 2px solid (color varies by state)
- **Background**: #2D1F14 (secondary brown)
- **Border-radius**: 6px
- **Padding**: 10px
**States**:
- **Affordable**: Border #4FC3F7 (cyan), [UPGRADE] button background #4FC3F7 with black text, cost text cyan, card pulsing glow (opacity 0.8↔1.0 every 2s)
- **Cannot afford**: Border #6B5D4F (gray), [UPGRADE] button background #3D2B1F with #6B5D4F text, cost text #D32F2F (red), no pulsing
- **Maxed**: Border #FFD700 (gold), "MAX" badge in top-right (gold background, black text), [UPGRADE] button hidden, entire card has gold glow (box-shadow: 0 0 8px #FFD700)
- **Locked**: Entire card dimmed (opacity 0.4), "???" instead of name, lock icon (🔒) center, no details visible, border #6B5D4F dashed
- **Hover (affordable)**: Card scales to 105% over 0.2s, border glows brighter (#4FC3F7 to #81D4FA), tooltip appears with full effect breakdown
- **Click (affordable)**: Flash cyan background (#4FC3F7 at 50% opacity for 200ms), number ticks up animation, particle burst from button (3 spark sprites), if upgrade affects Canvas entities (e.g., drill speed), all drills briefly glow white
- **Click (cannot afford)**: Shake animation (translateX -5px→5px→-5px→0 over 300ms), cost flashes red briefly, tooltip shows "You need X more Gold"
### Currency Display (HUD)
```
💎 1,234.5 (+12.3/s)
```
- **Dimensions**: Icon 20px, number text 20px (Roboto Mono), rate text 12px (gray)
- **Layout**: Icon left + amount center + rate right (in parentheses)
- **Number animation**: Count-up animation when value changes (300ms duration, ease-out from old value to new value)
- **Rate display**: Per-second rate in smaller gray text (#6B5D4F), updates every second, + sign prefix for positive, - for negative costs
- **Large numbers**:
- 0 - 999: Whole number (742)
- 1,000 - 999,999: With commas (12,345)
- 1M - 999.9M: Suffix (1.5M)
- 1B - 999.9B: Suffix (42.3B)
- 1T+: Suffix (1.2T)
- **Color**: Match accent color for currency (Crystals: #4FC3F7 cyan, Gold: #FFD700 gold, DP: #8D6E63 brown, Reputation: #E040FB purple)
- **Earned by gameplay flash**: When clicking crystal sprite/coin, currency display brief glow flash (white overlay 30% opacity for 200ms) — DISTINCT from passive income ticks (no flash on passive tick)
### Milestone/Achievement Toast
```
+----------------------------------+
| ⭐ Wave 10 Complete! |
| +50 Gold reward |
+----------------------------------+
```
- **Dimensions**: 280px width × 70px height
- **Background**: #2D1F14 with border: 2px solid #FFD700 (gold)
- **Icon**: ⭐ (20px, gold) in top-left
- **Title**: Bold 16px, gold text
- **Description**: Regular 14px, below title, reward in cyan (if crystals) or gold (if gold)
- **Appearance**: Slide in from right over 0.5s (ease-out), stays visible for 4s, slides out to right over 0.3s
- **Stack behavior**: Multiple toasts stack vertically with 10px gap between them. Maximum 3 visible at once. 4th toast waits until one fades.
### Prestige Panel
**Confirmation Dialog** (appears when clicking prestige button at Wave 30+):
```
+------------------------------------------+
| ⟳ PRESTIGE: NEW CAVERN |
| |
| YOU WILL EARN: ~85 Reputation |
| Current total: 0 |
| New total: 85 |
| |
| RESETS: |
| • All structures |
| • All Crystals and Gold |
| • Wave progress (back to Wave 1) |
| • Crystal deposits (cavern regenerates) |
| |
| KEEPS: |
| • All Reputation (permanent) |
| • Skill tree nodes purchased |
| • Permanent bonuses |
| |
| VISUAL CHANGE: |
| • Cavern walls embedded with crystals |
| • Dwarven banners appear |
| |
| Estimated Run 2 time: 15 min |
| (vs 30 min first run) |
| |
| [CANCEL] [PRESTIGE!] |
+------------------------------------------+
```
- **Dimensions**: 450px width × 400px height (centered modal)
- **Background**: #1A120B with gold border (3px solid #FFD700)
- **Icon**: ⟳ (28px, pulsing gold) in top-left
- **Title**: Bold 22px, gold text (#FFD700)
- **Sections**: Labeled with uppercase headers (brown text)
- **Buttons**:
- [CANCEL]: Left, brown background (#3D2B1F), hover darkens
- [PRESTIGE!]: Right, gold background (#FFD700) with black text, pulsing glow (scale 1.0-1.05 every 1s)
- **Animations**:
- Fade in from black (0.5s)
- Gold particles float upward when visible (CSS animation)
- On [PRESTIGE!] click: Screen flash white → Cavern collapses animation (rocks fall) → Fade to black → "NEW CAVERN DISCOVERED" text → Fade in to fresh game state with new visual flair
### Skill Tree Renderer
**How to render the skill tree in HTML/CSS**:
- **Layout approach**: CSS Flexbox with 3 columns (one per branch) + root node at top
- **Flex structure**:
```css
.skill-tree {
display: flex;
flex-direction: column;
align-items: center;
gap: 30px;
padding: 20px;
}
.branch-row {
display: flex;
justify-content: center;
gap: 60px;
}
.node {
position: relative;
width: 60px;
height: 60px;
border-radius: 50%;
/* Flex center icon + name */
}
```
- **Node size**: 60px diameter circular nodes (30px radius)
- **Connection lines**: SVG overlay (positioned absolute behind nodes). Draw paths using `<path>` elements with `d` attribute specifying curved cubic bezier lines. Or use CSS borders on rotated divs for straight lines.
- **Node states**:
- **Locked**: Opacity 0.4, dashed gray border 2px, lock icon center, cost/effect hidden
- **Available**: Solid branch color border 2px, semi-transparent background (20% opacity), cost in gold text, pulsing glow (opacity 0.6↔1.0 every 2s), small "BUYABLE" indicator top-right
- **Purchased**: Solid branch color background, checkmark icon (✓), gold border 3px, connection lines to parent light up with animated gradient (stroke-dashoffset animation), "MASTERED" in gold text below
- **Cannot afford**: Same as available BUT cost text red (#D32F2F), border solid red 2px, no pulsing, dimmer (70% opacity), "NOT ENOUGH POINTS" indicator red
- **Branch colors**: Mining Master (#4FC3F7 cyan), Defense Expert (#FF5252 orange), Specialist Engineer (#E040FB purple)
- **Responsive behavior**:
- Desktop (≥1280px): All 3 columns side-by-side
- No collapse below 1280px (hard requirement)
### Tooltip
```
+----------------------------------+
| Drill Speed (Level 2/5) |
| Increases crystal spawn rate |
| Current: +20% |
| Next level: +25% |
| Cost: 100 Gold |
+----------------------------------+
```
- **Dimensions**: Max 220px width, auto height (padding 10px)
- **Background**: #3D2B1F with border 1px solid #8D6E63, border-radius 4px
- **Arrow**: Small triangle pointing to hovered element (CSS ::before)
- **Trigger**: Hover (desktop) with 200ms delay before showing
- **Position**: Above element by default, clamped to viewport edges (if too close to top, show below instead)
- **Z-index**: 1000 (above all other UI)
- **Animation**: Fade in 0.2s (ease-out)
## Feedback Systems
### Visual Feedback Catalog
| Action | Canvas Feedback | UI Feedback | Duration |
|--------|----------------|-------------|----------|
| **Enemy defeated** | Death animation (fade out + spark sprite burst), floating "+5 Gold" | Gold counter pulses, count-up animation | 500ms |
| **Wave completed** | Brief screen flash (white 30% opacity), all enemies gone, "Wave Complete!" text center Canvas | Toast "Wave X Complete!", wave counter increments | 1s |
| **Crystal collected** | Sprite scales up → fades out, floating "+1" cyan text, sparkle particles | Crystal counter animates count-up, glows white | 300ms |
| **Gold coin collected** | Coin scales up → fades out, floating "+3" gold text | Gold counter animates count-up, glows white | 300ms |
| **Purchase upgrade** | If upgrade affects entities (e.g., drill speed), all relevant structures glow white briefly | Upgrade card flashes cyan, cost deducted animation, particle burst from button | 300ms |
| **Cannot afford click** | N/A | Card shakes, cost flashes red | 200ms |
| **Structure placed** | Sprite appears with flash white (200ms), puff of smoke particles (spark sprites), placement sound visual | Structure counter updates, DP bar fills | 300ms |
| **Structure destroyed** | Explosion particles (10+ sparks), sprite disappears, floating "DESTROYED" red text | Toast "Structure destroyed!", repair button appears if affordable | 1s |
| **New unlock** | N/A | Tab glow/pulse, notification dot, toast "Bats Unlocked!" | Until clicked |
| **Prestige** | Canvas transition: cavern fades to black, rocks fall animation, new cavern fades in with crystals in walls | Screen flash, transition modal, "NEW CAVERN" text | 2-3s |
| **Skill node purchased** | If skill affects Canvas (e.g., auto-collector), visual effect appears on relevant entities | Node fills with branch color, connections light up (gradient flow), ripple effect from center | 500ms |
| **Enemy takes damage** | Sprite flashes white briefly (100ms), floating damage number in red/white | N/A | 200ms |
| **Golem boss defeated** | Dramatic death: scale up 3x, massive particle explosion (30+ sparks), screen shake, "+100 Gold" floats | Boss toast appears, achievement notification if first kill | 2s |
| **Priority target set** | Red reticle appears around enemy, pulsing glow | N/A (reticle is visual feedback) | Until enemy dies or cancelled |
| **Wave incoming** | "Wave X incoming!" text top center of Canvas, spawn indicators pulse at right edge | Wave counter updates, toast if boss wave | 2s before wave |
### Number Formatting Rules
| Range | Format | Example |
|-------|--------|---------|
| 0 - 999 | Whole number | 742 |
| 1,000 - 999,999 | With commas | 12,345 |
| 1M - 999.9M | Suffix | 1.5M |
| 1B - 999.9B | Suffix | 42.3B |
| 1T+ | Suffix | 1.2T |
| Rates (/sec) | 1 decimal place, + sign prefix | +12.3/s |
| Costs (negative) | - sign prefix | -5.0/s |
| Damage numbers (Canvas) | Whole number, no commas | -15 |
### Progress Bars
- **Style**: Rounded corners (border-radius: 4px), horizontal orientation, solid fill with subtle inner glow (box-shadow inset)
- **Colors**:
- 0-49%: Red gradient (#D32F2F → #FF5252)
- 50-79%: Yellow/gold gradient (#FFB74D → #FFD700)
- 80-100%: Green-cyan gradient (#69F0AE → #4FC3F7)
- **Fill animation**: Smooth transition over 200ms (ease-out)
- **Label**: Percentage (85%) on right side, Current/Max (15/20 DP) on left side, both visible simultaneously
- **Background**: Dark brown (#3D2B1F) with 50% opacity
- **Height**: 16px (standard), 24px (prominent bars like DP cap), 8px (entity HP bars)
- **Special variants**:
- **DP bar**: Shows current/cap with segmented fill (each segment = 1 DP), brown color, glows when near cap
- **Wave progress bar**: Appears below HUD bar during wave, shows enemies remaining vs total, red color
- **Structure HP**: Mini bars above entities, color-coded by health %
## Responsive Considerations
- **Minimum width**: 1280px (hard requirement — game shows "Please resize your browser to at least 1280px width" message if smaller)
- **Maximum width**: Full viewport (no cap), but central Canvas max-width: 1600px for playability on ultra-wide monitors (side margins added)
- **Scaling approach**: Fixed px for critical UI elements (buttons, cards), rem/em for text (16px base font size), viewport units (vw/vh) for Canvas and panel heights
- **Panel collapse behavior**: Bottom panel can be collapsed to give Canvas more space during intense waves. On all viewports, collapse button available. Default state: expanded (so players see upgrades), but game suggests collapsing during boss waves.
## Accessibility
- **Contrast ratios**: All text meets WCAG AA minimum 4.5:1 (verified: #E8DCC8 on #1A120B = 12.8:1, #A89F91 on #2D1F14 = 6.5:1, #4FC3F7 on #2D1F14 = 7.2:1)
- **Focus indicators**: Visible focus outlines for keyboard navigation (2px solid #4FC3F7 cyan outline on focused elements)
- **Screen reader**: Currency amounts have `aria-live="polite"` regions for updates (announces changes to screen readers without interrupting)
- **Reduced motion**: Respect `prefers-reduced-motion` media query — disable all Canvas animations (sprite frame cycling, particle effects, floating numbers) and UI pulses if set, show static sprites instead
- **Keyboard navigation**: Full keyboard support — Tab through interactive elements, Enter/Space to activate, Escape to close modals, Arrow keys to navigate skill tree
- **Color blindness**: Avoid relying solely on color — use icons + text labels for all currency types (💎 Crystals, 🪙 Gold, 🛡️ DP), entity states (health bar + damaged sprite visuals), crystal types (shape + color: blue/red/purple diamonds)
- **Font scaling**: Support 200% text zoom without breaking layout (use relative units where possible, max-width constraints on containers)
## Settings Panel
| Setting | Type | Default | Effect |
|---------|------|---------|--------|
| **Notation format** | Toggle (Standard/Scientific) | Standard | Changes number display: 1,234 vs 1.234e3 |
| **Animation speed** | Slider (0.5x - 2x) | 1x | Scales all animation durations and Canvas game speed (entity movement, projectile speed, crystal drift) |
| **Auto-save interval** | Dropdown | 30s | How often game state saves to localStorage (options: 15s, 30s, 60s, Off) |
| **Canvas quality** | Toggle (High/Low) | High | Low disables glow effects and particles for performance (no spark bursts, no crystal trails, no structure glow on upgrade) |
| **Hard reset** | Button (with confirmation) | N/A | Wipe all data including Reputation, shows warning: "⚠️ This will delete ALL progress including prestiges. Are you sure?" |
| **Export save** | Button | N/A | Copy save string to clipboard, shows toast "Save copied to clipboard!" |
| **Import save** | Button + Textarea | N/A | Paste save string, validates and loads, shows error if invalid |
| **Show placement grid** | Toggle (On/Off) | On | Shows/hides subtle grid lines on Canvas for structure placement |
| **Crystal collection auto-fade** | Toggle (On/Off) | On | If On, crystal sprites fade out at 5s. If Off, crystals stay until clicked (cheats, not recommended) |
**Settings Modal**:
- Dimensions: 450px × 380px centered
- Background: #2D1F14 with border 2px solid #3D2B1F
- Sections: "Display", "Gameplay", "Data"
- Close button: × (top-right, 24px)
- Applies changes immediately (except hard reset, which requires confirmation modal)