# Combat System - Complete Index

Everything you need is here. Start with **START HERE** below.

## 🎯 START HERE

1. **[COMBAT_SYSTEM_SUMMARY.md](./COMBAT_SYSTEM_SUMMARY.md)** ← Read this first
   - Overview of what's been created
   - Quick 15-minute setup guide
   - Next steps to get running

2. **[Assets/Scripts/Maze/Combat/QUICK_START.md](./Assets/Scripts/Maze/Combat/QUICK_START.md)**
   - Copy-paste setup code
   - Create your first weapon/armor/monster
   - Get agents fighting in 5 minutes

3. **[COMBAT_REFERENCE.md](./COMBAT_REFERENCE.md)** ← Keep this open
   - API documentation for all classes
   - Common usage patterns
   - Quick lookup table

## 📚 Detailed Guides

| Document | Purpose | Read When |
|----------|---------|-----------|
| [Combat/README.md](./Assets/Scripts/Maze/Combat/README.md) | Full feature overview + setup | Understanding the system deeply |
| [Combat/ARCHITECTURE.md](./Assets/Scripts/Maze/Combat/ARCHITECTURE.md) | Class diagrams + data flow | Understanding relationships |
| [Combat/INTEGRATION_EXAMPLE.md](./Assets/Scripts/Maze/Combat/INTEGRATION_EXAMPLE.md) | Code snippets to copy-paste | Implementing integration |
| [Combat/IMPLEMENTATION_CHECKLIST.md](./Assets/Scripts/Maze/Combat/IMPLEMENTATION_CHECKLIST.md) | What's done, what's left | Planning your work |
| [Combat/COPY_PASTE_EXAMPLES.cs](./Assets/Scripts/Maze/Combat/COPY_PASTE_EXAMPLES.cs) | Code templates | Quick examples |

## 🧩 Core Classes Created

### Stats & Equipment
- **CharacterStats.cs** — Base stats (health, speed, attack, defense, magic)
- **CharacterSheet.cs** — Equipment + bonuses management
- **Items/Item.cs** — Base equipment class
- **Items/Weapon.cs** — Attack-boosting equipment
- **Items/Armor.cs** — Defense-boosting equipment

### Monsters & Encounters
- **Monsters/Monster.cs** — ScriptableObject monster template
- **Monsters/MonsterEncounter.cs** — Room encounter state + threat calculation
- **RoomEncounterConfig.cs** — Encounter spawning config

### Combat (Skeleton)
- **CombatResolver.cs** — Combat resolution (you expand this!)

### AI & Integration
- **AutonomousAgentBrain.cs** (updated) — Peek & retreat mechanics
- **MazeAgent.cs** (updated) — Character sheet + health tracking
- **Room.cs** (updated) — Can hold MonsterEncounter

## 🚀 Quick Setup (15 min)

```
1. Create Monster asset (2 min)
   Right-click > Create > Monster > Set stats > Save to Resources/Monsters/

2. Create Weapon asset (2 min)
   Right-click > Create > Weapon > Set bonuses > Save to Resources/Items/Weapons/

3. Create Armor asset (2 min)
   Right-click > Create > Armor > Set defense > Save to Resources/Items/Armor/

4. Update MazeSceneBuilder (5 min)
   Load resources, create agents with equipment, pass retreatThreshold

5. Update MazeGenerator (2 min)
   Spawn encounters in rooms

6. Test (2 min)
   Play & watch agents interact with monsters
```

See **COMBAT_SYSTEM_SUMMARY.md** for full code.

## 📋 Implementation Order

**Phase 1: Setup (Today)**
- [ ] Read COMBAT_SYSTEM_SUMMARY.md
- [ ] Create test assets (1 monster, 1 weapon, 1 armor)
- [ ] Update MazeSceneBuilder to load and use assets
- [ ] Update MazeGenerator to spawn encounters
- [ ] Verify agents spawn with equipment ✓

**Phase 2: Combat (Next)**
- [ ] Implement CombatResolver.cs full combat loop
- [ ] Integrate into MazeAgentController
- [ ] Test agent vs monster combat
- [ ] Implement victory/defeat outcomes

**Phase 3: Polish (Later)**
- [ ] Add UI (health bars, combat log)
- [ ] Implement monster AI
- [ ] Add loot drops
- [ ] Balance difficulty

## 🎮 Key Features

✅ **Done**
- Character stats system with multiple stat types
- Equipment system (weapons, armor, general items)
- Monster templates and spawning
- Rooms with monster encounters
- Agent intelligence (peek at threats, retreat from danger)
- Incomplete information (agents see 60-100% of monsters)
- Death tracking for agents

