# AI Agent System - Quick Implementation Guide

## What Was Created

I've created a complete AI agent spawning system for your MazeWalker game with the following:

### New Scripts (in `Assets/Scripts/`):
1. **AIAgent.cs** - Individual AI agents that navigate the maze
2. **AIAgentManager.cs** - Manages agent spawning and tracking
3. **AIRoomMemory.cs** - Tracks visited rooms per character type
4. **AIAgentUIDisplay.cs** - Optional UI display for agent stats
5. **AIAgentExampleSetup.cs** - Example scene setup helper

### New Documentation:
- **AI_AGENT_SETUP_GUIDE.md** - Comprehensive setup and usage guide

## Quick Setup (30 seconds)

### Option 1: Automatic (Recommended)
1. Select your **MazeController** GameObject in the scene
2. In the Inspector, find the "AI Agents" section
3. Check the **"Spawn AI Agents"** checkbox
4. (Optional) Adjust `Initial Agent Count` (default: 10)
5. Play the scene - 10 agents will spawn and start exploring!

### Option 2: Manual Setup
1. Create an empty GameObject as a child of MazeController
2. Add the **AIAgentManager** component to it
3. Configure `Initial Agent Count` to 10
4. Select MazeController and drag this GameObject to the `Agent Manager` field

## How It Works

- **10 AI agents** spawn at the start room
- Each agent only **knows about its current room**
- Agents **share knowledge** with other agents of the same type about which rooms have been explored
- When they know of an unvisited room, they path toward it
- They use **A* pathfinding** to navigate within each room
- When reaching a room exit, they move to the next room
- Eventually they reach the **goal room and exit**

## Key Features

✅ Configurable spawn count (default: 10)
✅ Can spawn more agents during gameplay
✅ Agents spawn in the start room
✅ Limited knowledge (only know current room + visited rooms by character type)
✅ Smart pathfinding to goal
✅ Shared memory between agents of same type
✅ Visual path debugging (yellow lines showing paths)
✅ Automatic reset when generating new maze

## Runtime Controls (Optional)

If you attach **AIAgentExampleSetup.cs** to a GameObject in your scene:
- Press **A** - Spawn 1 agent
- Press **S** - Spawn 5 agents
- Press **C** - Clear all agents
- Press **L** - Log agent statistics
- Press **R** - Regenerate maze

## Testing

1. **Start the game** - 10 agents should spawn at start
2. **Watch them explore** - Yellow lines show their paths
3. **Press K** to spawn more - Test runtime spawning
4. **Check console** - Agent spawn messages and statistics

## Next Steps (For Future)

The system is built to be extended with:
- **Combat stats** (health, damage, experience)
- **Different agent types** (warriors, scouts, rogues with different behaviors)
- **Monster encounters** - Agents can fight enemies
- **Stats system** - For player battles later
- **Persistence** - Save agent progress between sessions

## File Structure

```
Assets/Scripts/
├── AIAgent.cs                    // Individual agent behavior
├── AIAgentManager.cs             // Spawn/track agents
├── AIRoomMemory.cs               // Shared room knowledge
├── AIAgentUIDisplay.cs           // Optional UI
├── AIAgentExampleSetup.cs        // Example setup helper
├── MazeController.cs             // Updated with agent support
└── ... (other maze scripts)

Root/
├── AI_AGENT_SETUP_GUIDE.md       // Comprehensive documentation
└── MAZE_SETUP_GUIDE.md           // Existing maze guide
```

## Inspector Configuration

### MazeController
```
AI Agents section:
- Spawn AI Agents: ✓ (checked)
- Initial Agent Count: 10
- Agent Character Type: "Default"
- Spawn Delay: 0.1
```

### AIAgentManager (if manual setup)
```
Agent Spawning:
- Initial Agent Count: 10
- Agent Character Type: "Default"
- Spawn Delay: 0.1

Agent Prefab: (leave empty - auto-creates)

Visual Settings:
- Show Agent Paths: ✓ (checked)
- Agent Path Color: Yellow
```

## Debugging Tips

**Agents not appearing?**
- Check console for errors
- Verify `spawnAIAgents` is enabled on MazeController
- Make sure maze has rooms (check console output)

**Agents not moving?**
- Check they spawned at start point
- Verify `movementSpeed > 0`
- Check maze has exit points

**Performance issues?**
- Reduce agent count
- Increase `pathUpdateInterval` (0.5s → 1.0s)
- Disable `showAgentPaths` in inspector

## Code Examples

### Spawn agents at runtime:
```csharp
MazeController maze = FindFirstObjectByType<MazeController>();
AIAgentManager manager = maze.GetAgentManager();
manager.SpawnAgent();  // Spawn 1
manager.SpawnAgents(5); // Spawn 5
```

### Check agent progress:
```csharp
int agentCount = manager.GetAgentCount();
string stats = manager.GetAgentStats();
Debug.Log(stats);  // Shows exploration progress
```

### Monitor specific agent:
```csharp
List<AIAgent> agents = manager.GetActiveAgents();
foreach (var agent in agents)
{
    Debug.Log($"Agent {agent.AgentId} in room {agent.CurrentRoom}");
    Debug.Log($"Explored {agent.RoomMemory.VisitedCount} rooms");
}
```

---

**Everything is ready to go!** Just hit play and watch your agents explore the maze. 🎮

For more details, see **AI_AGENT_SETUP_GUIDE.md**.