# Combat & Monster System

This folder contains the foundation for a turn-based combat system with agents, monsters, items, and encounters.

## Overview

### Core Components

- **CharacterStats** — Base statistics for any character (Agent or Monster)
  - `MaxHealth` — Total durability
  - `Speed` — Initiative and movement speed
  - `Attack` — Physical damage output
  - `Defense` — Physical damage reduction
  - `Magic` — Magical power and spell effectiveness

- **CharacterSheet** — Wraps stats with equipment and temporary bonuses
  - Manages equipped weapons, armor, inventory
  - Applies stat bonuses from items
  - Tracks effective stats (base + bonuses)

- **Items** (Weapon, Armor)
  - ScriptableObjects you create in the editor
  - Automatically apply bonuses when equipped
  - Can have rarity, icons, descriptions for UI

- **Monster** — A template for spawning monster instances
  - Defines base stats, starting equipment, loot table
  - Created as ScriptableObjects in the editor
  - Instances get fresh stat copies when spawned

- **MonsterEncounter** — Represents monsters in a single room
  - Tracks alive/defeated monsters
  - Provides challenge rating (perceived vs. actual)
  - Agents don't see the true count (60-100% visibility)

- **RoomEncounterConfig** — Configures encounter spawning
  - Probability a room has an encounter
  - Min/max monster count per room
  - Which monsters can spawn here

## Setup Walkthrough

### 1. Create Base Weapons & Armor

In the editor, create ScriptableObjects of type `Weapon` and `Armor`:

1. Right-click in Project > Create > Weapon (or Armor)
2. Fill in stats:
   - **Weapon**: Attack bonus, optional magic/defense/speed bonuses
   - **Armor**: Defense bonus, optional health/magic/speed effects
3. Give it a name and set rarity (1-5)
4. Save to `Assets/Resources/Items/` or similar

**Example weapon config:**
- Name: "Iron Sword"
- Attack Bonus: +5
- Rarity: 1

**Example armor config:**
- Name: "Leather Armor"
- Defense Bonus: +3
- Speed Penalty: -0.5
- Rarity: 1

### 2. Create Monsters

Create ScriptableObjects of type `Monster`:

1. Right-click in Project > Create > Monster
2. Set the base stats (CharacterStats)
3. Optionally assign starting weapon/armor
4. Add items to the loot table (things it drops when defeated)
5. Save to `Assets/Resources/Monsters/` or similar

**Example monster config:**
- Name: "Goblin"
- Color: Green
- Stats:
  - Max Health: 15
  - Speed: 8
  - Attack: 4
  - Defense: 1
  - Magic: 0
- Starting Weapon: Iron Sword (optional)
- Possible Loot: [Leather Armor, Health Potion]

### 3. Create Agent Character Sheets

When spawning agents, you can give them starting equipment:

```csharp
var stats = new CharacterStats();  // Uses defaults or configure manually
var sheet = new CharacterSheet(stats);
sheet.EquipWeapon(playerWeapon);
sheet.EquipArmor(playerArmor);

var agent = new MazeAgent(agentName, startRoom, sheet);
```

Or agents can pick up loot after defeating monsters (integrate with your combat system).

### 4. Configure Room Encounters

Update `MazeSceneBuilder` to pass `RoomEncounterConfig` to `AutonomousAgentBrain.Initialize()`:

```csharp
var encounterConfig = new RoomEncounterConfig()
{
    EnableEncounters = true,
    EncounterChance = 0.7f,
    MinMonstersPerRoom = 1,
    MaxMonstersPerRoom = 3,
    MonsterPool = new[] { goblin, orc, troll }
};
```

Then in the generator or brain, when a new room is created:

```csharp
if (encounterConfig.ShouldHaveEncounter())
{
    var encounter = new MonsterEncounter();
    encounter.SpawnMonsters(
        encounterConfig.MonsterPool,
        encounterConfig.MinMonstersPerRoom,
        encounterConfig.MaxMonstersPerRoom
    );
    room.Encounter = encounter;
}
```

### 5. Integrate Peek & Retreat (Already in AutonomousAgentBrain)

The `AutonomousAgentBrain` now has:

- **`PeekThroughExit(exit, agent)`** — Returns perceived challenge rating
- **`ShouldTakeExit(exit, agent)`** — Evaluates if exit is worth taking
- **`FilterByThreat(exits, agent)`** — Removes dangerous exits from choice list

This is automatically called during `ChooseExit()` — agents will naturally avoid high-threat rooms if safer exits exist.

## Combat Skeleton (Not Yet Implemented)

You'll need to add:

1. **Combat resolution** — When an agent enters a room with monsters
   - Initiative order (based on Speed stat)
   - Attack vs. Defense calculation
   - Damage application
   - Victory/defeat conditions

2. **Loot distribution** — When a monster dies
   - Roll on loot table
   - Add items to agent inventory or drop them in room

3. **UI integration**
   - Show health bars during combat
   - Display stats, equipment, inventory
   - Ability to view perceived vs. actual monster counts

4. **Difficulty scaling**
   - Adjust monster stats by room depth
   - Scale encounter size with agent progression

## Extensibility

### Add a New Stat Type

1. Add field to `CharacterStats`
2. Add bonus dictionary to `CharacterSheet`
3. Add `GetEffectiveStat()` method
4. Add override in `Weapon`/`Armor` if applicable

### Create a New Item Type

Inherit from `Item`:

```csharp
public class Consumable : Item
{
    [SerializeField] private int _healthRestore = 20;

    public override bool OnEquip(CharacterSheet character)
    {
        // Use immediately instead of equipping
        character.Stats.CurrentHealth += _healthRestore;
        return false; // Don't stay equipped
    }
}
```

### Customize Challenge Rating

Override `MonsterEncounter.GetPerceivedChallengeRating()` for more complex threat evaluation:

```csharp
// E.g., factor in armor, magic resistance, count of monsters, etc.
```

## Current Limitations & TODOs

- **No actual combat system** — Just stat blocks and threat evaluation
- **Monster encounters spawn once** — No respawning, re-rolls, or dynamic generation
- **No item drop/pickup** — Loot tables defined but not used
- **Incomplete information** — Agent sees 60-100% of monsters; could be more nuanced
- **No special abilities** — Just base attack/defense stats (extensible via items)
- **No status effects** — Poison, stun, buff/debuff system not yet added