Simulation Platform for Digital Evolution Research
👉 SEE LIVE DEMO
Runs in your browser. No installation required.
simulation.mp4
Screenshots:
Web Visualizer Tick-by-tick inspection and debugging of organism state, registers, and EvoASM execution |
Web Analyzer Population metrics, environment composition, and genome analytics via pluggable charts |
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.
Requirements: Java 21 (JRE or JDK)
Download and unpack the latest distribution from the GitHub Releases page.
cd evochora-<version>
bin/evochora node runOpen 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_OPTSbefore starting:EVOCHORA_OPTS="-Xmx16g" bin/evochora node runThe system warns at startup if memory is insufficient for the configured world size.
- What is Evochora?
- Quick Start
- Why Evochora?
- Key Capabilities
- User Guide
- How It Works
- Comparison with Other Platforms
- Research Directions
- Contributing & Community
- License & Citation
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.
- 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
- 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
- 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
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 runOrganisms 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:
- Edit or create a
.evofile inassembly/ - Configure it in
config/evochora.conf(seesimulation-engine.options.organisms) - 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/
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 VMinspect— Inspect stored simulation data (ticks, runs, resources)video— Render simulation runs into videos (requiresffmpeg)
For full documentation and worked examples, see the CLI Usage Guide.
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.
Evochora is extensible at multiple levels through Java plugin interfaces:
- Mutation plugins — Implement
IBirthHandlerto define new mutation operators that run during organism reproduction. Built-in plugins: gene insertion, substitution, deletion, and duplication. - Environment plugins — Implement
ITickPluginto add new environmental processes. Built-in plugins: solar radiation, geysers, and seed energy distribution. - Death handlers — Implement
IDeathHandlerto control what happens when an organism dies (e.g., decay into energy). - Analytics plugins — Extend
AbstractAnalyticsPluginto define custom metrics exported as Parquet. Built-in plugins: population metrics, vital stats, age distribution, genome diversity, and more. - 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.
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.
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.
+---------------------------------------------------------------+
| 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 | |
| +-------------------------------------------------------+ |
+---------------------------------------------------------------+
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.
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
DirectiveHandlerRegistryfor 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.
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 │
└──────────────────┘
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)
└────────────┘ └────────────┘
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) │ │
│ │ │ └───────────────────────────┘ │
│ │ │ │
└──────────────────────────────────┘ └──────────────────────────────────┘
For more details, see the Assembly Specification, Compiler IR Specification, Scientific Overview, and Architecture Decisions.
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 |
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.
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:
- Discord:
- Live Demo: http://evochora.org/
- API Documentation: http://evochora.org/api-docs/
- Key documentation:
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={[Authors]},
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.
Note: Evochora is in active development. Some features described in documentation may be planned but not yet implemented. See the project documentation and roadmap for the current status.