Crate wunderkammer 

Wunderkammer

An experimental EC(S) crate.

Provides a simple Entity-Component structure, meant for small scoped data oriented games (eg. roguelikes).

It aims to solve the most basic requirements of a component storage:

• flexible object composition
• querying for entities with a certain component set attached and processing their data

The crate is merely a storage data structure and does not enforce any specific game architecture. It is meant to also work in a traditional game loop context.

Relies completely on static typing and compile time checks, while still allowing for runtime insertion and removal of components.

No unsafe code, internal mutability (like RefCell) or dynamic typing is used. It won’t crash on you if you’ll try to borrow a component set mutably twice :)

The internal component storage is based on sparse set data structures, rather then archetypes. It should still provide some level of cache locality - the component data is held in continuous vector types.

Crate goals

• Simple but flexible data storage for tiny games
• Reliability through compile-time checks and static typing
• Dynamic component insertion and removal
• Recycling of despawned entities
• Easy (de)serialization - via optional serialize feature
• As few dependencies as possible (currently only syn and quote libs to handle derive macros, + serde behind a feature flag)

Example usage

use wunderkammer::prelude::*;

#[derive(ComponentSet, Default)]
struct Components {
    pub health: ComponentStorage<u32>,
    pub name: ComponentStorage<String>,
    pub player: ComponentStorage<()>, // marker component
    pub poison: ComponentStorage<()>,
    pub strength: ComponentStorage<u32>,
}

#[derive(Default)]
struct Resources {
    current_level: u32,
}

type World = WorldStorage<Components, Resources>;

fn main() {
        let mut world = World::default();

        // spawn player
        let player = world.spawn();
        world.components.health.insert(player, 5);
        world.components.name.insert(player, "Player".to_string());
        world.components.player.insert(player, ());
        world.components.strength.insert(player, 3);

        // spawn npcs
        let rat = world.spawn();
        world.components.health.insert(rat, 2);
        world.components.name.insert(rat, "Rat".to_string());
        world.components.strength.insert(rat, 1);

        let serpent = world.spawn();
        world.components.health.insert(serpent, 3);
        world.components.name.insert(serpent, "Serpent".to_string());
        world.components.strength.insert(serpent, 2);

        // find all npc entities, returns HashSet<Entity>
        let npcs = query!(world, Without(player), With(health));
        assert_eq!(npcs.len(), 2);

        // poison the player and the serpent
        world.components.poison.insert(player, ());
        world.components.poison.insert(serpent, ());

        // apply poison damage
        query_execute_mut!(world, With(health, poison), |_, h: &mut u32, _| {
            *h = h.saturating_sub(1);
        });

        assert_eq!(world.components.health.get(player), Some(&4));
        assert_eq!(world.components.health.get(rat), Some(&2));
        assert_eq!(world.components.health.get(serpent), Some(&2));

        // heal player from poison
        let _ = world.components.poison.remove(player);
        let poisoned = query!(world, With(poison));
        assert_eq!(poisoned.len(), 1);

        // use resource
        world.resources.current_level += 1;
    }

Modules

prelude

Macros

query

Base query that extracts matching entities from the World struct.

query_execute

Helper query that allows to execute a given closure on each matching entity and it’s components.

query_execute_mut

Helper query that allows to execute a mutating closure on each matching entity and it’s components.

query_iter

Query returning and immutable iterator over matching entities with their components.