Archetype ECS

A high-performance, strictly-typed, archetype-based Entity Component System for Rust.

Archetype ECS is what happens when you take ECS seriously, strip out the "game engine" bloat, and focus on raw performance. It's the ECS equivalent of a sports car - fast, focused, and doesn't come with cup holders.

What This Is (Probably)

Archetype ECS is a prototype ECS library for Rust game engines. It follows Unix philosophy (does one thing, hopefully well) and provides the ECS components you'd need to integrate into a larger engine.

Fair Warning: This is a library component, not a complete solution. You'll need to bring your own rendering, materials, lighting, and scene management. Think of it as an engine block for your car - it works, but you can't drive it alone.

Core Concepts

What It Does

✅ High Performance: Cache-friendly archetype storage with SoA (Structure of Arrays) layout ✅ Parallel Execution: Automatic multi-threaded system scheduling with dependency resolution ✅ Reactive Queries: Efficient Changed<T> and Added<T> filters for change detection ✅ Hierarchy System: First-class parent-child relationships with transform propagation ✅ Serialization: Built-in JSON serialization for entities, components, and worlds ✅ Hot Reload: System hot-reloading for development workflow (Code) ✅ Profiling: Integrated tracing instrumentation for performance analysis ✅ Error Types: Asset loading error types for your asset manager

What It Doesn't Do

❌ Rendering (but works perfectly with ash_renderer) ❌ Physics (but integrates seamlessly with particle_accelerator) ❌ Asset Management (we intentionally separate data from logic) ❌ Materials/Lighting (that's your renderer's job)

Integration Examples

With particle_accelerator (Physics)

use archetype_ecs::prelude::*;
use particle_accelerator::{PhysicsWorld, RigidBody, Collider};

fn setup_physics_world() -> Result<()> {
    let mut world = World::new();
    let mut physics = PhysicsWorld::new();
    
    // Spawn physics entities
    let ball = world.spawn_entity((
        Position { x: 0.0, y: 10.0, z: 0.0 },
        Velocity { x: 5.0, y: 0.0, z: 0.0 },
        RigidBody::dynamic(),
        Collider::sphere(1.0),
    ));
    
    // Physics system integration
    physics.update(&mut world, 0.016)?;
    
    Ok(())
}

With archetype_assets (Asset Management)

use archetype_ecs::prelude::*;
use archetype_assets::{AssetManager, Handle};

fn setup_assets() -> Result<()> {
    let mut world = World::new();
    let mut assets = AssetManager::new();
    
    // Load assets
    let texture_handle = assets.load::<Texture>("player.png")?;
    let mesh_handle = assets.load::<Mesh>("player.obj")?;
    
    // Store asset manager in world
    world.insert_resource(assets);
    
    // Spawn entity with asset handles
    let player = world.spawn_entity((
        Position::default(),
        MeshComponent { handle: mesh_handle },
        TextureComponent { handle: texture_handle },
    ));
    
    Ok(())
}

Quick Start

Installation

[dependencies]
archetype_ecs = "1.2.0"
glam = "0.30"            # Required for transform types

1. Basic ECS Usage (The Foundation)

use archetype_ecs::prelude::*;

fn main() -> Result<()> {
    let mut world = World::new();
    
    // Spawn some entities
    let player = world.spawn_entity((
        Position { x: 0.0, y: 0.0 },
        Velocity { x: 1.0, y: 0.0 },
    ));
    
    // Query and update
    for (pos, vel) in world.query_mut::<(&mut Position, &Velocity)>() {
        pos.x += vel.x;
        pos.y += vel.y;
    }
    
    Ok(())
}

2. Systems & Hot Reloading (The Real Deal)

We support hot-reloading of systems using the hot_reload module. This allows you to iterate on game logic without restarting the application.

use archetype_ecs::prelude::*;

struct MovementSystem;

impl System for MovementSystem {
    fn name(&self) -> &'static str { "Movement" }
    
    fn access(&self) -> SystemAccess {
        SystemAccess::new()
            .read::<Velocity>()
            .write::<Position>()
    }
    
    fn run(&mut self, world: &mut World) -> Result<()> {
        for (pos, vel) in world.query_mut::<(&mut Position, &Velocity)>() {
            pos.x += vel.x * 0.016; // 60 FPS dt
        }
        Ok(())
    }
}

Performance

Archetype ECS is designed for speed because slow ECS libraries are sad ECS libraries.

• Iteration: Linear memory access pattern allows efficient prefetching. Your CPU will thank you.
• Change Detection: Bitset-based filtering makes reactive systems negligible in cost.
• Fragmentation: Archetype moves can be expensive; we recommend using distinct components for distinct states (e.g. Walking vs Flying).

(Benchmarks running on Intel Core i5-11400f, 100k entities)

• Simple Iteration: ~1-2ns / entity (very fast)
• Composed Query: ~2-3ns / entity (still fast)
• Parallel Dispatch: Scales linearly with cores for disjoint data

Known Limitations (Being Honest)

What We Don't Do (Because We're Focused)

• ❌ Rendering (use ash_renderer, wgpu, or your own solution)
• ❌ Materials/Lighting (that's your engine's job, not ours)
• ❌ Asset loading (we provide error types, you bring the loader; see archetype_assets)
• ❌ Code generation (we prefer explicit typed code over macro magic)

Current Limitations

• Archetype Moves: Adding/removing components moves entities between arrays. This is O(N) for the components being moved.
• No Built-in Networking: We focus on single-machine performance.
• Serialization: JSON support is MVP. Binary serialization is planned.

Troubleshooting

"My entities aren't spawning!"

Check:

• Are you using spawn_entity() instead of the deprecated spawn()?
• Did you remember to import the prelude?
• Is your Bundle implementation correct?

"My queries aren't finding anything!"

Check:

• Did you actually spawn entities with those components?
• Are you using the right query type (query vs query_mut)?
• Did you despawn the entities and forget to flush removals?

Contributing

Contributions are welcome. I appreciate:

• Clean code (clippy is your friend)
• Performance justifications ("It's faster" -> Show me the benchmark)
• Honest PR descriptions

License

Apache-2.0. Because nobody likes monsters.

Acknowledgments

This library wouldn't exist without:

• The Rust gamedev community (for putting up with ECS experimentation)
• glam (for making math not painful)
• serde (for making serialization not a nightmare)