Currencies
{
"gameName": "Stream Valley Garden",
"version": "1.0",
"lastUpdated": "2026-02-10",
"diagrams": {
"economyFlow": {
"title": "Economy Flow Diagram",
"mermaid": "flowchart LR\n subgraph \"Sources (Gameplay - Canvas Actions)\"\n Harvest[\"Harvest Crops\\nSeeds: baseYield * quality\\nBiomass: 5 per mature plant\"]\n Lifecycle[\"Let Plant Complete Cycle\\nBiomass: 15 per plant\\nSeeds: 2-4 auto-sown\"]\n PestKill[\"Click to Squish Pest\\nBiomass: +2 per pest\"]\n BeePollinate[\"Bee Pollination Event\\nBiomass: +8 per pollination\"]\n LadybugEat[\"Ladybug Eating Pest\\nBiomass: +5 per pest eaten\"]\n CatchButterfly[\"Catch Butterfly\\nKnowledge: +10 per species\"]\n end\n subgraph \"Sources (Passive/Environmental)\"\n FlowGen[\"Water Flow Through Redirectors\\nFlowEnergy: 0.5 per water droplet\"]\n EfficientFlow[\"Efficient Flow Pattern Bonus\\nFlowEnergy: +25 per elegant design\"]\n Discovery[\"First-Time Discovery\\nKnowledge: +5-50 per discovery\"]\n Biodiversity[\"Biodiversity Bonus\\nSeeds: +10 per 5 species\"]\n end\n subgraph \"Currencies\"\n Seeds((\"Seeds\\nPrimary\\nstart: 10\\nuncapped))\n Biomass((\"Biomass\\nSecondary\\nstart: 0\\nuncapped))\n FlowEnergy((\"Flow Energy\\nTertiary\\nstart: 0\\ncap: 100))\n Knowledge((\"Knowledge\\nPrestige\\nstart: 0\\nuncapped\\npersists))\n end\n subgraph \"Sinks (Planting & Growth)\"\n PlantCrops[\"Plant Seeds\\nCost: 1-5 seeds per crop\"]\n CrossBreed[\"Cross-Breeding\\nCost: 10 seeds + 5 biomass\"]\n Fertilize[\"Fertilize Soil\\nCost: 3 biomass\"]\n end\n subgraph \"Sinks (Ecosystem)\"\n BuyBee[\"Purchase Bee Hive\\nCost: 25 biomass\"]\n BuyLadybug[\"Purchase Ladybug\\nCost: 15 biomass\"]\n ExpandTerrace[\"Unlock New Terrace\\nCost: 50 biomass + 20 FlowEnergy\"]\n Terraform[\"Terraform Tool\\nCost: 10-30 FlowEnergy\"]\n end\n subgraph \"Sinks (Special Actions)\"\n CallRain[\"Call Rain Cloud\\nCost: 15 FlowEnergy\"]\n FloodControl[\"Emergency Flood Control\\nCost: 20 FlowEnergy\"]\n BuyRedirector[\"Unlock Redirector Types\\nCost: 5-20 biomass\"]\n end\n subgraph \"Sinks (Prestige)\"\n KnowledgeUpgrade[\"Permanent Seed Bonus\\nCost: 10 Knowledge\"]\n RedirectorEfficiency[\"Permanent Flow Efficiency\\nCost: 25 Knowledge\"]\n CreatureLifespan[\"Creature Longevity\\nCost: 20 Knowledge\"]\n TerraceFertility[\"Starting Soil Quality\\nCost: 30 Knowledge\"]\n end\n subgraph \"Conversions\"\n SeedToBiomass[\"Convert Seeds to Biomass\\n10 Seeds → 3 Biomass\"]\n BiomassToSeeds[\"Convert Biomass to Seeds\\n5 Biomass → 15 Seeds\"]\n end\n\n Harvest --> Seeds\n Harvest --> Biomass\n Lifecycle --> Biomass\n PestKill --> Biomass\n BeePollinate --> Biomass\n LadybugEat --> Biomass\n CatchButterfly --> Knowledge\n FlowGen --> FlowEnergy\n EfficientFlow --> FlowEnergy\n Discovery --> Knowledge\n Biodiversity --> Seeds\n \n Seeds --> PlantCrops\n Seeds --> CrossBreed\n Seeds --> SeedToBiomass\n Biomass --> CrossBreed\n Biomass --> Fertilize\n Biomass --> BuyBee\n Biomass --> BuyLadybug\n Biomass --> BuyRedirector\n Biomass --> ExpandTerrace\n Biomass --> BiomassToSeeds\n FlowEnergy --> ExpandTerrace\n FlowEnergy --> CallRain\n FlowEnergy --> FloodControl\n FlowEnergy --> Terraform\n Knowledge --> KnowledgeUpgrade\n Knowledge --> RedirectorEfficiency\n Knowledge --> CreatureLifespan\n Knowledge --> TerraceFertility\n \n SeedToBiomass --> Biomass\n BiomassToSeeds --> Seeds"
},
"currencyDefinitions": {
"title": "Currency Definitions",
"mermaid": "graph TD\n subgraph \"Seeds [Primary Currency]\"\n S_display[\"Display: 🌱 Seeds\\n0 decimals\\nSuffixes: K/M/B\"]\n S_earn[\"Earning:\\nHarvest crop: baseYield * qualityMultiplier\\nBiodiversity bonus: +10 per 5 species\\nConvert from Biomass: 5 Biomass → 15 Seeds\"]\n S_spend[\"Spending:\\nPlant crops: 1-5 seeds each\\nCross-breeding: 10 seeds\\nConvert to Biomass: 10 Seeds → 3 Biomass\"]\n S_inflation[\"Inflation Control:\\nCrop costs scale with plant rarity\\nCross-breeding costs increase\\nBiomass conversion drain\"]\n end\n \n subgraph \"Biomass [Secondary Currency]\"\n B_display[\"Display: 🌿 Biomass\\n0 decimals\\nSuffixes: K/M/B\"]\n B_earn[\"Earning:\\nHarvest mature: +5 per crop\\nLet cycle complete: +15 per plant\\nPest squished: +2\\nBee pollination: +8 per event\\nLadybug eats pest: +5\\nConvert from Seeds: 10 Seeds → 3 Biomass\"]\n B_spend[\"Spending:\\nBuy bee hive: 25 biomass\\nBuy ladybug: 15 biomass\\nUnlock redirectors: 5-20 biomass\\nFertilize soil: 3 biomass\\nTerrace expansion: 50 biomass\\nConvert to Seeds: 5 Biomass → 15 Seeds\"]\n B_inflation[\"Inflation Control:\\nCreature costs scale (1.2^count)\\nRedirector costs increase\\nExpansion costs per terrace\"]\n end\n \n subgraph \"Flow Energy [Tertiary Currency]\"\n F_display[\"Display: 💧 Flow Energy\\n0 decimals\\nSuffixes: none (capped)\\nCap: 100 (display bar)\"]\n F_earn[\"Earning:\\nWater flow: +0.5 per droplet\\nEfficient pattern: +25 per bonus\\nPassive generation from redirectors: base * redirectorLevel/sec\"]\n F_spend[\"Spending:\\nCall rain: 15 FlowEnergy\\nFlood control: 20 FlowEnergy\\nTerraform tools: 10-30 FlowEnergy\\nTerrace expansion: 20 FlowEnergy\"]\n F_inflation[\"Inflation Control:\\nHard cap at 100 creates urgency\\nAbility costs scale with use (1.1^uses)\\nMust spend to continue earning\"]\n end\n \n subgraph \"Knowledge [Prestige Currency]\"\n K_display[\"Display: 📚 Knowledge\\n0 decimals\\nSuffixes: none\\nPersists on Prestige: YES\"]\n K_earn[\"Earning:\\nFirst discovery: +5-50\\nCatch butterfly: +10 per species\\nComplete achievements: +10-100\\nPrestige milestone: +100 base + 50 per biodiversity level\"]\n K_spend[\"Spending:\\nSeed starting bonus: 10 Knowledge\\nRedirector efficiency: 25 Knowledge\\nCreature lifespan: 20 Knowledge\\nTerrace fertility: 30 Knowledge\\nUnlock rare species: 15-50 Knowledge\"]\n K_inflation[\"Inflation Control:\\nUpgrade costs scale (1.3^level)\\nDiscovery sources diminish (first-time only)\\nPrestige gives diminishing returns\"]\n end"
},
"conversionRates": {
"title": "Conversion Rate Diagram",
"mermaid": "flowchart LR\n Seeds[\"Seeds\\n(10)\"] -->|\"10:3 ratio\\nUnlocked at: 50 Seeds\\nNo cooldown\\nMax: 5 per batch\"| Biomass1[\"Biomass\\n(3)\"]\n Biomass2[\"Biomass\\n(5)\"] -->|\"5:15 ratio\\nUnlocked at: 25 Biomass\\nNo cooldown\\nMax: 3 per batch\"| Seeds1[\"Seeds\\n(15)\"]\n \n note1[\"Strategic Decision:\\nConvert Seeds → Biomass when creature\\nneeded immediately\\nConvert Biomass → Seeds when\\nplanting bulk crops\"]\n \n Seeds --- note1\n Biomass2 --- note1\n Biomass1 --- note1"
},
"pacingTimeline": {
"title": "Currency Pacing Timeline (First 30 Minutes)",
"mermaid": "gantt\n title Currency Pacing (First 30 Minutes)\n dateFormat mm:ss\n axisFormat %M:%S\n\n section Seeds Milestones\n First crop affordable (1 Seed) :milestone, 00:05, 0\n First harvest (5-8 Seeds) :milestone, 00:45, 0\n Cross-breeding unlocked (10 Seeds) :milestone, 02:30, 0\n Polyculture viable (50 Seeds) :milestone, 05:00, 0\n Mid-game abundance (500 Seeds) :milestone, 12:00, 0\n Pre-prestige (5K Seeds) :milestone, 25:00, 0\n\n section Biomass Milestones\n First ladybug (15 Biomass) :milestone, 03:00, 0\n First bee hive (25 Biomass) :milestone, 04:30, 0\n Terrace 2 unlock (50 Biomass) :milestone, 07:00, 0\n Creature army (200 Biomass) :milestone, 15:00, 0\n Terrace 4 unlock (400 Biomass) :milestone, 22:00, 0\n\n section Flow Energy Milestones\n First redirector (5 FE) :milestone, 01:00, 0\n Call rain unlocked (15 FE) :milestone, 02:00, 0\n Terraforming unlocked (10 FE) :milestone, 04:00, 0\n Flow cap hit (100 FE) :milestone, 06:00, 0\n Efficient flow mastery :milestone, 18:00, 0\n\n section Knowledge Milestones\n First discovery (5 Knowledge) :milestone, 01:30, 0\n Catch first butterfly (10 Knowledge) :milestone, 08:00, 0\n Unlock rare species (15 Knowledge) :milestone, 10:00, 0\n First permanent upgrade (10 Knowledge) :milestone, 14:00, 0\n Prestige unlocked (100 Knowledge) :milestone, 28:00, 0"
},
"upgradeCostCurves": {
"title": "Upgrade Cost Curves",
"mermaid": "graph LR\n subgraph \"Creature Purchases (One-Time, Scaling Costs)\"\n C1[\"Ladybug #1\\nCost: 15 Biomass\\nLifespan: 30 pests\"]\n C2[\"Ladybug #3\\nCost: 22 Biomass\\nLifespan: 30 pests\"]\n C3[\"Ladybug #5\\nCost: 31 Biomass\\nLifespan: 30 pests\"]\n C4[\"Ladybug #10\\nCost: 78 Biomass\\nLifespan: 30 pests\"]\n C1 --> C2 --> C3 --> C4\n end\n \n subgraph \"Bee Hive Upgrades (Level-Based)\"\n B1[\"Level 1\\nCost: 25 Biomass\\nBees: 2\\nPollination rate: 1 per 5 sec\"]\n B2[\"Level 3\\nCost: 45 Biomass\\nBees: 4\\nPollination rate: 1 per 3 sec\"]\n B3[\"Level 5\\nCost: 81 Biomass\\nBees: 6\\nPollination rate: 1 per 2 sec\"]\n B4[\"Level 10\\nCost: 307 Biomass\\nBees: 12\\nPollination rate: 1 per 1 sec\"]\n B1 --> B2 --> B3 --> B4\n end\n \n subgraph \"Redirector Unlocks (One-Time)\"\n R1[\"Basic Channel\\nCost: 5 Biomass\\nShape: Straight\"]\n R2[\"90° Turn\\nCost: 8 Biomass\\nShape: L-bend\"]\n R3[\"Splitter\\nCost: 12 Biomass\\nShape: Y-split\"]\n R4[\"Dam\\nCost: 18 Biomass\\nShape: Wall\"]\n R5[\"Pump\\nCost: 20 Biomass\\nShape: Upslope\"]\n R1 --> R2 --> R3 --> R4 --> R5\n end\n \n subgraph \"Terrace Expansions (Scaling Per Terrace)\"\n T1[\"Terrace 2\\nCost: 50 Biomass + 20 FE\\nTiles: 12\"]\n T2[\"Terrace 3\\nCost: 100 Biomass + 25 FE\\nTiles: 15\"]\n T3[\"Terrace 4\\nCost: 150 Biomass + 30 FE\\nTiles: 18\"]\n T4[\"Terrace 5 (Summit)\\nCost: 250 Biomass + 50 FE\\nTiles: 24\"]\n T1 --> T2 --> T3 --> T4\n end\n \n subgraph \"Permanent Knowledge Upgrades (Prestige)\"\n K1[\"Seed Starting Bonus\\nLevel 1: +5 starting seeds\\nCost: 10 Knowledge\"]\n K2[\"Seed Starting Bonus\\nLevel 3: +15 starting seeds\\nCost: 22 Knowledge\"]\n K3[\"Seed Starting Bonus\\nLevel 5: +25 starting seeds\\nCost: 48 Knowledge\"]\n K4[\"Redirector Efficiency\\nLevel 1: +10% flow generation\\nCost: 25 Knowledge\"]\n K5[\"Creature Lifespan\\nLevel 1: +20% creature lifespan\\nCost: 20 Knowledge\"]\n K1 --> K2 --> K3\n K4\n K5\n end"
},
"collectibleStateMachines": {
"title": "Collectible Entity State Machines",
"mermaid": "stateDiagram-v2\n [*] --> Spawning: crop harvested / plant cycled\n Spawning --> Active: spawn animation (200ms)\n Active --> Collected: player clicks within radius\n Active --> Expired: lifetime exceeded (8s)\n Active --> Magnetized: collector upgrade active\n Magnetized --> Collected: reaches player (300ms)\n Collected --> [*]: add currency + floating text\n Expired --> [*]: fade out (500ms)\n\n note right of Active\n Visual: bob animation (2px amplitude, 2Hz)\n Glowing effect based on value\n Clickable radius: 20px\n Sprite: seed packet with quantity label\n Sound: none (spawn)\n end note\n\n note right of Collected\n Triggers: currency.add('seeds', value)\n Triggers: floatingText(\"+{value} Seeds\", color)\n Triggers: particle burst (3 particles)\n Sound: collect_seed.mp3\n end note\n\n stateDiagram-v2\n [*] --> Spawning: creature action (pollination, pest eat)\n Spawning --> Active: spawn animation (150ms)\n Active --> Collected: auto-collect (no click)\n Active --> Expired: lifetime exceeded (5s)\n Collected --> [*]: add biomass + UI update\n Expired --> [*]: fade out (300ms)\n\n note right of Active\n Visual: spiral upward motion\n Green glow effect\n Auto-collect radius: entire screen\n Sprite: green leaf particle\n No player interaction needed\n end note\n\n note right of Collected\n Triggers: currency.add('biomass', value)\n Triggers: floatingText(\"+{value} Biomass\", position)\n Sound: biomass_gain.mp3 (subtle)\n end note\n\n stateDiagram-v2\n [*] --> Spawning: water passes redirector\n Spawning --> Active: instant (no animation)\n Active --> Collected: auto-collect immediately\n Collected --> [*]: add FlowEnergy + cap check\n\n note right of Active\n Visual: blue sparkles at redirector\n No lifetime (instant collect)\n No click interaction\n Sprite: droplet sparkle\n end note\n\n note right of Collected\n Triggers: currency.add('flowEnergy', 0.5)\n Triggers: updateFlowBar()\n Triggers: checkCapAndDisplayWarning()\n Sound: flow_energy.mp3 (soft)\n end note"
},
"currencyEventFlows": {
"title": "Currency Event Flow Diagrams",
"mermaid": "sequenceDiagram\n participant Canvas as Canvas (Game World)\n participant Entity as Entity System\n participant Currency as CurrencyManager\n participant UI as HUD Display\n participant EventBus as EventBus\n\n Canvas->>Entity: player.click(crop)\n Entity->>Entity: crop.isMature() → true\n Entity->>Canvas: harvest animation (scale 1→0, 300ms)\n Entity->>EventBus: emit('crop-harvested', {type, position, yield})\n EventBus->>Currency: currency.add('seeds', yield.seeds)\n EventBus->>Currency: currency.add('biomass', yield.biomass)\n EventBus->>Canvas: spawnCollectible({type: 'seedPacket', position, value: yield.seeds})\n Canvas->>Canvas: collectible spawns with pop-in (200ms)\n Note over Canvas: Player clicks collectible OR auto-collect\n Canvas->>EventBus: emit('collectible-collected', {type, value, position})\n EventBus->>Currency: currency.add('seeds', value)\n EventBus->>UI: floatingText(\"+{value} Seeds\", position)\n EventBus->>UI: updateDisplay('seeds')\n UI->>UI: count-up animation (200ms)\n\n sequenceDiagram\n participant Canvas as Canvas (Game World)\n participant Creature as Creature System\n participant Currency as CurrencyManager\n participant UI as HUD Display\n participant EventBus as EventBus\n\n Canvas->>Creature: bee reaches flower\n Creature->>Creature: flower.pollinate()\n Creature->>Canvas: pollination particles (golden dust)\n Creature->>EventBus: emit('bee-pollinated', {position, value: 8})\n EventBus->>Currency: currency.add('biomass', 8)\n EventBus->>Canvas: spawnCollectible({type: 'biomassParticle', position, value: 8})\n Canvas->>Canvas: particle spirals upward (500ms)\n Canvas->>EventBus: emit('biomass-collected', {value, position})\n EventBus->>UI: floatingText(\"+8 Biomass\", position)\n EventBus->>UI: updateDisplay('biomass')\n\n sequenceDiagram\n participant Canvas as Canvas (Game World)\n participant Water as Water System\n participant Currency as CurrencyManager\n participant UI as Flow Bar\n participant EventBus as EventBus\n\n Canvas->>Water: water droplet passes redirector\n Water->>Water: redirector.generateEnergy()\n Water->>EventBus: emit('flow-generated', {amount: 0.5, position})\n EventBus->>Currency: currency.add('flowEnergy', 0.5)\n EventBus->>Canvas: spawnVisualEffect({type: 'sparkle', position})\n EventBus->>UI: updateFlowBar()\n UI->>UI: bar fills with animation (100ms)\n UI->>UI: checkCapAndWarn()\n\n sequenceDiagram\n participant Canvas as Canvas (Game World)\n participant Player as Player Action\n participant Currency as CurrencyManager\n participant EventBus as EventBus\n participant UI as HUD Display\n\n Canvas->>Player: player clicks butterfly\n Player->>Player: catch skill check (timing)\n Player->>Canvas: butterfly capture animation\n Player->>EventBus: emit('butterfly-caught', {species, position})\n EventBus->>Currency: currency.add('knowledge', 10)\n EventBus->>UI: floatingText(\"+10 Knowledge - New Species!\", position)\n EventBus->>UI: updateDisplay('knowledge')\n EventBus->>Canvas: showUnlockNotification({species})"
}
},
"config": {
"currencies": {
"seeds": {
"displayName": "Seeds",
"icon": "🌱",
"startingAmount": 10,
"cap": null,
"decimals": 0,
"suffixes": [
"K",
"M",
"B",
"T"
]
},
"biomass": {
"displayName": "Biomass",
"icon": "🌿",
"startingAmount": 0,
"cap": null,
"decimals": 0,
"suffixes": [
"K",
"M",
"B",
"T"
]
},
"flowEnergy": {
"displayName": "Flow Energy",
"icon": "💧",
"startingAmount": 0,
"cap": 100,
"decimals": 0,
"suffixes": [],
"showAsBar": true,
"barColor": "#4FC3F7"
},
"knowledge": {
"displayName": "Knowledge",
"icon": "📚",
"startingAmount": 0,
"cap": null,
"decimals": 0,
"suffixes": [],
"persistsOnPrestige": true
}
},
"currencySources": {
"harvestCrop": {
"currencies": {
"seeds": {
"formula": "baseYield * qualityMultiplier * (1 + 0.05 * biodiversityLevel)",
"baseYield": 5
},
"biomass": {
"formula": "5 * qualityMultiplier",
"baseValue": 5
}
}
},
"lifecycleComplete": {
"currencies": {
"biomass": {
"formula": "15 * qualityMultiplier",
"baseValue": 15
},
"seeds": {
"formula": "randInt(2, 4) * crossBreedChance",
"baseValue": 3
}
}
},
"pestSquish": {
"currencies": {
"biomass": {
"formula": "2",
"baseValue": 2
}
}
},
"beePollination": {
"currencies": {
"biomass": {
"formula": "8 * pollinationChain",
"baseValue": 8,
"maxChainBonus": 2
}
}
},
"ladybugEat": {
"currencies": {
"biomass": {
"formula": "5 * creatureEfficiencyMultiplier",
"baseValue": 5
}
}
},
"waterFlow": {
"currencies": {
"flowEnergy": {
"formula": "0.5 * redirectorEfficiency * globalMultiplier",
"baseValue": 0.5
}
}
},
"efficientFlowBonus": {
"currencies": {
"flowEnergy": {
"formula": "25 * eleganceScore",
"baseValue": 25,
"cooldown": 30
}
}
},
"butterflyCatch": {
"currencies": {
"knowledge": {
"formula": "10 * speciesRarity",
"baseValue": 10,
"maxRarity": 3
}
}
},
"firstDiscovery": {
"currencies": {
"knowledge": {
"formula": "baseValue * discoveryType",
"baseValue": 5,
"types": {
"newPlant": 1,
"newCreature": 2,
"newPattern": 3,
"rareSpecies": 5
}
}
}
},
"biodiversityBonus": {
"currencies": {
"seeds": {
"formula": "floor(speciesCount / 5) * 10",
"baseValue": 10,
"triggerThreshold": 5
}
}
}
},
"collectibles": {
"seedPacket": {
"sprite": "seedPacket",
"scale": 1.2,
"lifetime": 8,
"collectRadius": 20,
"bobAmplitude": 2,
"bobSpeed": 2,
"spawnAnimation": "popIn",
"spawnDuration": 200,
"collectAnimation": "burst",
"particleCount": 3,
"requiresClick": true,
"magnetizable": true,
"magnetRange": 80
},
"biomassParticle": {
"sprite": "leaf",
"scale": 0.8,
"lifetime": 5,
"collectRadius": 999,
"motionType": "spiralUp",
"spiralSpeed": 100,
"spawnAnimation": "fadeScale",
"spawnDuration": 150,
"collectAnimation": "none",
"requiresClick": false,
"autoCollect": true
},
"flowSparkle": {
"sprite": "sparkle",
"scale": 0.6,
"lifetime": 0.5,
"collectRadius": 999,
"motionType": "static",
"spawnAnimation": "instant",
"collectAnimation": "none",
"requiresClick": false,
"autoCollect": true
},
"knowledgeStar": {
"sprite": "star",
"scale": 1.5,
"lifetime": 3,
"collectRadius": 999,
"motionType": "floatUp",
"floatSpeed": 60,
"spawnAnimation": "burstIn",
"spawnDuration": 400,
"collectAnimation": "none",
"requiresClick": false,
"autoCollect": true
}
},
"upgradeCosts": {
"planting": {
"wheat": {
"baseCost": 1,
"costMultiplier": 1,
"currency": "seeds"
},
"tomato": {
"baseCost": 2,
"costMultiplier": 1,
"currency": "seeds"
},
"berries": {
"baseCost": 3,
"costMultiplier": 1,
"currency": "seeds"
},
"pumpkin": {
"baseCost": 4,
"costMultiplier": 1,
"currency": "seeds"
},
"rareSpecies": {
"baseCost": 5,
"costMultiplier": 1,
"currency": "seeds"
}
},
"creatures": {
"ladybug": {
"baseCost": 15,
"costMultiplier": 1.1,
"currency": "biomass"
},
"beeHive": {
"baseCost": 25,
"costMultiplier": 1.15,
"currency": "biomass"
}
},
"creatureUpgrades": {
"beeHiveLevel": {
"baseCost": 25,
"costMultiplier": 1.25,
"currency": "biomass"
},
"ladybugLifespan": {
"baseCost": 20,
"costMultiplier": 1.3,
"currency": "biomass"
}
},
"redirectors": {
"basicChannel": {
"baseCost": 5,
"costMultiplier": 1,
"currency": "biomass",
"oneTime": true
},
"turn90": {
"baseCost": 8,
"costMultiplier": 1,
"currency": "biomass",
"oneTime": true
},
"splitter": {
"baseCost": 12,
"costMultiplier": 1,
"currency": "biomass",
"oneTime": true
},
"dam": {
"baseCost": 18,
"costMultiplier": 1,
"currency": "biomass",
"oneTime": true
},
"pump": {
"baseCost": 20,
"costMultiplier": 1,
"currency": "biomass",
"oneTime": true
}
},
"terraforming": {
"callRain": {
"baseCost": 15,
"costMultiplier": 1.1,
"currency": "flowEnergy"
},
"floodControl": {
"baseCost": 20,
"costMultiplier": 1.15,
"currency": "flowEnergy"
},
"terraformBasic": {
"baseCost": 10,
"costMultiplier": 1,
"currency": "flowEnergy"
},
"terraformAdvanced": {
"baseCost": 30,
"costMultiplier": 1,
"currency": "flowEnergy"
}
},
"terraces": {
"terrace2": {
"baseCost": {
"biomass": 50,
"flowEnergy": 20
},
"costMultiplier": 1,
"oneTime": true
},
"terrace3": {
"baseCost": {
"biomass": 100,
"flowEnergy": 25
},
"costMultiplier": 1,
"oneTime": true
},
"terrace4": {
"baseCost": {
"biomass": 150,
"flowEnergy": 30
},
"costMultiplier": 1,
"oneTime": true
},
"terrace5": {
"baseCost": {
"biomass": 250,
"flowEnergy": 50
},
"costMultiplier": 1,
"oneTime": true
}
},
"crossBreeding": {
"basic": {
"baseCost": {
"seeds": 10,
"biomass": 5
},
"costMultiplier": 1,
"currency": "mixed"
},
"advanced": {
"baseCost": {
"seeds": 20,
"biomass": 15
},
"costMultiplier": 1,
"currency": "mixed"
}
},
"permanent": {
"seedStartingBonus": {
"baseCost": 10,
"costMultiplier": 1.3,
"currency": "knowledge"
},
"redirectorEfficiency": {
"baseCost": 25,
"costMultiplier": 1.3,
"currency": "knowledge"
},
"creatureLifespan": {
"baseCost": 20,
"costMultiplier": 1.3,
"currency": "knowledge"
},
"terraceFertility": {
"baseCost": 30,
"costMultiplier": 1.3,
"currency": "knowledge"
},
"unlockRareSpecies": {
"baseCost": 15,
"costMultiplier": 1.2,
"currency": "knowledge"
}
}
},
"conversions": {
"seedsToBiomass": {
"input": {
"currency": "seeds",
"amount": 10
},
"output": {
"currency": "biomass",
"amount": 3
},
"unlockCondition": "seeds >= 50",
"maxBatchSize": 5,
"cooldown": 0
},
"biomassToSeeds": {
"input": {
"currency": "biomass",
"amount": 5
},
"output": {
"currency": "seeds",
"amount": 15
},
"unlockCondition": "biomass >= 25",
"maxBatchSize": 3,
"cooldown": 0
}
},
"inflationControl": {
"creatureCostScaling": {
"formula": "baseCost * 1.1^(purchasedCount)",
"appliesTo": [
"ladybug",
"beeHive"
]
},
"terraformingCostScaling": {
"formula": "baseCost * 1.1^(useCount)",
"appliesTo": [
"callRain",
"floodControl"
]
},
"upgradeCostScaling": {
"formula": "baseCost * costMultiplier^level",
"appliesTo": [
"beeHiveLevel",
"ladybugLifespan"
]
},
"permanentUpgradeScaling": {
"formula": "baseCost * 1.3^level",
"appliesTo": [
"seedStartingBonus",
"redirectorEfficiency",
"creatureLifespan",
"terraceFertility"
]
}
}
},
"formulas": {
"generatorCost": "baseCost * costMultiplier^level",
"generatorRate": "baseRate * level * globalMultiplier",
"harvestYield": "baseYield * qualityMultiplier * (1 + 0.05 * biodiversityLevel)",
"lifecycleBiomass": "15 * qualityMultiplier",
"pollinationReward": "8 * min(pollinationChain, 2.0)",
"waterFlowEnergy": "0.5 * redirectorEfficiency * globalMultiplier",
"creaturePurchaseCost": "baseCost * 1.1^(purchasedCount)",
"terraformingCost": "baseCost * 1.1^(useCount)",
"conversion": "floor(inputAmount / ratio) * outputAmount",
"biodiversityBonus": "floor(speciesCount / 5) * 10",
"prestigeKnowledge": "100 + (50 * biodiversityLevel) + (10 * achievementsCompleted)"
},
"balanceTargets": [
{
"time": "0:30",
"seeds": 8,
"biomass": 0,
"flowEnergy": 5,
"knowledge": 0,
"event": "First crops planted"
},
{
"time": "1:00",
"seeds": 15,
"biomass": 0,
"flowEnergy": 12,
"knowledge": 0,
"event": "First redirector placed"
},
{
"time": "2:00",
"seeds": 25,
"biomass": 5,
"flowEnergy": 25,
"knowledge": 0,
"event": "First harvest complete"
},
{
"time": "3:00",
"seeds": 20,
"biomass": 15,
"flowEnergy": 35,
"knowledge": 5,
"event": "First discovery"
},
{
"time": "5:00",
"seeds": 50,
"biomass": 40,
"flowEnergy": 50,
"knowledge": 5,
"event": "First ladybug purchased"
},
{
"time": "7:00",
"seeds": 80,
"biomass": 60,
"flowEnergy": 70,
"knowledge": 5,
"event": "Terrace 2 unlocked"
},
{
"time": "10:00",
"seeds": 150,
"biomass": 100,
"flowEnergy": 90,
"knowledge": 15,
"event": "Bee hive active"
},
{
"time": "15:00",
"seeds": 300,
"biomass": 200,
"flowEnergy": 100,
"knowledge": 20,
"event": "Mid-game ecosystem stable"
},
{
"time": "20:00",
"seeds": 600,
"biomass": 350,
"flowEnergy": 100,
"knowledge": 30,
"event": "Rare species unlocked"
},
{
"time": "25:00",
"seeds": 1500,
"biomass": 500,
"flowEnergy": 100,
"knowledge": 50,
"event": "Terrace 4 unlocked"
},
{
"time": "30:00",
"seeds": 5000,
"biomass": 800,
"flowEnergy": 100,
"knowledge": 90,
"event": "Prestige available"
}
],
"edgeCases": [
"Overflow protection: Switch to BigNum at 1e9 for seeds and biomass",
"Negative balance: All purchases check canAfford() before executing",
"Flow Energy cap: At 100, display warning and stop generation until spent",
"First harvest protection: Minimum 5 seeds from first crop to prevent soft-lock",
"Creature death: Ladybugs expire after eating 30 pests, bees last 5 minutes",
"Crop failure: If plant dies before harvest, refund 50% of seed cost",
"Conversion batching: Limit conversions to prevent exploit (max 5 seeds→biomass per batch)",
"Discovery uniqueness: First-time discovery bonus only applies once per species/pattern",
"Prestige validation: Check biodiversity level (10 species) before allowing prestige"
],
"qualityChecklist": [
"Economy flow diagram shows all 4 currencies, all sources, all sinks, and conversions",
"Primary currency (Seeds) earned through harvesting - active Canvas gameplay",
"Secondary currency (Biomass) earned through creature interactions and lifecycle completion",
"Tertiary currency (Flow Energy) earned through water flow - visible Canvas action",
"Prestige currency (Knowledge) earned through discoveries and butterfly catching",
"All formulas are exact and copy-pasteable",
"Conversions create strategic decisions (timing and resource allocation)",
"Pacing timeline shows 30-minute target with meaningful milestones",
"Flow Energy capped at 100 creates scarcity and urgency",
"First 30 seconds generous: 10 starting seeds, first crop costs 1 seed",
"All currencies remain relevant throughout gameplay",
"Consistent variable naming across all formulas",
"Economy forms interconnected web with multiple feedback loops",
"Developers can implement entire economy from diagrams alone",
"Collectible state machines define lifecycle for seed packets, biomass particles, flow sparkles, and knowledge stars",
"Currency event flows show complete chains from harvest, pollination, water flow, and butterfly catch",
"CONFIG.currencies has exact values for all 4 currencies",
"CONFIG.collectibles defines all 4 collectible types with sprites, scales, lifetimes, and radii",
"CONFIG.currencySources defines all 10 earning pathways with formulas and base values",
"CONFIG.upgradeCosts defines all upgrade categories with baseCosts, costMultipliers, and currencies",
"CONFIG.conversions defines both conversion directions with input/output amounts and unlock conditions"
]
}
Progression
{
"gameName": "Stream Valley Garden",
"version": "1.0",
"lastUpdated": "2026-02-10",
"diagrams": {
"unlockFlow": {
"title": "Complete Unlock Flow - 30 Minute Progression",
"mermaid": "flowchart TD\n Start([\"Game Start<br/>0:00\"]) --> FirstEntities([\"🌱 First Crops Visible on Canvas<br/>Water flows automatically<br/>Player can plant wheat immediately\"])\n FirstEntities -->|\"First redirector placed<br/>(~20 sec)\"| FlowGen([\"💧 Flow Energy Generation Begins<br/>Blue sparkles at redirectors<br/>Flow bar fills in HUD\"])\n FirstEntities -->|\"First crop harvested<br/>(~45 sec)\"| FirstHarvest([\"🌾 Harvest Loop Established<br/>Seed packets spawn on Canvas<br/+Seeds floating text\"])\n FlowGen -->|\"5 Flow Energy accumulated<br/>(~1 min)\"| CallRain([\"🔓 Unlock: Call Rain Cloud<br/>New ability button glows<br/>Rain animates across sky\"])\n FirstHarvest -->|\"15 Seeds earned<br/>(~1:30 min)\"| Discovery([\"🔓 First Discovery: '+5 Knowledge'<br/>Toast appears<br/>Knowledge counter revealed in HUD\"])\n FirstHarvest -->|\"25 Seeds accumulated<br/>(~2 min)\"| SecondSeed([\"🔓 Unlock: Tomato Seeds<br/>New red sprite in seed selector<br/>Shows different growth pattern\"])\n CallRain -->|\"First rain event<br/>(~2:30 min)\"| WeatherSystem([\"🔓 Unlock: Weather Events<br/>Clouds drift in background<br/>Puddles form on terraces\"])\n SecondSeed -->|\"5 Biomass from harvests<br/>(~3 min)\"| BiomassReveal([\"🔓 Unlock: Biomass Currency<br/>🌿 appears in HUD<br/>New currency bar animates in\"])\n BiomassReveal -->|\"15 Biomass reached<br/>(~4 min)\"| LadybugUnlock([\"🔓 Unlock: Ladybug Purchases<br/>Red sprite appears in shop<br/>Creature inventory slot created\"])\n LadybugUnlock -->|\"First ladybug placed<br/>(~5 min)\"| PestSystem([\"🔓 Unlock: Pest System<br/>Aphid sprites spawn on Canvas<br/>Ladybug eats pests with particles\"])\n PestSystem -->|\"10 pests killed by player<br/>(~6 min)\"| ManualSquish([\"🔓 Unlock: Manual Pest Squish<br/>Clicking pests gives +2 Biomass<br/>Crush animation on Canvas\"])\n PestSystem -->|\"50 Biomass + 20 Flow Energy<br/>(~7 min)\"| Terrace2([\"🔓 Unlock: Terrace 2<br/>New terrace level animates upward<br/>Water cascades to new level\"])\n Terrace2 -->|\"Terrace 2 active<br/>(~8 min)\"| VerticalPuzzle([\"🔓 Unlock: Vertical Water Puzzle<br/>Splitter redirector available<br/>Water divides between levels\"])\n VerticalPuzzle -->|\"25 Biomass reached<br/>(~9 min)\"| BeeUnlock([\"🔓 Unlock: Bee Hive<br/>Yellow/black sprites unlocked<br/>Pollination particles (gold dust)\"])\n BeeUnlock -->|\"First pollination event<br/>(~10 min)\"| PollinationBonus([\"🔓 Unlock: Growth Acceleration<br/>Plants glow when pollinated<br/>2x growth rate visible\"])\n PollinationBonus -->|\"50 Seeds reached<br/>(~11 min)\"| BerrySeeds([\"🔓 Unlock: Berry Seeds<br/>Purple/blue fruit sprites<br/>Attracts butterflies\"])\n BerrySeeds -->|\"First butterfly appears<br/>(~12 min)\"| ButterflySystem([\"🔓 Unlock: Butterfly Spawns<br/>Multi-colored wing sprites<br/>Catch skill check enabled\"])\n ButterflySystem -->|\"Butterfly caught<br/>(~13 min)\"| KnowledgeGain([\"🔓 Unlock: Knowledge from Catches<br/>+10 Knowledge, species revealed<br/>Rare plant unlocks hinted\"])\n KnowledgeGain -->|\"20 Knowledge total<br/>(~14 min)\"| CrossBreed([\"🔓 Unlock: Cross-Breeding<br/>Cross-breed button appears<br/>New plant variants possible\"])\n CrossBreed -->|\"First cross-breed success<br/>(~15 min)\"| RareSpecies([\"🔓 Unlock: Rare Plant Species<br/>Pumpkin sprites (orange)<br/>Special growth patterns\"])\n RareSpecies -->|\"150 Biomass + 30 Flow Energy<br/>(~18 min)\"| Terrace4([\"🔓 Unlock: Terrace 4<br/>4th terrace level expands<br/>Background mountains visible\"])\n Terrace4 -->|\"4 terraces active<br/>(~20 min)\"| EcosystemMastery([\"🔓 Unlock: Ecosystem Stability<br/>Biodiversity meter revealed<br/>Shows species count\"])\n EcosystemMastery -->|\"8 different species<br/>(~22 min)\"| BiodiversityBonus([\"🔓 Unlock: Biodiversity Rewards<br/>+10 Seeds per 5 species<br/>Bonus cascade particles\"])\n BiodiversityBonus -->|\"250 Biomass + 50 Flow Energy<br/>(~25 min)\"| Terrace5([\"🔓 Unlock: Terrace 5 (Summit)<br/>Greenhouse appears at peak<br/>Ancient architecture visible\"])\n Terrace5 -->|\"Summit reached<br/>(~27 min)\"| PrestigeTeaser([\"🔓 Prestige Teaser Revealed<br/>Button pulses at summit<br/>Shows requirement: 10 species 1 cycle\"])\n PrestigeTeaser -->|\"10 species maintained 1 cycle<br/>(~30 min)\"| PrestigeReady([\"✨ Prestige Available!<br/>Ecosystem mastered<br/>Knowledge reward calculated\"])"
},
"gateDependencyGraph": {
"title": "Hard and Soft Gates",
"mermaid": "graph TD\n subgraph \"Hard Gates (Progress Pauses Until Condition Met)\"\n HG1[\"⛔ Gate: First Harvest<br/>Requirement: First crop reaches maturity (40 sec)<br/>Wait: ~40 sec<br/>Blocks: Seed income, Biomass generation\"]\n HG2[\"⛔ Gate: Ladybug Purchase<br/>Requirement: 15 Biomass accumulated<br/>Wait: ~3 min from start<br/>Blocks: Pest defense system\"]\n HG3[\"⛔ Gate: Terrace 2 Expansion<br/>Requirement: 50 Biomass + 20 Flow Energy<br/>Wait: ~7 min from start<br/>Blocks: Vertical puzzle complexity\"]\n HG4[\"⛔ Gate: Bee Hive Purchase<br/>Requirement: 25 Biomass<br/>Wait: ~9 min from start<br/>Blocks: Pollination acceleration\"]\n HG5[\"⛔ Gate: Terrace 4 Expansion<br/>Requirement: 150 Biomass + 30 Flow Energy<br/>Wait: ~18 min from start<br/>Blocks: Late-game complexity\"]\n HG6[\"⛔ Gate: Summit Terrace<br/>Requirement: 250 Biomass + 50 Flow Energy<br/>Wait: ~25 min from start<br/>Blocks: Prestige unlock\"]\n HG7[\"⛔ Gate: Prestige Availability<br/>Requirement: 10 species, 1 full day-night cycle<br/>Wait: ~30 min from start<br/>Blocks: Prestige action\"]\n end\n\n subgraph \"Soft Gates (Progress Slows, Redirects Player)\"\n SG1[\"🟡 Gate: Early Resource Plateau<br/>Time: 2-4 min<br/>Cause: Limited seeds, waiting for harvest<br/>Redirect: Optimize water flow for Flow Energy\"]\n SG2[\"🟡 Gate: Mid-Game Biomass Crunch<br/>Time: 8-12 min<br/>Cause: Creature purchases expensive<br/>Redirect: Cross-breeding for efficiency\"]\n SG3[\"🟡 Gate: Pre-Prestige Grind<br/>Time: 22-28 min<br/>Cause: Terrace costs high, species at 8/10<br/>Redirect: Biodiversity bonus hunting\"]\n SG4[\"🟡 Gate: Flow Energy Cap Management<br/>Time: 6-30 min (ongoing)<br/>Cause: Flow Energy capped at 100<br/>Redirect: Must spend to terraform/call rain\"]\n end"
},
"progressionTimeline": {
"title": "Progression Pacing (30 Minutes)",
"mermaid": "gantt\n title Progression Pacing Timeline\n dateFormat mm:ss\n axisFormat %M:%S\n\n section Onboarding (0-2 min)\n Water flows, first crops visible :active, 00:00, 20s\n First redirector placed :crit, 00:20, 20s\n First harvest, seed loop established :milestone, 00:45, 0s\n Flow Energy generation begins :01:00, 30s\n First discovery (Knowledge gained) :01:30, 30s\n\n section Foundation (2-7 min)\n Tomato seeds unlocked (new sprite) :02:00, 60s\n Biomass currency revealed :02:30, 30s\n Ladybug unlocked, pest system active :03:30, 90s\n Terrace 2 expansion (vertical puzzle) :crit, 05:00, 120s\n\n section Expansion (7-15 min)\n Bee hive unlocked, pollination begins :07:00, 120s\n Growth acceleration visible (2x speed) :09:00, 60s\n Berry seeds unlocked, butterfly spawns :11:00, 120s\n First butterfly caught (Knowledge burst) :crit, 13:00, 60s\n Cross-breeding unlocked :14:00, 60s\n\n section Complexity (15-25 min)\n Rare species (pumpkin) discovered :15:00, 180s\n Terrace 4 expansion :crit, 18:00, 120s\n Ecosystem stability meter revealed :20:00, 120s\n Biodiversity bonuses active :22:00, 180s\n Summit terrace (greenhouse) unlocked :crit, 25:00, 60s\n\n section Mastery & Prestige (25-30 min)\n Prestige teaser revealed :26:00, 120s\n Species at 9/10, race for final species :28:00, 120s\n 10 species maintained 1 cycle :crit, 30:00, 0s"
},
"tensionCurve": {
"title": "Emotional Tension Arc",
"mermaid": "graph LR\n subgraph \"Emotional Arc Throughout Session\"\n T1[\"0-2 min<br/>🟢 Excitement<br/>Tension: 4/5<br/>First water flows, crops planted<br/>Learning basic mechanics\"]\n T2[\"2-4 min<br/>🟡 Patience<br/>Tension: 2/5<br/>Waiting for first harvest<br/>Optimizing redirector placement\"]\n T3[\"4-7 min<br/>🟢 Discovery<br/>Tension: 4/5<br/>Ladybugs, pests, Terrace 2<br/>New systems unfolding rapidly\"]\n T4[\"7-10 min<br/>🟡 Strategic<br/>Tension: 3/5<br/>Building creature army<br/>Planning ecosystem layout\"]\n T5[\"10-15 min<br/>🟢 Delight<br/>Tension: 4/5<br/>Pollination, butterflies, cross-breeds<br/>Seeing ecosystem come alive\"]\n T6[\"15-20 min<br/>🟡 Optimization<br/>Tension: 3/5<br/>Rare species, fine-tuning<br/>Maximizing biodiversity\"]\n T7[\"20-25 min<br/>🟢 Achievement<br/>Tension: 5/5<br/>Terrace 4, stability meter<br/>Approaching summit\"]\n T8[\"25-30 min<br/>🟢 Climax<br/>Tension: 5/5<br/>Final species chase, prestige ready<br/>Ecosystem master moment\"]\n end\n T1 --> T2 --> T3 --> T4 --> T5 --> T6 --> T7 --> T8"
},
"milestoneRewards": {
"title": "Gameplay Milestones and Rewards",
"mermaid": "graph LR\n subgraph \"Onboarding Milestones\"\n M1[\"🏆 First Sprout<br/>Trigger: Plant first wheat<br/>Reward: None (tutorial)<br/>Toast: 'Your garden begins!'\"]\n M2[\"🏆 Flow Master<br/>Trigger: Place first redirector<br/>Reward: +2 Flow Energy<br/>Toast: 'Water redirected!'\"]\n M3[\"🏆 First Harvest<br/>Trigger: Harvest first mature crop<br/>Reward: +5 Seeds (guaranteed)<br/>Toast: 'Seeds collected!'\"]\n M4[\"🏆 Discovery<br/>Trigger: First unique event (pollination/pest)<br/>Reward: +5 Knowledge<br/>Toast: 'New discovery recorded!'\"]\n end\n\n subgraph \"Expansion Milestones\"\n M5[\"🏆 Defender Arrives<br/>Trigger: Purchase first ladybug<br/>Reward: Ladybug lifetime +20%<br/>Toast: 'The guardian awakens!'\"]\n M6[\"🏆 Vertical Thinker<br/>Trigger: Unlock Terrace 2<br/>Reward: +10 Seeds (free)<br/>Toast: 'New heights reached!'\"]\n M7[\"🏆 Pollinator<br/>Trigger: First bee pollination<br/>Reward: 2x pollination rewards 30s<br/>Toast: 'Golden harvest accelerated!'\"]\n M8[\"🏆 Catch<br/>Trigger: Catch first butterfly<br/>Reward: +20 Knowledge (double)<br/>Toast: 'Rare species documented!'\"]\n end\n\n subgraph \"Mastery Milestones\"\n M9[\"🏆 Cross-Breeder<br/>Trigger: First successful cross-breed<br/>Reward: Unlock rare species seed<br/>Toast: 'New variation created!'\"]\n M10[\"🏆 Ecosystem Builder<br/>Trigger: Maintain 5 species simultaneously<br/>Reward: +25 Biomass<br/>Toast: 'Biodiversity thrives!'\"]\n M11[\"🏆 Summit Seeker<br/>Trigger: Unlock Terrace 5 (Greenhouse)<br/>Reward: +50 Flow Energy<br/>Toast: 'The peak is yours!'\"]\n M12[\"🏆 Ecosystem Master<br/>Trigger: 10 species, 1 full cycle<br/>Reward: Prestige unlocked, +100 Knowledge<br/>Toast: 'Mastery achieved!'\"]\n end"
},
"tutorialFlow": {
"title": "First 60 Seconds - Tutorial Sequence",
"mermaid": "sequenceDiagram\n participant Player\n participant Canvas as Game Canvas\n participant UI as HUD/UI\n participant Sys as Game Systems\n\n Note over Player,Sys: 0-15 Seconds: First Impressions\n Player->>Canvas: Game loads\n Canvas->>Player: Shows terraces with flowing water<br/>Wheat already planted in starter zone<br/>Water droplets animating down slopes\n UI->>Player: HUD shows: 🌱 Seeds: 10<br/>Highlight on wheat seed button<br/>Tooltip: 'Click soil to plant'\n\n Note over Player,Sys: 15-30 Seconds: First Interaction\n Player->>Canvas: Clicks on soil patch\n Canvas->>Canvas: Plant spawn animation (scale 0→1, 200ms)<br/>Green sprout appears\n UI->>Player: Seeds counter animates: 10 → 9<br/>Floating text: '-1 🌱'\n Canvas->>Canvas: Crop grows through stages based on water<br/>Soil darkens where water flows\n\n Note over Player,Sys: 30-45 Seconds: Discovery Moment\n Canvas->>Player: First crop reaches maturity<br/>Visual: Crop glows, grows 20% larger<br/>UI->>Player: Harvest cursor appears on hover<br/>Tooltip: 'Click to harvest!'\n Player->>Canvas: Clicks mature crop\n Canvas->>Canvas: Harvest animation (scale 1→0, 300ms)<br/>Seed packet sprite spawns with pop-in\n UI->>Player: Seeds: 9 → 14<br/>Floating text: '+5 🌱'<br/>Toast: 'First Harvest! 🏆'\n\n Note over Player,Sys: 45-60 Seconds: Water Discovery\n Canvas->>Player: Water flows past barren area<br/>Dying wheat visible (wilting animation)\n UI->>Player: Redirector button pulses<br/>Tooltip: 'Drag to redirect water'\n Player->>Canvas: Drags on terrace to place channel\n Canvas->>Canvas: Stone structure animates in (scale 0→1)<br/>Water flow visibly redirects<br/>Blue sparkle particles at redirector\n UI->>Player: 💧 Flow Energy bar appears<br/>Fills from 0 → 3<br/>Toast: 'Flow Energy Generated! 💧'\n\n Note over Player,Sys: Post-Tutorial: Systems Online\n Sys->>Player: All core loops established<br/>Player sees: Water management, planting, harvesting<br/>Next objective: 'Reach 15 Seeds for next unlock'"
},
"entityLifecyclePlant": {
"title": "Plant Entity State Machine",
"mermaid": "stateDiagram-v2\n [*] --> Locked: game start\n Locked --> Available: seed type unlocked\n Available --> Planted: player clicks soil with seed selected\n Planted --> Sprouting: spawn animation (200ms)\n Sprouting --> Growing: growth stage 1 of 4\n Growing --> Growing: +1 stage (time-based, modified by water/pollination)\n Growing --> Wilting: soil moisture < 20% for 10s\n Growing --> Moldy: soil moisture > 90% for 10s\n Growing --> Mature: reaches stage 4\n Wilting --> Growing: watered to > 40%\n Wilting --> Dying: moisture < 10% for 5s\n Moldy --> Dying: not remedied in 15s\n Mature --> Harvested: player clicks mature crop\n Mature --> Cycling: player leaves untouched (30s timer)\n Cycling --> SeedDrop: lifecycle complete\n Harvested --> [*]: harvest animation, seed packet spawn\n Cycling --> [*]: biomass awarded, seeds auto-sown nearby\n Dying --> [*]: death animation, 50% seed refund\n SeedDrop --> [*]: cross-breed check, seeds scatter\n\n note right of Locked\n Not visible in seed selector<br/>\n No hint shown<br/>\n Requires unlock condition\n end note\n\n note right of Available\n Sprite visible in seed UI<br/>\n Cost: 1-5 seeds<br/>\n Hover shows growth time\n end note\n\n note right of Planted\n Position: clicked tile<br/>\n Animation: scale 0→1 (200ms)<br/>\n Cost deducted immediately\n end note\n\n note right of Growing\n Growth rate = base * waterMultiplier * pollinationMultiplier<br/>\n Visual: size increases 25% per stage<br/>\n Check moisture every 2s\n end note\n\n note right of Wilting\n Visual: turns yellow/brown<br/>\n Growth paused<br/>\n 5s to recover before dying\n end note\n\n note right of Mature\n Visual: glows, fruit visible<br/>\n 30s window to harvest<br/>\n Then auto-cycles\n end note\n\n note right of Harvested\n Triggers: seed packet spawn<br/>\n Rewards: seeds, biomass<br/>\n Sound: harvest.mp3\n end note"
},
"entityLifecycleCreature": {
"title": "Creature Entity State Machine",
"mermaid": "stateDiagram-v2\n [*] --> Locked: creature type not discovered\n Locked --> Available: unlock condition met\n Available --> InInventory: player purchases creature\n Available --> Deploying: player clicks to place from inventory\n Deploying --> Active: placement animation (300ms)\n Active --> Seeking: scanning for targets (flowers/pests)\n Seeking --> Moving: target found, moving toward it\n Seeking --> Idle: no targets in range\n Moving --> Interacting: reached target\n Idle --> Seeking: rescan (1s interval)\n Interacting --> Active: action complete (pollinate/eat)\n Active --> Exhausted: lifespan/pest limit reached\n Active --> Fleeing: predator/environment threat\n Exhausted --> Dying: depletion animation (500ms)\n Fleeing --> Dying: caught by threat or expired\n Dying --> [*]: remove from canvas, reward particles\n\n note right of Locked\n No sprite in shop<br/>\n No unlock hint<br/>\n Discovery trigger reveals\n end note\n\n note right of Available\n Shop sprite visible<br/>\n Cost shown in biomass<br/>\n 'New!' indicator for 30s\n end note\n\n note right of Deploying\n Position: clicked tile<br/>\n Animation: scale 0→1 with bounce<br/>\n Brief invulnerability (500ms)\n end note\n\n note right of Seeking\n Detection radius: 150px<br/>\n Target priority: closest valid<br/>\n Scan interval: 500ms\n end note\n\n note right of Interacting\n Bees: pollinate (2s), +8 Biomass per event<br/>\n Ladybugs: eat pest (1s), +5 Biomass, +1 to pest count<br/>\n Visual: particle effects\n end note\n\n note right of Exhausted\n Bees: 5 minute lifetime<br/>\n Ladybugs: 30 pests eaten<br/>\n Visual: slows down, fades\n end note"
},
"entityLifecycleWater": {
"title": "Water Droplet State Machine",
"mermaid": "stateDiagram-v2\n [*] --> Spawning: generated at water source\n Spawning --> Flowing: spawn animation (100ms fade-in)\n Flowing --> Redirecting: hits player-placed redirector\n Flowing --> Wicking: enters soil tile\n Flowing --> Falling: reaches terrace edge (waterfall)\n Flowing --> Pooling: hits dam or depression\n Redirecting --> Flowing: direction changed\n Redirecting --> EnergyGenerated: passes redirector\n Falling --> Flowing: lands on lower terrace\n Pooling --> Wicking: saturation threshold<br/>exceeded after 3s\n Pooling --> Flowing: dam overflows or<br/>removed after 5s\n Wicking --> Absorbed: completely absorbed<br/>by soil (moisture increase)\n Wicking --> Flowing: soil saturated,<br/>continues flowing\n EnergyGenerated --> [*]: +0.5 Flow Energy<br/>blue sparkle effect\n Absorbed --> [*]: soil moisture +10%<br/>droplet removed\n\n note right of Spawning\n Source: top of terrace or<br/>waterfall from above<br/>\n Spawn rate: 1 per second<br/>\n Per active source\n end note\n\n note right of Flowing\n Velocity: 60px/sec<br/>\n Direction: gravity + redirectors<br/>\n Visual: blue circle with trail<br/>\n Opacity: varies by depth\n end note\n\n note right of Redirecting\n Check redirector type:<br/>\n - Channel: straight flow<br/>\n - Turn: 90° redirect<br/>\n - Splitter: divides into 2<br/>\n - Dam: stops, pools<br/>\n - Pump: moves upward\n end note\n\n note right of EnergyGenerated\n Triggers: FlowEnergy +0.5<br/>\n Visual: blue sparkle sprite<br/>\n Auto-collected instantly<br/>\n Update flow bar UI\n end note"
},
"weatherState": {
"title": "Weather System State Machine",
"mermaid": "stateDiagram-v2\n [*] --> Clear: game start\n Clear --> Drifting: random cloud spawn (2% chance/min)\n Clear --> Drought: random event (1% chance/min)<br/>after 5 min playtime\n Drifting --> Rain: cloud triggered by player<br/>(Call Rain ability) or random (5% chance)\n Drifting --> Clear: cloud exits screen (30s timeout)\n Rain --> Pouring: rain intensity ramp-up (3s)\n Pouring --> Flooding: heavy rain duration > 15s<br/>on single terrace\n Pouring --> Clear: cloud dissipated (20s duration)\n Flooding --> FloodDamage: plants in pooled water<br/>take 5% HP/sec for 10s\n FloodDamage --> Receding: rain stops or player<br/>uses flood control\n Receding --> Clear: water drains (5s)<br/>soil moisture at 100%\n Drought --> Clear: weather breaks (20s duration)<br/>soil moisture -20%\n\n note right of Drifting\n Visual: grey cloud sprite<br/>in sky background layer<br/>Slow horizontal drift<br/>30px/sec\n end note\n\n note right of Pouring\n Visual: rain particle overlay<br/>Water spawn rate 3x normal<br/>All terraces gain moisture<br/>Sound: rain_ambient.mp3\n end note\n\n note right of Flooding\n Visual: puddles expand on<br/>saturated terraces<br/>Plants show mold state<br/>Warning toast appears\n end note\n\n note right of Drought\n Visual: yellow/orange tint<br/>Water spawn rate 0.5x normal<br/>All terraces lose moisture<br/>Plants wilt faster\n end note"
}
},
"config": {
"progression": {
"unlockStages": {
"stage0": {
"name": "Garden Start",
"timeframe": "0:00-1:00",
"unlocks": [
"wheatSeed",
"basicRedirector",
"harvesting"
],
"uiReveals": [
"seedsCounter",
"seedSelector"
],
"canvasFeatures": [
"waterFlow",
"singleTerrace",
"basicCrops"
]
},
"stage1": {
"name": "Flow Discovery",
"timeframe": "1:00-3:00",
"unlocks": [
"flowEnergy",
"tomatoSeed",
"discoveries"
],
"uiReveals": [
"flowEnergyBar",
"knowledgeCounter"
],
"canvasFeatures": [
"redirectorEffects",
"multiCropTypes"
],
"triggers": {
"flowEnergy": "place first redirector",
"tomatoSeed": "earn 15 seeds",
"discoveries": "first unique event"
}
},
"stage2": {
"name": "Ecosystem Awakening",
"timeframe": "3:00-7:00",
"unlocks": [
"biomassCurrency",
"ladybugs",
"pests",
"manualSquish",
"terrace2"
],
"uiReveals": [
"biomassCounter",
"creatureInventory",
"shop"
],
"canvasFeatures": [
"pestSpawns",
"creatureAI",
"verticalPuzzle"
],
"triggers": {
"biomassCurrency": "earn 5 biomass from harvests",
"ladybugs": "accumulate 15 biomass",
"terrace2": "50 biomass + 20 flowEnergy"
}
},
"stage3": {
"name": "Pollination & Weather",
"timeframe": "7:00-12:00",
"unlocks": [
"bees",
"callRain",
"weatherEvents",
"berrySeeds",
"butterflies"
],
"uiReveals": [
"weatherIndicator",
"speciesCounter"
],
"canvasFeatures": [
"pollinationEffects",
"rainSystem",
"butterflySpawns"
],
"triggers": {
"bees": "accumulate 25 biomass",
"callRain": "accumulate 15 flowEnergy",
"berrySeeds": "accumulate 50 seeds",
"butterflies": "first pollination on berry plant"
}
},
"stage4": {
"name": "Advanced Systems",
"timeframe": "12:00-20:00",
"unlocks": [
"crossBreeding",
"rareSpecies",
"terrace4",
"ecosystemStability"
],
"uiReveals": [
"crossBreedUI",
"biodiversityMeter"
],
"canvasFeatures": [
"plantVariants",
"complexTerraces"
],
"triggers": {
"crossBreeding": "accumulate 20 knowledge",
"rareSpecies": "first cross-breed success",
"terrace4": "150 biomass + 30 flowEnergy",
"ecosystemStability": "maintain 5 species 30s"
}
},
"stage5": {
"name": "Mastery & Prestige",
"timeframe": "20:00-30:00",
"unlocks": [
"terrace5",
"biodiversityBonus",
"prestigeTeaser",
"prestige"
],
"uiReveals": [
"summitIndicator",
"prestigeButton"
],
"canvasFeatures": [
"greenhouse",
"fullEcosystem"
],
"triggers": {
"terrace5": "250 biomass + 50 flowEnergy",
"biodiversityBonus": "achieve 8 species simultaneously",
"prestigeTeaser": "unlock terrace 5",
"prestige": "maintain 10 species for full day-night cycle (60s)"
}
}
},
"unlocks": {
"wheatSeed": {
"requirement": "gameStart",
"unlocks": "wheatSeed",
"toast": null,
"indicator": null
},
"basicRedirector": {
"requirement": "gameStart",
"unlocks": "basicChannelRedirector",
"toast": null,
"indicator": null
},
"flowEnergy": {
"requirement": "redirectorsPlaced >= 1",
"unlocks": "flowEnergySystem",
"toast": "Flow Energy Discovered! 💧",
"indicator": "hud-reveal"
},
"tomatoSeed": {
"requirement": "seedsEarned >= 15",
"unlocks": "tomatoSeed",
"toast": "New Seed: Tomato! 🍅",
"indicator": "seed-selector-glow"
},
"discoveries": {
"requirement": "firstUniqueEvent",
"unlocks": "knowledgeSystem",
"toast": "Discovery Recorded! +5 Knowledge 📚",
"indicator": "hud-reveal"
},
"biomassCurrency": {
"requirement": "biomassEarned >= 5",
"unlocks": "biomassDisplay",
"toast": "Biomass Cycle Active! 🌿",
"indicator": "hud-reveal"
},
"ladybugs": {
"requirement": "biomass >= 15",
"unlocks": "ladybugPurchase",
"toast": "Ladybugs Available! 🐞",
"indicator": "shop-glow"
},
"pests": {
"requirement": "ladybugsPurchased >= 1",
"unlocks": "pestSystem",
"toast": "Pests Detected! Defend your garden!",
"indicator": "canvas-warning"
},
"manualSquish": {
"requirement": "pestsKilledByPlayer >= 10",
"unlocks": "manualPestSquish",
"toast": "Pest Squish Mastery! +2 Biomass per squish",
"indicator": "ability-unlock"
},
"terrace2": {
"requirement": "biomass >= 50 && flowEnergy >= 20",
"unlocks": "terraceLevel2",
"toast": "Terrace 2 Unlocked! 🏔️",
"indicator": "terrace-expand"
},
"bees": {
"requirement": "biomass >= 25",
"unlocks": "beeHivePurchase",
"toast": "Bees Unlocked! 🐝",
"indicator": "shop-glow"
},
"callRain": {
"requirement": "flowEnergy >= 15",
"unlocks": "callRainAbility",
"toast": "Rain Calling Unlocked! 🌧️",
"indicator": "ability-glow"
},
"weatherEvents": {
"requirement": "firstRainEvent",
"unlocks": "weatherSystem",
"toast": null,
"indicator": null
},
"berrySeeds": {
"requirement": "seeds >= 50",
"unlocks": "berrySeed",
"toast": "New Seed: Berries! 🫐",
"indicator": "seed-selector-glow"
},
"butterflies": {
"requirement": "berryPlanted && pollinated",
"unlocks": "butterflySpawns",
"toast": "Butterflies Arrive! 🦋",
"indicator": "canvas-arrival"
},
"crossBreeding": {
"requirement": "knowledge >= 20",
"unlocks": "crossBreedSystem",
"toast": "Cross-Breeding Discovered! 🧬",
"indicator": "ui-unlock"
},
"rareSpecies": {
"requirement": "firstCrossBreedSuccess",
"unlocks": "pumpkinSeed",
"toast": "Rare Species: Pumpkin! 🎃",
"indicator": "seed-selector-glow"
},
"terrace4": {
"requirement": "biomass >= 150 && flowEnergy >= 30",
"unlocks": "terraceLevel4",
"toast": "Terrace 4 Unlocked! 🏔️",
"indicator": "terrace-expand"
},
"ecosystemStability": {
"requirement": "speciesSimultaneous >= 5 && duration >= 30",
"unlocks": "stabilityMeter",
"toast": "Ecosystem Stable! 🌱",
"indicator": "hud-reveal"
},
"terrace5": {
"requirement": "biomass >= 250 && flowEnergy >= 50",
"unlocks": "terraceLevel5",
"toast": "Summit Greenhouse Unlocked! 🏛️",
"indicator": "terrace-expand"
},
"biodiversityBonus": {
"requirement": "speciesSimultaneous >= 8",
"unlocks": "biodiversityRewards",
"toast": "Biodiversity Bonus! +10 Seeds per 5 species 🌿",
"indicator": "bonus-active"
},
"prestigeTeaser": {
"requirement": "terrace5Unlocked",
"unlocks": "prestigeButtonVisible",
"toast": "Prestige Approaching... Show your mastery!",
"indicator": "button-pulse"
},
"prestige": {
"requirement": "speciesSimultaneous >= 10 && fullCycleCompleted",
"unlocks": "prestigeAvailable",
"toast": "ECOSYSTEM MASTER! Prestige Available! ✨",
"indicator": "prestige-ready"
}
},
"milestones": [
{
"id": "firstSprout",
"trigger": "cropsPlanted >= 1",
"reward": {},
"toast": "Your garden begins! 🌱",
"repeatable": false
},
{
"id": "flowMaster",
"trigger": "redirectorsPlaced >= 1",
"reward": {
"flowEnergy": 2
},
"toast": "Water redirected! 💧",
"repeatable": false
},
{
"id": "firstHarvest",
"trigger": "cropsHarvested >= 1",
"reward": {
"seeds": 5
},
"toast": "First Harvest! 🌾",
"repeatable": false
},
{
"id": "firstDiscovery",
"trigger": "discoveryCount >= 1",
"reward": {
"knowledge": 5
},
"toast": "Discovery recorded! 📚",
"repeatable": false
},
{
"id": "defenderArrives",
"trigger": "ladybugsPurchased >= 1",
"reward": {
"ladybugLifetimeBonus": 0.2
},
"toast": "The guardian awakens! 🐞",
"repeatable": false
},
{
"id": "verticalThinker",
"trigger": "terrace2Unlocked",
"reward": {
"seeds": 10
},
"toast": "New heights reached! 🏔️",
"repeatable": false
},
{
"id": "pollinator",
"trigger": "pollinations >= 1",
"reward": {
"pollinationBonusMultiplier": 2,
"duration": 30
},
"toast": "Golden harvest accelerated! 🐝",
"repeatable": false
},
{
"id": "butterflyCatch",
"trigger": "butterfliesCaught >= 1",
"reward": {
"knowledge": 20
},
"toast": "Rare species documented! 🦋",
"repeatable": false
},
{
"id": "crossBreeder",
"trigger": "crossBreedsSuccess >= 1",
"reward": {
"unlockSeed": "randomRare"
},
"toast": "New variation created! 🧬",
"repeatable": true,
"maxRepeats": 5
},
{
"id": "ecosystemBuilder",
"trigger": "speciesSimultaneous >= 5 && duration >= 30",
"reward": {
"biomass": 25
},
"toast": "Biodiversity thrives! 🌿",
"repeatable": true
},
{
"id": "summitSeeker",
"trigger": "terrace5Unlocked",
"reward": {
"flowEnergy": 50
},
"toast": "The peak is yours! 🏛️",
"repeatable": false
},
{
"id": "ecosystemMaster",
"trigger": "prestigeUnlocked",
"reward": {
"knowledge": 100
},
"toast": "Mastery achieved! ✨",
"repeatable": false
}
]
},
"prestige": {
"teaserCondition": "terrace5Unlocked",
"minWave": null,
"minCondition": "speciesSimultaneous >= 10 && fullCycleCompleted",
"formula": "100 + (50 * biodiversityLevel) + (10 * achievementsCompleted)",
"threshold": 0,
"resets": [
"seeds",
"biomass",
"flowEnergy",
"crops",
"creatures",
"redirectors",
"terraces"
],
"persists": [
"knowledge",
"prestigeCount",
"prestigeUpgrades",
"achievements",
"discoveredSpecies",
"totalCycles"
],
"visualTiers": [
{
"tier": 0,
"minPrestiges": 0,
"background": "#1a2e1a",
"enemyPalette": null,
"description": "Base valley - wild terraces"
},
{
"tier": 1,
"minPrestiges": 1,
"background": "#1a2e2e",
"enemyPalette": {
"hueShift": 20,
"saturationMultiplier": 1.2
},
"description": "Restored foundations - ancient stones visible"
},
{
"tier": 2,
"minPrestiges": 3,
"background": "#2e1a2e",
"enemyPalette": {
"hueShift": 180,
"saturationMultiplier": 1.3
},
"description": "Mystical valley - bioluminescent night plants"
},
{
"tier": 3,
"minPrestiges": 5,
"background": "#2e2e1a",
"enemyPalette": {
"hueShift": 60,
"saturationMultiplier": 1.5
},
"description": "Golden age - rare species flourish"
}
],
"upgrades": {
"seedStartingBonus": {
"name": "Ancient Seeds",
"description": "Start each run with bonus seeds",
"maxLevel": 5,
"baseCost": 10,
"costMultiplier": 1.3,
"effect": "startingSeeds + (5 * level)",
"visualChange": "Seed packet sprites glow golden"
},
"redirectorEfficiency": {
"name": "Flow Mastery",
"description": "Generate more Flow Energy from redirectors",
"maxLevel": 5,
"baseCost": 25,
"costMultiplier": 1.3,
"effect": "flowEnergyMultiplier + (0.1 * level)",
"visualChange": "Redirectors emit stronger blue particles"
},
"creatureLifespan": {
"name": "Creature Vitality",
"description": "Creatures live longer and work more efficiently",
"maxLevel": 5,
"baseCost": 20,
"costMultiplier": 1.3,
"effect": "creatureLifespanMultiplier + (0.2 * level)",
"visualChange": "Creatures have subtle glow auras"
},
"terraceFertility": {
"name": "Enriched Soil",
"description": "Starting terraces have better soil quality",
"maxLevel": 3,
"baseCost": 30,
"costMultiplier": 1.4,
"effect": "startingSoilQuality + (0.15 * level)",
"visualChange": "Soil appears darker/richer at start"
},
"growthSpeed": {
"name": "Accelerated Growth",
"description": "All plants grow faster",
"maxLevel": 5,
"baseCost": 35,
"costMultiplier": 1.35,
"effect": "globalGrowthMultiplier + (0.1 * level)",
"visualChange": "Plants have more frequent growth stage animations"
},
"pestResistance": {
"name": "Natural Defenses",
"description": "Plants resist pests better",
"maxLevel": 3,
"baseCost": 28,
"costMultiplier": 1.4,
"effect": "pestSpawnRate - (0.02 * level)",
"visualChange": "Plants show subtle protective shimmer"
}
},
"run2Acceleration": {
"targetTimeRatio": 0.4,
"description": "Run 2 should reach Run 1's prestige point in 40% of the time",
"factors": [
"Starting seeds from upgrades reduce early waiting",
"Better redirector efficiency means faster Flow Energy",
"Creature longevity means less micromanagement",
"Growth speed accelerates all loops",
"Player knowledge eliminates tutorial overhead"
]
}
},
"upgradeTiers": {
"tier1": {
"name": "Basic Improvements",
"unlock": "gameStart",
"choices": "independent",
"upgrades": [
{
"id": "wheatYield",
"name": "Wheat Yield Boost",
"description": "Wheat produces more seeds",
"maxLevel": 5,
"cost": {
"seeds": 10
},
"effect": "wheatYield + (1 * level)",
"visualChange": "Wheat grows 10% larger per level"
},
{
"id": "waterRetention",
"name": "Water Retention",
"description": "Soil holds moisture longer",
"maxLevel": 3,
"cost": {
"biomass": 8
},
"effect": "soilDryRate - (0.1 * level)",
"visualChange": "Soil stays dark blue longer"
},
{
"id": "redirectorDurability",
"name": "Redirector Durability",
"description": "Redirectors generate Flow Energy more efficiently",
"maxLevel": 5,
"cost": {
"biomass": 5
},
"effect": "redirectorEfficiency + (0.05 * level)",
"visualChange": "Sparkles appear more frequently"
}
]
},
"tier2": {
"name": "Strategic Paths",
"unlock": "terrace2Unlocked",
"choices": "mutuallyExclusive",
"description": "Choose one specialization path",
"paths": [
{
"id": "monoculturePath",
"name": "Monoculture Mastery",
"description": "Boost single-species planting efficiency",
"upgrades": [
{
"id": "monocultureBonus",
"cost": {
"biomass": 30
},
"effect": "sameSpeciesYieldBonus + 0.25",
"visualChange": "Single-crop terraces show uniform golden glow"
},
{
"id": "densePlanting",
"cost": {
"biomass": 40
},
"effect": "cropDensity + 1",
"visualChange": "Can plant more crops per terrace"
}
]
},
{
"id": "polyculturePath",
"name": "Polyculture Synergy",
"description": "Boost multi-species biodiversity",
"upgrades": [
{
"id": "polycultureBonus",
"cost": {
"biomass": 30
},
"effect": "speciesVarietyBonus + 0.3",
"visualChange": "Mixed terraces show rainbow particle effects"
},
{
"id": "crossBreedChance",
"cost": {
"biomass": 40
},
"effect": "crossBreedChance + 0.15",
"visualChange": "Cross-breed events more frequent"
}
]
},
{
"id": "hydrologyPath",
"name": "Hydrology Focus",
"description": "Maximize water flow efficiency",
"upgrades": [
{
"id": "flowEnergyBonus",
"cost": {
"biomass": 30
},
"effect": "flowEnergyGeneration + 0.3",
"visualChange": "Water trails glow blue"
},
{
"id": "weatherControl",
"cost": {
"flowEnergy": 15
},
"effect": "callRainCooldown - 5",
"visualChange": "Rain clouds appear faster"
}
]
}
]
},
"tier3": {
"name": "Mastery Synergies",
"unlock": "terrace4Unlocked",
"choices": "combination",
"description": "Unlock powerful combination bonuses",
"upgrades": [
{
"id": "creatureSwarm",
"name": "Creature Swarm Tactics",
"description": "Creatures work better together",
"requirements": {
"beesPurchased": 3,
"ladybugsPurchased": 3
},
"cost": {
"biomass": 100
},
"effect": "creatureSynergyBonus + 0.5",
"visualChange": "Creatures show linking lines when near each other"
},
{
"id": "perfectFlow",
"name": "Perfect Flow Patterns",
"description": "Elegant water networks generate massive bonuses",
"requirements": {
"redirectorsPlaced": 15
},
"cost": {
"flowEnergy": 30
},
"effect": "efficientFlowBonus + 25",
"visualChange": "Elegant patterns show golden flow lines"
},
{
"id": "biodiversityCascade",
"name": "Biodiversity Cascade",
"description": "More species = exponential bonuses",
"requirements": {
"speciesSimultaneous": 7
},
"cost": {
"knowledge": 15
},
"effect": "biodiversityMultiplier + 0.1",
"visualChange": "Each new species triggers celebration particles"
},
{
"id": "lifecycleMastery",
"name": "Lifecycle Harmony",
"description": "Letting plants cycle grants huge bonuses",
"requirements": {
"lifecyclesCompleted": 10
},
"cost": {
"knowledge": 20
},
"effect": "lifecycleBiomassBonus + 10",
"visualChange": "Cycling plants show elaborate seed-scatter animation"
}
]
}
},
"antiFrustration": {
"stuckDetection": {
"enabled": true,
"conditions": [
{
"type": "noHarvest",
"threshold": 90,
"action": "boostGrowthSpeed",
"value": 2,
"duration": 30
},
{
"type": "noProgress",
"threshold": 120,
"action": "giftSeeds",
"value": 15
},
{
"type": "pestOverwhelm",
"threshold": "pestsCount > 10 && ladybugs == 0",
"action": "giftLadybug",
"value": 1
}
]
},
"catchup": {
"badUpgradeRecoveryTime": 120,
"minimumHarvestYield": 5,
"firstHarvestProtection": true,
"cropFailureRefund": 0.5
},
"visualProgress": {
"alwaysShowMilestones": true,
"progressBarsOnLocked": true,
"nextUnlockHint": true,
"distanceToGoal": true
}
},
"motivators": {
"timeframe": [
{
"period": "next30sec",
"drivers": [
"Watching crops grow toward harvest",
"Almost have enough for next upgrade",
"Water flow optimization puzzles",
"Pest outbreak requiring attention"
]
},
{
"period": "next5min",
"drivers": [
"New seed type unlocking soon",
"Approaching terrace expansion cost",
"First creature purchase within reach",
"Cross-breeding about to unlock"
]
},
{
"period": "session",
"drivers": [
"Reaching summit greenhouse",
"Achieving 10-species biodiversity",
"Unlocking prestige for permanent power",
"Seeing ecosystem transformation"
]
}
]
}
},
"qualityChecklist": [
"Unlock flow diagram shows EVERY unlock with exact trigger conditions",
"Triggers use gameplay events (harvests, purchases, discoveries) not just currency amounts",
"First 30 seconds have visible gameplay (water flowing, crops growing) immediately",
"No phase lasts more than 5 minutes without something new",
"Each major unlock CHANGES Canvas visuals (new entities, effects, abilities)",
"Every hard gate has estimated wait time under 2 minutes for early game",
"Timeline covers 0-30 minutes completely",
"Tension curve has clear peaks and valleys",
"Prestige is teased before available (terrace 5 unlock → full 10-species requirement)",
"12 milestones spread across session",
"State machines defined for Plants, Creatures, Water, and Weather",
"CONFIG.progression.unlockStages defines 6 progression stages",
"CONFIG.progression.unlocks has 20+ unlocks with requirements, toasts, and indicators",
"CONFIG.progression.milestones has 12 milestones with triggers and rewards",
"CONFIG.prestige defines 6 permanent upgrades with costs, effects, and visual changes",
"CONFIG.prestige.visualTiers defines 4 visual transformation tiers",
"CONFIG.upgradeTiers defines 3 tiers with meaningful choices (mutually exclusive at tier 2)",
"CONFIG.antiFrustration defines stuck detection and catchup mechanics",
"All formulas are exact and copy-pasteable",
"Developers can implement entire progression from diagrams alone"
]
}
Ui Ux
{
"gameName": "Stream Valley Garden",
"version": "1.0",
"lastUpdated": "2026-02-10",
"overview": {
"visualIdentity": "Stream Valley Garden presents as a whimsical, living ecosystem rendered in warm earth tones and vibrant blues. The visual identity evokes the feeling of nurturing a terraced mountain valley coming back to life - think 'cozy farming simulator meets zen garden.' The Canvas displays a cross-section of terraced slopes with animated water cascading down, plants swaying gently, and tiny creatures foraging. Day/night cycles create mood shifts from golden warm growth to mysterious bioluminescent nights. The interface floats above this living world like garden notes - minimal, functional, and never obscuring the ecosystem you're cultivating.",
"canvasFirst": "The Canvas game world IS the game. It occupies 65% of the screen and is always visible. Player hands spend most of their time clicking soil to plant, dragging terraces to place water channels, clicking pests to squish, and harvesting mature crops. The bottom upgrade panel supports these strategic decisions BETWEEN active gameplay moments. Numbers and upgrades are secondary to watching your garden grow.",
"colorScheme": "Earthy browns (#8B7355, #A0826D) for soil and terraces, vibrant greens (#4CAF50, #66BB6A) for healthy plants, deep blues (#2196F3, #4FC3F7) for water flow, golden yellows (#FFD700, #FFC107) for seeds and pollen, and soft purples (#9C27B0, #E040FB) for rare species and night effects. The background is a deep valley gradient from mountain peaks to forest floor.",
"emotionalTone": "The interface evokes curiosity, satisfaction, and peaceful stewardship. Growth animations should feel rewarding (plants swell visibly, harvest pops with particle effects). Water flow should look satisfying (droplets sparkle, channels gurgle with blue glow). Creature movement should look deliberate and purposeful (bees flutter with purpose, ladybugs crawl with determination). The UI should feel like a gardener's journal - organized, helpful, and never overwhelming."
},
"colorPalette": {
"backgroundPrimary": "#1a1814",
"backgroundSecondary": "#2d2620",
"backgroundTertiary": "#3d3428",
"canvasBackground": "#2d4a3e",
"textPrimary": "#e8e4dc",
"textSecondary": "#a8a49c",
"textMuted": "#68645c",
"accent1": "#FFD700",
"accent2": "#4FC3F7",
"accent3": "#E040FB",
"success": "#4CAF50",
"warning": "#FF9800",
"danger": "#F44336",
"prestige": "#E040FB"
},
"typography": {
"fontFamily": "'Nunito', 'Segoe UI', system-ui, sans-serif",
"headings": {
"weight": "700",
"sizeRange": "18px - 28px"
},
"bodyText": {
"weight": "400",
"size": "14px"
},
"numbersCurrencies": {
"font": "'Roboto Mono', 'Courier New', monospace",
"weight": "600"
},
"buttons": {
"font": "'Nunito', sans-serif",
"weight": "700",
"size": "14px"
}
},
"screenLayout": {
"masterLayout": "+--------------------------------------------------+\n| [HUD Bar - currencies, rates, day/night, weather] |\n+--------------------------------------------------+\n| |\n| [CANVAS - Main Game World] |\n| (65% of screen height) |\n| Terraced valley with water flow |\n| Plants, creatures, particles, weather |\n| |\n+--------------------------------------------------+\n| [Bottom Panel - tabs for seeds, creatures, tools] |\n| (35% of screen height, collapsible) |\n+--------------------------------------------------+",
"hudBar": {
"description": "Always visible, overlays top of screen with semi-transparent dark background",
"elements": [
{
"name": "Seeds Display",
"position": "left",
"content": "🌱 1,234 (+12/s)",
"behavior": "Animate count-up (300ms) on change. Color: #FFD700. Glow briefly on gameplay-earned (harvest), distinct from passive ticks."
},
{
"name": "Biomass Display",
"position": "left-center",
"content": "🌿 567 (+8/s)",
"behavior": "Animate count-up (300ms). Color: #4CAF50. Green pulse on creature events."
},
{
"name": "Flow Energy Bar",
"position": "center",
"content": "💧 [████████░░] 45/100",
"behavior": "Bar fills from left (100ms animation). Color: #4FC3F7. Flash red warning when capped. Blue sparkles at bar when generated."
},
{
"name": "Knowledge Display",
"position": "right-center",
"content": "📚 42",
"behavior": "Static (prestige currency). Color: #E040FB. Purple burst on discovery/butterfly catch."
},
{
"name": "Species Counter",
"position": "right",
"content": "🦋 8/10 Species",
"behavior": "Updates on species change. Color: #9C27B0. Progress bar underneath."
},
{
"name": "Settings Button",
"position": "far-right",
"content": "⚙️",
"behavior": "Opens settings modal"
},
{
"name": "Day/Night Indicator",
"position": "center-top",
"content": "☀️/🌙 with progress bar",
"behavior": "Shows current cycle (60s day, 30s night). Sky color shifts on Canvas."
},
{
"name": "Weather Indicator",
"position": "center-below-daynight",
"content": "Cloud icon with rain animation",
"behavior": "Only shows during weather events. Pulsing during active rain."
}
]
},
"gameWorldCanvas": {
"dimensions": "Responsive width, fixed height ratio (16:9 aspect ratio maintained)",
"backgroundColor": "#2d4a3e (deep valley green with subtle gradient)",
"layers": [
{
"order": 1,
"name": "Background Layer",
"contents": "Sky gradient (day/night cycle), distant mountains, terrace soil with moisture visualization (darker blue = wetter)"
},
{
"order": 2,
"name": "Entity Layer",
"contents": "All game sprites - water droplets, crops (all growth stages), redirectors (channels, dams, splitters), creatures (bees, ladybugs, butterflies), pests (aphids), collectibles (seed packets)"
},
{
"order": 3,
"name": "Effect Layer",
"contents": "Damage numbers, floating reward text, death particles, pollination golden dust, water sparkles, harvest pop effects"
},
{
"order": 4,
"name": "HUD Overlay Layer",
"contents": "Plant health bars, growth progress indicators, creature range circles, selection highlights, placement preview ghosts, moisture level text on hover"
}
],
"camera": "Fixed view of all unlocked terraces. As terraces unlock, view scales to fit (zoom out slightly). No scrolling - entire valley always visible.",
"clickInteractions": [
{
"action": "Plant Seed",
"trigger": "Left click on soil tile when seed selected",
"effect": "Spawn plant animation (scale 0→1, 200ms), deduct seed cost, soil darkens at planting spot"
},
{
"action": "Place Water Redirector",
"trigger": "Left drag on terrace when redirector tool selected",
"effect": "Ghost preview follows cursor, release to place. Stone structure animates in (scale 0→1, 300ms). Water flow visibly redirects around it with blue sparkle particles."
},
{
"action": "Harvest Crop",
"trigger": "Left click on mature (glowing) crop",
"effect": "Crop shrinks with pop animation (scale 1→0, 300ms), seed packet sprite spawns at position, +floating text shows yield. Empty soil tile remains."
},
{
"action": "Squish Pest",
"trigger": "Left click on aphid cluster",
"effect": "Pest sprite flashes white, then fades (200ms), green squish particle burst, +floating Biomass text."
},
{
"action": "Deploy Creature",
"trigger": "Left click on Canvas when creature selected from inventory",
"effect": "Creature spawns at click position with bounce animation (scale 0→1 with overshoot, 400ms). Immediately begins AI behavior."
},
{
"action": "Inspect Tile",
"trigger": "Right click on any tile",
"effect": "Tooltip shows: soil moisture %, plant species/growth stage, water flow rate, any active effects. Persists while holding."
},
{
"action": "Collect Seed Packet",
"trigger": "Left click on spawned seed packet collectible",
"effect": "Packet bursts into 3 particles and flies toward currency counter, Seeds count animates up."
},
{
"action": "Catch Butterfly",
"trigger": "Left click on butterfly (skill-based timing)",
"effect": "Butterfly stops mid-flight, capture animation (spiral shrink), +Knowledge star particle, species unlock toast."
}
]
},
"bottomPanel": {
"height": "35% of viewport, collapsible to 40px (just tab bar)",
"collapseButton": "Up arrow icon (^) when expanded, down arrow (v) when collapsed. Smooth height transition (300ms).",
"whenCollapsed": "Only tab bar visible as single row of icons/labels. Canvas expands to fill space.",
"layout": "+--------------------------------------------------+\n| [Seeds] [Creatures] [Tools] [Shop] [Knowledge] [^] |\n+--------------------------------------------------+\n| |\n| [Active Tab Content Area] |\n| (Seed selector, creature inventory, redirector tools, |\n| upgrade cards, cross-breed UI, skill tree) |\n| |\n+--------------------------------------------------+"
},
"navigation": {
"tabs": [
{
"id": "seeds",
"label": "Seeds",
"icon": "🌱",
"unlockedAt": "gameStart",
"content": "Seed type selector with cost, growth time, water needs. Shows discovered species. Locked seeds show as ??? with lock icon."
},
{
"id": "creatures",
"label": "Creatures",
"icon": "🐝",
"unlockedAt": "biomass >= 15 (ladybug unlock)",
"content": "Creature inventory (bees, ladybugs in stock), purchase buttons for new creatures, creature stats (lifespan, efficiency)."
},
{
"id": "tools",
"label": "Tools",
"icon": "🔧",
"unlockedAt": "gameStart",
"content": "Water redirector types (channel, turn, splitter, dam, pump), terraforming abilities (call rain, flood control), placement info."
},
{
"id": "shop",
"label": "Shop",
"icon": "🏪",
"unlockedAt": "biomassCurrency revealed",
"content": "Upgrade cards (crop yield, water retention, redirector efficiency), permanent upgrades (Knowledge shop), prestige upgrades."
},
{
"id": "knowledge",
"label": "Knowledge",
"icon": "📚",
"unlockedAt": "knowledge >= 20 (cross-breeding unlock)",
"content": "Discovered species log, cross-breeding interface, achievements, biodiversity meter, prestige button."
}
],
"tabAppearanceAnimation": "When unlocked, tab fades in (500ms) with a glow pulse effect. 'New!' badge shows for 30 seconds. Notification dot appears until tab clicked once."
},
"tabContents": {
"seedsTab": {
"layout": "+---------------------------------------+\n| SELECT SEED TYPE [Q/E cycle] |\n| +--------+ +--------+ +--------+ |\n| | Wheat | | Tomato | | Berry | |\n| | 🌾 | | 🍅 | | 🫐 | |\n| | Cost:1 | | Cost:2 | | Cost:3 | |\n| | 40s | | 60s | | 90s | |\n| +--------+ +--------+ +--------+ |\n| |\n| +--------+ +--------+ +--------+ |\n| |Pumpkin | | ??? | | ??? | |\n| | 🎃 | | 🔒 | | 🔒 | |\n| | Cost:4 | | ? | | ? | |\n| | 120s | | ? | | ? | |\n| +--------+ +--------+ +--------+ |\n+---------------------------------------+",
"elements": [
{
"name": "Seed Card",
"content": "Shows: species icon, name, seed cost, growth time, water need indicator (droplet icons)",
"interaction": "Click to select for planting. Selected card glows gold. Hover shows tooltip with detailed info (yield per harvest, biomass from lifecycle, cross-breed potential).",
"visualStates": {
"available": "Normal colors, full info visible, clickable",
"selected": "Gold border (#FFD700), glow effect, checkmark indicator",
"cannotAfford": "Border dimmed, cost text red, semi-transparent (50% opacity)",
"locked": "Entire card dimmed, shows ??? and lock icon, no details, click reveals hint",
"newUnlock": "Rainbow glow pulse for 10 seconds, 'New!' badge top-right"
}
}
]
},
"creaturesTab": {
"layout": "+---------------------------------------+\n| CREATURE INVENTORY |\n| +--------+ +--------+ +--------+ |\n| | Ladybug| | Bee | | Empty | |\n| | 🐞 x3 | | 🐝 x1 | | slot | |\n| | Ready | | Ready | | - | |\n| +--------+ +--------+ +--------+ |\n| |\n| PURCHASE MORE |\n| +--------+ +--------+ |\n| | Ladybug| | Bee | |\n| | 🐞 | | 🐝 | |\n| | 15 Bio | | 25 Bio | |\n| | [BUY] | | [BUY] | |\n| +--------+ +--------+ |\n+---------------------------------------+",
"elements": [
{
"name": "Creature Slot",
"content": "Shows: creature icon, count in inventory, status (Ready/Deployed/Exhausted), click to deploy",
"interaction": "Click to select for placement. Cursor changes to creature sprite. Click on Canvas to deploy.",
"visualStates": {
"available": "Full opacity, creature visible, count badge, clickable",
"selected": "Blue glow (#4FC3F7), cursor becomes creature",
"zeroStock": "Greyed out, count shows 0, not clickable",
"exhausted": "Red tint, 'Zzz' icon, not clickable until cooldown"
}
},
{
"name": "Purchase Button",
"content": "Creature icon, cost in Biomass, BUY button",
"interaction": "Click to purchase if affordable. Stock +1, cost deducted, creature card flashes green.",
"visualStates": {
"affordable": "Green button (#4CAF50), white text, full opacity",
"cannotAfford": "Grey button (#9E9E9E), red cost text, not clickable",
"maxStock": "Button hidden, 'MAX' badge shows"
}
}
]
},
"toolsTab": {
"layout": "+---------------------------------------+\n| WATER REDIRECTORS |\n| +--------+ +--------+ +--------+ |\n| |Channel | | Turn | |Splitter| |\n| | ═══ | | ║ | | Y | |\n| | 5 Bio | | 8 Bio | | 12 Bio | |\n| | [BUY] | | [BUY] | | [BUY] | |\n| +--------+ +--------+ +--------+ |\n| |\n| +--------+ +--------+ +--------+ |\n| | Dam | | Pump | | ??? | |\n| | ≡≡≡ | | ↑ | | 🔒 | |\n| | 18 Bio | | 20 Bio | | ? | |\n| | [BUY] | | [BUY] | | [??] | |\n| +--------+ +--------+ +--------+ |\n| |\n| TERRAFORMING ABILITIES |\n| +------------------+ +------------------+\n| | Call Rain | | Flood Control |\n| | 🌧️ 15 Flow | | 🌊 20 Flow |\n| | [USE] | | [USE] |\n| +------------------+ +------------------+\n+---------------------------------------+",
"elements": [
{
"name": "Redirector Card",
"content": "Shape icon, name, cost, BUY button (one-time unlock)",
"interaction": "Click BUY to unlock. Once unlocked, infinite use. Click to select for placement, drag on Canvas to place.",
"visualStates": {
"locked": "Dimmed, lock icon, cost hidden, click shows hint",
"unlockedNotPurchased": "Full visible, BUY button green if affordable",
"purchased": "Checkmark, 'Unlocked', selectable for placement",
"selected": "Gold border, ghost preview follows cursor on Canvas"
}
},
{
"name": "Terraforming Ability",
"content": "Icon, name, Flow Energy cost, cooldown timer, USE button",
"interaction": "Click USE to activate. Some abilities target cursor (rain cloud appears at mouse), others are instant.",
"visualStates": {
"ready": "Glowing border, USE button blue (#4FC3F7)",
"onCooldown": "Greyed out, countdown timer visible",
"cannotAfford": "Red cost text, button grey, not clickable"
}
}
]
},
"shopTab": {
"layout": "+---------------------------------------+\n| UPGRADES - BIOMASS |\n| +--------+ +--------+ +--------+ |\n| |Wheat | |Water | |Redir. | |\n| |Yield | |Retention|Efficiency|\n| |Lv.2/5 | |Lv.1/3 | |Lv.3/5 | |\n| |10 Bio | |8 Bio | |5 Bio | |\n| |[UPGRADE]| |[UPGRADE]| |[UPGRADE]|\n| +--------+ +--------+ +--------+ |\n| |\n| PERMANENT UPGRADES - KNOWLEDGE |\n| +--------+ +--------+ |\n| |Ancient | |Flow | |\n| |Seeds | |Mastery | |\n| |Lv.1/5 | |Lv.0/5 | |\n| |10 Know | |25 Know | |\n| |[UPGRADE]| |[UPGRADE]| |\n| +--------+ +--------+ |\n+---------------------------------------+",
"elements": [
{
"name": "Upgrade Card",
"content": "Name, current level/max, cost, effect description, UPGRADE button",
"interaction": "Hover shows detailed tooltip (current effect, next level effect). Click UPGRADE to purchase. Card flashes green, level animates up.",
"visualStates": {
"affordable": "Normal opacity, green button, full info visible",
"cannotAfford": "Cost text red, button grey, slight transparency",
"maxed": "MAX badge in gold, button hidden, full green border",
"newUnlock": "Rainbow pulse for 15 seconds, 'New!' badge"
}
}
]
},
"knowledgeTab": {
"layout": "+---------------------------------------+\n| DISCOVERED SPECIES: 8/10 |\n| [████████░░] 80% to next bonus |\n| |\n| +-----+ +-----+ +-----+ +-----+ +-----+ |\n| |Wheat| |Tomat| |Berry| |Ladyb| |Bee | |\n| | 🌾 | | 🍅 | | 🫐 | | 🐞 | | 🐝 | |\n| +-----+ +-----+ +-----+ +-----+ +-----+ |\n| |\n| +-----+ +-----+ +-----+ +-----+ |\n| |Butterfly|Pumpkin| ??? | ??? | |\n| | 🦋 | | 🎃 | | 🔒 | | 🔒 | |\n| +-------+ +-----+ +-----+ +-----+ |\n| |\n| CROSS-BREEDING (select 2 adjacent plants) |\n| [━━━━━━━━━━━━━━] Select 1st parent |\n| [━━━━━━━━━━━━━━] Select 2nd parent |\n| [BREED] Cost: 10 Seeds + 5 Biomass |\n| |\n| ACHIEVEMENTS |\n| ☑ First Harvest ☐ Pollination Master |\n+---------------------------------------+",
"elements": [
{
"name": "Species Badge",
"content": "Species icon, name (on hover), discovered status",
"interaction": "Hover shows species details (unlocked when, special properties). Locked shows ??? with hint.",
"visualStates": {
"discovered": "Full color icon, glow effect, clickable for details",
"undiscovered": "Silhouette with lock icon, question mark, no hover info",
"newDiscovery": "Rainbow pulse for 30 seconds, 'New!' badge"
}
},
{
"name": "Cross-Breed Interface",
"content": "Two parent slots, progress bars showing selection, BREED button with cost",
"interaction": "Click BREED then click two adjacent crops on Canvas. Both crops glow when selected. Click BREED to attempt cross-breed.",
"visualStates": {
"inactive": "Slots empty, button grey",
"selecting1st": "First slot pulses, cursor becomes crosshair",
"selecting2nd": "Both slots show, second pulses",
"readyToBreed": "Both slots show parent icons, button gold, can click to breed",
"cannotAfford": "Button grey, cost text red"
}
},
{
"name": "Achievement List",
"content": "Checkbox icon, achievement name, reward amount",
"interaction": "Completed show checkmark, locked show lock. Hover reveals hint for locked achievements.",
"visualStates": {
"completed": "Green checkmark, gold text",
"inProgress": "Empty checkbox, normal text",
"locked": "Lock icon, dimmed text, no hint (spoiler prevention)"
}
},
{
"name": "Prestige Button",
"content": "Large button at bottom of Knowledge tab: 'PRESTIGE: ECOSYSTEM MASTERY'",
"interaction": "Only appears when condition met (10 species, 1 cycle). Opens prestige confirmation modal.",
"visualStates": {
"locked": "Button hidden, shows requirements progress instead",
"available": "Pulsing rainbow border, 'READY!' badge, large and prominent",
"hovered": "Shows preview of Knowledge reward on hover"
}
}
]
}
},
"notificationsArea": {
"toastMessages": {
"position": "top-right, 20px from edge",
"behavior": "Slide in from right (300ms ease-out), fade after 4 seconds, stack up to 3 toasts vertically",
"style": "Semi-transparent dark background (#2d2620, 0.95), light text, colored icon on left"
},
"milestonePopup": {
"position": "Center screen, overlays Canvas",
"behavior": "Scale in from 0 (400ms), dramatic gold glow effect, auto-dismiss after 5 seconds or click to dismiss",
"style": "Large icon (64px), achievement name in gold, description, reward amount, star particles around border"
}
}
},
"componentSpecifications": {
"upgradeCard": {
"layout": "+----------------------------------+\n| [Icon] Upgrade Name [Lv.3/5] |\n| Increases crop yield by 15% |\n| Current: +15% → Next: +20% |\n| Cost: 10 Biomass [UPGRADE] |\n+----------------------------------+",
"states": {
"affordable": {
"border": "#4CAF50 (green), 2px solid",
"buttonColor": "#4CAF50, white text",
"textColor": "#e8e4dc (primary)",
"background": "#2d2620"
},
"cannotAfford": {
"border": "#68645c (muted), 1px solid",
"buttonColor": "#9E9E9E (grey), white text",
"costColor": "#F44336 (red)",
"background": "#2d2620, 0.8 opacity"
},
"maxed": {
"border": "#FFD700 (gold), 3px solid",
"badge": "'MAX' in gold, top-right corner",
"buttonHidden": true,
"glowEffect": "Subtle gold pulse animation"
},
"locked": {
"entireCard": "Dimmed to 0.4 opacity",
"content": "Shows lock icon, '???' instead of name, no details revealed",
"clickBehavior": "Shows hint toast: 'Unlock by [condition]'"
},
"hoverAffordable": {
"border": "#66BB6A (lighter green), 3px solid",
"glow": "Green glow shadow (0 0 10px rgba(76, 175, 80, 0.5))",
"tooltip": "Detailed info panel appears above card"
},
"clickAffordable": {
"animation": "Flash white (200ms) → green flash (100ms)",
"numberAnimation": "Level counter animates up (count 3→4 over 300ms)",
"satisfaction": "Subtle scale bounce (1.05 → 1.0 over 200ms)",
"canvasEffect": "If upgrade affects Canvas entities (e.g., crop yield), affected entities briefly glow white"
},
"clickCannotAfford": {
"animation": "Shake left-right (3x, 50ms each)",
"costFlash": "Cost text flashes red twice (200ms total)",
"buttonFeedback": "Button briefly shows red border"
}
}
},
"currencyDisplayHUD": {
"layout": "🌱 1,234.5 (+12.3/s)",
"elements": [
{
"name": "Icon",
"content": "Currency emoji (🌱, 🌿, 💧, 📚)",
"size": "20px"
},
{
"name": "Amount",
"content": "Current count, formatted with commas",
"font": "Roboto Mono, 600, 16px",
"color": "Currency accent color"
},
{
"name": "Rate",
"content": "Per-second production rate in parentheses",
"font": "Nunito, 400, 12px",
"color": "Secondary text (#a8a49c)",
"visibility": "Only shows if rate > 0"
}
],
"behaviors": {
"numberAnimation": "Count-up animation from old value to new value over 300ms using ease-out timing. Numbers scroll like slot machine if increase > 50.",
"rateDisplay": "Updates every 1 second. Smaller font, gray color. If rate is 0, hide entirely.",
"largeNumbers": "Switch to K suffix at 1,000,000 (1M), B at 1,000,000,000 (1B), T at 1,000,000,000,000 (1T).",
"color": "Match accent color for currency (Seeds: #FFD700, Biomass: #4CAF50, Flow Energy: #4FC3F7, Knowledge: #E040FB).",
"earnedByGameplayFlash": {
"description": "When currency earned from Canvas action (harvest, creature event), NOT passive ticks",
"effect": "Brief gold/colored pulse glow on the entire currency display (200ms). Larger flash for big amounts (>50). Distinct from subtle passive income tick flash."
},
"passiveTickFlash": {
"description": "When currency earned from passive sources (auto-generation, conversions)",
"effect": "Very subtle brightness bump (50ms). Almost imperceptible, prevents UI from feeling static."
}
}
},
"milestoneToast": {
"layout": "+----------------------------------+\n| ★ First Harvest! |\n| You harvested your first crop. |\n| +5 Seeds |\n+----------------------------------+",
"appearance": "Slide in from right edge with easing (300ms). 300px width, auto height.",
"duration": "4 seconds visible, then fade out (500ms). Click to dismiss early.",
"stackBehavior": "Multiple toasts stack vertically with 10px gap. Max 3 visible, oldest dismissed when 4th arrives.",
"elements": [
{
"name": "Icon",
"content": "Star (★) or achievement icon",
"size": "24px, gold color (#FFD700)"
},
{
"name": "Title",
"content": "Achievement name",
"font": "Nunito, 700, 16px, gold color"
},
{
"name": "Description",
"content": "Brief description text",
"font": "Nunito, 400, 14px, primary text color"
},
{
"name": "Reward",
"content": "Currency reward amount with icon",
"font": "Roboto Mono, 600, 14px, accent color"
}
]
},
"prestigePanel": {
"layout": "+------------------------------------------+\n| ⟳ ECOSYSTEM MASTERY |\n| |\n| You have achieved harmony with the valley! |\n| |\n| You will earn: +125 Knowledge |\n| Current total: 42 Knowledge |\n| New total: 167 Knowledge |\n| |\n| ───────── RESETS ───────── |\n| ✗ All terraces (revert to wild state) |\n| ✗ All crops (cleared from soil) |\n| ✗ Creature inventories (emptied) |\n| ✗ Water redirectors (removed) |\n| ✗ Seeds, Biomass, Flow Energy (reset to 0) |\n| |\n| ───────── KEEPS ───────── |\n| ✓ Knowledge (persists) |\n| ✓ Permanent upgrades (Ancient Seeds, etc.) |\n| ✓ Achievements (all progress saved) |\n| ✓ Discovered species (unlocked in next run) |\n| ✓ Prestige count (for visual tiers) |\n| |\n| ───────── VISUAL TRANSFORMATION ───────── |\n| Your valley shows signs of past work: |\n| • Ancient terrace foundations remain visible |\n| • Old water channels mark the soil |\n| • Rare 'ghost species' occasionally spawn |\n| from seeds left behind |\n| |\n| [CANCEL] [PRESTIGE!] |\n+------------------------------------------+",
"modalBehavior": "Semi-transparent dark overlay behind modal. Modal scales in from center (400ms). Prestige button triggers full-screen white flash transition (1s) when confirmed.",
"elements": [
{
"name": "Reward Section",
"content": "Knowledge gain calculation, current → new total",
"color": "Purple/gold gradient text for emphasis"
},
{
"name": "Resets List",
"content": "All lost progress with ✗ indicators",
"color": "Red/coral for warning color"
},
{
"name": "Keeps List",
"content": "All saved progress with ✓ indicators",
"color": "Green for reassurance"
},
{
"name": "Visual Transformation",
"content": "Description of how valley will look different next run",
"style": "Italicized, slightly smaller text, with bullet points"
},
{
"name": "Buttons",
"content": "CANCEL (grey, left), PRESTIGE! (gold/purple gradient, right, larger)",
"hover": "PRESTIGE! button pulses with rainbow border on hover"
}
]
},
"skillTreeRenderer": {
"layoutApproach": "CSS Grid with absolute positioning for connection lines. Each node is a grid cell (80px × 80px). Connections drawn using SVG lines layered behind nodes.",
"nodeSize": "80px × 80px per skill node",
"connectionLines": "SVG paths with stroke width 3px. Lines glow when connected nodes are unlocked. Arrows show direction (from parent to child).",
"nodeStates": [
{
"state": "locked",
"appearance": "Grey background (#68645c), lock icon, no text visible, dimmed border",
"hover": "Shows tooltip: 'Unlock by [condition]'"
},
{
"state": "available",
"appearance": "Primary background (#3d3428), normal border, icon visible, cost visible in bottom-right corner",
"hover": "Border glows gold, tooltip shows full description and effect"
},
{
"state": "purchased",
"appearance": "Green background (#1a3d1a), gold border, icon glows, checkmark badge",
"glow": "Subtle green pulse animation (2s cycle)"
},
{
"state": "maxed",
"appearance": "Gold gradient background, rainbow border, large icon with crown badge",
"effect": "Particle emitter spawns occasional sparkles around node"
}
],
"layoutPattern": "Tree structure with permanent upgrades at top (seed bonus, flow efficiency), branching into creature upgrades, ecosystem upgrades, and special abilities at bottom."
},
"tooltip": {
"layout": "+----------------------------------+\n| Wheat Yield Boost (Level 2) |\n| Wheat produces +2 more seeds |\n| per harvest |\n| |\n| Current: +2 seeds |\n| Next level: +3 seeds |\n| |\n| Cost: 10 Biomass |\n+----------------------------------+",
"trigger": "Hover (desktop) - 200ms delay before appearing",
"position": "Above element, offset by 10px. Clamped to viewport edges (never overflow screen).",
"maxWidth": "250px",
"elements": [
{
"name": "Title",
"content": "Upgrade/item name with level",
"font": "Nunito, 700, 14px, gold color"
},
{
"name": "Description",
"content": "Brief description of what it does",
"font": "Nunito, 400, 12px, primary text color"
},
{
"name": "Current Effect",
"content": "What it does now",
"font": "Roboto Mono, 600, 12px, green color"
},
{
"name": "Next Level",
"content": "What it will do at next level",
"font": "Roboto Mono, 600, 12px, blue color"
},
{
"name": "Cost",
"content": "Currency cost to purchase/upgrade",
"font": "Roboto Mono, 600, 12px, warning color if unaffordable"
}
]
}
},
"uiEventFlowDiagrams": {
"playerInteractionFlows": [
{
"title": "Place Water Redirector",
"mermaid": "sequenceDiagram\n participant Player\n participant Canvas as Canvas\n participant Entities as Entity System\n participant Events as EventBus\n participant UI as HUD/Panels\n\n Note over Player,UI: Player selects redirector tool\n Player->>UI: Click 'Channel' in Tools tab\n UI->>Player: Cursor changes to channel icon\n UI->>Canvas: Show ghost preview at cursor\n\n Note over Player,UI: Player drags on terrace to place\n Player->>Canvas: Drag across terrace tiles\n Canvas->>Canvas: Update ghost preview in real-time\n Canvas->>Canvas: Show valid/invalid placement (green/red tint)\n\n Note over Player,UI: Player releases to confirm placement\n Player->>Canvas: Release mouse button\n Canvas->>Canvas: Validate placement (not overlapping, within terrace bounds)\n Canvas->>Entities: createEntity('channel', x, y)\n Entities->>Canvas: Spawn animation (scale 0→1, 300ms)\n Entities->>Canvas: Stone structure sprite appears\n Entities->>Events: emit('redirector-placed', {type, position, cost})\n Events->>UI: Deduct Biomass cost\n Events->>UI: Biomass counter animates down\n Events->>Canvas: Placement flash effect (white glow, 200ms)\n Events->>Canvas: Water flow recalculates, droplets redirect around new structure\n Canvas->>Canvas: Blue sparkle particles at redirector (first water passes)"
},
{
"title": "Plant Seed → Grow → Harvest",
"mermaid": "sequenceDiagram\n participant Player\n participant Canvas as Canvas\n participant Entities as Entity System\n participant Events as EventBus\n participant UI as HUD/Panels\n\n Note over Player,UI: Player selects seed type\n Player->>UI: Click 'Wheat' in Seeds tab\n UI->>Player: Wheat card shows selected (gold border)\n\n Note over Player,UI: Player plants seed\n Player->>Canvas: Click on soil tile\n Canvas->>Canvas: Check: valid soil tile? not already planted?\n Canvas->>Entities: createEntity('wheatCrop', x, y)\n Entities->>Canvas: Spawn animation (scale 0→1, 200ms)\n Entities->>Canvas: Sprout sprite appears, soil darkens\n Entities->>Events: emit('crop-planted', {type, position, cost})\n Events->>UI: Deduct 1 Seed\n Events->>UI: Seeds counter animates down\n\n Note over Player,UI: Crop grows over time (based on water)\n Entities->>Canvas: Growth stage 1 → 2 → 3 → 4 (mature)\n Canvas->>Canvas: Plant size increases 25% per stage\n Canvas->>Canvas: Leaves change color based on moisture\n Entities->>Events: emit('crop-grew', {stage, position})\n\n Note over Player,UI: Player harvests mature crop\n Canvas->>Player: Mature crop glows, cursor changes on hover\n Player->>Canvas: Click mature crop\n Canvas->>Entities: crop.harvest()\n Entities->>Canvas: Harvest animation (scale 1→0, 300ms)\n Entities->>Events: emit('crop-harvested', {type, position, yield})\n Events->>Canvas: spawnCollectible('seedPacket', position, value: yield.seeds)\n Canvas->>Canvas: Seed packet sprite spawns with pop-in (200ms)\n Canvas->>Canvas: Bob animation on seed packet\n Events->>UI: floatingText('+5 Seeds', position, color: #FFD700)\n Events->>UI: Seeds count-up animation (300ms)\n Events->>UI: Seeds display flashes gold (gameplay-earned flash)\n Player->>Canvas: Click seed packet to collect (or wait 8s for auto-collect)\n Canvas->>Events: emit('collectible-collected', {type, value})"
},
{
"title": "Bee Pollination → Biomass Reward",
"mermaid": "sequenceDiagram\n participant Canvas as Canvas\n participant Creature as Creature System\n participant Events as EventBus\n participant UI as HUD/Panels\n\n Note over Canvas,UI: Bee seeks flower\n Creature->>Canvas: Bee scans for flowering crops\n Creature->>Creature: Find target within 150px\n Creature->>Canvas: Bee moves toward flower (flutter animation)\n\n Note over Canvas,UI: Bee pollinates\n Creature->>Canvas: Bee reaches flower\n Creature->>Canvas: Pollination animation (golden dust particles, 2s)\n Creature->>Events: emit('bee-pollinated', {position, value: 8})\n Events->>Canvas: spawnCollectible('biomassParticle', position, value: 8)\n Canvas->>Canvas: Green leaf sprite spawns with spiral-up motion (500ms)\n Canvas->>Canvas: Flower glows gold briefly (pollinated indicator)\n Canvas->>Events: emit('biomass-collected', {value, position})\n Events->>UI: floatingText('+8 Biomass', position, color: #4CAF50)\n Events->>UI: Biomass count-up animation (300ms)\n Events->>UI: Biomass display flashes green (gameplay-earned flash)\n Creature->>Canvas: Bee moves to next flower (chain bonus if within range)"
},
{
"title": "Pest Outbreak → Ladybug Defense",
"mermaid": "sequenceDiagram\n participant Canvas as Canvas\n participant Creature as Creature System\n participant Player\n participant Events as EventBus\n participant UI as HUD/Panels\n\n Note over Canvas,UI: Pest spawn (random event)\n Creature->>Canvas: spawnEntity('aphidSwarm', cropPosition)\n Canvas->>Canvas: Green slime sprites appear on crop\n Creature->>Canvas: Aphids spread to adjacent crops (every 5s)\n Canvas->>Canvas: Affected crops show wilting animation\n\n Note over Canvas,UI: Player responds (manual or creature)\n Player->>Canvas: Click individual aphids to squish\n Canvas->>Canvas: Squish animation (white flash, fade 200ms)\n Canvas->>Events: emit('pest-squished', {position, value: 2})\n Events->>UI: floatingText('+2 Biomass', position)\n \n alt Player has ladybug\n Player->>UI: Click ladybug in inventory\n Player->>Canvas: Click near outbreak center\n Canvas->>Creature: createEntity('ladybug', position)\n Creature->>Canvas: Ladybug spawns with bounce animation (400ms)\n Creature->>Canvas: Ladybug moves toward nearest aphid\n Creature->>Canvas: Ladybug eats aphid (1s animation)\n Creature->>Events: emit('ladybug-ate-pest', {position, value: 5})\n Events->>UI: floatingText('+5 Biomass', position)\n Creature->>Canvas: Ladybug creates 'protected zone' (green circle radius 50px)\n Creature->>Canvas: Aphids in zone take damage, flee\n end\n\n Note over Canvas,UI: Outbreak resolved\n Creature->>Canvas: All aphids eliminated\n Canvas->>Canvas: Affected crops recover (wilting reverses)\n Canvas->>Events: emit('outbreak-defeated', {pestCount})"
},
{
"title": "Butterfly Catch (Knowledge Discovery)",
"mermaid": "sequenceDiagram\n participant Canvas as Canvas\n participant Creature as Creature System\n participant Player\n participant Events as EventBus\n participant UI as HUD/Panels\n\n Note over Canvas,UI: Butterfly spawns (rare event)\n Creature->>Canvas: spawnEntity('butterfly', randomTerrace)\n Canvas->>Canvas: Multi-colored wing sprite appears (ghost variant)\n Creature->>Canvas: Flutter animation with erratic movement pattern\n Creature->>Canvas: Butterfly migrates between terraces (slow, deliberate)\n\n Note over Canvas,UI: Player attempts catch (skill check)\n Player->>Canvas: Click on butterfly\n Canvas->>Canvas: Timing check (butterfly must be in 'catchable' state)\n \n alt Successful catch\n Canvas->>Canvas: Butterfly capture animation (spiral shrink, 300ms)\n Canvas->>Creature: butterfly.remove()\n Creature->>Events: emit('butterfly-caught', {species, position, value: 10})\n Events->>Canvas: spawnVisualEffect('knowledgeStar', position)\n Canvas->>Canvas: Star sprite bursts in (400ms), floats upward\n Events->>UI: floatingText('+10 Knowledge - New Species!', position, color: #E040FB)\n Events->>UI: Knowledge count-up animation\n Events->>UI: Knowledge display flashes purple (gameplay-earned flash)\n Events->>UI: Toast appears: 'New Species Documented! 🦋'\n Events->>UI: Species badge unlocks in Knowledge tab\n else Missed catch\n Canvas->>Canvas: Butterfly flees (speed boost 3x for 2s)\n Canvas->>Canvas: 'Whoosh' particle effect\n end"
},
{
"title": "Wave/Day-Night Cycle → Growth Rate Changes",
"mermaid": "sequenceDiagram\n participant Canvas as Canvas\n participant Systems as Game Systems\n participant UI as HUD/Panels\n participant Events as EventBus\n\n Note over Canvas,UI: Day cycle begins\n Systems->>Canvas: Set sky color to warm blue (#87CEEB)\n Systems->>Canvas: Sun sprite rises in background\n Systems->>Systems: Set globalGrowthMultiplier = 1.0 (normal)\n Events->>UI: Update day/night indicator (☀️ icon, progress bar starts)\n UI->>UI: Day lasts 60 seconds (progress bar fills)\n Canvas->>Canvas: All plants show 'perky' animation (slight bounce)\n\n Note over Canvas,UI: Night cycle begins\n Systems->>Canvas: Transition sky to dark blue (#1a1a3e) over 3s\n Systems->>Canvas: Stars appear, moon rises\n Systems->>Systems: Set globalGrowthMultiplier = 0.5 (slower growth)\n Events->>UI: Update indicator (🌙 icon, progress bar resets)\n UI->>UI: Night lasts 30 seconds\n Canvas->>Canvas: Plants show 'sleeping' animation (slight droop)\n Canvas->>Canvas: Bioluminescent plants glow (if rare species unlocked)\n\n Note over Canvas,UI: Cycle repeats\n Systems->>Canvas: Return to day, sky warms again\n Systems->>Systems: Reset growth multiplier to 1.0\n Events->>UI: Progress bar continues (90s total cycle)"
}
]
},
"uiStateMachine": {
"title": "UI State Machine",
"mermaid": "stateDiagram-v2\n [*] --> Loading: page load\n Loading --> TutorialOverlay: assets loaded, first visit\n Loading --> Playing: assets loaded, returning player\n\n state TutorialOverlay {\n [*] --> Visible: localStorage shows firstVisit\n Visible --> Playing: 'Got it!' clicked OR click outside\n Visible --> [*]: Set localStorage.visited = true\n }\n\n state Playing {\n [*] --> PlantingPhase\n PlantingPhase: Player plants seeds, places redirectors\n PlantingPhase: Bottom panel fully visible\n PlantingPhase: Canvas interactive (click to plant/drag to place)\n \n PlantingPhase --> CreatureActive: Creature purchased/deployed\n CreatureActive: Bees pollinating, ladybugs hunting\n CreatureActive: Canvas shows creature activity\n \n CreatureActive --> WeatherEvent: Random rain/drought\n WeatherEvent: Clouds animate in, rain particles\n WeatherEvent: Player can use terraforming abilities\n WeatherEvent --> PlantingPhase: Weather clears\n \n PlantingPhase --> HarvestReady: Crop reaches maturity\n HarvestReady: Crop glows, harvest cursor\n HarvestReady: Player clicks to harvest\n \n HarvestReady --> PestOutbreak: Random spawn\n PestOutbreak: Aphids appear on crops\n PestOutbreak: Player can click to squish OR deploy ladybug\n PestOutbreak --> PlantingPhase: Outbreak resolved\n \n PlantingPhase --> ButterflySpawn: Rare event\n ButterflySpawn: Butterfly appears, catch skill check\n ButterflySpawn --> PlantingPhase: Butterfly caught or fled\n }\n\n Playing --> PrestigeConfirmation: Prestige button clicked\n PrestigeConfirmation --> Playing: CANCEL clicked\n PrestigeConfirmation --> PrestigeTransition: PRESTIGE! clicked\n \n state PrestigeTransition {\n [*] --> WhiteFlash: Full screen white fade (1s)\n WhiteFlash --> ValleyReset: All entities removed\n ValleyReset --> NewRun: Valley respawns with visual tier changes\n NewRun --> [*]: Return to Playing with persistent upgrades\n }\n\n Playing --> SettingsModal: Gear icon clicked\n SettingsModal --> Playing: Modal closed\n \n Playing --> TabSwitch: Player clicks different tab\n TabSwitch --> Playing: Tab content changes, Canvas remains visible"
},
"feedbackSystems": {
"visualFeedbackCatalog": [
{
"action": "Enemy/Pest Defeated",
"canvasFeedback": "Aphid sprite flashes white, fades out (200ms). Green squish particles burst (5 particles). Floating '+2 Biomass' text rises from position.",
"uiFeedback": "Biomass counter pulses green, count-up animation (300ms). If it was the 10th pest killed by player, toast appears: 'Pest Squish Mastery!'",
"duration": "200ms (sprite fade) + 800ms (floating text)"
},
{
"action": "Crop Harvested",
"canvasFeedback": "Crop sprite shrinks from scale 1→0 (300ms). Seed packet sprite spawns with pop-in (200ms). Packet bobs gently (2px amplitude, 2Hz).",
"uiFeedback": "Seeds counter displays count-up animation (300ms). Gold flash on Seeds display (distinct from passive). Floating '+5 Seeds' text in gold.",
"duration": "300ms (harvest) + indefinite (until collected or 8s timeout)"
},
{
"action": "Seed Packet Collected",
"canvasFeedback": "Packet bursts into 3 sparkle particles, spirals toward currency counter position, fades out (500ms).",
"uiFeedback": "Seeds display pulses gold again (reinforcement). Sound effect (collect_seed.mp3).",
"duration": "500ms"
},
{
"action": "Purchase Upgrade",
"canvasFeedback": "If upgrade affects crops (yield boost): All crops of that type glow white briefly (200ms), then show growth boost animation (slight size bump). If redirector efficiency: All redirectors emit extra sparkle particles.",
"uiFeedback": "Upgrade card flashes green (200ms), shakes slightly for satisfaction. Level counter animates up (2→3 over 300ms). Cost deducted from currency with count-down animation.",
"duration": "300ms"
},
{
"action": "Cannot Afford Click",
"canvasFeedback": "None (UI-only feedback)",
"uiFeedback": "Card shakes left-right (3x, 50ms each). Cost text flashes red twice (200ms). Button briefly shows red border.",
"duration": "200ms"
},
{
"action": "New Unlock (Seed/Creature/Tool)",
"canvasFeedback": "New entity type appears on Canvas for first time (if creature) OR preview animation in relevant UI panel.",
"uiFeedback": "Tab glows/pulses for 30 seconds. Notification dot appears on tab. Toast slides in: 'New Seed: Tomato! 🍅'. New badge shows on item for 30 seconds.",
"duration": "30 seconds (glow/badge), toast 4 seconds"
},
{
"action": "Prestige",
"canvasFeedback": "Full screen white flash (1s). Valley fades out. All entities removed. Valley fades back in with new visual tier (ancient foundations visible, ghost species particles).",
"uiFeedback": "Screen flash white. Prestige modal appears with Knowledge reward. After confirmation, full-screen transition animation (1-2s). All currencies reset to 0 (count-down animation). Knowledge persists with + animation.",
"duration": "1-2 seconds (transition)"
},
{
"action": "Skill Node Purchased (Knowledge upgrades)",
"canvasFeedback": "If upgrade affects creatures (lifespan, efficiency): All creatures on Canvas briefly glow with aura. If seed bonus: Seed packets in inventory show golden glow.",
"uiFeedback": "Skill node fills with green color from center (scale 0→1, 500ms). Connection lines to node light up with glow effect. Level counter animates up.",
"duration": "500ms"
},
{
"action": "Unit/Creature Spawned",
"canvasFeedback": "Sprite appears with spawn animation: fade in + scale up from center (0→1 over 300ms for crops, 400ms with overshoot bounce for creatures). For ladybugs/bee: brief invulnerability flash (white outline for 500ms).",
"uiFeedback": "Resource cost deducted with count-down animation. Creature inventory slot updates (count -1, or stock depleted).",
"duration": "300-400ms"
},
{
"action": "Entity Takes Damage (Pests eating crops)",
"canvasFeedback": "Crop sprite flashes white briefly (100ms), then shows wilting animation (slight droop, color shift to yellow/brown). Floating damage number ('-5 HP') in red.",
"uiFeedback": "None (Canvas-only)",
"duration": "200ms"
},
{
"action": "Plant Completes Lifecycle (Not Harvested)",
"canvasFeedback": "Mature plant shows elaborate seed-scatter animation (seeds burst outward in 8 directions, fade over 1s). Plant sprite fades (opacity 1→0 over 500ms). New sprouts appear in adjacent tiles.",
"uiFeedback": "Biomass counter pulses green (+15). Knowledge counter if rare discovery. Toast: 'Lifecycle Complete! +15 Biomass'.",
"duration": "1 second (seed scatter) + 500ms (fade)"
},
{
"action": "Bee Pollination Chain",
"canvasFeedback": "Pollen golden dust trails behind bee as it moves between flowers. Each pollinated flower glows gold (2s glow). Chain bonus: trail gets brighter with each pollination (max 2x).",
"uiFeedback": "Each pollination event shows floating '+8 Biomass' (or +16 with chain bonus). Biomass counter animates up on each. At 5-chain milestone, toast: 'Pollination Master! 2x rewards for 30s!'",
"duration": "Per event: 2s (pollination) + 300ms (UI animation)"
},
{
"action": "Flow Energy Generated (Water passes redirector)",
"canvasFeedback": "Blue sparkle sprite appears at redirector position (instant, fades over 200ms). Redirector briefly glows blue (100ms).",
"uiFeedback": "Flow Energy bar fills from left (100ms animation). At cap (100), bar flashes red warning, brief shake.",
"duration": "200ms"
},
{
"action": "Terrace Expansion (New tier unlocked)",
"canvasFeedback": "New terrace animates upward from below screen (slide up + fade in, 800ms). Soil texture reveals with growing grass effect. Water cascade animates down to new level.",
"uiFeedback": "Full screen celebration: confetti particles, toast: 'Terrace 2 Unlocked! 🏔️'. Species counter updates (new species possible).",
"duration": "800ms (terrace animation) + 3s celebration"
},
{
"action": "Cross-Breed Success",
"canvasFeedback": "Both parent plants glow, merge animation (spirals move toward center, 500ms). New rare plant sprite spawns at center with rainbow burst (scale 0→1 with overshoot, 600ms).",
"uiFeedback": "Knowledge counter animates up. Toast: 'New Variation Created! 🧬'. New species badge unlocks in Knowledge tab with rainbow pulse.",
"duration": "600ms (spawn) + 4s (toast)"
},
{
"action": "Weather Event Start (Rain)",
"canvasFeedback": "Cloud sprite drifts in from screen edge (slow, 10s to cross). Rain particle overlay appears (droplets fall diagonally). All terraces gradually darken (soil moisture increases). Puddles expand on saturated tiles.",
"uiFeedback": "Weather indicator appears in HUD (cloud icon with rain animation). Toast on first rain: 'Rain Arrived! Watch for flooding!'",
"duration": "Weather lasts 20-30s, warning toast 4s"
},
{
"action": "Biodiversity Milestone (5, 8, 10 species)",
"canvasFeedback": "All creatures on Canvas pause, perform 'celebration' animation (bounce in unison, 500ms). Rainbow particles emit from biodiversity meter area.",
"uiFeedback": "Biodiversity meter fills to new tier. Toast: 'Biodiversity Thrives! +10 Seeds per 5 species 🌿'. Bonus Seeds awarded with count-up animation.",
"duration": "500ms (celebration) + 4s (toast)"
}
]
},
"numberFormattingRules": [
{
"range": "0 - 999",
"format": "Whole number",
"example": "742"
},
{
"range": "1,000 - 999,999",
"format": "With commas",
"example": "12,345"
},
{
"range": "1,000,000 - 999,999,999",
"format": "Suffix with 1 decimal",
"example": "1.5M"
},
{
"range": "1B - 999B",
"format": "Suffix with 1 decimal",
"example": "42.3B"
},
{
"range": "1T+",
"format": "Suffix with 1 decimal",
"example": "1.2T"
},
{
"range": "Rates (/sec)",
"format": "1 decimal, always show + sign",
"example": "+12.3/s"
},
{
"range": "Damage/Healing numbers (Canvas)",
"format": "Whole number, no suffix, color-coded",
"example": "-15 (red), +10 (green)"
}
],
"progressBars": {
"style": "Rounded corners (4px radius), striped background (diagonal stripes at 45°, 10% opacity of fill color), animated fill (width transition over 300ms)",
"color": "Green gradient (light #66BB6A to dark #4CAF50) for most bars. Flow Energy uses blue (#4FC3F7). Experience/growth uses gold (#FFD700).",
"label": "Percentage on right side (e.g., '75%'), current/max below bar (e.g., '45/60')"
},
"controlsPanel": {
"position": "Semi-transparent overlay bar at bottom of Canvas (not in bottom panel). Always visible, never hidden.",
"height": "28px, padding 8px",
"backgroundColor": "rgba(26, 24, 20, 0.85)",
"layout": "🖱️ Click Soil: Plant | Drag Terrace: Place Channel | Click Crop: Harvest | Right-Click: Inspect",
"style": "Compact single-line, light text (#e8e4dc), monospace font for shortcuts, 13px, semi-transparent background",
"responsive": "On narrower viewports (< 1400px), use icon shorthand: '🌱 Plant | 🔄 Place | 🌾 Harvest | 🔍 Inspect'",
"alwaysVisible": true,
"allInteractions": [
{
"action": "Plant Seed",
"trigger": "Click soil (with seed selected)",
"hotkey": "None (mouse only)"
},
{
"action": "Place Redirector",
"trigger": "Drag terrace (with tool selected)",
"hotkey": "Q/E to cycle tools"
},
{
"action": "Harvest",
"trigger": "Click mature crop",
"hotkey": "None (mouse only)"
},
{
"action": "Inspect",
"trigger": "Right-click tile",
"hotkey": "None (mouse only)"
}
]
},
"gettingStartedOverlay": {
"trigger": "Shows automatically on first page load (check localStorage.visited === undefined)",
"dismiss": "'Got it!' button OR click anywhere outside overlay",
"persistence": "Set localStorage.visited = 'true' on dismiss. Never show again.",
"content": [
"🌱 Click on soil to plant wheat — watch it grow based on water flow",
"🔄 Drag on terraces to place stone channels — redirect water to thirsty crops",
"🌾 Harvest by clicking mature plants — earn seeds to expand your garden",
"🐝 Deploy creatures to help — bees pollinate, ladybugs defend against pests"
],
"layout": "+------------------------------------------+\n| |\n| HOW TO PLAY |\n| |\n| 🌱 Click on soil to plant wheat |\n| Watch it grow based on water flow |\n| |\n| 🔄 Drag on terraces to place channels |\n| Redirect water to thirsty crops |\n| |\n| 🌾 Harvest by clicking mature plants |\n| Earn seeds to expand your garden |\n| |\n| 🐝 Deploy creatures to help |\n| Bees pollinate, ladybugs defend |\n| |\n| |\n| [ GOT IT! ] |\n+------------------------------------------+",
"style": "Semi-transparent dark overlay (#1a1814, 0.95). Centered modal, 400px width. Large readable text (16px body, 20px heading). Prominent dismiss button (gold background, 200px width, 44px height). Z-index: 9999 (above everything including Canvas)."
},
"responsiveConsiderations": {
"minWidth": "1280px (below this, show warning message)",
"maxWidth": "Full viewport (no cap)",
"scalingApproach": "Canvas scales to fit available width while maintaining 16:9 aspect ratio. Bottom panel uses rem-based sizing for consistent proportions.",
"panelCollapseBehavior": "Bottom panel can be collapsed via arrow button to give Canvas more space. On narrow viewports (< 1400px), default to collapsed state with expand button prominent.",
"controlsPanel": "Shrinks to icon-only mode below 1400px width. Full text shows at 1400px+."
},
"accessibility": {
"contrastRatios": "All text meets WCAG AA minimum 4.5:1. Primary text (#e8e4dc on #1a1814) = 12.8:1. Secondary text (#a8a49c on #2d2620) = 5.2:1.",
"focusIndicators": "Visible focus outlines for keyboard navigation (2px solid #4FC3F7, 4px radius). All interactive elements are keyboard-accessible.",
"screenReader": "Currency amounts have aria-live='polite' regions for updates. Canvas state changes announced (e.g., 'Crop harvested, +5 Seeds').",
"reducedMotion": "Respect prefers-reduced-motion media query. Disable all Canvas animations (particles, growth animations), use static sprites. Remove UI transition animations. Show state changes instantly."
},
"settingsPanel": {
"settings": [
{
"name": "Number Notation",
"type": "Toggle",
"options": [
"Standard (K/M/B)",
"Scientific (1.5e6)"
],
"default": "Standard",
"effect": "Changes how large numbers are displayed in all UI elements"
},
{
"name": "Animation Speed",
"type": "Slider",
"range": "0.5x - 2x",
"default": "1x",
"effect": "Scales all animation durations and Canvas game speed (growth rates, creature movement, water flow)"
},
{
"name": "Auto-Save Interval",
"type": "Dropdown",
"options": [
"Off",
"30s",
"60s",
"120s"
],
"default": "30s",
"effect": "How often game state saves to localStorage"
},
{
"name": "Canvas Quality",
"type": "Toggle",
"options": [
"High",
"Low"
],
"default": "High",
"effect": "Low disables glow effects and particle systems for better performance"
},
{
"name": "Day/Night Cycle",
"type": "Toggle",
"options": [
"On",
"Off"
],
"default": "On",
"effect": "Toggle day/night visual changes and growth rate modifiers"
},
{
"name": "Show Controls Panel",
"type": "Toggle",
"options": [
"Always",
"Hover"
],
"default": "Always",
"effect": "Controls panel always visible OR only shows on Canvas hover (mouse-over)"
},
{
"name": "Hard Reset",
"type": "Button (with confirmation)",
"default": "N/A",
"effect": "Wipe all save data (localStorage), reload page as fresh start. Confirmation modal required."
},
{
"name": "Export Save",
"type": "Button",
"default": "N/A",
"effect": "Copy save string to clipboard (base64 encoded JSON). Toast confirms: 'Save copied to clipboard!'"
},
{
"name": "Import Save",
"type": "Button",
"default": "N/A",
"effect": "Prompt for save string, validate and load. Confirmation modal shows preview of imported data before applying."
}
]
},
"config": {
"canvas": {
"width": 1280,
"height": 720,
"backgroundColor": "#2d4a3e",
"gridCellSize": 16,
"layers": [
"background",
"entities",
"effects",
"hudOverlay"
],
"terraceConfig": {
"terraceHeight": 120,
"terracePadding": 20,
"soilColor": "#8B7355",
"soilWetColor": "#5D4E37",
"grassColor": "#4CAF50"
},
"waterConfig": {
"dropletSize": 4,
"dropletColor": "#4FC3F7",
"flowSpeed": 60,
"spawnRate": 1
},
"skyGradient": {
"day": [
"#87CEEB",
"#E0F7FA"
],
"night": [
"#1a1a3e",
"#2d2d5e"
],
"transitionDuration": 3000
}
},
"ui": {
"tickRate": 20,
"autoSaveInterval": 30000,
"theme": "dark",
"hudHeight": 50,
"bottomPanelHeight": 280,
"bottomPanelCollapsedHeight": 40,
"canvasMinHeight": 400,
"controlsPanelHeight": 28,
"tabs": [
{
"id": "seeds",
"label": "Seeds",
"icon": "🌱",
"unlockedAt": "gameStart"
},
{
"id": "creatures",
"label": "Creatures",
"icon": "🐝",
"unlockedAt": "biomass >= 15"
},
{
"id": "tools",
"label": "Tools",
"icon": "🔧",
"unlockedAt": "gameStart"
},
{
"id": "shop",
"label": "Shop",
"icon": "🏪",
"unlockedAt": "biomassCurrency revealed"
},
{
"id": "knowledge",
"label": "Knowledge",
"icon": "📚",
"unlockedAt": "knowledge >= 20"
}
],
"notifications": {
"toastDuration": 4000,
"toastPosition": "top-right",
"milestoneDisplayDuration": 5000,
"stackLimit": 3
},
"animations": {
"fastDuration": 150,
"normalDuration": 300,
"slowDuration": 600,
"bounceEasing": "cubic-bezier(0.68, -0.55, 0.265, 1.55)",
"easeOut": "cubic-bezier(0.25, 0.46, 0.45, 0.94)"
}
},
"effects": {
"particles": {
"seedCollection": {
"count": 3,
"sprite": "spark",
"lifetime": 500,
"spread": 15
},
"biomassParticle": {
"count": 1,
"sprite": "leaf",
"lifetime": 500,
"spread": 0,
"motion": "spiralUp"
},
"pollinationDust": {
"count": 8,
"sprite": "spark",
"lifetime": 1000,
"spread": 20,
"color": "#FFD700"
},
"pestDeath": {
"count": 5,
"sprite": "spark",
"lifetime": 300,
"spread": 10,
"color": "#4CAF50"
},
"harvestPop": {
"count": 6,
"sprite": "spark",
"lifetime": 400,
"spread": 25
},
"crossBreedBurst": {
"count": 20,
"sprite": "spark",
"lifetime": 800,
"spread": 40,
"rainbow": true
},
"flowSparkle": {
"count": 1,
"sprite": "sparkle",
"lifetime": 200,
"spread": 0,
"color": "#4FC3F7"
},
"terraceExpand": {
"count": 30,
"sprite": "spark",
"lifetime": 1200,
"spread": 100
}
},
"floatingText": {
"duration": 800,
"riseSpeed": 30,
"fontSize": 14,
"fontWeight": "bold",
"colors": {
"seeds": "#FFD700",
"biomass": "#4CAF50",
"flowEnergy": "#4FC3F7",
"knowledge": "#E040FB",
"damage": "#FF4444",
"heal": "#44FF44"
}
},
"screenFlash": {
"harvest": {
"color": "#FFFFFF",
"opacity": 0.2,
"duration": 150
},
"prestige": {
"color": "#FFFFFF",
"opacity": 1,
"duration": 500
},
"unlock": {
"color": "#FFD700",
"opacity": 0.3,
"duration": 300
},
"damage": {
"color": "#FF4444",
"opacity": 0.2,
"duration": 100
}
},
"placementFlash": {
"duration": 200,
"color": "#FFFFFF",
"opacity": 0.5
}
},
"entities": {
"wheatCrop": {
"sprite": "procedural",
"spriteType": "plant",
"scale": 2,
"team": "player",
"hp": 100,
"growthStages": 4,
"growthTime": 40000,
"waterNeed": 0.5,
"yield": {
"seeds": 5,
"biomass": 5
},
"states": {
"planted": {
"type": "scaleIn",
"duration": 200
},
"growing": {
"frames": [
0,
1,
2,
3
],
"frameDuration": 10000
},
"mature": {
"frames": [
3
],
"glow": true
},
"wilting": {
"colorShift": "#A0826D",
"frames": [
2
]
},
"moldy": {
"colorShift": "#5D7A6D",
"frames": [
2
]
},
"harvested": {
"type": "scaleOut",
"duration": 300,
"spawnCollectible": "seedPacket"
},
"dying": {
"type": "fade",
"duration": 500,
"opacity": 0
},
"cycling": {
"type": "seedScatter",
"duration": 1000,
"particleCount": 8
}
},
"healthBar": {
"show": false
},
"placementRules": {
"snapToGrid": true,
"gridSize": 16,
"blocksPlacement": true
}
},
"tomatoCrop": {
"sprite": "procedural",
"spriteType": "plant",
"scale": 2.5,
"team": "player",
"hp": 80,
"growthStages": 4,
"growthTime": 60000,
"waterNeed": 0.7,
"yield": {
"seeds": 7,
"biomass": 6
},
"states": {
"planted": {
"type": "scaleIn",
"duration": 200
},
"growing": {
"frames": [
0,
1,
2,
3
],
"frameDuration": 15000
},
"mature": {
"frames": [
3
],
"fruitVisible": true,
"glow": true
},
"wilting": {
"colorShift": "#A0826D",
"frames": [
2
]
},
"harvested": {
"type": "scaleOut",
"duration": 300,
"spawnCollectible": "seedPacket"
}
},
"healthBar": {
"show": false
}
},
"berryCrop": {
"sprite": "procedural",
"spriteType": "plant",
"scale": 2.2,
"team": "player",
"hp": 90,
"growthStages": 4,
"growthTime": 90000,
"waterNeed": 0.6,
"yield": {
"seeds": 8,
"biomass": 7
},
"attracts": [
"butterfly"
],
"states": {
"planted": {
"type": "scaleIn",
"duration": 200
},
"growing": {
"frames": [
0,
1,
2,
3
],
"frameDuration": 22500
},
"mature": {
"frames": [
3
],
"berriesVisible": true,
"glow": true
},
"harvested": {
"type": "scaleOut",
"duration": 300,
"spawnCollectible": "seedPacket"
}
},
"healthBar": {
"show": false
}
},
"pumpkinCrop": {
"sprite": "procedural",
"spriteType": "plant",
"scale": 3,
"team": "player",
"hp": 120,
"growthStages": 4,
"growthTime": 120000,
"waterNeed": 0.4,
"yield": {
"seeds": 12,
"biomass": 10
},
"rare": true,
"states": {
"planted": {
"type": "scaleIn",
"duration": 200
},
"growing": {
"frames": [
0,
1,
2,
3
],
"frameDuration": 30000
},
"mature": {
"frames": [
3
],
"pumpkinVisible": true,
"glow": true
},
"harvested": {
"type": "scaleOut",
"duration": 300,
"spawnCollectible": "seedPacket"
}
},
"healthBar": {
"show": false
}
},
"bee": {
"sprite": "wizard",
"scale": 1.5,
"team": "player",
"hp": 30,
"lifespan": 300,
"states": {
"deploying": {
"type": "bounceIn",
"duration": 400
},
"seeking": {
"frames": [
0,
1
],
"frameDuration": 100
},
"moving": {
"frames": [
0,
1,
2,
3
],
"frameDuration": 50
},
"pollinating": {
"frames": [
2,
3
],
"frameDuration": 500,
"spawnParticles": "pollenDust"
},
"exhausted": {
"type": "fade",
"duration": 500
}
},
"flipX": true,
"colorVariant": {
"primary": "#FFC107",
"secondary": "#212121"
}
},
"ladybug": {
"sprite": "procedural",
"spriteType": "ladybug",
"scale": 1.2,
"team": "player",
"hp": 50,
"pestLimit": 30,
"states": {
"deploying": {
"type": "bounceIn",
"duration": 400
},
"seeking": {
"frames": [
0,
1
],
"frameDuration": 200
},
"moving": {
"frames": [
0,
1
],
"frameDuration": 150
},
"eating": {
"frames": [
1
],
"frameDuration": 500
},
"exhausted": {
"type": "fade",
"duration": 500
}
},
"protectedZone": {
"radius": 50,
"color": "rgba(76, 175, 80, 0.2)"
}
},
"aphidPest": {
"sprite": "slime",
"scale": 1,
"team": "enemy",
"hp": 10,
"damage": 5,
"states": {
"spawning": {
"type": "scaleIn",
"duration": 300
},
"spreading": {
"frames": [
0,
1,
2,
3
],
"frameDuration": 200
},
"eating": {
"frames": [
2,
3
],
"frameDuration": 500
},
"dying": {
"type": "squish",
"duration": 200,
"particles": "greenSpark"
}
},
"colorVariant": {
"primary": "#4CAF50",
"secondary": "#2E7D32"
}
},
"butterfly": {
"sprite": "ghost",
"scale": 2,
"team": "neutral",
"hp": 1,
"catchable": true,
"states": {
"spawning": {
"type": "fadeScale",
"duration": 500
},
"fluttering": {
"frames": [
0,
1,
2,
3
],
"frameDuration": 150
},
"migrating": {
"frames": [
0,
1,
2,
3
],
"frameDuration": 200
},
"caught": {
"type": "spiralShrink",
"duration": 300
},
"fleeing": {
"frames": [
0,
1,
2,
3
],
"frameDuration": 50,
"speedMultiplier": 3
}
},
"colorVariant": "rainbow",
"erraticMovement": true
},
"waterDroplet": {
"sprite": "procedural",
"spriteType": "droplet",
"scale": 0.5,
"team": "neutral",
"states": {
"spawning": {
"type": "fade",
"duration": 100
},
"flowing": {
"frames": [
0
],
"motion": "gravity"
},
"redirecting": {
"frames": [
0
],
"motion": "followRedirector"
},
"falling": {
"frames": [
0
],
"motion": "waterfall"
},
"wicking": {
"type": "fade",
"duration": 500
}
},
"color": "#4FC3F7",
"opacity": 0.7,
"trail": true
},
"channelRedirector": {
"sprite": "procedural",
"spriteType": "channel",
"scale": 2,
"team": "player",
"states": {
"placing": {
"type": "ghost",
"opacity": 0.5
},
"placed": {
"type": "scaleIn",
"duration": 300
},
"active": {
"frames": [
0
],
"emitParticles": "flowSparkle"
},
"removing": {
"type": "scaleOut",
"duration": 200
}
},
"color": "#8B7355",
"placementRules": {
"snapToGrid": true,
"gridSize": 16,
"blocksWater": true
}
},
"damRedirector": {
"sprite": "procedural",
"spriteType": "dam",
"scale": 2,
"team": "player",
"states": {
"placing": {
"type": "ghost",
"opacity": 0.5
},
"placed": {
"type": "scaleIn",
"duration": 300
},
"filling": {
"frames": [
0
],
"pooling": true
},
"overflowing": {
"frames": [
1
]
}
},
"color": "#8B7355"
},
"rainCloud": {
"sprite": "procedural",
"spriteType": "cloud",
"scale": 8,
"team": "environment",
"states": {
"drifting": {
"frames": [
0,
1
],
"frameDuration": 1000
},
"raining": {
"frames": [
1
],
"spawnParticles": "rainDroplet"
},
"dissipating": {
"type": "fade",
"duration": 2000
}
},
"color": "#9E9E9E",
"opacity": 0.8
},
"seedPacket": {
"sprite": "procedural",
"spriteType": "packet",
"scale": 1.2,
"team": "collectible",
"lifetime": 8,
"states": {
"spawning": {
"type": "popIn",
"duration": 200
},
"idle": {
"frames": [
0
],
"bob": {
"amplitude": 2,
"speed": 2
}
},
"collected": {
"type": "burst",
"duration": 300,
"particleCount": 3
},
"expired": {
"type": "fade",
"duration": 500
}
},
"collectRadius": 20
},
"biomassParticle": {
"sprite": "procedural",
"spriteType": "leaf",
"scale": 0.8,
"team": "collectible",
"lifetime": 5,
"states": {
"spawning": {
"type": "fadeScale",
"duration": 150
},
"rising": {
"frames": [
0
],
"motion": "spiralUp"
},
"collected": {
"type": "none"
}
},
"autoCollect": true,
"color": "#4CAF50"
}
},
"colorPalette": {
"background": {
"primary": "#1a1814",
"secondary": "#2d2620",
"tertiary": "#3d3428"
},
"canvas": "#2d4a3e",
"text": {
"primary": "#e8e4dc",
"secondary": "#a8a49c",
"muted": "#68645c"
},
"accent1": "#FFD700",
"accent2": "#4FC3F7",
"accent3": "#E040FB",
"success": "#4CAF50",
"warning": "#FF9800",
"danger": "#F44336",
"prestige": "#E040FB"
}
},
"entityStateMachines": [
{
"entity": "Crop Plant (Wheat, Tomato, Berry, Pumpkin)",
"mermaid": "stateDiagram-v2\n [*] --> Available: seed type unlocked\n Available --> Planted: player clicks soil with seed selected\n Planted --> Sprouting: spawn animation (200ms)\n Sprouting --> Growing: growth stage 1 of 4\n Growing --> Growing: +1 stage (time-based, modified by water/pollination)\n Growing --> Wilting: soil moisture < 20% for 10s\n Growing --> Moldy: soil moisture > 90% for 10s\n Growing --> Mature: reaches stage 4 (40-120s depending on species)\n Wilting --> Growing: watered to > 40%\n Wilting --> Dying: moisture < 10% for 5s\n Moldy --> Dying: not remedied in 15s\n Mature --> Harvested: player clicks mature crop\n Mature --> Cycling: player leaves untouched (30s timer)\n Cycling --> SeedDrop: lifecycle complete\n Harvested --> [*]: harvest animation, seed packet spawn\n Cycling --> [*]: biomass awarded, seeds auto-sown nearby\n Dying --> [*]: death animation, 50% seed refund\n\n note right of Sprouting\n Animation: scale 0→1 (200ms)\n Position: clicked tile\n Cost deducted immediately\n end note\n\n note right of Growing\n Growth rate = base * waterMultiplier * pollinationMultiplier * dayNightMultiplier\n Visual: size increases 25% per stage\n Check moisture every 2s\n Stage durations: Wheat 10s, Tomato 15s, Berry 22.5s, Pumpkin 30s\n end note\n\n note right of Wilting\n Visual: turns yellow/brown\n Growth paused\n 5s to recover before dying\n end note\n\n note right of Mature\n Visual: glows white, fruit/berries visible\n 30s window to harvest\n Then auto-cycles\n end note\n\n note right of Harvested\n Triggers: seed packet spawn\n Rewards: seeds (5-12), biomass (5-10)\n Animation: scale 1→0 (300ms)\n end note\n\n note right of Cycling\n Triggers: elaborate seed-scatter (8 directions)\n Rewards: biomass (15), seeds auto-sown (2-4)\n Chance: cross-breed if adjacent to different species\n end note"
},
{
"entity": "Bee",
"mermaid": "stateDiagram-v2\n [*] --> InInventory: purchased from shop\n InInventory --> Deploying: player clicks 'deploy' then clicks canvas position\n Deploying --> Seeking: placement animation (400ms bounce)\n Seeking --> Moving: flower found within 150px\n Seeking --> Idle: no flowers in range\n Moving --> Pollinating: reached target flower\n Pollinating --> Moving: pollination complete, seek next flower\n Pollinating --> Seeking: no more flowers in range\n Idle --> Seeking: rescan (500ms interval)\n Moving --> Exhausted: lifespan expired (5 minutes)\n Pollinating --> Exhausted: lifespan expired\n Exhausted --> Dying: fade out animation (500ms)\n Dying --> [*]: remove from canvas\n\n note right of Deploying\n Position: clicked tile\n Animation: bounce in (scale 0→1.2→1)\n Brief invulnerability (500ms)\n Cost deducted: 25 Biomass\n end note\n\n note right of Seeking\n Detection radius: 150px\n Target priority: closest mature flowering crop\n Scan interval: 500ms\n Flutter animation: frames 0-1\n end note\n\n note right of Pollinating\n Duration: 2 seconds\n Visual: golden dust particles spawn\n Reward: +8 Biomass (+16 with chain bonus)\n Flower glows gold for 2s\n Growth acceleration: 2x for 30s\n end note\n\n note right of Exhausted\n Lifespan: 5 minutes (300 seconds)\n Visual: slows down, fades opacity\n Cannot be revived\n end note"
},
{
"entity": "Ladybug",
"mermaid": "stateDiagram-v2\n [*] --> InInventory: purchased from shop\n InInventory --> Deploying: player clicks 'deploy' then clicks canvas position\n Deploying --> Seeking: placement animation (400ms bounce)\n Seeking --> Moving: aphid found within 150px\n Seeking --> Idle: no aphids in range\n Moving --> Eating: reached target aphid\n Eating --> Moving: aphid eaten, seek next\n Eating --> Seeking: no more aphids in range\n Idle --> Seeking: rescan (500ms interval)\n Moving --> Exhausted: pest limit reached (30 aphids)\n Eating --> Exhausted: pest limit reached\n Exhausted --> Dying: fade out animation (500ms)\n Dying --> [*]: remove from canvas\n\n note right of Deploying\n Position: clicked tile\n Animation: bounce in (scale 0→1.2→1)\n Brief invulnerability (500ms)\n Cost deducted: 15 Biomass\n Creates protected zone (50px radius)\n end note\n\n note right of Seeking\n Detection radius: 150px\n Target priority: closest aphid swarm\n Scan interval: 500ms\n Crawl animation: frames 0-1\n end note\n\n note right of Eating\n Duration: 1 second\n Visual: ladybug overlays aphid\n Reward: +5 Biomass per aphid\n Aphid removed from canvas\n Green squish particles\n end note\n\n note right of Exhausted\n Pest limit: 30 aphids eaten\n Visual: slows down, fades opacity\n Cannot be revived\n end note"
},
{
"entity": "Aphid Pest",
"mermaid": "stateDiagram-v2\n [*] --> Spawning: random spawn event near weak crop\n Spawning --> Spreading: spawn animation (300ms scale 0→1)\n Spreading --> Eating: attached to crop, dealing damage\n Eating --> Spreading: reproduce, spread to adjacent crop (5s interval)\n Eating --> Dying: ladybug reaches position\n Eating --> Dying: player clicks to squish\n Spreading --> Dying: crop dies or treated\n Dying --> [*]: remove from canvas\n\n note right of Spawning\n Trigger: random event (higher chance on weak crops)\n Position: near crop with low HP or poor moisture\n Visual: green slime cluster appears\n end note\n\n note right of Spreading\n Movement: crawl to adjacent crop every 5s\n Visual: frames 0-1-2-3 animating\n Damage: 5 HP per second to attached crop\n end note\n\n note right of Eating\n Crop shows wilting animation\n Crop HP decreases\n Aphid sprite shows feeding animation\n end note\n\n note right of Dying (Player Squish)\n Trigger: player click\n Animation: white flash, fade (200ms)\n Reward: +2 Biomass (+2 after upgrade)\n Green squish particles\n end note\n\n note right of Dying (Ladybug)\n Trigger: ladybug reaches aphid\n Animation: ladybug overlays, eats (1s)\n Reward: +5 Biomass\n Green particles, aphid removed\n end note"
},
{
"entity": "Butterfly",
"mermaid": "stateDiagram-v2\n [*] --> Spawning: rare spawn from pollinated berry plant\n Spawning --> Fluttering: spawn animation (500ms fade + scale)\n Fluttering --> Migrating: no player interaction\n Fluttering --> Caught: player successful click (skill check)\n Migrating --> Fluttering: reaches terrace edge, change direction\n Migrating --> Caught: player click (harder timing)\n Caught --> [*]: capture animation, Knowledge awarded\n Fluttering --> Fled: player misses click, butterfly speeds away\n Fled --> [*]: remove from canvas (no reward)\n\n note right of Spawning\n Trigger: pollinated berry plant (rare, 5% chance)\n Position: near berry plant\n Visual: multi-colored ghost sprite appears\n Rarity: determines species variant\n end note\n\n note right of Fluttering\n Movement: erratic, random direction changes\n Speed: slow (30px/sec)\n Animation: frames 0-1-2-3 fluttering wings\n Catchable: brief windows (200ms every 2s)\n end note\n\n note right of Migrating\n Movement: deliberate paths between terraces\n Duration: 30-60 seconds on screen\n Exits screen if not caught\n end note\n\n note right of Caught\n Skill check: click during 'catchable' window\n Animation: spiral shrink (300ms)\n Reward: +10 Knowledge per species rarity\n Unlocks: species badge in Knowledge tab\n Toast: 'Rare Species Documented!'\n end note\n\n note right of Fled\n Trigger: missed click or timeout\n Speed boost: 3x for 2 seconds\n 'Whoosh' particle effect\n No reward\n end note"
},
{
"entity": "Water Droplet",
"mermaid": "stateDiagram-v2\n [*] --> Spawning: generated at water source (top of terrace)\n Spawning --> Flowing: spawn animation (100ms fade-in)\n Flowing --> Redirecting: hits player-placed redirector\n Flowing --> Wicking: enters soil tile\n Flowing --> Falling: reaches terrace edge (waterfall)\n Flowing --> Pooling: hits dam or depression\n Redirecting --> Flowing: direction changed\n Redirecting --> EnergyGenerated: passes redirector (triggers flow energy)\n Falling --> Flowing: lands on lower terrace\n Pooling --> Wicking: saturation exceeded after 3s\n Pooling --> Flowing: dam overflows or removed after 5s\n Wicking --> Absorbed: completely absorbed by soil\n Wicking --> Flowing: soil saturated, continues flowing\n EnergyGenerated --> [*]: +0.5 Flow Energy, blue sparkle effect\n Absorbed --> [*]: soil moisture +10%, droplet removed\n\n note right of Spawning\n Source: top of terrace or waterfall from above\n Spawn rate: 1 per second per active source\n Visual: blue circle with trail\n end note\n\n note right of Flowing\n Velocity: 60px/sec\n Direction: gravity + redirectors\n Visual: blue circle (4px), opacity 0.7\n Leaves lighter trail behind\n end note\n\n note right of Redirecting\n Check redirector type:\n - Channel: straight flow\n - Turn: 90° redirect\n - Splitter: divides into 2 droplets\n - Dam: stops, pools behind\n - Pump: moves upward\n end note\n\n note right of EnergyGenerated\n Triggers: FlowEnergy +0.5\n Visual: blue sparkle sprite at redirector\n Auto-collected instantly\n Update flow bar UI\n Cap: 100 (warning when full)\n end note"
},
{
"entity": "Seed Packet (Collectible)",
"mermaid": "stateDiagram-v2\n [*] --> Spawning: crop harvested\n Spawning --> Idle: spawn animation (200ms pop-in)\n Idle --> Collected: player clicks within 20px radius\n Idle --> Expired: lifetime exceeded (8s)\n Collected --> [*]: add seeds + floating text + particles\n Expired --> [*]: fade out (500ms)\n\n note right of Spawning\n Trigger: crop harvest event\n Position: at harvested crop position\n Value: seed yield (5-12 based on species)\n Visual: packet sprite with value label\n end note\n\n note right of Idle\n Animation: bob (2px amplitude, 2Hz)\n Glowing effect based on value\n Clickable radius: 20px\n Lifetime: 8 seconds (auto-collect after)\n end note\n\n note right of Collected\n Triggers: currency.add('seeds', value)\n Triggers: floatingText('+{value} Seeds', position, gold)\n Triggers: particle burst (3 sparkles)\n Animation: packet bursts, spirals toward currency counter\n end note"
}
],
"entityInteractionDiagram": {
"mermaid": "flowchart LR\n subgraph Player Entities\n Crop[\"Crop\\n(grows, harvested, cycles)\"]\n Bee[\"Bee\\n(pollinates flowers)\"]\n Ladybug[\"Ladybug\\n(eats aphids)\"]\n Redirector[\"Water Redirector\\n(generates Flow Energy)\"]\n end\n subgraph Enemy Entities\n Aphid[\"Aphid Pest\\n(eats crops)\"]\n end\n subgraph Environment\n Water[\"Water Droplet\\n(flows, wicks into soil)\"]\n Cloud[\"Rain Cloud\\n(spawns water)\"]\n end\n subgraph Collectibles\n Seed[\"Seed Packet\\n(clickable)\"]\n Biom[\"Biomass Particle\\n(auto-collect)\"]\n Flow[\"Flow Sparkle\\n(instant)\"]\n end\n subgraph Neutral\n Butterfly[\"Butterfly\\n(rare, catchable)\"]\n end\n\n Crop -->|\"on death → spawns\"| Seed\n Crop -->|\"attracts if pollinating\"| Bee\n Aphid -->|\"attacks\"| Crop\n Ladybug -->|\"eats\"| Aphid\n Aphid -->|\"on death → spawns\"| Biom\n Bee -->|\"on pollination → spawns\"| Biom\n Redirector -->|\"water passes → spawns\"| Flow\n Water -->|\"enters soil\"| Crop\n Cloud -->|\"spawns\"| Water\n Crop -->|\"berry + pollinated → spawns\"| Butterfly\n Butterfly -->|\"player clicks → collect\"| Butterfly\n Seed -->|\"player clicks → collect\"| Seed"
},
"engagementSelfAudit": {
"isThisActuallyAGame": {
"canDescribe30Seconds": "Yes: Water cascades down terraces, player spots dry wheat wilting, drags to place stone channel redirecting flow, water animates around new structure, wheat perks up visually, aphid sprites appear on tomatoes, player clicks to squish, deploys ladybug which crawls to eat pests, pumpkins mature with glow, player clicks harvest, seed packets spawn with pop, golden coins float up, bee cluster forms around flowers accelerating growth, rain cloud drifts from left.",
"playerInteractionEvery10Seconds": "Yes - Player is constantly clicking soil to plant, dragging terraces to place channels, clicking mature crops to harvest, clicking pests to squish, clicking seed packets to collect, deploying creatures, catching butterflies. Every 10 seconds has meaningful Canvas interaction.",
"canvasWithoutUpgrades": "Yes - Without any upgrade panels, there's still a complete simulation game: water flows, crops grow based on moisture, creatures forage, pests attack, weather events occur, day/night cycles change growth rates. The ecosystem lives independently.",
"bystanderUnderstanding": "Yes - A bystander would see: water flowing down terraces, plants growing at different rates, tiny creatures moving around, pest outbreaks being fought, harvests being collected. The visual cause-and-effect is clear: water makes plants grow, creatures help or hurt, player manages the ecosystem."
},
"feedbackLoopCompleteness": {
"placeStructure": {
"canvas": "Spawn animation (scale 0→1, 300ms), stone structure appears, water visibly redirects, blue sparkle particles",
"ui": "Biomass deducted with count-down, card flashes green"
},
"cropHarvest": {
"canvas": "Crop shrinks (scale 1→0, 300ms), seed packet spawns with pop-in, bob animation",
"ui": "Seeds count-up animation, gold flash on currency display, floating '+5 Seeds' text"
},
"buyUpgrade": {
"canvas": "Affected entities glow white briefly, crops show size bump if yield upgrade, redirectors emit extra sparkles",
"ui": "Card flashes green, level animates up, cost deducted"
},
"enemyDeath": {
"canvas": "Aphid flashes white, fades out, green squish particles burst",
"ui": "Biomass pulses up, floating '+2 Biomass' text"
}
},
"rewardVisibility": {
"alwaysVisible": [
"Next affordable upgrade (cost visible in Shop tab, progress shows if close)",
"Next unlock threshold (progress bars or indicators on locked items)",
"Current production rate (Seeds/sec, Biomass/sec visible in HUD)"
]
},
"variableReward": {
"waveCompletionVariants": [
"Harvest yields vary by crop quality (random 0.8-1.2x multiplier)",
"Biomass from lifecycle: 15 base, but varies by species (pumpkin gives more)",
"Butterfly catches: 10-30 Knowledge based on species rarity (random spawn)",
"First discovery bonuses: +5-50 Knowledge based on discovery type (new plant, new creature, new pattern, rare species)",
"Cross-breeding: random rare species from parent combinations",
"Biodiversity bonus: triggers every 5 species, but species composition varies",
"Efficient flow pattern: +25 Flow Energy bonus when elegant design detected (rare, player skill-based)"
],
"surpriseElements": [
"Rare butterfly spawns (unpredictable, skill-based catch)",
"Cross-breed discoveries (new plant variants with unique properties)",
"Pest outbreaks (random timing, force player response)",
"Rain events (create both opportunities and emergencies)",
"Ghost species spawns after prestige (rare callbacks to previous runs)"
]
}
},
"qualityChecklist": [
"Canvas game world is PRIMARY element, occupying 65% of screen",
"Upgrade panels are SECONDARY, in bottom panel (not whole screen)",
"Currency displays ALWAYS visible in HUD (never hidden behind tabs)",
"Every entity type has visual specs (sprite, scale, animation states)",
"Canvas layers specified (background, entities, effects, HUD overlay)",
"Every UI element has specified states (locked, available, affordable, maxed)",
"Feedback specified for BOTH Canvas effects AND UI effects",
"Floating damage/reward numbers specified for Canvas",
"Color palette has enough contrast for readability (dark theme)",
"Tab unlock conditions match progression.md unlock sequence",
"Number formatting rules cover full range from 0 to 1T+",
"Prestige UI shows visual transformation info",
"Skill tree rendering approach is implementable in vanilla CSS/JS",
"Accessibility basics covered (contrast, keyboard, reduced motion)",
"Design works at 1280x720 minimum resolution",
"NO language about 'the UI IS the game' - Canvas is the game",
"Every entity type has state machine diagram with all visual states",
"Entity interaction diagram shows how all entity types relate",
"UI event flow diagrams cover all major interaction paths",
"UI state machine shows game phases",
"CONFIG.entities spec has every entity with sprite, scale, team, states",
"CONFIG.canvas spec has width, height, backgroundColor, gridCellSize, layers",
"CONFIG.ui spec has tab definitions with unlock conditions",
"CONFIG.effects spec has particle, floatingText, screenFlash definitions",
"CONFIG.colorPalette has hex values for every UI color role",
"Entity state definitions in CONFIG match state machine diagrams exactly",
"Permanent controls panel designed showing ALL player interactions",
"'How to Play' overlay designed for first-load tutorial",
"Controls panel is ALWAYS visible (not hidden behind tabs/menus)",
"Tutorial overlay has dismiss button and localStorage persistence"
]
}