dartemis 0.7.3

  • Readme
  • Changelog
  • Installing
  • 0

dartemis #

Build Status Coverage Status Pub

Content #

About #

dartemis is a Dart port of the Entity System Framework Artemis.

The original has been written in Java by Arni Arent and Tiago Costa and can be found here: http://gamadu.com/artemis with the source available here: https://code.google.com/p/artemis-framework/

Ports for other languages are also available:

Some useful links about what an Entity System/Entity Component System is:

Getting started #

  1. Add dartemis to your project by adding it to your pubspec.yaml:

     dependencies:
       dartemis: any
    
  2. Import it in your project:

     import 'package:dartemis/dartemis.dart';
    
  3. Create a world:

     World world = new World();
    
  4. Create entities, add components to them and finally add those entities to the world. Entities with different components will be processed by different systems:

     Entity entity  = world.createEntity();
     entity.addComponent(new Position(world, 0, 0));
     entity.addComponent(new Velocity(world, 1, 1));
     entity.addToWorld();
    

    A Component is a pretty simple structure and should not contain any logic:

     class Position extends Component {
         num x, y;
         Position(this.x, this.y);
     }
    

    Or if you want to use a PooledComponent (see dartemis_transformer if you want to use them without having to write this code):

     class Position extends PooledComponent {
         num x, y;
    
         Position._();
         factory Position(num x, num y) {
             Position position = new Pooled.of(Position, _constructor);
             position.x = x;
             position.y = y;
             return position;
         }
         static Position _constructor() => new Position._();
     }
    

    By using a factory constructor and calling the factory constructor in Pooled, dartemis is able to reuse destroyed components and they will not be garbage collected. For more information about why this is done you might want to read this article: Free Lists For Predictable Game Performance

  5. Define a systems that should process your entities. The Aspect defines which components an entity needs to have in order to be processed by the system:

     class MovementSystem extends EntityProcessingSystem {
         Mapper<Position> positionMapper;
         Mapper<Velocity> velocityMapper;
    
         MovementSystem() : super(Aspect.getAspectForAllOf([Position, Velocity]));
    
         void initialize() {
           // initialize your system
           // Mappers, Systems and Managers have to be assigned here
           // see dartemis_transformer if you don't want to write this code
           positionMapper = new Mapper<Position>(Position, world);
           velocityMapper = new Mapper<Velocity>(Velocity, world);
         }
    
         void processEntity(Entity entity) {
           Position position = positionMapper[entity];
           Velocity vel = velocityMapper[entity];
           position.x += vel.x;
           position.y += vel.y;
         }
     }
    
  6. Add your system to the world:

     world.addSystem(new MovementSystem());
    
  7. Initialize the world:

     world.initialize();
    
  8. In your game loop you then process your systems:

     world.process();
    

    If your game logic requires a delta you can set it by calling:

     world.delta = delta;
    

Documentation #

API #

Reference Manual

Example Games using dartemis #

Add-ons #

  • dartemis_toolbox - A set of addons to use with dartemis (like EntityStateMachine, ...) and other libraries for gamedev.
  • dartemis_transformer - A transformer to modify and generate code that turns Components into PooledComponents and initializes EntitySystems and Managers.

Changelog #

##0.7.3

Bugfixes #

  • adding an entity to a dirty EntityBag could lead to an inconsistency between the bitset and the list of entities ##0.7.2

Bugfixes #

  • removing an entity multiple times caused it to be added to the entity pool multiple times ##0.7.1

Internal #

  • upgraded dependencies

##0.7.0

Breaking API Changes #

  • renamed Poolable to Pooled
  • renamed ComponentPoolable to PooledComponent
  • removed FastMath and Utils, unrelated to ECS
  • removed removeAll from Bag
  • time and frame getters have been moved from World to EntitySystem, World has methods instead

API Changes #

  • deprecated ComponentMapper use Mapper instead
  • deprecated ComponentMapper#get(Entity), use Mapper[Entity] instead
  • properties have been added to the World, can be accessed using the [] operator
  • Systems can be assigned to a group when adding them to the World, Word.process() can be called for a specific group

Enhancements #

  • performance improvement when removing entities

Bugfixes #

  • DelayedEntityProcessingSystem keeps running until all current entities have expired

Internal #

  • upgraded dependencies

##0.6.0

API Changes #

  • Bag is Iterable
  • removed ReadOnlyBag, when upgrading to 0.6.0 replace every occurence of ReadOnlyBag with Iterable

##0.5.2

Enhancements #

  • injection works for Managers
  • initialize() in the Manager is no longer abstract (same as in EntitySystem)
  • World.createEntity got an optional paramter to create an Entity with components
  • new function World.createAndAddEntity which adds the Entity to the world after creation

Bugfixes #

  • added getter for the World in Manager
  • the uniqueId of an Entity was always 0, not very unique

##0.5.1

Internal #

  • added version constraint for release of Dart

##0.5.0

Enhancements #

  • more injection, less boilerplate (when using dartemis_mirrors)
    • Instances of ComponentMapper no longer need to be created in the initialize-method of a system, they will be injected
    • Managers and EntitySystems no longer need to be requested from the World in the initialize-method of a system, they will be injected

##0.4.2

Bugfixes #

  • EntityManager.isEnabled() no longer fails if the bag of disabled entities is smaller than the id of the checked entity

Enhancements #

  • added getters for current time and frame to World

##0.4.1

Bugfixes #

  • World.deleteAllEntites() did not work if there was already a deleted entity
  • writing to the Bag by index doesn't make it smaller anymore

##0.4.0

API Changes #

  • swapped parameters of Tagmanager.register
  • replaced ImmutableBag with ReadOnlyBag, added getter for ReadOnlyBag to Bag
  • changed FreeComponents to ObjectPool
  • old Component has changed, there are two different kinds of components now:
    • instances of classes extending ComponentPoolable will be added to the ObjectPool when they are removed from an Entity (preventing garbage collection and allowing reuse)
    • instances of classes extending Component will not be added to the ObjectPool when they are removed from an Entity (allowing garbage collection)

Enhancements #

  • added function deleteAllEntities to World
  • IntervalEntitySystem has a getter for the delta since the systm was processed last
  • updated to work with Dart M4

Bugfixes #

  • GroupManager.isInGroup works if entity is in no group

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  dartemis: ^0.7.3

2. Install it

You can install packages from the command line:

with pub:


$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:dartemis/dartemis.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
0
Health:
Code health derived from static analysis. [more]
--
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
--
Overall:
Weighted score of the above. [more]
0
Learn more about scoring.

The package version is not analyzed, because it does not support Dart 2. Until this is resolved, the package will receive a health and maintenance score of 0.

Analysis issues and suggestions

Support Dart 2 in pubspec.yaml.

The SDK constraint in pubspec.yaml doesn't allow the Dart 2.0.0 release. For information about upgrading it to be Dart 2 compatible, please see https://dart.dev/dart-2#migration.

Maintenance issues and suggestions

Make sure dartdoc successfully runs on your package's source files. (-10 points)

Dependencies were not resolved.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.8.0 <2.0.0