👉 SEE LIVE DEMO
Runs in your browser. No installation required.
Screenshots:
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.
Quick Start
Requirements: Java 25 (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.
Table of Contents
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.
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 and demography, genomes and lineage, mutation, instruction usage, and environment composition
- 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 the identical simulation state and trajectory, guaranteed — independent of thread count and of pause/resume
- 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
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/default/main.evo) is a replicator put together from the behaviors of the library: a main loop checks energy and entropy and gives each behavior, reproducing and harvesting energy, its turn by priority. It is enclosed in a STRUCTURE shell and does not build its child into other organisms unless it is compiled with the flag AGGRESSIVE.
This design leaves room for experimentation. For example:
- New behavior — write a behavior for the library and give it a block in the main loop
- 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:
- Edit or create a
.evo file in assembly/
- Configure it in
config/evochora.conf (see simulation-engine.options.organisms)
- Run
bin/evochora node run — the engine compiles automatically
Resources:
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)node resume — Continue the newest run, or the one named with --runnode fork — Record a window of a run again as a new run, densely (--from, --to, --profile, --sampling)node show — Serve the indexed runs to the visualizer and analyzer without running a simulationcompile — Compile EvoASM programs for the Evochora VMinspect — Inspect stored simulation data (ticks, runs, resources)video — Render simulation runs into videos (requires ffmpeg)
For full documentation and worked examples, see the CLI Usage Guide.
Development & Local Build
git clone https://github.com/evochora/evochora.git
cd evochora
./gradlew build
./gradlew run --args="node run"
Open the visualizer: http://localhost:8081/visualizer/
See CONTRIBUTING.md for the full contribution guide, including coding conventions and architecture guidelines.
Extending the Platform
Evochora is extensible at multiple levels through Java plugin interfaces:
- Mutation plugins — Implement
IBirthHandler to define new mutation operators that run during organism reproduction. Built-in plugins: gene insertion, substitution, deletion, and duplication.
- Environment plugins — Implement
ITickPlugin to add new environmental processes. Built-in plugins: solar radiation, geysers, and seed energy distribution.
- Death handlers — Implement
IDeathHandler to control what happens when an organism dies (e.g., decay into energy).
- Analytics plugins — Extend
AbstractAnalyticsPlugin to define custom metrics exported as Parquet. Built-in plugins cover population and demography, genomes and lineage, mutation, instruction usage, and environment composition.
- Compiler extensions — Each compiler phase is extensible via handler registries (directives, IR converters, layout, linking, emission).
- VM instructions — Add new instructions to the ISA via the instruction registry.
How It Works
Evochora is built as a modular stack of four components: Runtime, Compiler, Data Pipeline, and Web Frontends.
Each layer is independently extensible through plugins and registries.
Runtime
The runtime implements the simulation environment and its physical laws. It provides the n-dimensional grid in which organisms exist as spatially distributed code, subject to thermodynamic constraints. Each organism is an independent virtual machine with its own registers, stacks, and pointers. Organisms interact with the world exclusively through their Instruction Pointer (IP) and Data Pointers (DPs) — they have no global view of the simulation.
Thermodynamic costs are fully configurable: actions can cost energy, produce entropy, or both. An organism dies when its energy is depleted or its entropy exceeds its threshold.
Unlike classical von Neumann architectures, jump instructions in Evochora do not target exact addresses. Instead, they resolve targets through fuzzy label matching based on Hamming distance. This makes genomes inherently resilient to mutations that insert, delete, or shift code — a prerequisite for meaningful evolution.
Conceptual Architecture of an Evochora Organism
+---------------------------------------------------------------+
| Evochora "World" (n-D Grid) |
| |
| [ ENERGY ] [ STRUCTURE ] [ CODE ] [ DATA ] |
+-------^-----------------^----------------^-------------^------+
| | | |
Interaction: | | | |
(HARVEST) (BLOCK) (EXECUTE) (READ)
| | | |
| | | |
+-------|-----------------|----------------|-------------|------+
| | ORGANISM | | | |
| | | | | |
| +---v-----------------v----+ +----v-------------v----+ |
| | Data Pointers (DPs) | | Inst. Pointer (IP) | |
| | [DP 0] [DP 1] ... [DP n] |<-----| | |
| +-------------^------------+ +-----------^-----------+ |
| | | |
| (Move/Read/Write) (Control) |
| | | |
| +-------------v-------------------------------v---------+ |
| | Virtual Machine | |
| | | |
| | Registers: [DRs] [LRs] [PDRs] [PLRs] | |
| | [FDRs] [FLRs] [SDRs] [SLRs] | |
| | | |
| | Stacks: [Data Stack] [Call Stack] [Loc. Stack] | |
| | | |
| | Metabolism: [Thermodynamics (ER/SR)] --(Cost)--> 0 | |
| +-------------------------------------------------------+ |
+---------------------------------------------------------------+
Compiler
The Evochora compiler is a multi-pass pipeline that transforms human-readable EvoASM assembly code into a ProgramArtifact ready for execution. The design separates concerns into a frontend (parsing and analysis) and a backend (layout and code generation). Most phases are extensible via handler registries, allowing new syntactical features to be added in a modular way. EvoASM supports procedures, scoped variables, macros, and spatial layout directives for placing code in n-dimensional space.
Compiler Frontend
The frontend parses the source code and transforms it into a machine-independent Intermediate Representation (IR).
- Preprocessor: Handles macros (
#macro) and file inclusions (#include).
- Parser: Converts tokens into an Abstract Syntax Tree (AST). Extensible via
DirectiveHandlerRegistry for new directives.
- Semantic Analyzer: Validates the AST, checks types, and builds a symbol table.
- IR Generator: Converts the AST into an Intermediate Representation (IR). Extensible via
IrConverterRegistry.
Compiler Backend
The backend takes the IR and generates the final, executable ProgramArtifact.
- Layout Engine: Determines the final spatial coordinates of all molecules. Extensible via
LayoutDirectiveRegistry.
- Linker: Resolves symbolic references (e.g., labels). Extensible via
LinkingRegistry.
- Emitter: Generates the final binary machine code. Extensible via
EmissionRegistry.
┌──────────────────┐
│ EvoASM File │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Preprocessor │
└────────┬─────────┘
│ (Token Stream)
▼
┌──────────────────┐
│ Parser │
└────────┬─────────┘
│ (AST)
▼
┌──────────────────┐
│ Semantic Analyzer│
└────────┬─────────┘
│ (Validated AST)
▼
┌──────────────────┐
│ IR Generator │
└────────┬─────────┘
│ (IR)
▼
┌──────────────────┐
│ Layout Engine │
└────────┬─────────┘
│ (Placed IR)
▼
┌──────────────────┐
│ Linker │
└────────┬─────────┘
│ (Linked IR)
▼
┌──────────────────┐
│ Emitter │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Program Artifact │
└──────────────────┘
Data Pipeline
The simulation engine is decoupled from data processing. Raw simulation data flows through a queue into a persistence service, then through indexers into a queryable database. This separation means the simulation can run at full speed while data is processed independently — and raw data can be reindexed at any time with new or modified indexers.
All pipeline services except the simulation engine are designed as idempotent competing consumers. All inter-service communication is abstracted behind resource interfaces (queues, storage, topics, databases). The default mode runs all components in a single process, but this architecture lays the groundwork for horizontal scaling and distributed deployments.
┌────────────────────────────┐
│ SimulationEngine │
└─────────────┬──────────────┘
│ (TickData)
▼
┌────────────────────────────┐
│ Tick Queue │
└─────────────┬──────────────┘
│ (Batches)
▼
┌────────────────────────────┐
│ Persistence Service │ (Competing Consumers)
└─┬─────────────────────┬────┘
│ (Data) (BatchInfo Event)
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ Storage │ │ Topics │
└─────┬─────┘ └──────┬────┘
│ (Reads) (Triggers)
│ │
└────────┬────────┘
│
▼
┌────────────────────────────┐
│ Indexer Services │ (Competing Consumer Groups)
└─────────────┬──────────────┘
│ (Indexed Data)
▼
┌────────────────────────────┐
│ Database │
└─────┬───────────────┬──────┘
│ │ (Queries)
▼ ▼
┌────────────┐ ┌────────────┐
│ Visualizer │ │ Analyzer │ (Web based)
└────────────┘ └────────────┘
Web Frontends
Evochora includes two web-based frontends for interacting with simulation data:
- Visualizer: Provides a tick-by-tick view of the simulation. Step through time, inspect the state of individual organisms (registers, stacks), and debug the execution of their EvoASM code in the browser.
- Analyzer: Offers a high-level overview of simulation metrics over the entire run. It features a pluggable interface for adding new metrics and visualizations. The Analyzer performs range requests on Parquet files served by the backend, enabling custom queries and analysis directly in the browser using DuckDB-WASM.
Browser (JavaScript Apps) Node (Java Backend)
┌──────────────────────────────────┐ ┌──────────────────────────────────┐
│ │ │ │
│ ┌───────────────────────────┐ │ │ ┌───────────────────────────┐ │
│ │ Visualizer App │ │ │ │ Visualizer Controllers │ │
│ │---------------------------│ │ │ │ - EnvironmentController │ │
│ │ - EnvironmentApi.js │───┼───HTTP──┼─►│ - OrganismController │ │
│ │ - OrganismApi.js │ │ │ │ - SimulationController │ │
│ │ - SimulationApi.js │ │ │ └───────────────────────────┘ │
│ └───────────────────────────┘ │ │ │
│ │ │ │
│ ┌───────────────────────────┐ │ │ │
│ │ Analyzer App │ │ │ │
│ │---------------------------│ │ │ ┌───────────────────────────┐ │
│ │ - AnalyticsApi.js │───┼───HTTP──┼─►│ AnalyticsController │ │
│ │ - DuckDBClient.js (WASM) │ │ │ └───────────────────────────┘ │
│ └───────────────────────────┘ │ │ │
│ │ │ ┌───────────────────────────┐ │
│ │ │ │ PipelineController │ │
│ (Admin Tools/Scripts) ────┼───HTTP──┼─►│ (For pipeline management) │ │
│ │ │ └───────────────────────────┘ │
│ │ │ │
└──────────────────────────────────┘ └──────────────────────────────────┘
Further Reading
For more details, see the Assembly Specification, Compiler IR Specification, Scientific Overview, and Architecture Decisions.
Comparison with Other Platforms
Evochora builds on the legacy of seminal Artificial Life platforms. This comparison highlights the different scientific questions and design trade-offs each system explores.
| Feature / Aspect | Tierra (Ray, 1991) | Avida (Ofria et al., 2004) | Lenia (Chan, 2019) | Evochora |
|---|
| Core Concept | Self-replicating code in linear RAM ("Soup") | Agents solving logic tasks in 2D grid | Continuous cellular automata (Math-Biology) | Spatial code execution in n-Dimensional grid |
| Physics / Environment | CPU cycles & memory access (Fixed) | Rewards for logical tasks (NOT, AND) (Fixed) | Differential equations (flow, kernel) (Fixed) | Extensible via Plugins (Thermodynamics, Resource Distribution) |
| Organism Body | Disembodied (Code string only) | Disembodied (CPU + Memory buffer) | Morphological patterns (solitons) | IP + DPs navigating spatial grid |
| Interaction Model | Parasitism (reading neighbor's RAM) | Limited (mostly competition for space) | Collision, fusion & repulsion of patterns | Direct & Spatial (via DPs); Planned: Signaling |
| Evolutionary Driver | Implicit competition for memory/CPU | Directed (user-defined rewards) | Spontaneous pattern formation | Metabolic & spatial constraints |
| Execution Model | Sequential (Single IP) | Sequential (Single IP) | Parallel (Continuous dynamics) | Sequential; Planned: Intra-organism parallelism (multiple execution threads) |
| Primary Research Focus | Ecology of code & parasites | Evolution of complex logic functions | Self-organizing morphology | User-defined evolution experiments |
Research Directions
Evochora is designed as an open platform for a wide range of evolutionary experiments. Here are some research directions the architecture is built to support:
- Mutation & Evolvability — How do different mutation regimes affect long-term evolutionary potential? Compare gene insertion, substitution, deletion, and duplication strategies or design your own.
- Thermodynamic Selection — How do energy and entropy policies shape population dynamics? Explore the space between harsh and permissive environments.
- Cooperation & Communication — Can organisms that coordinate through environmental signals (molecules placed in the grid) outcompete solitary strategies?
- Digital Chemistry — Can reaction chains (A + B → C + Energy) lead to emergent trophic levels and metabolic recycling?
- Digital Eukaryogenesis — Can intra-organism parallelism lead to internal division of labor, analogous to the prokaryote-to-eukaryote transition?
- Complexity Measurement — How do you rigorously quantify whether evolution produces increasingly complex organisms? The data pipeline persists complete organism state for external analysis.
- Open-Ended Evolution — What conditions help a population overcome the next complexity hurdle? Investigate which combinations of physics, mutation, and environmental structure enable incremental gains in complexity.
For the full scientific context behind these questions, see the Scientific Overview.
Contributing & Community
We welcome contributions of all kinds — code, experiment design, scientific discussion, documentation, and testing.
See CONTRIBUTING.md for the full contribution guide, including development standards, PR process, and good first issues.
For the current roadmap, see the GitHub Project Board.
Community:
License & Citation
Evochora is open-source and available under the MIT License (see LICENSE).
If you use Evochora in your research, please cite:
@software{evochora2025,
title={Evochora: Simulation Platform for Digital Evolution Research},
author={{Evochora Project}},
url={https://github.com/evochora/evochora},
year={2025}
}
Full disclosure: This project uses AI coding assistants. Humans define the architecture, write specifications, and review generated code to ensure correctness and maintain the overall design.
