Evochora

<div align="center"> <img width="465" height="74" alt="logo" src="https://github.com/user-attachments/assets/4724aed1-a596-4e03-9c3c-41f791b0babd" /> <br><code>Simulation Platform for Digital Evolution Research</code>

<br><br>

<a href="http://evochora.org" style="font-size: 1.5em; font-weight: bold; text-decoration: none;" target="_blank">👉 SEE LIVE DEMO</a> <br> _{Runs in your browser. No installation required.}

<br> <a href="https://opensource.org/licenses/MIT"> <img src="https://img.shields.io/badge/License-MIT-2ea44f?style=flat&logo=opensourceinitiative&logoColor=white" height="28"> </a> &nbsp;&nbsp; <a href="https://discord.gg/t9yEJc4MKX"> <img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=flat&logo=discord&logoColor=white" height="28"> </a> &nbsp;&nbsp; <a href="https://github.com/evochora/evochora/actions"> <img src="https://img.shields.io/github/actions/workflow/status/evochora/evochora/build.yml?branch=main&style=flat&logo=github&logoColor=white&label=Build" height="28"> </a> &nbsp;&nbsp; <a href="https://colab.research.google.com/github/evochora/evochora/blob/main/notebooks/data_analysis_guide.ipynb?flush_cache=true"> <img src="https://colab.research.google.com/assets/colab-badge.svg" height="28"> </a> </div>

<br><br>

<!--<video src="https://github.com/user-attachments/assets/2dd2163a-6abe-4121-936d-eb46cc314859" loop></video>--> <!--<video src="https://github.com/user-attachments/assets/28c329bc-9554-4b10-8d65-049f00eeda86" loop></video>-->

<video src="https://github.com/user-attachments/assets/69b33e5b-074b-46d6-917c-9b9cf06e10ef" loop></video>

<br>

Screenshots:

<table> <tr> <td align="center" width="50%"> <a href="https://github.com/user-attachments/assets/3bf0aa8e-f2bd-4b98-a03f-dd33d449ed93" target="_blank"> <img alt="Web Visualizer" src="https://github.com/user-attachments/assets/3bf0aa8e-f2bd-4b98-a03f-dd33d449ed93" width="100%"> </a> <br><strong>Web Visualizer</strong> <br>_{Tick-by-tick inspection and debugging of organism state, registers, and EvoASM execution} </td> <td align="center" width="50%"> <a href="https://github.com/user-attachments/assets/c30c6bcc-cdbe-4637-befe-3d69b21319db" target="_blank"> <img alt="Web Analyzer" src="https://github.com/user-attachments/assets/c30c6bcc-cdbe-4637-befe-3d69b21319db" width="100%"> </a> <br><strong>Web Analyzer</strong> <br>_{Population metrics, environment composition, and genome analytics via pluggable charts} </td> </tr> </table> <br>

What is Evochora?

Evochora is a scientific simulation platform where digital organisms — written in EvoASM, a spatial assembly language — live as distributed code in an n-dimensional grid. They interact with their surroundings exclusively through local pointers and replicate under configurable thermodynamic constraints. There is no fitness function and no external selection pressure.

The platform is extensible at every layer: the compiler pipeline, the VM instruction set, the mutation operators, and the rules of the world are all configurable or replaceable through plugins. A decoupled data pipeline persists complete simulation state and exports all metrics as standard Parquet files — ready for analysis in Python, R, Jupyter, or DuckDB. A web-based frontend allows tick-by-tick inspection and debugging of organism behavior.

<br>

Quick Start

Requirements: Java 21 (JRE or JDK)

Download and unpack the latest distribution from the GitHub Releases page.

cd evochora-<version>
bin/evochora node run

Open the visualizer in your browser: http://localhost:8081/visualizer/

The node starts a complete in-process simulation with the default primordial organism, including persistence, indexing, and the web frontend. Press Ctrl+C to stop.

Resource requirements: Evochora records every tick for full replay. Allow sufficient disk space for long-running experiments. The default heap size is 8 GB. To increase it, set EVOCHORA_OPTS before starting:

EVOCHORA_OPTS="-Xmx16g" bin/evochora node run

The system warns at startup if memory is insufficient for the configured world size.

<br>

Table of Contents

