Jomy10/kiwi-ecs

A performant, small and versatile entity component system written in Rust

A performant, zero-dependency ECS library with a nice API written in Rust.

Usage

# Cargo.toml

[dependecies]
kiwi-ecs = "1.3"

// lib.rs
use kiwi_ecs::*;

The world

To start, create a new World. This is the starting point of the ecs. The program can have multiple independent worlds.

pub fn main() {
  let mut world = World::new();
}

Components

Components are defined as follows:

#[derive(Component)]
struct Position {
  x: u32,
  y: u32
}

Flags

Unit structs can't be used as Components, this is where you would have to use a flag. Flags are represented as an enum:

#[flags]
enum Flags {
  Player,
  Enemy,
  Ground,
}

Entities

To spawn a new entity with the given components:

// spawn_entity macro accepts the world as the first parameter, and the 
// components to add to the entity as the other parameters
let entity_id = spawn_entity!(world, Position { x: 0, y: 0 });

You can give an entity a flag using the set_flag method:

world.set_flag(entity_id, Flags::Player);

Systems

There are two ways to define systems.

The first is using the system macro:

// immutable system
#[system(pos: Position)]
fn print_positions(world: &World) {
  println!("{:?}", pos);
}

// mutable system
#[system(pos: Position, vel: Vel)]
fn move_entities(world: &mut World) {
  pos.x += vel.x;
  pos.y += vel.y
}

// query entity ids as well
#[system(id: EntityId, pos: Position)]
/// prints all entities ids having the position component
fn print_entity_ids(world: &World) {
  println!("{id}");
}

pub fn main() {
  let mut world = World::new();
  
  //--snip
  
  // Call the systems
  print_positions(&world);
  move_entities(&mut world);
  print_entity_ids(&world);
}

To create a mutable system, the function should contain world: &mut World as its first argument, for an immutable one, add world: &World.

The function can contain any number of arguments you can pass to it when calling.

The function can return any type of Result<(), Any>. If this function has the given result return type, Ok(()) will be returned at the end of the system.

The second is using the query and query_mut macros:

pub fn main() {
  let mut world = World::new();
  
  //--snip
  
  let query_result = query!(world, Position);
  let query_result = query_mut!(world, Position, Velocity);
  let query_result = query!(world, EntityId, Position);
  
  // You can now loop over the components
  query_result.for_each(|components| {
    // ...
  });
}

Flags in queries

You can further filter queries using flags:

#[system(id: EntityId, pos: Position)]
fn on_player(world: &World) {
  if world.has_flag(id, Flags::Player) {
    // ...
  }
}

let query_result = query!(world, EntityId, Position)
  .filter(|(id, _pos)| world.has_flag(*id, Flags::Player));

Feature flags

try

The try feature of this crate enables returning early from a system.

To enable it:

# Cargo.toml

[dependencies]
kiwi-ecs = { version = "*", features = ["try"] }

Usage

Mark a system which returns a Result of ok type () with try:

#[system(try, id: EntityId, pos: Position)]
fn a_system_with_a_fallible_condition(world: &World) -> Result<(), String> {
  let mesh = get_mesh(id)?; // fallible function
  render(mesh, pos)?;
}

Next to returning an Err, you can also use return std::ops::ControlFlow::Continue(()) to skip the current entity and continue to the next or return std::ops::ControlFlow::Break(()) to break from the function without an error.

Contributing

Contributors are always welcome. If you find any bugs, feel free to open an issue. If you feel like it, PRs are also appreciated!

License

Licensed under the MIT license.