README.md

TinyVillage

TinyVillage is a 2D simulation game where AI characters autonomously go about their lives in a dynamic village. Each AI character has a history, likes and dislikes, relationships, careers, bank accounts, and more. The game is driven by an advanced AI system using TinyLlama, a locally-run language model based on Llama 2, which powers the decision-making processes of the characters.

Features

• Autonomous AI Characters: Characters make decisions based on their personal histories, relationships, and current game states.
• Dynamic Interactions: Characters interact with each other and the environment, creating a constantly evolving game world.
• Complex Simulation: The game includes various systems like buildings, jobs, items, and events, all interconnected to provide a rich simulation experience.
• Strategic AI Planning: Utilizes Goal-Oriented Action Planning (GOAP) and utility-based evaluations to simulate realistic character behaviors.

Directory Structure

• actions.py: Defines possible actions characters can take.
• tiny_brain_io.py: Manages input/output operations for the AI brain.
• tiny_buildings.py: Handles interactions related to game buildings.
• tiny_characters.py: Manages character data and attributes.
• tiny_event_handler.py: Processes game events and routes them to appropriate components.
• tiny_gameplay_controller.py: Coordinates the main game loop and updates.
• tiny_goap_system.py: Implements the GOAP system for action planning.
• tiny_graph_manager.py: Manages the graph of all game entities and their relationships.
• tiny_items.py: Manages game items and their interactions.
• tiny_jobs.py: Handles job-related data and interactions.
• tiny_memories.py: Stores and retrieves characters' memories.
• tiny_output_interpreter.py: Translates AI decisions into game commands.
• tiny_prompt_builder.py: Constructs dynamic prompts for the AI.
• tiny_strategy_manager.py: Formulates overarching strategies for the AI.
• tiny_time_manager.py: Manages game time and synchronizes processes.
• tiny_utility_functions.py: Evaluates utility scores for action planning.
• tiny_util_funcs.py: Provides various utility functions supporting game logic and AI decisions.

Getting Started

Prerequisites

• Python 3.12
• Required Python packages (listed in requirements.txt)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/tinyvillage.git

2. Navigate to the project directory:

   cd tinyvillage

3. Install the required packages with Python 3.12:

   python3.12 -m pip install -r requirements.txt

Running the Game

To start the game, run the following command:

python main.py

The game supports multiple modes:

Visual Demo (Full pygame display):

python main.py --mode visual

Minimal Demo (Console output, no display):

python main.py --mode minimal

Integration Tests (Verify system integration):

python main.py --mode test

Additional Options:

python main.py --characters 3      # Create 3 characters
python main.py --no-llm            # Disable LLM (use fallback logic)
python main.py --fps 30            # Run at 30 FPS
python main.py --verbose           # Enable debug logging
python main.py --help              # Show all options

For more detailed instructions, see the Quickstart Guide.

Documentation

Comprehensive documentation is available in the docs/ directory:

• User Guides - Getting started and usage guides

  • Quickstart Guide - Get running in under 5 minutes
  • Checkpoint System Guide - Save system usage
  • LLM Integration Guide - Using LLM features

• Technical Reference - API and system documentation

  • System Integration Status - Current implementation status
  • Contributor Agent Guide - Canonical repository guidance for contributor agents
  • Supplemental Agent Reference - Additional architecture background
  • Checkpoint System Documentation - Technical details
  • Storytelling System - Narrative generation
  • And more...

• Testing Documentation - Testing guidelines and best practices

  • Memory Testing Best Practices
  • Randomness Testing Guide

• Design Documents - Architecture and design deep-dives

  • High-Level Architecture
  • Module Connectivity Map
  • Graph Manager Deep Dive
  • Data Flow & Decision Cycle

See docs/README.md for a complete documentation index.

Contributing

We welcome contributions! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

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

Acknowledgments The TinyLlama model, based on Llama 2, for powering our AI characters. OpenAI for providing the language model architecture. Contact For any inquiries or issues, please contact your-email@example.com.

css Copy code