DOCSEARCHbyAlgolia
Submit Docs

Ark ECS

repository·main·Indexed 43 days ago

https://github.com/mlange-42/ark

A high-performance, archetype-based Entity Component System (ECS) for Go. It features a type-safe API, zero dependencies, and a query-based architecture designed for game engines and simulations. Key capabilities include entity relationships, an extensible event system, and world serialization via the ark-serde package.

Tokens
16.3K
Snippets
44
Records
90
Agent score
55%

What's inside Ark

  1. What is Ark?

    main
    Ark is an archetype-based Entity Component System (ECS) for Go. It is designed for high performance and provides a type-safe API for managing entities and components. Unlike many ECS frameworks, Ark does not enforce a 'systems' architecture; instead, it focuses on providing powerful queries, allowing developers to use their own structures or provided tools to drive logic.

  2. Understand Ark's core API and design philosophy

    main

    Ark is an Entity Component System (ECS) designed primarily for scientific, individual-based models, though it is also suitable for game development. Its core is the World object, which acts as a data store for entities and components.

    Key design principles include:

    • Simplicity & Type-Safety: Uses Go generics to provide a fully type-safe API for queries and component manipulation. This ensures compile-time safety and avoids the performance overhead of reflection.
    • Performance: Uses archetype-based storage for cache-friendly memory layouts and supports batch operations.
    • Determinism: Guarantees that identical operations on the same World will always produce the same iteration sequence, ensuring reproducible simulations.
    • Safety: Ark prioritizes strict behavior over silent failures. It will panic on violations such as removing a dead entity, adding a duplicate component, or attempting to modify a locked world.
    • Minimalism: Ark does not include a built-in update loop or systems; these are implemented by the user to provide maximum control.

  3. Ark Key Features

    main

    Ark provides several core capabilities for building game engines or simulations in Go:

    • Performance: Highly optimized archetype-based architecture (see Benchmarks for details).
    • Type-Safe API: Well-documented and type-safe interfaces.
    • Entity Relationships: Supported as a first-class feature.
    • Extensible Event System: Includes filtering and support for custom event types.
    • Batch Operations: Fast operations for mass manipulation of entities.
    • Query-Centric: No mandatory 'systems' requirement; logic is driven via queries.
    • Serialization: Supports world serialization and deserialization via the ark-serde package.
    • Zero Dependencies: The core library has no external dependencies.

  4. Explore Ark example patterns

    main

    The examples directory contains several implementations demonstrating core Ark features and integration patterns:

    • Minimal Setup: readme provides the simplest possible usage pattern.
    • Entity Relationships: relations shows how to manage connections between entities.
    • Event Systems: events and custom_events demonstrate built-in and user-defined event types.
    • Concurrency & Locking: world_lock shows how to manipulate entities while the world is locked during query iteration; parallel_queries demonstrates parallel query execution; parallel_runs shows how to run multiple simulations in parallel.
    • Systems & Scheduling: systems demonstrates implementing systems and a scheduler.
    • Hybrid Data Structures: entity_grid and kdtree show how to mix ECS with non-ECS structures like grids or k-d trees.
    • Engine Integration: ebitengine demonstrates using Ark with the Ebiten game engine.

  5. Understand the Array of Structs (AoS) benchmarks

    main
    The benchmark/aos directory contains the source code used to generate the performance comparison plots between Ark's data layout and the standard Array of Structs (AoS) pattern. These benchmarks are specifically used to illustrate the performance characteristics discussed in the Filters & queries section of the user guide.

  6. Explore external tools for Ark

    main

    Ark has a growing ecosystem of external tools designed to extend its functionality. Key tools include:

    • ark-serde: Handles JSON serialization and deserialization for Ark's World.
    • ark-tools: Provides essential ECS components like systems and a scheduler.
    • ark-pixel: Integrates OpenGL graphics and live plotting using the Pixel game engine.

  7. Available Ark ecosystem tools

    main

    Ark provides several companion tools for extended functionality:

    • ark-serde: Provides JSON serialization and deserialization for an Ark World.
    • ark-tools: Provides systems, a scheduler, and other utility structures for Ark.
    • ark-pixel: Provides OpenGL graphics and live plots via the Pixel game engine.

  8. Performance trade-offs of archetype-based ECS

    main

    While archetypes optimize for fast iteration, they introduce costs when modifying an entity's composition.

    The Cost of Mutation

    • Component Changes: Adding or removing a component requires relocating the entity to a different archetype. This involves moving all existing component data for that entity, costing approximately 20ns per involved component.

    Optimization Strategies

    • Batch Mutations: To minimize relocation costs, add, remove, or exchange multiple components simultaneously rather than performing individual operations sequentially.
    • Batch Commands: Use batching to manipulate many entities in a single command to improve efficiency.

  9. Use component mappers to manage entity components

    main

    Ark provides component mappers (such as Map1, Map2, etc.) as helpers to create entities with specific components, add components to existing entities, or remove components from them.

    Because of Go's generic limitations, mappers are parameterized by the number of components they handle (e.g., NewMap2 handles two components). For managing a single component type, use the dedicated Map mapper, which provides additional specialized methods.

    // Example usage of a mapper (conceptual based on documentation)
// NewMap2 denotes a mapper for 2 components
mapper := ecs.NewMap2[ComponentA, ComponentB]()
entity := mapper.Create(world, compA, compB)
// ...
mapper.Add(world, entity, compA)
mapper.Remove(world, entity, compB)

  10. When to use entity relations vs. standard components

    main

    Choosing between Ark's first-class relations and manual component storage (e.g., storing a slice of entities in a struct) depends on your data distribution:

    Use Entity Relations when:

    • You have a moderate number of relation targets.
    • There are many entities per target (e.g., many animals in one farm).
    • You want to use efficient queries to find all entities related to a specific target.
    • You need to represent abstract categories (e.g., factions, render layers, or FSM states) as entities.

    Use Standard Components (e.g., []ecs.Entity) when:

    • You have a very high number of target entities (tens of thousands).
    • You have 1:1 relationships (storing the target entity directly in a component is more efficient).

  11. How the archetype graph accelerates component changes

    main

    Ark uses a dynamic archetype graph to quickly find the new archetype when components are added or removed.

    Graph Mechanics

    • Nodes and Transitions: Nodes represent archetypes. Arrows (transitions) represent adding (solid head) or removing (empty head) a single component.
    • Search Algorithm: When an entity's composition changes, the system follows existing transitions in the graph. If a transition doesn't exist, it searches through nodes using the component mask and creates new nodes/connections on demand.
    • Performance: Transitions are stored within nodes using a lookup mechanism that is approximately 10x faster than a standard Go map. The graph typically stabilizes quickly during a simulation run.

  12. Archetype and table recycling for relations

    main

    Ark manages memory for relation-based archetypes through specialized recycling:

    • Relation Tables: Unlike standard archetype tables, sub-tables created for relation targets can be recycled.
    • Recycling Process: When a target entity dies, its associated sub-table is deactivated. The memory for entities and components is retained.
    • Reuse: If a new request is made for a table in the same archetype for a different target entity, Ark reuses a recycled table if one is available.
    • Tracking: Ark uses a bitset to efficiently track which entities are currently targets of a relation to determine if a table can be safely removed.