Kiwi

Kiwi is a versatile entity component system focussing on fast iteration and a nice api.

To get started, read the usage guide below.

The library is available from ruby gems:

gem install kiwi-ecs

To use it in your ruby source files:

require 'kiwi-ecs'

The world is the main object that controls the ecs.

world = Kiwi::World.new

Creating a component is as simple as declaring a struct:

Position = Struct.new :x, :y

Classes can also be used instead of structs

class Velocity
  attr_accessor :x
  attr_accessor :y
end

An entity is spawned with a set of components:

entityId = world.spawn(Position.new(10, 10))

world.spawn(Position.new(3, 5), Velocity.new(1.5, 0.0))

The world.spawn(*components) function will return the id of the spawned entity.

Killing an entity can be done using world.kill(entityId):

world.kill(entityId)

Queries can be constructed as follows:

# Query all position componentss
world.query(Position) do |pos|
    puts pos
end

# Query all entities having a position and a velocity component, and their entity ids
world.query_with_ids(Position, Velocity) do |id, pos, vel|
  # ...
end

Entities can be tagged using flags

A flag is an integer

module Flags
  Player = 0
  Enemy = 1
end

id = world.spawn

world.set_flag(id, Flags::Player)

world.remove_flag(id, Flags::Player)

world.has_flag(id, Flags::Player)

world.query_with_ids(Pos)
  .filter do |id, pos|
    world.has_flag(id, Flags::Player)
  end
  .each do |id, pos|
    # Do something with the filtered query
  end

The hasFlags function is also available for when you want to check multiple flags.

• System groups

Contributors are welcome to open an issue requesting new features or fixes or opening a pull request for them.

The library is licensed under LGPLv3.