#ecs #gamedev


A performant, small and versatile entity component system

11 stable releases

1.4.1 Feb 24, 2023
1.4.0 Feb 21, 2023
1.3.1 Nov 18, 2022
1.2.2 Oct 31, 2022

#294 in Game dev

MIT license

643 lines

kiwi ecs

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


# Cargo.toml

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 are defined as follows:

struct Position {
  x: u32,
  y: u32


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

enum Flags {


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);


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) {

pub fn main() {
  let mut world = World::new();
  // Call the systems
  move_entities(&mut 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();
  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


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

To enable it:

# Cargo.toml

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

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.


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


Licensed under the MIT license.


~35K SLoC