• What is Evochora?
• Quick Start
• Why Evochora?
• Key Capabilities
• User Guide
• How It Works
• Comparison with Other Platforms
• Research Directions
• Contributing & Community
• License & Citation

<br>

Why Evochora?

Landmark platforms like Tierra and Avida demonstrated that digital evolution can produce genuine ecological dynamics and complex adapted functions. Evochora asks a complementary question: how do the fundamental rules of a world shape the evolutionary outcomes within it?

To answer this, the physics of the world are themselves the experiment. Thermodynamic models, mutation operators, resource distribution, and death mechanics are all swappable plugins. Instead of asking "what evolves under these rules?", researchers can ask "how do the rules shape what evolves?" — and test the answer by changing them.

For the full scientific motivation, see the Scientific Overview. For the personal story behind the project, see the Origin Story.

<br>

Key Capabilities

Design Your Experiments

• Spatial Worlds — Configurable grid size and dimensionality (2D to n-D), bounded or toroidal
• Custom Organisms — Write organisms in EvoASM, a spatial assembly language with an extensible multi-pass compiler
• Configurable Thermodynamics — Configurable energy and entropy costs; customize selection pressure or write your own thermodynamic rules replacing or extending existing policies, decay rules, and resource distribution
• Mutation Models — Configure existing gene insertion, substitution, deletion, and duplication rules or write your own mutation plugins
• Extensible Instruction Set — Customize or extend the VM instruction set without modifying the core runtime

Analyze Your Results

• Standard Formats — All simulation data exports as Parquet, ready for Python, R, or Jupyter
• Pluggable Analytics — Add custom metrics as analytics plugins with built-in chart visualization; built-in plugins cover population, vital stats, age distribution, genome diversity, and more
• Web-Based Inspection — Step through every tick, inspect organism registers, stacks, and debug EvoASM execution in the browser
• Jupyter Notebook — A ready-to-use data analysis notebook with phylogenetic trees, Muller plots, and cross-metric analysis using pandas, networkx, and DuckDB

Trust Your Results

• Deterministic Simulation — Seed-based; identical input produces identical output, guaranteed
• Complete Data Persistence — Every tick is recorded; nothing is lost or aggregated away
• Decoupled Data Pipeline — Raw data can be reindexed at any time with new or modified analytics plugins
• No Built-In Selection Bias — By default, no global culling or task-based rewards; organisms survive through their own actions in a spatial environment

<br>

User Guide

Configuration

Evochora is configured via HOCON configuration files. The main configuration file config/evochora.conf serves as an experiment template with the most common parameters. All defaults are defined in reference.conf (embedded in JAR, loaded automatically).

For custom experiments, copy the template and adjust parameters:

cp config/evochora.conf config/my-experiment.conf
# Edit config/my-experiment.conf
bin/evochora -c config/my-experiment.conf node run

Writing Your Own Organisms

Organisms are programmed in EvoASM, Evochora's custom spatial assembly language. The default primordial organism (assembly/primordial/main.evo) is a conservative replicator: a main loop checks the energy level and decides whether to call the reproduction or energy harvesting subroutine. It is enclosed in a STRUCTURE shell but does not overwrite other organisms.

This design leaves room for experimentation. For example:

• Aggressive variant — overwrite neighboring organisms' code to claim territory
• Defensive variant — add a subroutine that periodically repairs the STRUCTURE shell against aggressive neighbors
• Cooperative variant — write data molecules into the environment as signals; other organisms can read them to coordinate behavior or share energy
• Efficient variant — optimize the energy harvesting routine to cover more ground with fewer instructions

To create your own organism:

1. Edit or create a .evo file in assembly/
2. Configure it in config/evochora.conf (see simulation-engine.options.organisms)
3. Run bin/evochora node run — the engine compiles automatically

Resources:

• Language Reference: docs/ASSEMBLY_SPEC.md
• Syntax Highlighting: VS Code/Cursor extension in extensions/vscode/

Command Line Interface (CLI)

The Evochora CLI is the main entry point for running simulations and tools.

• node run — Start the simulation node (engine, pipeline, HTTP server)
• compile — Compile EvoASM programs for the Evochora VM
• inspect — Inspect stored simulation data (ticks, runs, resources)
• video — Render simulation runs into videos (requires ffmpeg)

For full documentation an