Mana-Loop/GAME_SYSTEMS_ANALYSIS.md

# 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*