Initial commit

2026-04-03 17:23:15 +00:00
commit 4f474dbcf3
192 changed files with 47527 additions and 0 deletions
--- a/GAME_SYSTEMS_ANALYSIS.md
+++ b/GAME_SYSTEMS_ANALYSIS.md
@@ -0,0 +1,510 @@
+# Mana Loop - Game Systems Analysis Report
+
+**Generated:** Task ID 24
+**Purpose:** Comprehensive review of all game systems, their completeness, and "feel"
+
+---
+
+## Executive Summary
+
+Mana Loop is an incremental/idle game with a time-loop mechanic, spellcasting combat, equipment enchanting, and attunement-based progression. The game has solid core mechanics but several systems feel incomplete or disconnected from the main gameplay loop.
+
+**Overall Assessment:** ⚠️ **Needs Polish** - Core systems work but lack depth and integration
+
+---
+
+## System-by-System Analysis
+
+### 1. 🔮 Core Mana System
+
+**Status:** ✅ **Complete & Functional**
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Mana Regeneration | ⭐⭐⭐⭐⭐ | Well-implemented with upgrades affecting it |
+| Mana Cap | ⭐⭐⭐⭐⭐ | Clear scaling through skills |
+| Click Gathering | ⭐⭐⭐⭐ | Works but feels less important late-game |
+| Mana Types | ⭐⭐⭐⭐ | Good variety (18 types) |
+| Compound Mana | ⭐⭐⭐⭐ | Auto-unlocks when components available |
+
+**What Works Well:**
+- Clear progression: raw mana → elemental mana → compound mana
+- Attunements provide passive conversion
+- Incursion mechanic adds urgency late-loop
+
+**What Feels Lacking:**
+- Limited use cases for many mana types
+- Compound mana types unlock automatically but feel disconnected from gameplay
+- No meaningful choices in which mana to generate/prioritize
+- Exotic elements (void, stellar, crystal) are very difficult to unlock
+
+**Suggestions:**
+1. Add spells that specifically use compound/exotic elements
+2. Allow players to choose which elements to generate from attunements
+3. Add "mana conversion" buildings/upgrades that transform elements
+
+---
+
+### 2. ⚔️ Combat/Spire System
+
+**Status:** ⚠️ **Partially Complete**
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Floor Scaling | ⭐⭐⭐⭐⭐ | Good HP progression |
+| Spell Casting | ⭐⭐⭐⭐ | Cast speed system works well |
+| Elemental Weakness | ⭐⭐⭐⭐ | Opposing elements deal bonus damage |
+| Guardian Fights | ⭐⭐⭐⭐ | Unique perks add flavor |
+| Pact System | ⭐⭐⭐⭐⭐ | Excellent incentive to progress |
+
+**What Works Well:**
+- Guardian pacts provide permanent progression
+- Each guardian has unique perks that feel impactful
+- Descent mechanic prevents easy farming
+- Barrier system on guardians adds tactical depth
+
+**What Feels Lacking:**
+- No active combat decisions - purely automatic
+- Floor HP regeneration can feel frustrating without burst damage
+- Limited spell selection (only from equipment)
+- No enemy variety beyond floors/guardians
+- Combo system exists in types but isn't actually used
+
+**Critical Gap - Combo System:**
+```typescript
+// From types.ts - combo exists but isn't used
+combo: {
+  count: number;
+  maxCombo: number;
+  multiplier: number;
+  elementChain: string[];
+  decayTimer: number;
+}
+```
+The combo state is tracked but never affects gameplay. This is a dead system.
+
+**Suggestions:**
+1. Implement combo multiplier affecting damage
+2. Add enemy types with different weaknesses
+3. Allow manual spell selection mid-combat
+4. Add tactical choices (focus fire, defensive casting, etc.)
+
+---
+
+### 3. ✨ Enchanting System (Enchanter Attunement)
+
+**Status:** ✅ **Complete & Well-Designed**
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Design Stage | ⭐⭐⭐⭐⭐ | Clear, intuitive UI |
+| Prepare Stage | ⭐⭐⭐⭐ | Good time investment |
+| Apply Stage | ⭐⭐⭐⭐ | Mana sink feels appropriate |
+| Effect Variety | ⭐⭐⭐⭐ | Good selection of effects |
+| Spell Granting | ⭐⭐⭐⭐⭐ | Primary way to get spells |
+
+**What Works Well:**
+- 3-stage process (Design → Prepare → Apply) feels meaningful
+- Effect research system provides clear progression
+- Spells come from equipment - creates itemization
+- Disenchanting recovers some mana
+
+**What Feels Lacking:**
+- Effect capacity limits can feel arbitrary
+- No way to preview enchantment before committing
+- No rare/special enchantments
+- Enchantment effects feel same-y (mostly +stats)
+
+**Suggestions:**
+1. Add "rare" effect drops from guardians
+2. Allow effect combining/stacking visually
+3. Add visual flair to enchanted items
+4. Create set bonuses for themed enchantments
+
+---
+
+### 4. 💜 Invoker/Pact System
+
+**Status:** ⚠️ **Conceptually Complete, Implementation Lacking**
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Pact Signing | ⭐⭐⭐⭐ | Time investment, meaningful choice |
+| Guardian Perks | ⭐⭐⭐⭐⭐ | Unique and impactful |
+| Pact Multipliers | ⭐⭐⭐⭐ | Clear progression |
+| Invoker Skills | ⭐⭐⭐ | Skills exist but category is sparse |
+
+**What Works Well:**
+- 10 unique guardians with distinct perks
+- Pact multiplier system rewards guardian hunting
+- Each pact feels like a real achievement
+
+**What Feels Lacking:**
+- **No Invocation category spells/skills defined**
+- Invoker attunement has no primary mana type
+- Limited invoker-specific progression
+- Once you sign a pact, interaction ends
+
+**Critical Gap - Invocation Skills:**
+```typescript
+// From SKILL_CATEGORIES
+{ id: 'invocation', name: 'Invocation', icon: '💜', attunement: 'invoker' },
+{ id: 'pact', name: 'Pact Mastery', icon: '🤝', attunement: 'invoker' },
+```
+
+Looking at SKILLS_DEF, there are **NO skills** in the 'invocation' or 'pact' categories! The attunement promises these categories but delivers nothing.
+
+**Suggestions:**
+1. Add Invocation skills:
+   - Spirit Call (summon guardian echo)
+   - Elemental Channeling (boost pact element)
+   - Guardian's Boon (enhance perks)
+2. Add Pact skills:
+   - Pact Binding (reduce signing time)
+   - Soul Link (gain mana from guardian defeats)
+   - Pact Synergy (combine perk effects)
+3. Allow upgrading existing pacts
+
+---
+
+### 5. ⚒️ Fabricator/Golemancy System
+
+**Status:** ❌ **NOT IMPLEMENTED**
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Golem Defs | ❌ | GOLEM_DEFS does not exist |
+| Golem Summoning | ❌ | No summoning logic |
+| Golem Combat | ❌ | Golems don't fight |
+| Crafting Skills | ⚠️ | Only in constants, not evolved |
+
+**Critical Gap:**
+```typescript
+// From types.ts - these exist
+export interface GolemDef { ... }
+export interface ActiveGolem { ... }
+
+// In GameState
+activeGolems: ActiveGolem[];
+unlockedGolemTypes: string[];
+golemSummoningProgress: Record<string, number>;
+```
+
+But GOLEM_DEFS is referenced nowhere. The entire golemancy system is **stub code**.
+
+**What Should Exist:**
+1. GOLEM_DEFS with 5-10 golem types
+2. Golem summoning logic (earth mana cost)
+3. Golem combat integration (they fight alongside player)
+4. Golem variants (earth + fire = magma golem)
+5. Golem equipment/crystals for customization
+
+**Suggestions:**
+1. Implement basic earth golem first
+2. Add golem as "pet" that attacks automatically
+3. Golems should have limited duration (HP-based)
+4. Crystals can enhance golem stats
+
+---
+
+### 6. 📚 Skill System
+
+**Status:** ⚠️ **Inconsistent**
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Skill Categories | ⭐⭐⭐⭐ | Good organization |
+| Study System | ⭐⭐⭐⭐⭐ | Clear time investment |
+| Evolution Paths | ⭐⭐⭐⭐⭐ | 5 tiers with choices |
+| Upgrade Choices | ⭐⭐⭐⭐ | Meaningful decisions |
+
+**What Works Well:**
+- 4 upgrade choices per milestone (2 selected max)
+- Tier progression multiplies effects
+- Study time creates opportunity cost
+
+**What Feels Lacking:**
+- Many skills have no evolution path
+- 'craft' category is legacy/unclear
+- 'effectResearch' is scattered
+- Some skills do nothing (scrollCrafting, fieldRepair)
+
+**Dead Skills:**
+```typescript
+// In SKILLS_DEF but not implemented
+scrollCrafting: { ... desc: "Create scrolls..." }, // No scroll system
+fieldRepair: { ... desc: "+15% repair efficiency" }, // No repair system
+```
+
+**Suggestions:**
+1. Remove or implement scrollCrafting/fieldRepair
+2. Add evolution paths to all skills
+3. Consolidate effectResearch into clearer tree
+4. Add skill synergies (combining skills = bonus)
+
+---
+
+### 7. 🎯 Attunement System
+
+**Status:** ⚠️ **Good Concept, Incomplete Execution**
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Concept | ⭐⭐⭐⭐⭐ | Class-like specialization |
+| Enchanter | ⭐⭐⭐⭐⭐ | Fully implemented |
+| Invoker | ⭐⭐ | Missing skills |
+| Fabricator | ⭐ | Missing golemancy |
+| Leveling | ⭐⭐⭐⭐ | Good XP scaling |
+
+**What Works Well:**
+- Enchanter attunement is complete and functional
+- Attunement XP through gameplay feels natural
+- Level-scaled conversion rates
+
+**What Feels Lacking:**
+- Invoker and Fabricator unlock conditions unclear
+- Invoker has no Invocation/Pact skills
+- Fabricator has no golemancy implementation
+- Only 3 attunements, no late-game options
+
+**Unlock Mystery:**
+```typescript
+// From attunements.ts
+invoker: {
+  unlockCondition: 'Defeat your first guardian and choose the path of the Invoker',
+  // But no code checks for this condition
+}
+```
+
+**Suggestions:**
+1. Add clear unlock triggers in code
+2. Implement missing skill categories
+3. Add 4th attunement for late-game (Void Walker?)
+4. Create attunement-specific achievements
+
+---
+
+### 8. 🏆 Achievement System
+
+**Status:** ✅ **Defined But Passive**
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Definitions | ⭐⭐⭐⭐ | Good variety |
+| Progress Tracking | ⭐⭐⭐ | State exists |
+| Rewards | ⭐⭐ | Mostly insight |
+
+**What Works Well:**
+- Categories organized (mana, combat, progression)
+- Progress tracked in state
+
+**What Feels Lacking:**
+- Achievements don't unlock anything unique
+- No visual display of achievements
+- Rewards are passive (insight)
+- No hidden/challenge achievements
+
+**Suggestions:**
+1. Add achievement-locked cosmetics/titles
+2. Create achievement showcase UI
+3. Add challenge achievements (speedrun, no-upgrade, etc.)
+4. Unlock effects through achievements
+
+---
+
+### 9. 📦 Equipment System
+
+**Status:** ✅ **Complete**
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Equipment Types | ⭐⭐⭐⭐ | 8 slots, 40+ types |
+| Capacity System | ⭐⭐⭐⭐⭐ | Clear limits |
+| Rarity | ⭐⭐⭐ | Exists but cosmetic |
+
+**What Works Well:**
+- 8 equipment slots provide customization
+- Capacity system limits power creep
+- Equipment grants spells
+
+**What Feels Lacking:**
+- Equipment only comes from starting gear
+- No way to craft equipment (except from blueprints)
+- Rarity doesn't affect much
+- No equipment drops from combat
+
+**Critical Gap - Equipment Acquisition:**
+Players start with:
+- Basic Staff (Mana Bolt)
+- Civilian Shirt
+- Civilian Shoes
+
+After that, the ONLY way to get equipment is:
+1. Blueprint drops from floors (rare)
+2. Craft from blueprint (expensive)
+
+There's no consistent equipment progression!
+
+**Suggestions:**
+1. Add equipment drops from floors
+2. Create more crafting recipes
+3. Add equipment merchant/shop
+4. Allow equipment upgrading
+
+---
+
+### 10. 🔁 Prestige/Loop System
+
+**Status:** ✅ **Complete**
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Loop Reset | ⭐⭐⭐⭐⭐ | Clear, saves insight |
+| Prestige Upgrades | ⭐⭐⭐⭐ | Good variety |
+| Memory System | ⭐⭐⭐ | Keeps some progress |
+| Victory Condition | ⭐⭐⭐⭐ | Defeat floor 100 guardian |
+
+**What Works Well:**
+- 30-day time limit creates urgency
+- Insight economy for permanent upgrades
+- Memory slots for keeping spells
+- Clear victory condition
+
+**What Feels Lacking:**
+- No insight milestones/unlocks
+- Memory system is shallow (just spell slots)
+- No "loop challenges" or modifiers
+- Limited replayability after first victory
+
+**Suggestions:**
+1. Add loop modifiers (harder floors, better rewards)
+2. Insight milestones unlock attunements
+3. Loop-specific achievements
+4. New Game+ mode with modifiers
+
+---
+
+### 11. 🗓️ Time/Incursion System
+
+**Status:** ✅ **Complete**
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Day/Hour Cycle | ⭐⭐⭐⭐⭐ | Clear progression |
+| Incursion Mechanic | ⭐⭐⭐⭐ | Adds late-game pressure |
+| Time Actions | ⭐⭐⭐ | Study, craft, prepare |
+
+**What Works Well:**
+- 30 days = one loop
+- Incursion starts day 20, scales to 95% penalty
+- Actions have clear time costs
+
+**What Feels Lacking:**
+- No time manipulation (beyond debug)
+- No day/night effects on gameplay
+- Incursion is purely negative, no strategy around it
+
+**Suggestions:**
+1. Add time manipulation skills (slow incursion)
+2. Night bonuses (different for guardians)
+3. Incursion-specific rewards (void mana?)
+
+---
+
+## Missing Systems Summary
+
+### High Priority (Break Promises)
+
+| System | Promised By | Status |
+|--------|-------------|--------|
+| Golemancy | Fabricator attunement | ❌ Not implemented |
+| Invocation Skills | Invoker attunement | ❌ No skills defined |
+| Pact Skills | Invoker attunement | ❌ No skills defined |
+| Combo System | ComboState in types | ❌ State exists, unused |
+| Scroll Crafting | scrollCrafting skill | ❌ No scroll system |
+
+### Medium Priority (Incomplete)
+
+| System | Issue |
+|--------|-------|
+| Fabricator Unlocks | Unlock condition not coded |
+| Invoker Unlocks | Unlock condition not coded |
+| Equipment Progression | Only starting gear + rare blueprints |
+| Evolution Paths | Not all skills have 5 tiers |
+
+### Low Priority (Polish)
+
+| System | Issue |
+|--------|-------|
+| Field Repair | Repair system doesn't exist |
+| Guardian Variants | Not implemented |
+| Achievement Rewards | Passive only |
+| Enemy Variety | Only floors/guardians |
+
+---
+
+## "Feel" Analysis
+
+### What Feels Good
+
+1. **Guardian Pacts** - Defeating a guardian and signing a pact feels like a major achievement
+2. **Enchanting Process** - 3-stage system feels involved and meaningful
+3. **Cast Speed System** - Different spells feel different to use
+4. **Skill Evolution** - Choosing upgrades at milestones gives agency
+5. **Compound Mana** - Auto-unlocking elements through gameplay
+
+### What Feels Bad
+
+1. **Helplessness** - Combat is 100% automatic with no player input
+2. **Dead Ends** - Attunements unlock with no skills to use
+3. **Empty Promises** - Golemancy is mentioned everywhere but doesn't exist
+4. **Grind Walls** - Exotic elements require absurd amounts of base elements
+5. **Useless Skills** - scrollCrafting, fieldRepair do nothing
+
+### What Feels Confusing
+
+1. **Attunement Unlocks** - How do I get Invoker/Fabricator?
+2. **Equipment Progression** - Where do I get better gear?
+3. **Exotic Elements** - How do void/stellar/crystal work?
+4. **Combo System** - UI mentions it but it does nothing
+5. **Incursion** - Is there anything I can do about it?
+
+---
+
+## Recommended Priorities
+
+### Phase 1: Fix Broken Promises (1-2 weeks)
+1. Implement basic golemancy (1 golem type, auto-attacks)
+2. Add Invocation/Pact skill categories with 3-4 skills each
+3. Add attunement unlock conditions in code
+4. Remove or implement scrollCrafting/fieldRepair
+
+### Phase 2: Fill Content Gaps (2-3 weeks)
+1. Add equipment drops from floors
+2. Implement combo system for damage bonuses
+3. Add more spells using compound/exotic elements
+4. Create evolution paths for all skills
+
+### Phase 3: Polish & Depth (2-3 weeks)
+1. Add tactical combat options
+2. Create achievement showcase
+3. Add loop modifiers/challenges
+4. Implement equipment upgrading
+
+---
+
+## Conclusion
+
+Mana Loop has a strong foundation with unique mechanics (attunements, enchanting, pacts) that differentiate it from typical incremental games. However, several systems are incomplete or disconnected, creating confusion and limiting engagement.
+
+**The biggest issues are:**
+1. Golemancy is completely missing despite being promised
+2. Invoker attunement has no skills
+3. Combat has no player agency
+4. Equipment progression is broken
+
+**Focus on completing existing systems before adding new ones.**
+
+---
+
+*End of Analysis Report*