DarwinSim

A deterministic evolutionary ecosystem simulator with a Python backend and Pygame frontend.

🚀 Current Release: v0.1.0

Overview

DarwinSim explores natural selection, genetics, and emergent behavior through autonomous organisms. Its reusable Python simulation backend owns authoritative world behavior, while a Pygame frontend observes immutable state and provides rendering and interaction.

The first stable release completes the v0.1.0 world-and-movement milestone: a deterministic generated environment containing water, trees, plants, and wandering rabbits. A Unity frontend is planned for v2.0.0, using the same Python backend through a future network adapter.

Current features

• Deterministic seeded world generation.
• Water regions, trees, plants, and rabbits.
• Validated TOML configuration.
• Fixed-timestep simulation and deterministic rabbit wandering.
• World-boundary handling and water avoidance.
• Immutable, detached frontend snapshots.
• Local backend-to-frontend adapter.
• Snapshot-driven Pygame rendering.
• Optional sprites with primitive fallback graphics.
• Camera movement, mouse-wheel zoom, clamping, and resizable-window support.
• Automated unit, integration, headless Pygame, and architecture-boundary tests.
• Ruff and pytest checks in GitHub Actions CI.

Architecture

DarwinSim follows one central rule:

Python determines what happens; the frontend determines how it looks.

The backend owns simulation rules and mutable world state. The frontend owns rendering, camera state, input, overlays, and presentation. It communicates with the backend only through the local adapter and immutable snapshots.

TOML configuration
       |
       v
Python simulation backend
       |
       v
Immutable world snapshot
       |
       v
Local simulation adapter
       |
       v
Pygame frontend

See Backend Architecture for the implemented design.

Installation

Python 3.12 or the version required by pyproject.toml is required. From Windows PowerShell:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

If PowerShell blocks activation scripts, review your local execution policy rather than bypassing organizational security controls.

Running DarwinSim

With the virtual environment active:

python scripts/run_pygame.py

Controls

Input	Action
W or Up Arrow	Move camera up
S or Down Arrow	Move camera down
A or Left Arrow	Move camera left
D or Right Arrow	Move camera right
Mouse Wheel	Zoom in or out
Window Close	Exit DarwinSim

Testing and quality checks

python -m ruff format --check .
python -m ruff check .
python -m pytest
python -m pytest --cov=darwinsim --cov-report=term-missing

Coverage reporting is diagnostic and is not currently enforced as a CI threshold.

To apply safe Ruff lint fixes and formatting locally:

python -m ruff check --fix .
python -m ruff format .

Project structure

DarwinSim/
|-- assets/                         Images and optional Pygame assets
|-- config/                         Default TOML configuration
|-- scripts/                        Application and setup entry points
|-- src/darwinsim/
|   |-- backend/                    World, entities, simulation, and systems
|   |-- adapters/                   Frontend-safe simulation adapters
|   |-- contracts/                  Immutable snapshot contracts
|   |-- frontend/pygame/            Pygame application and presentation
|   |-- shared/                     Frontend-independent shared primitives
|   `-- DevCatalog/                 Architecture and development documentation
`-- tests/
    |-- unit/                        Focused behavior and boundary tests
    `-- integration/                 Adapter and headless Pygame tests

Roadmap

Milestone	Focus
v0.1	Deterministic generated world and wandering rabbits
v0.2	Hunger and thirst
v0.3	Reproduction and aging
v0.4	Genetics and inheritance
v0.5	Foxes and predator-prey behavior
v0.6	Plant regrowth
v0.7	Analytics and population statistics
v0.8	Save and load
v0.9	Optimization and polish
v1.0	Stable Pygame ecosystem
v2.0	Unity frontend using the same Python backend

Documentation

• Development Plan
• v0.1 Roadmap
• v0.1.0 Release Notes
• Backend Architecture
• Frontend Architecture
• Snapshot Architecture
• Backend/Frontend Separation ADR
• Fixed-Timestep ADR
• Snapshot ADR
• Changelog
• Contributing Guide
• Security Policy
• Support Guide

Current limitations

The current release does not yet include hunger, thirst, reproduction, genetics, predators, plant regrowth, persistence, or Unity integration. Entity-to-entity collision avoidance and formal long-run performance targets are also outside the current implementation.

License

DarwinSim is available under the MIT License.