src/ai/README.md

# Medieval Village AI System

This directory contains the AI system implementation for a medieval village simulator. The system includes various components for managing villager behavior, movement, and interactions.

## Components

### Pathfinding (`pathfinding.js`)
Implements A* pathfinding using navigation meshes for efficient village-scale navigation in 3D space.

Key features:
- Navigation mesh support for complex 3D environments
- Path calculation between any two points in the village
- Entity movement along calculated paths

### Behavior Trees (`behavior.js`)
Implements a behavior tree system for complex villager decision-making.

Key features:
- Behavior tree nodes (Selector, Sequence, Action, Condition)
- Villager behavior management for daily routines
- Extensible behavior system for custom actions

### Crowd Simulation (`crowd.js`)
Implements crowd simulation with collision avoidance for multiple villagers.

Key features:
- Steering behaviors for natural movement
- Spatial partitioning for efficient neighbor queries
- Collision avoidance to prevent villagers from walking through each other

### Daily Routines (`routines.js`)
Manages villager daily routines including work, rest, and social interactions.

Key features:
- Schedule-based routine system
- Activity management (sleep, work, eat, socialize)
- Need-based systems (energy, hunger, social)

### Environmental Interaction (`environment.js`)
Handles how villagers interact with their environment, including resource gathering and building usage.

Key features:
- Resource management system
- Building interaction system
- Inventory system for villagers

### Performance Optimization (`optimization.js`)
Implements various optimization techniques for managing multiple AI entities efficiently.

Key features:
- Entity manager with update queuing
- Spatial partitioning for efficient queries
- Object pooling to reduce garbage collection

### Main System (`main.js`)
Integrates all components into a cohesive AI system for the village simulator.

## Integration with Three.js

The AI system is designed to integrate with Three.js for 3D rendering:

1. Pathfinding uses Three.js Vector3 for positions
2. Crowd simulation uses Three.js Vector3 for positions and velocities
3. Environmental interactions use Three.js Vector3 for positions
4. The main system takes a Three.js scene object for integration

## Usage Example

```javascript
import VillageAISystem from './ai/main.js';
import * as THREE from 'three';

// Create a Three.js scene
const scene = new THREE.Scene();

// Initialize the AI system
const aiSystem = new VillageAISystem(scene);

// Create villagers
const villager1 = aiSystem.createVillager('villager1', new THREE.Vector3(0, 0, 0));
const villager2 = aiSystem.createVillager('villager2', new THREE.Vector3(5, 0, 5));

// In your animation loop
function animate(deltaTime) {
    // Update the AI system
    aiSystem.update(deltaTime);
    
    // Render the scene
    renderer.render(scene, camera);
    
    requestAnimationFrame(animate);
}
```

## Performance Considerations

1. **Entity Updates**: Uses a queuing system to limit the number of entities updated per frame
2. **Spatial Partitioning**: Implements spatial partitioning for efficient neighbor queries
3. **Object Pooling**: Reduces garbage collection through object pooling
4. **Level of Detail**: In a full implementation, you would add LOD systems to reduce AI complexity for distant entities

## Extending the System

The system is designed to be extensible:

1. Add new behavior tree nodes for custom actions
2. Extend the villager class for specialized villager types
3. Add new resource and building types
4. Implement additional optimization techniques as needed