---
title: Medieval Village AI Emulator
emoji: 🏰
colorFrom: blue
colorTo: purple
sdk: static
app_file: index.html
pinned: false
license: mit
---

# Medieval Village AI Emulator

An interactive 3D simulation of a medieval village powered by artificial intelligence. Watch as AI-controlled villagers go about their daily routines, work, eat, sleep, and socialize in a dynamically generated environment.

## Features

- **3D Visualization**: Real-time 3D rendering of villagers, buildings, and resources using Three.js
- **AI-Powered Villagers**: Villagers with complex behaviors based on needs (energy, hunger, social)
- **Dynamic Environment**: Weather system, disasters, and wildlife interactions
- **Interactive Controls**: Add villagers, trigger disasters, spawn animals, and dispatch warriors
- **LLM Integration**: Optional integration with Hugging Face models for enhanced AI behaviors

## How to Use

1. The simulation starts automatically with 3 villagers
2. Use the controls panel on the left to interact with the village:
   - Add Villager: Creates a new villager at a random position
   - Reset Simulation: Clears all villagers and restarts the simulation
   - Adjust Time Speed: Control simulation speed (0.1x to 5.0x)
   - Toggle Paths/Titles: Show/hide movement paths and villager names
3. Camera controls:
   - Mouse: Look around (orbit)
   - Mouse Wheel: Zoom in/out
   - Right Mouse + Drag: Pan camera
4. Click on any villager to see detailed information about their state, needs, and current activities

## Technical Details

This simulation demonstrates several AI techniques:

- **Pathfinding**: A* algorithm for efficient navigation
- **Behavior Trees**: Decision-making system for villager actions
- **Daily Routines**: Time-based scheduling system
- **Crowd Simulation**: Steering behaviors and collision avoidance
- **Resource Management**: Villagers gather and use resources
- **Environmental Interaction**: Villagers interact with buildings and resources

## LLM Integration

The simulator can optionally integrate with Hugging Face models for enhanced AI behaviors. To use this feature:

1. Get a Hugging Face API token from [https://huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)
2. Set the token in the browser console: `window.HF_TOKEN = "your-token-here"`
3. Select a model from the LLM Controls dropdown
4. Ask questions about the simulation using the LLM query input

## Architecture

```
index.html          # Main HTML file with UI
├── app_new.js      # Main application logic
└── src/ai/         # AI system components
    ├── main.js     # AI system integration
    ├── routines.js # Daily routine management
    ├── environment.js # Environment interaction
    ├── pathfinding.js # Navigation system
    ├── behavior.js # Behavior trees
    ├── crowd.js    # Crowd simulation
    └── optimization.js # Performance optimization
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.