A sophisticated colony simulation game where each colonist is an autonomous LLM agent with persistent memory, evolving personality traits, and emergent decision-making capabilities. The game combines the narrative depth of Dwarf Fortress with the accessible systems design of RimWorld, creating a living world where AI-driven characters generate unique stories through their interactions.
- Autonomous LLM Agents: Each colonist operates as an independent AI with unique personality, memories, and decision-making
- Emergent Narratives: Stories arise naturally from agent interactions without scripted events
- Persistent Memory: Colonists remember experiences and learn from them over time
- Dynamic Relationships: Social bonds evolve based on interactions and shared experiences
- World Simulation: Rich environment with weather, resources, wildlife, and events
- Personality Evolution: Traits change gradually based on experiences and decisions
- Language: Python 3.11+
- LLM Framework: LangChain with custom agent wrappers
- Local Model Runtime: Ollama (primary) / llama.cpp (fallback)
- Game Engine: Custom event-driven simulation loop
- Data Persistence: SQLite with JSON blob storage
- Configuration: YAML for game rules, JSON for runtime state
colony_sim/
├── core/
│ ├── agents/ # LLM agent wrappers and personality systems
│ ├── world/ # World simulation and environment
│ ├── events/ # Event system and triggers
│ └── systems/ # Game mechanics (needs, skills, combat)
├── llm/
│ ├── prompts/ # Prompt templates and chains
│ ├── memory/ # Context window management
│ └── models/ # Model loading and configuration
├── api/ # FastAPI backend
├── ui/ # React frontend
├── data/
│ ├── configs/ # YAML game configuration
│ ├── archetypes/ # Colonist templates
│ └── saves/ # Game state persistence
└── tests/ # Unit and integration tests
- Python 3.11+
- Ollama (recommended for full LLM functionality)
# Install Ollama curl -fsSL https://ollama.com/install.sh | sh # Pull required models ollama pull llama3.2 ollama pull llama3.2:1b # Faster fallback model
-
Clone the repository
git clone <repository-url> cd ColonySim
-
Install dependencies
pip install -r requirements.txt
-
Run the demo
python demo.py
The demo showcases:
- 4 colonists with different archetypes (Scientist, Builder, Explorer, Socialite)
- 50 simulation ticks demonstrating decision-making and interactions
- Real-time LLM-powered autonomous behavior
- Emergent social dynamics and memory formation
- World events and environmental challenges
Primary Models (via Ollama):
llama3.2- Main decision-making modelllama3.2:1b- Faster fallback for simple decisionsphi3- Alternative lightweight model
Fallback Mode: When LLM services are unavailable, the system uses rule-based decision making to ensure gameplay continuity.
- Memory: 8GB+ RAM recommended for llama3.2
- Performance: Decisions typically take 2-5 seconds per colonist
- Concurrent Requests: Configurable (default: 5 simultaneous)
-
Scientist
- High intellectual trait (0.9)
- Focuses on research and discovery
- Background: "Former university researcher specializing in ecology"
-
Builder
- High industrious trait (0.9)
- Excels at construction and crafting
- Background: "Experienced carpenter with 15 years of experience"
-
Explorer
- High creative trait (0.8), low cautious trait (0.3)
- Driven by wanderlust and discovery
- Background: "Former wilderness guide who traveled vast continents"
-
Socialite
- High social (0.9) and empathetic (0.9) traits
- Builds community and resolves conflicts
- Background: "Community organizer known for bringing people together"
-
Survivor
- High cautious (0.9) and industrious (0.8) traits
- Focuses on preparation and survival
- Background: "Survivor of natural disaster who learned to never depend on others"
Each colonist has 8 personality traits (0.0 to 1.0):
- Intellectual: Preference for research and learning
- Social: Enjoyment of interpersonal interactions
- Aggressive: Tendency toward confrontation
- Industrious: Drive to work and build
- Cautious: Risk aversion and careful planning
- Creative: Innovation and artistic thinking
- Empathetic: Understanding and caring for others
- Leadership: Natural ability to guide groups
- Terrain Types: Grassland, Forest, Mountain, Water, Desert
- Weather System: Dynamic weather affecting colonist behavior
- Resource Management: Food, water, materials, and rare items
- Wildlife: Passive, neutral, and aggressive creatures
- Day/Night Cycle: Affects colonist activities and needs
- Size: Configurable (default 80x80 tiles)
- Biome Distribution: Realistic terrain clustering
- Resource Spawning: Biome-appropriate resource distribution
- Special Locations: Natural harbors, fertile valleys, mineral deposits
- Danger Zones: Predator territories, unstable terrain
Colonists have 7 core needs that decay over time:
- Hunger (0.02/tick decay)
- Thirst (0.03/tick decay)
- Rest (0.015/tick decay)
- Safety (0.005/tick decay)
- Social (0.01/tick decay)
- Recreation (0.008/tick decay)
- Purpose (0.005/tick decay)
8 skills that improve through use:
- Research, Medicine, Construction, Social
- Farming, Hunting, Crafting, Leadership
Memory Types:
- Episodic: Specific events and experiences
- Semantic: General knowledge and facts
- Emotional: Emotionally significant memories
- Social: Relationship and interaction memories
- Skill: Learning and development memories
Memory Features:
- Importance scoring (0.0 to 1.0)
- Emotional valence (-1.0 to 1.0)
- Temporal decay with access-based retention
- Context-aware retrieval for decision making
Key configuration files:
data/configs/game_config.yaml- Core game parametersdata/configs/world_gen.yaml- World generation settingsdata/configs/prompts/decision_making.yaml- LLM prompt templates
- Simulation speed and tick duration
- LLM model selection and timeouts
- Memory management settings
- Need decay rates and skill progression
- World size and resource abundance
- Event frequency and difficulty
- Create YAML file in
data/archetypes/ - Define traits, skills, and behavioral patterns
- Add background templates and decision weights
Example archetype structure:
archetype:
name: "Custom Archetype"
base_traits:
intellectual: 0.7
social: 0.6
# ... other traits
starting_skills:
research: 5
# ... other skills
behavioral_tendencies:
- "Describes key behavior patterns"- Add new prompt templates in
llm/prompts/ - Implement custom decision logic in
core/agents/ - Configure model parameters in
llm/models/
- Batch LLM requests for efficiency
- Queue management prevents model overload
- Memory compression for long-running games
- Async processing for parallel colonist decisions
- Game events logged to
colony_sim_demo.log - Configurable log levels (DEBUG, INFO, WARNING, ERROR)
- LLM performance tracking and statistics
- Average LLM response time
- Decision success rates
- Memory usage and compression statistics
- Simulation tick performance
- LLM agent framework
- World simulation engine
- Memory and context management
- Basic colonist archetypes
- Demo implementation
- Event and storyteller system
- Save/load functionality
- Advanced social interactions
- Skill progression and specialization
- FastAPI backend with WebSocket support
- React-based frontend
- Real-time colony visualization
- Interactive colonist management
- Personality evolution over time
- Cultural knowledge sharing
- Economic and trade systems
- Multiplayer colony interactions
[Add license information]
[Add contribution guidelines]
[Add support information]
Note: This is an experimental project exploring the intersection of LLM technology and game simulation. The AI agents may occasionally produce unexpected behavior as they learn and adapt to their environment.