{"id":36955333,"url":"https://github.com/evochora/evochora","last_synced_at":"2026-02-02T01:11:47.690Z","repository":{"id":307484966,"uuid":"1029360690","full_name":"evochora/evochora","owner":"evochora","description":"Evochora: Simulation for foundational artificial life research","archived":false,"fork":false,"pushed_at":"2026-01-10T13:45:22.000Z","size":22223,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T04:15:59.933Z","etag":null,"topics":["alife","artificial-life","digital-life","evolution","java","open-ended-evolution","simulation"],"latest_commit_sha":null,"homepage":"http://evochora.org","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evochora.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-30T23:47:51.000Z","updated_at":"2026-01-10T13:45:25.000Z","dependencies_parsed_at":"2025-08-15T03:19:01.308Z","dependency_job_id":"9b60b593-dc62-45b3-ac42-fa80506cbf38","html_url":"https://github.com/evochora/evochora","commit_stats":null,"previous_names":["rainco77/evochora"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/evochora/evochora","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evochora%2Fevochora","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evochora%2Fevochora/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evochora%2Fevochora/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evochora%2Fevochora/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evochora","download_url":"https://codeload.github.com/evochora/evochora/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evochora%2Fevochora/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28385808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T12:01:30.995Z","status":"ssl_error","status_checked_at":"2026-01-13T12:00:09.625Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alife","artificial-life","digital-life","evolution","java","open-ended-evolution","simulation"],"created_at":"2026-01-13T13:02:51.969Z","updated_at":"2026-02-02T01:11:47.675Z","avatar_url":"https://github.com/evochora.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n  \u003cimg width=\"465\" height=\"74\" alt=\"logo\" src=\"https://github.com/user-attachments/assets/4724aed1-a596-4e03-9c3c-41f791b0babd\" /\u003e\n  \u003cbr\u003e\u003ccode\u003eSimulator for Foundational Artificial Life Research\u003c/code\u003e\n\n  \u003cbr\u003e\u003cbr\u003e\n  **Evochora is a research-oriented artificial life simulator designed to investigate conditions under which emergent and increasing complexity can arise without global culling or task-based rewards**\n\n  \u003ca href=\"http://evochora.org\" style=\"font-size: 1.5em; font-weight: bold; text-decoration: none;\" target=\"_blank\"\u003e👉 SEE LIVE DEMO\u003c/a\u003e\n  \u003cbr\u003e\n  \u003csub\u003eRuns in your browser. No installation required.\u003c/sub\u003e\n\n  \u003cbr\u003e\n\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-2ea44f?style=flat\u0026logo=opensourceinitiative\u0026logoColor=white\" height=\"28\"\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://discord.gg/t9yEJc4MKX\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=flat\u0026logo=discord\u0026logoColor=white\" height=\"28\"\u003e\n  \u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://github.com/evochora/evochora/actions\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/evochora/evochora/build.yml?branch=main\u0026style=flat\u0026logo=github\u0026logoColor=white\u0026label=Build\" height=\"28\"\u003e\n  \u003c/a\u003e\n\n\u003c/div\u003e\n\n\u003cbr\u003e\u003cbr\u003e\n\n\u003c!--\u003cvideo src=\"https://github.com/user-attachments/assets/2dd2163a-6abe-4121-936d-eb46cc314859\" loop\u003e\u003c/video\u003e--\u003e\n\u003cvideo src=\"https://github.com/user-attachments/assets/28c329bc-9554-4b10-8d65-049f00eeda86\" loop\u003e\u003c/video\u003e\n\n\n\n\n\u003cbr\u003e\n\n## What is Evochora?\n\nEvochora is an Artificial Life platform to explore why digital evolution tends to stagnate. It's designed as an evolving research system to identify and overcome complexity hurdles one by one—from stability to mutation tolerance to scaling. The goal is to expand the simulation's capabilities and refine its physical laws to explore what becomes possible next, without assuming where evolution will ultimately lead.\n\nEvochora executes organisms consisting of spatial low-level assembly code directly on a custom virtual machine in an n-dimensional environment. The system already supports a functional primordial organism written in EvoASM, Evochora’s own assembly language, compiled via a multi-pass compiler extensible with plugins.\nThe simulation separates the hot execution path from the cold data processing path, allowing experimental runs to be analyzed efficiently and supporting future horizontal scaling. Evochora’s design contrasts with previous platforms such as Tierra or Avida by embedding organisms in a spatial and energetic environment rather than applying external task-based rewards or global culling.\n\n👉 **[Jump to Quick Start](#quick-start-run-a-simulation)** to run your own simulations\n\u003cbr\u003eor proceed reading for more details and background\n\n\u003cbr\u003e\n\n## Table of Contents\n\n- I. [The \"Boring Billion\" as Inspiration](#i-the-boring-billion-as-inspiration)\n- II. [The Platform](#ii-the-platform)\n  - [Key Features](#key-features)\n  - [Contextualizing Evochora in ALife research (Comparison)](#contextualizing-evochora-in-alife-research)\n  - [Request for Comments \u0026 Collaboration](#request-for-comments--collaboration)\n- III. [System Architecture](#iii-system-architecture)\n  - [Compiler](#compiler)\n  - [Runtime: The Digital Physics of Evochora](#runtime-the-digital-physics-of-evochora)\n  - [Data pipeline](#data-pipeline)\n  - [Web frontends](#web-frontends)\n- IV. [User Guide](#iv-user-guide)\n  - [Quick Start (Run a Simulation)](#quick-start-run-a-simulation)\n  - [Configuration Overview](#configuration-overview)\n  - [Command Line Interface (CLI)](#command-line-interface-cli)\n  - [Development \u0026 Local Build](#development--local-build)\n  - [Contributing](#contributing)\n- [Platform Engineering Roadmap](#platform-engineering-roadmap)\n- [Community \u0026 Links](#community--links)\n\n\u003cbr\u003e\n\n## I. The \"Boring Billion\" as Inspiration\n\nEarth's evolution experienced a \"Boring Billion\"—a long period of slow innovation, likely held back by the energetic limits of prokaryotic life. This parallel is fascinating when looking at Artificial Life. Pioneering platforms like Tierra and Avida often introduce artificial constraints (like global culling or task-based rewards) to ensure population stability. These are effective, but it also introduces a strong, fixed selection pressures that may limit long-term evolvability.\n\nEvochora is an experiment to explore an alternative. What if the primary constraint isn't an external rule, but the physics of the world itself? In Evochora, organisms are fully embodied. They occupy space and underlie thermodynamic constraints. Survival is not a task to be solved, but a constant energetic balancing act.\n\nThis approach appears to be viable, and the results are encouraging:\n* **A Working Primordial:** There is a self-replicating organism (see video) capable of sustaining populations for over 500,000 ticks. It navigates, harvests resources, and copies its 1500-instruction genome without any central oversight or pre-defined rewards.\n\nWith the primordial replicator organism and stable populations secured by implemented thermodynamic constraints now serving as a solid foundation, the platform is ready to tackle deeper questions. The focus shifts from basic survival mechanics to complex evolutionary dynamics. Here are the next frontiers for research:\n\n*   **Pluggable Mutation Models:** While the current system focuses on stability, the next major step is to implement a flexible mutation system as first-class plugins. This aims to allow experiments with different concepts of variation, from simple bit-flips to complex genomic rearrangements, to study their impact on evolvability.\n*   **Evolvability \u0026 Robustness:** We plan to experiment with \"fuzzy jumps\" (targeting code patterns instead of addresses) to understand how genomic resilience can evolve.\n*   **Internal Parallelism (Digital Eukaryogenesis):** The VM allows an organism to `FORK` its execution. With the new molecule marker system enabling signaling, we can now investigate if organisms evolve an internal division of labor—for instance, one thread for metabolism and another for replication. This is a fascinating step towards investigating cellular coordination.\n*   **Emergent Ecosystems \u0026 Niche Construction:** The physics engine is designed to be extensible with reaction chains (e.g., `A + B -\u003e Energy + C`). This creates a testbed for exploring if trophic levels can emerge spontaneously, allowing organisms to alter their environment by creating waste that becomes a resource for others—a process known as Niche Construction.\n\n👉 **[Read the full Scientific Overview](docs/SCIENTIFIC_OVERVIEW.md)** or **[Jump to Quick Start](#quick-start-run-a-simulation)**\n\n\u003cbr\u003e\n\n## II. The Platform\n\n## Key Features\n- **Spatial Worlds**: Configurable grid size and dimensionality (2D to n-D), bounded or toroidal shape containing molecules of different types.\n- **Simulation Core**: The core runs on a flattened `int32` memory grid optimized for CPU cache locality, avoiding Java object overhead.\n- **Embodied Agency**: Organisms must navigate via instruction pointers (IP) and data pointers (DPs) to interact with the molecules in their direct surrounding, and know nothing about the simulation itself.\n- **Compiler Stack**: Includes a custom multi-pass compiler converting high-level and spatial `EvoASM` assembly into raw executable molecules.\n- **Selection Pressure**: Survival requires actively dealing with thermodynamics. Every instruction costs energy and/or creates entropy that organisms need to manage.\n- **Data Pipeline**: The simulation engine is decoupled from data processing to index and analyze raw simulation data (via Protobuf/Queue). The pipeline architecture is designed for horizontal scaling in cloud infrastructure (currently in roadmap).\n- **Web Frontends**: Simulation runs can be visualized and analyzed. The visualizer allows inspection of every simulation step and debugging of internal state and `EvoASM` execution for each organism. The analyzer can visualize population and environment metrics, and a video renderer can render full simulation runs. (all 2D only currently)\n- **Extensibility**: Plugin systems for the simulation, the VM, each compiler pass, and the analyzer allow for customization.\n- **Determinism**: The simulation is deterministic, ensuring experiments are reproducible with a given seed.\n\n\u003cbr\u003e\n\n## Contextualizing Evochora in ALife Research\n\nEvochora builds on the legacy of seminal Artificial Life platforms. This comparison highlights the different scientific questions and design trade-offs each system explores, positioning Evochora's focus on embodied agents and extensible physics.\n\n| Feature / Aspect | Tierra (Ray, 1991) | Avida (Ofria et al., 2004) | Lenia (Chan, 2019) | Evochora |\n| :--- | :--- | :--- | :--- | :--- |\n| **Core Concept** | Self-replicating code in linear RAM (\"Soup\") | Agents solving logic tasks in 2D grid | Continuous cellular automata (Math-Biology) | Embodied agents in n-Dimensional space |\n| **Physics / Environment** | CPU cycles \u0026 memory access (Fixed) | Rewards for logical tasks (NOT, AND) (Fixed) | Differential equations (flow, kernel) (Fixed) | Extensible via Plugins (e.g., Energy; Planned: Mutation) |\n| **Organism Body** | Disembodied (Code string only) | Disembodied (CPU + Memory buffer) | Morphological patterns (solitons) | Embodied (IP + DPs navigating spatial grid) |\n| **Interaction Model** | Parasitism (reading neighbor's RAM) | Limited (mostly competition for space) | Collision, fusion \u0026 repulsion of patterns | Direct \u0026 Spatial (via DPs); Planned: Signaling |\n| **Evolutionary Driver** | Implicit competition for memory/CPU | Directed (user-defined rewards) | Spontaneous pattern formation | Metabolic \u0026 spatial constraints |\n| **Execution Model** | Sequential (Single IP) | Sequential (Single IP) | Parallel (Continuous dynamics) | Parallel (Planned: Multi-threaded via FORK) |\n| **Primary Research Focus** | Ecology of code \u0026 parasites | Evolution of complex logic functions | Self-organizing morphology | Bioenergetics \u0026 Major Transitions |\n\n\u003cbr\u003e\n\n## Looking for Contributors\n\nEvochora is an open-source project and thrives on collaboration. The goal is to build a shared, flexible tool for the ALife community. We are looking for Systems Engineers and ALife Researchers to help design and implement the next wave of features. This is a great opportunity to shape the core physics of a digital world.\n\nSome of the open challenges we're currently thinking about are:\n\n- **Evolution of Evolvability (Mutation Models):** How do different mutation regimes (e.g., bit-flips vs. genomic rearrangements) affect the long-term potential for complexity? We need to build a flexible plugin system to test this.\n- **Fuzzy Addressing (SignalGP):** Can we move from absolute memory addresses to pattern-matching jumps to make the genome more resilient to mutation?\n- **Signaling \u0026 Concurrency:** How can organisms utilize multiple execution contexts (via FORK) and internal signaling to evolve more complex behaviors (Digital Eukaryogenesis)?\n\nThis is just a starting point, and we're open to new ideas.\n👉 **For a deeper dive, check out the [OPEN_RESEARCH_QUESTIONS.md](docs/OPEN_RESEARCH_QUESTIONS.md)**\n\n\u003cbr\u003e\n\n## III. System Architecture\n\nThe system is designed as a modular stack to serve as a flexible testbed for evolutionary experiments. Its architecture emphasizes clear separation of concerns and extensibility across all layers:\n\n- **Compiler**  \n  Translates EvoASM into VM instructions and layouts via an immutable phase pipeline (preprocessor, parser, semantic analyzer, IR generator, layout engine, and emitter).\n\n- **Runtime / Virtual Machine**  \n  Each organism is an independent VM with its own registers, stacks, and pointers in an n-dimensional world of typed Molecules (CODE, DATA, ENERGY, STRUCTURE).  \n  Strong locality and an energy-first design create intrinsic selection pressure.\n\n- **Data Pipeline**  \n  Simulation Engine → queue → Persistence Service → storage → Indexer → queryable indexes for debugging and analysis.\n\n- **Node \u0026 HTTP API**  \n  Orchestrates services and resources, exposes REST endpoints (e.g. `/api/pipeline/...`) and powers the web-based visualizer.\n\n\u003cbr\u003e\n\n### Compiler\n\nThe Evochora compiler is a multi-pass pipeline that transforms human-readable EvoASM assembly code into a `ProgramArtifact` ready for execution. This design ensures determinism and separates concerns into a frontend (parsing and analysis) and a backend (layout and code generation). Most phases are extensible via handler registries, allowing new features to be added in a modular way.\n\n#### Compiler Frontend\nThe frontend parses the source code and transforms it into a machine-independent Intermediate Representation (IR).\n\n1.  **Preprocessor**: Handles macros (`#macro`) and file inclusions (`#include`).\n2.  **Parser**: Converts tokens into an Abstract Syntax Tree (AST). Extensible via `DirectiveHandlerRegistry` for new directives.\n3.  **Semantic Analyzer**: Validates the AST, checks types, and builds a symbol table.\n4.  **IR Generator**: Converts the AST into an Intermediate Representation (IR). Extensible via `IrConverterRegistry`.\n\n#### Compiler Backend\nThe backend takes the IR and generates the final, executable `ProgramArtifact`.\n\n5.  **Layout Engine**: Determines the final spatial coordinates of all molecules. Extensible via `LayoutDirectiveRegistry`.\n6.  **Linker**: Resolves symbolic references (e.g., labels). Extensible via `LinkingRegistry`.\n7.  **Emitter**: Generates the final binary machine code. Extensible via `EmissionRegistry`.\n\n```text\n ┌──────────────────┐\n │   EvoASM File    │\n └────────┬─────────┘\n          │\n          ▼\n ┌──────────────────┐\n │  Preprocessor    │\n └────────┬─────────┘\n          │ (Token Stream)\n          ▼\n ┌──────────────────┐\n │      Parser      │\n └────────┬─────────┘\n          │ (AST)\n          ▼\n ┌──────────────────┐\n │ Semantic Analyzer│\n └────────┬─────────┘\n          │ (Validated AST)\n          ▼\n ┌──────────────────┐\n │   IR Generator   │\n └────────┬─────────┘\n          │ (IR)\n          ▼\n ┌──────────────────┐\n │   Layout Engine  │\n └────────┬─────────┘\n          │ (Placed IR)\n          ▼\n ┌──────────────────┐\n │      Linker      │\n └────────┬─────────┘\n          │ (Linked IR)\n          ▼\n ┌──────────────────┐\n │     Emitter      │\n └────────┬─────────┘\n          │\n          ▼\n ┌──────────────────┐\n │ Program Artifact │\n └──────────────────┘\n```\n\nFor more details on the assembly language and the compiler's internal representation, see:\u003cbr\u003e\n👉 **[Evochora Assembly: Language Reference](docs/ASSEMBLY_SPEC.md)**\u003cbr\u003e\n👉 **[Compiler Intermediate Representation (IR) Specification](docs/COMPILER_IR_SPEC.md)**\n\n\u003cbr\u003e\n\n### Runtime: The Digital Physics of Evochora\n\nThe Runtime implements the simulation environment and its physical laws. It enforces spatial embodiment and thermodynamic constraints within the n-dimensional grid. \n\n#### Conceptual Architecture of an Evochora Organism\n         +---------------------------------------------------------------+\n         |                 Evochora \"World\" (n-D Grid)                   |\n         |                                                               |\n         |   [ ENERGY ]      [ STRUCTURE ]      [ CODE ]      [ DATA ]   |\n         +-------^-----------------^----------------^-------------^------+\n                 |                 |                |             |\n    Interaction: |                 |                |             |\n             (HARVEST)          (BLOCK)         (EXECUTE)      (READ)\n                 |                 |                |             |\n                 |                 |                |             |\n         +-------|-----------------|----------------|-------------|------+\n         |       |    ORGANISM     |                |             |      |\n         |       |                 |                |             |      |\n         |   +---v-----------------v----+      +----v-------------v----+ |\n         |   |    Data Pointers (DPs)   |      |   Inst. Pointer (IP)  | |\n         |   | [DP 0] [DP 1] ... [DP n] |\u003c-----|                       | |\n         |   +--------------------------+      +-----------------------+ |\n         |                 ^                                  ^          |\n         |         (Move/Read/Write)                      (Control)      |\n         |                 |                                  |          |\n         |   +-------------v----------------------------------v------+   |\n         |   |                  Virtual Machine                      |   |\n         |   |                                                       |   |\n         |   |  Registers: [DRs] [PRs] [FPRs] [LRs] (Locations)      |   |\n         |   |                                                       |   |\n         |   |  Stacks:    [Data Stack] [Call Stack] [Loc. Stack]    |   |\n         |   |                                                       |   |\n         |   |  Metabolism: [Thermodyamics (ER/SR)] --(Cost)--\u003e 0    |   |\n         |   +-------------------------------------------------------+   |\n         +---------------------------------------------------------------+\n\n👉 **See Assembly specification:** [EvoASM Reference](docs/ASSEMBLY_SPEC.md) for more details\n\n\u003cbr\u003e\n\n### Data pipeline\n\n```\n┌────────────────────────────┐\n│      SimulationEngine      │\n└─────────────┬──────────────┘\n              │ (TickData)\n              ▼\n┌────────────────────────────┐\n│        Tick Queue          │\n└─────────────┬──────────────┘\n              │ (Batches)\n              ▼\n┌────────────────────────────┐\n│    Persistence Service     │ (Competing Consumers)\n└─┬─────────────────────┬────┘\n  │ (Data)       (BatchInfo Event)\n  │                     │\n  ▼                     ▼\n┌───────────┐    ┌───────────┐\n│  Storage  │    │  Topics   │\n└─────┬─────┘    └──────┬────┘\n      │ (Reads)    (Triggers)\n      │                 │\n      └────────┬────────┘\n               │\n               ▼\n┌────────────────────────────┐\n│      Indexer Services      │ (Competing Consumer Groups)\n└─────────────┬──────────────┘\n              │ (Indexed Data)\n              ▼\n┌────────────────────────────┐\n│          Database          │\n└─────┬───────────────┬──────┘\n      │               │ (Queries)\n      ▼               ▼\n┌────────────┐  ┌────────────┐\n│ Visualizer │  │  Analyzer  │ (Web based)\n└────────────┘  └────────────┘\n```\n\nEvery service in this diagram can be deployed in Docker or a dedicated machine. The communication resources between the services (queue, storage, database, etc.) use implementation-abstract interfaces and can be easily implemented as cloud resources. As this is still in development, we still see this as a roadmap topic.\n\n\u003cbr\u003e\n\n### Web frontends\n\nEvochora includes two web-based frontends for interacting with the simulation data: the **Visualizer** and the **Analyzer**. Both are built with modern vanilla JavaScript to enable direct API interaction without heavy frameworks.\n\nThe backend is powered by a lightweight Javalin HTTP server. Backend `Controller` classes register API endpoints (e.g., `/api/visualizer/...`) that are called by the frontend. These controllers, in turn, interact with backend services like the `ServiceRegistry` to fetch simulation data.\n\n-   **Visualizer**: Provides a high-fidelity, tick-by-tick view of the simulation. It allows you to step through time, inspect the state of individual organisms (registers, stacks), and debug the execution of their EvoASM code live in the browser.\n-   **Analyzer**: Offers a high-level overview of simulation metrics over the entire run. It features a pluggable interface for adding new metrics and visualizations. For maximum flexibility, the Analyzer can perform range requests on Parquet files served by the backend, enabling custom queries and analysis directly in the browser using DuckDB-WASM.\n\nThe following diagram shows which frontend components communicate with which backend controllers:\n\n```text\n       Browser (JavaScript Apps)                       Node (Java Backend)\n  ┌──────────────────────────────────┐         ┌──────────────────────────────────┐\n  │                                  │         │                                  │\n  │  ┌───────────────────────────┐   │         │  ┌───────────────────────────┐   │\n  │  │      Visualizer App       │   │         │  │ Visualizer Controllers    │   │\n  │  │---------------------------│   │         │  │ - EnvironmentController   │   │\n  │  │ - EnvironmentApi.js       │───┼───HTTP──┼─►│ - OrganismController      │   │\n  │  │ - OrganismApi.js          │   │         │  │ - SimulationController    │   │\n  │  │ - SimulationApi.js        │   │         │  └───────────────────────────┘   │\n  │  └───────────────────────────┘   │         │                                  │\n  │                                  │         │                                  │\n  │  ┌───────────────────────────┐   │         │                                  │\n  │  │       Analyzer App        │   │         │                                  │\n  │  │---------------------------│   │         │  ┌───────────────────────────┐   │\n  │  │ - AnalyticsApi.js         │───┼───HTTP──┼─►│    AnalyticsController    │   │\n  │  │ - DuckDBClient.js (WASM)  │   │         │  └───────────────────────────┘   │\n  │  └───────────────────────────┘   │         │                                  │\n  │                                  │         │  ┌───────────────────────────┐   │\n  │                                  │         │  │     PipelineController    │   │\n  │      (Admin Tools/Scripts)   ────┼───HTTP──┼─►│ (For pipeline management) │   │\n  │                                  │         │  └───────────────────────────┘   │\n  │                                  │         │                                  │\n  └──────────────────────────────────┘         └──────────────────────────────────┘\n```\n👉 **[Full HTTP API Reference](http://evochora.org/api-docs/)**\n\n\n\u003cbr\u003e\n\n## IV. User Guide\n\n### Quick Start (Run a Simulation)\n\n### Requirements\n- Java 21 (JRE or JDK)\n\n### Start the Simulation Node\nDownload and unpack the latest distribution from the [GitHub Releases page](https://github.com/evochora/evochora/releases).\n\n```bash\ncd evochora-\u003cversion\u003e\nbin/evochora node run\n```\n\nThis will:\n\n- Load configuration from [`config/evochora.conf`](./evochora.conf).\n- Start the in-process simulation node (simulation engine, persistence, indexer, HTTP server)\n- Run until you terminate it (Ctrl + C)\n\n**Note on Resources:** By default, Evochora records telemetry for every tick to allow perfect replay.\n\n*   **Storage:** Ensure sufficient disk space for long-running experiments or adjust the configuration to reduce logging frequency.\n*   **Memory:** Running all services in a single process (default mode) requires significant heap memory (8GB+ recommended). The system estimates requirements at startup and warns if the allocated heap is insufficient.\n\n#### Open the Web UI\n\nOnce the node is running, it will by default execute the primordial organism defined in [`assembly/primordial/main.evo`](./assembly/primordial/main.evo) as configured in [`config/evochora.conf`](./evochora.conf).  \n\nOpen the web frontend in your browser:\n`http://localhost:8081/visualizer/`\n\n\u003cbr\u003e\n\n\n### Usage Modes\n\nEvochora supports multiple usage and deployment modes:\n\n- **In-Process Mode (current default)**  \n  All core components (Simulation Engine, Persistence Service, Indexer, HTTP server) run in a single process or container.  \n  Best for local experiments, quick iteration, and single-machine runs.\n\n- **Planned Distributed Cloud Mode**  \n  Each service (Simulation Engine, Persistence, Indexer, HTTP server, etc.) runs in its own container or process and can be scaled horizontally. Intended for large-scale, long-duration experiments and cloud deployments.\n\nThe current releases focus on the in-process mode; the distributed mode is part of the roadmap.\n\n\u003cbr\u003e\n\n### Configuration Overview\n\nEvochora is configured via a HOCON configuration file, typically named [`config/evochora.conf`](./evochora.conf).\n\nA complete example configuration is provided as [`config/evochora.conf`](./evochora.conf) in the repository and included in the distribution.\n\n### Writing Your Own Organisms\n\nOrganisms are programmed in **EvoASM**, Evochora's custom assembly language. The primordial organism in `assembly/primordial/main.evo` is a good starting point.\n\n**Quick Start:**\n1. Edit or create a `.evo` file in `assembly/`\n2. Configure it in `evochora.conf` (see `simulation-engine.options.organisms`)\n3. Run `bin/evochora node run` - the engine compiles automatically\n\n**Resources:**\n- **Language Reference:** [docs/ASSEMBLY_SPEC.md](docs/ASSEMBLY_SPEC.md)\n- **Syntax Highlighting:** VS Code/Cursor extension in [`extensions/vscode/`](extensions/vscode/README.md)\n\n### Command Line Interface (CLI)\n\nThe Evochora CLI is the main entry point for running simulations and tools.\n\n**Main commands:**\n\n- `node` – Run and control the simulation node (pipeline, services, HTTP API)\n- `compile` – Compile EvoASM (Evochora Assembly) programs for the Evochora VM\n- `inspect` – Inspect stored simulation data (ticks, runs, resources)\n- `video` – Render simulation runs into videos (requires `ffmpeg`)\n\nFurther CLI documentation and fully worked examples:\n\n👉 **[CLI Usage Guide](docs/CLI_USAGE.md)** – All commands, parameters, and usage examples (including `node`, `compile`, `inspect`, and `video`).\n\n\u003cbr\u003e\n\n### Development \u0026 Local Build\n\nIf you want to develop Evochora itself:\n\n```bash\n# Clone the repository\ngit clone https://github.com/evochora/evochora.git\ncd evochora\n\n# Build \u0026 test\n./gradlew build\n\n# Run the node in dev mode (uses ./evochora.conf by default)\n./gradlew run --args=\"node run\"\n```\n\nOpen the web frontend in your browser:\n`http://localhost:8081/visualizer/`\n\nSee also:\n\n👉  [`CONTRIBUTING.md`](./CONTRIBUTING.md) – Contribution workflow and expectations.\u003cbr\u003e\n👉  [`AGENTS.md`](./AGENTS.md) – Coding conventions, architecture and compiler/runtime design principles, testing rules.\n\n\u003cbr\u003e\n\n### Contributing\n\nWe welcome contributions of all kinds:\n\n- Scientific discussion about the \"laws\" of the digital universe\n- Code contributions (VM, compiler, data pipeline, analysis tools, web visualizer)\n- Experiment design and benchmark scenarios\n- Documentation, tutorials, and examples\n- Testing\n\nBasic contribution workflow:\n\n1. Fork the repository\n2. Create a feature branch (e.g. `git checkout -b feature/amazing-feature`)\n3. Follow the style and guidelines in `AGENTS.md`\n4. Add tests where appropriate\n5. Open a Pull Request with a clear description and rationale\n\n\u003cbr\u003e\n\n## Platform Engineering Roadmap\n\nSome key directions for the technical evolution of Evochora:\n\n- **Distributed Cloud Mode** – Run Simulation Engine, Persistence Service, Indexer, HTTP server, etc. as separate processes/containers with horizontal scaling for large experiments.\n- **Multithreaded Simulation Engine** – Parallelize the plan/resolve/execute phases across CPU cores to support larger worlds and more organisms on a single machine.\n- **Pluggable Mutation System** – Make mutation models first-class plugins (e.g., replication errors, background radiation, genomic rearrangements) to study their impact on open-ended evolution.\n- **Extended Data Pipeline \u0026 Resume Support** – More scalable, cloud-native persistence and indexing with the ability to resume simulations from stored states.\n\n👉 **Project Board \u0026 Roadmap:** [GitHub Projects](https://github.com/orgs/evochora/projects/1/views/1)\n\n\u003cbr\u003e\n\n---\n\n## Community \u0026 Links\n\n- Discord (Community Chat):  \n  [![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=flat-square\u0026logo=discord)](https://discord.gg/t9yEJc4MKX)\n\n- Live Visualizer Demo:  \n  http://evochora.org/\n\n- API Documentation (developer-focused):  \n  http://evochora.org/api-docs/\n\n- Key documentation in this repository:\n    - [Scientific Overview](docs/SCIENTIFIC_OVERVIEW.md)\n    - [CLI Usage Guide](docs/CLI_USAGE.md)\n    - [Assembly Specification](docs/ASSEMBLY_SPEC.md) (EvoASM – Evochora Assembly)\n    - [Architecture \u0026 Design Decisions](docs/ARCHITECTURE_DECISIONS.md) (Why Java? Why Custom Assembly? Why Microservices?)\n\n\u003cbr\u003e\n\n---\n\n_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._\n\n\n## Logo\n\n```text\n  ■■■■■  ■   ■   ■■■    ■■■   ■   ■   ■■■   ■■■■     ■  \n  ■      ■   ■  ■   ■  ■   ■  ■   ■  ■   ■  ■   ■   ■ ■ \n  ■      ■   ■  ■   ■  ■      ■   ■  ■   ■  ■   ■  ■   ■\n  ■■■■    ■ ■   ■   ■  ■      ■■■■■  ■   ■  ■■■■   ■   ■\n  ■       ■ ■   ■   ■  ■      ■   ■  ■   ■  ■ ■    ■■■■■\n  ■       ■ ■   ■   ■  ■   ■  ■   ■  ■   ■  ■  ■   ■   ■\n  ■■■■■    ■     ■■■    ■■■   ■   ■   ■■■   ■   ■  ■   ■\n```\n---\n\n## License \u0026 Citation\n\nEvochora is open-source and available under the **MIT License** (see [`LICENSE`](./LICENSE)).\n\nIf you use Evochora in your research, please cite:\n\n```bibtex\n@article{evochora2025,\n  title={Evochora: A Collaborative Platform for Research into the Foundational Physics of Digital Evolution},\n  author={[Authors]},\n  journal={[Journal]},\n  year={2025},\n  note={In preparation}\n}\n```\n\n---\n\n**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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevochora%2Fevochora","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevochora%2Fevochora","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevochora%2Fevochora/lists"}