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

Overview

kiwi ecs

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.

You might also like...
A nine slice/patch plugin for bevy ui nodes as single component using a fragment shader.
A nine slice/patch plugin for bevy ui nodes as single component using a fragment shader.

Bevy nine slice/patch Material Plugin Quick and easy auto-scaling nine slice/patch material for bevy ui nodes implemented as Fragment Shader. Features

A small, portable and extensible game framework written in Rust.
A small, portable and extensible game framework written in Rust.

What is This? Crayon is a small, portable and extensible game framework, which loosely inspired by some amazing blogs on bitsquid, molecular and flooo

Bindings to TinyGL, a Small, Free and Fast Subset of OpenGL

TinyGL is a very lightweight partial OpenGL implementation. Its small size makes it ideal for static linking.

A canvas on which you can draw anything with ease before drawing the pixels on your small hardware display.
A canvas on which you can draw anything with ease before drawing the pixels on your small hardware display.

embedded-canvas โ€‚โ€‚ canvas - a piece of cloth backed or framed as a surface for a painting NOTE: This crate is still in development and may have breaki

๐Ÿคนโ€ 2D sprite rendering extension for the specs ECS system

specs-blit 2D sprite rendering extension for the Specs ECS system. All sprites are loaded onto a big array on the heap. Example // Setup the specs wor

Hanabi โ€” a particle system plugin for the Bevy game engine.

Hanabi โ€” a particle system plugin for the Bevy game engine

An atomic save/load system for Bevy Game Engine.

โ˜ข๏ธ Bevy Atomic Save An atomic save/load system for Bevy. Features Save and load a World into a RON file on disk Control which entities should particip

Action-based animation system for Bevy.

bevy_action_animation Action-based animation system for Bevy. Introduction This plugin provides users of the Bevy game engine with an action/trigger-b

Simple action system for Bevy.

bevy_action Simple action system for Bevy. Introduction This plugin exists mainly to facilitate a common action system for other plugins to hook in to

Releases(v1.3.1)
Owner
Jonas Everaert
Interested in all things coding, and especially in WebAssembly applications.
Jonas Everaert
Entity Component System focused on usability and speed.

Shipyard โš“ Shipyard is an Entity Component System focused on usability and speed. If you have any question or want to follow the development more clos

Dylan Ancel 524 Jan 1, 2023
A generated entity component system ๐ŸฆŽ

gecs ?? A generated entity component system. The gecs crate provides a compile-time generated, zero-overhead ECS for simulations on a budget. Unlike o

null 61 Jun 16, 2023
a prototype crate for creating modular and performant 3D CPU particle systems, inspired by Unity's Shuriken Particle System.

bevy_prototype_particles This is a prototype crate for creating modular and performant 3D CPU particle systems, inspired by Unity's Shuriken Particle

James Liu 28 Sep 12, 2022
Rust bindings for entity-gym.

EntityGym for Rust EntityGym is a Python library that defines a novel entity-based abstraction for reinforcement learning environments which enables h

null 18 Apr 15, 2023
Minimalistic implementation of entity kinds for Bevy ECS.

Bevy ?? Kindly This crate is a minimalistic implementation of Kinded Entities for Bevy game engine. In summary, it allows the user to define, construc

null 10 Jan 26, 2023
Small game where you play a big spider chasing small spiders, written in Rust and Macroquad.

Ludum Dare #49 Compo entry - Procedural Spider Small game where you play a big spider chasing small spiders. Each spider you catch makes you bigger! C

Jakub Arnold 16 Sep 5, 2022
A safe, fast and cross-platform 2D component-based game framework written in rust

shura shura is a safe, fast and cross-platform 2D component-based game framework written in rust. shura helps you to manage big games with a component

Andri 28 Jan 17, 2023
A visual novel engine that draws inspiration from RenPy and is meant to be a more performant replacement with feature parity.

VN Engine A visual novel engine that draws inspiration from RenPy and is meant to be a more performant replacement with feature parity. The engine is

Alexandros Panagiotakis 2 Sep 9, 2022
A visual novel engine that draws inspiration from RenPy and is meant to be a more performant replacement with feature parity.

VN Engine A visual novel engine that draws inspiration from RenPy and is meant to be a more performant replacement with feature parity. The engine is

Alexandros Panagiotakis 2 Sep 9, 2022
A rollback library that buffers component state. Useful for netcode.

bevy_timewarp Buffer and rollback to states up to a few frames ago, for rollback networking. Doesn't do any networking, just concerned with buffering

Richard Jones 7 Sep 4, 2023