🔨 **Skeleton (Expand)**
- Combat resolution (basic structure, implement turns)
- Monster AI (currently just attacks)
- Ability system (structure for items to have effects)
- UI integration

❌ **Not Done Yet**
- Special abilities/spells
- Status effects
- Inventory UI
- Loot pickup
- Difficulty scaling
- Boss encounters

## 📝 Class Reference

**Quick lookup:**
```csharp
// Create a character
var stats = new CharacterStats();
var sheet = new CharacterSheet(stats);

// Equip items
sheet.EquipWeapon(ironSword);
sheet.EquipArmor(leatherArmor);

// Get effective stats (includes bonuses)
float atk = sheet.GetEffectiveAttack();

// Create agent with character
var agent = new MazeAgent("Agent_0", startRoom, sheet);

// Spawn monsters
var encounter = new MonsterEncounter();
encounter.SpawnMonsters(new[] { goblin }, 1, 3);
room.Encounter = encounter;

// Evaluate threat
float cr = encounter.GetPerceivedChallengeRating(agent.CharacterSheet);

// Resolve combat (when implemented)
var outcome = CombatResolver.ResolveCombat(agent, encounter);
```

See **COMBAT_REFERENCE.md** for full API.

## 🐛 Common Issues

| Issue | Solution |
|-------|----------|
| Compile errors about CharacterSheet | Unity hasn't recompiled yet. Wait or press Ctrl+Shift+R |
| Resources not loading | Ensure assets are in `Resources/Monsters/`, `Resources/Items/Weapons/`, etc. |
| Agents don't have equipment | Pass CharacterSheet to MazeAgent constructor |
| Agents don't retreat | Set lower retreatThreshold (e.g., 0.8 instead of 1.5) |
| Combat doesn't happen | Implement MazeAgentController trigger for room with encounter |
| Dead agents still moving | Call agent.Die() when defeated |

## 📞 Design Decisions Made

1. **Incomplete information** — Agents see 60-100% of monsters (not exact count)
   - Creates strategic risk
   - Agents make decisions without perfect info
   - Customizable per encounter

2. **Retreatable** — Agents can choose not to fight
   - Uses challenge rating threshold
   - Only if safer exits exist
   - Cornered agents will fight anyway

3. **Extensible equipment** — Easy to add new item types
   - Base Item class is abstract
   - Weapon/Armor derive from it
   - Can add Consumable, Accessory, etc.

4. **Per-instance stats** — Monsters are templates, instances get copied stats
   - Allows variation (same goblin can have different stats)
   - Instances don't affect templates
   - Modular and safe

5. **Separate combat resolution** — CombatResolver is independent
   - Can test separately
   - Easy to replace with different system
   - No coupling to scene/UI

## 🔗 Dependencies

```
MazeAgent
  └─ CharacterSheet
     └─ CharacterStats
     └─ Weapon/Armor
        └─ Item

AutonomousAgentBrain (peek & retreat)
  └─ MonsterEncounter
     └─ Monster
        └─ CharacterStats + Items

Room
  └─ MonsterEncounter

CombatResolver (skeleton)
  └─ MazeAgent + MonsterEncounter
```

## ✨ What Makes This System Good

- **Modular** — Each piece is independent and testable
- **Extensible** — Easy to add new items, stats, effects
- **Data-driven** — All content is ScriptableObjects (no code changes for new monsters)
- **Agent-intelligent** — Agents make decisions based on actual threat
- **Performance-conscious** — Stats are just numbers, support many agents
- **Incomplete info** — Creates real strategy, not just stats

## 🎓 Learning Path

1. Create one weapon, armor, monster → understand ScriptableObjects
2. Create agent with equipment → understand CharacterSheet
3. Spawn encounter in room → understand MonsterEncounter
4. Implement simple attack resolution → understand combat loop
5. Add turn order → understand initiative systems
6. Add status effects → understand effect composition
7. Add monster AI → understand decision making
8. Expand to full system → you're a game dev now! 🚀

## 📞 Support

All documentation is in this folder:
- `COMBAT_SYSTEM_SUMMARY.md` — Big picture
- `COMBAT_REFERENCE.md` — API lookup
- `QUICK_START.md` — Immediate setup
- `INTEGRATION_EXAMPLE.md` — Code examples
- `ARCHITECTURE.md` — Class diagrams
- `README.md` — Detailed guide
- `IMPLEMENTATION_CHECKLIST.md` — Progress tracking

**Start with COMBAT_SYSTEM_SUMMARY.md** ← You are here 👈

---

**Version:** 1.0
**Last Updated:** 2026-08-25
**Status:** ✅ All foundation classes complete, skeleton for combat ready