spoved / entitas.cr

Entity Component System Framework writen in crystal

Entitas

A Entity Component System Framework for Crystal. Ported from: Entitas-CSharp

Entitas is a super fast Entity Component System Framework (ECS). Internal caching and blazing fast component access makes it second to none. Several design decisions have been made to work optimal in a garbage collected environment and to go easy on the garbage collector. Utilizing Crystal's macro system, all code generation is done compile time. No need for a code generator!

First glimpse

public def create_red_gem(context : GameContext, position)
  entity.is_game_board_element = true
  entity.is_movable = true
  entity = context.create_entity
  entity.add_position(position)
  entity.add_asset("RedGem")
  entity.is_interactive = true
  entity
end

entities = context.get_entities(Entitas::Matcher.all_of(Position, Velocity))
entities.each do |e|
  pos = e.position
  vel = e.velocity
end

Installation

Add this to your application's shard.yml:

dependencies:
  entitas:
    github: spoved/entitas.cr

Usage

require "entitas"

Documentation

Run crystal docs to generate API Docs and examples. You may need to include an example, as there are no default contexts and the macros need at least one for some things. To generate documentation run: crystal docs docs.cr

Since there is so much code that is auto generated, it is also recomended to include ./lib/entitas/src/entitas.cr when generating documentation for your application/lib. Like so:

crystal docs ./lib/entitas/src/entitas.cr ./src/

Error: enum Index must have at least one member

This error occurs when you have no components declared. The Entitas::Component::Index enum is auto generated by indexing all the sub-classes of Entitas::Component. Without any, the enum is empty, causing this error.

Examples

Examples can also be found in the spec/fixtures and examples folders. Ive replicated every test i could from the C# lib, so many examples and translations can be found there as well.

Logging

To enable verbose logging please provide the compile time flag -Dentitas_enable_logging. This will enable the Spoved::Logger. This is disabled by default to keep the code as performant as possible.

To enable some debug output for the code generator, include the flag -Dentitas_debug_generator.

Benchmarks

It is very important to make sure the lib is compariable to the original entitas. Here are some of the benchmarks to compare. Each benchmark was written as close as possible to the main source. As well as any aliases of the methods were tested. Most impressivly, the slowest test (EntityRemoveAddComponent) clocked in at 868.6 ms vs the crystal equivilant (#remove_component & #add_component) at 290.0 ms. Thats a 3x speed improvement.

Enitas C#

Running performance tests...
ContextCreateEntity:                    98.5355 ms
ContextDestroyEntity:                   33.0015 ms
ContextDestroyAllEntities:              32.4288 ms
ContextGetGroup:                        6.2042 ms
ContextGetEntities:                     2.322 ms
ContextHasEntity:                       1.9293 ms
ContextOnEntityReplaced:                21.4785 ms

EntityAddComponent:                     496.7223 ms
EntityGetComponent:                     39.1669 ms
EntityGetComponents:                    5.9182 ms
EntityHasComponent:                     5.4402 ms
EntityRemoveAddComponent:               868.6205 ms
EntityReplaceComponent:                 164.2688 ms

Entitas Cr

You can run the following command to run the benchmarks:

crystal run --release ./spec/performance/bench.cr

--## Entitas::Context(TEntity) ##--
-- Total execution time --

                       user     system      total        real
#get_entities      0.000000   0.000000   0.000000 (  0.001150)
#has_entity?       0.000000   0.000000   0.000000 (  0.000714)
OnEntityReplaced   0.000000   0.000000   0.000000 (  0.005321)

- Create Entity -
                             user     system      total        real
#create_entity w/o pre   0.080000   0.000000   0.080000 (  0.083808)
#create_entity w/ pre    0.020000   0.000000   0.020000 (  0.019606)

- Destroy all entities -
                                          user     system      total        real
control                               0.000000   0.000000   0.000000 (  0.000001)
#get_entities &Entity.destroy!        0.020000   0.010000   0.030000 (  0.021025)
#destroy_all_entities                 0.020000   0.000000   0.020000 (  0.020348)
#destroy_all_entities (pre-destroy)   0.020000   0.000000   0.020000 (  0.016953)

- #get_group -
                          user     system      total        real
#get_group by Int32   0.050000   0.000000   0.050000 (  0.053371)
#get_group by class   0.050000   0.000000   0.050000 (  0.047716)
#get_group by Enum    0.050000   0.000000   0.050000 (  0.047686)


--## Entitas::Entity ##--
-- Total execution time --

                         user     system      total        real
#add_component       0.370000   0.000000   0.370000 (  0.374146)
#get_components      0.000000   0.000000   0.000000 (  0.002171)
#replace_component   0.040000   0.000000   0.040000 (  0.040704)
#total_components    0.000000   0.000000   0.000000 (  0.000001)

- Get Component A -
                                                user     system      total        real
#get_component(Entitas::Component::Index)   0.040000   0.000000   0.040000 (  0.035134)
#get_component(Int32)                       0.030000   0.000000   0.030000 (  0.033637)
#get_component(A::INDEX)                    0.040000   0.000000   0.040000 (  0.036969)
#get_component(A::INDEX_VALUE)              0.030000   0.000000   0.030000 (  0.033226)
#a                                          0.040000   0.000000   0.040000 (  0.041205)

- Has Component? -
                      user     system      total        real
#has_component?   0.000000   0.000000   0.000000 (  0.000001)
#a?               0.000000   0.000000   0.000000 (  0.000001)

- Remove and Add Component -
                                         user     system      total        real
#remove_component & #add_component   0.250000   0.040000   0.290000 (  0.298851)
#del_a & #add_a                      0.250000   0.040000   0.290000 (  0.292872)

Development

Dont forget to add your pre-commit hooks!

ln ./pre-commit .git/hooks/pre-commit

Contributing

1. Fork it (https://github.com/spoved/entitas.cr/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Holden Omans - creator, maintainer

entitas.cr's Issues

component_name.id.underscore doesnt handle namespaced classes

@Blacksmoke16 pointed out that:

idk if this is an issue or not, but component_name.id.underscore doesnt handle namespaced stuff
i.e. module Foo::Bar would be foo::bar
which isnt valid

This should be fixed so components within a namespace can be used.

Error: enum Index must have at least one member

I'm getting this error around line 70 of generator.cr both while trying to run a program similar to the hello world example, and while trying to run crystal docs.

Any suggestions?

Update examples/inter_context_communication.cr

Hello everyone,

First I love your work thanks a lot. I'm using it for some personal project. However I'm not a veteran of ECS, I'm still learning alot.

I saw examples/inter_context_communication.cr is a little bit dated, I think they have been update on the framework since then. Do you mind updating it if you can spare some time?

🤟