dartemis 0.8.0

  • Readme
  • Changelog
  • Installing
  • 69

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 = World();
    
  4. Create an entity from a list of components. Entities with different components will be processed by different systems:

     world.createEntity([
       Position(0, 0), 
       Velocity(1, 1),
     ]);
    

    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:

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

    By using a factory constructor and calling the static function Pooled.of, dartemis is able to reuse destroyed components and they will not be garbage collected.

  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.forAllOf([Position, Velocity]));
    
         void initialize() {
           // initialize your system
           // Mappers, Systems and Managers have to be assigned here
           // see dartemis_builder if you don't want to write this code
           positionMapper = Mapper<Position>(world);
           velocityMapper = Mapper<Velocity>(world);
         }
    
         void processEntity(int 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(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 #

  • darteroids - Very simple example included in the example folder of dartemis, (Source)
  • Shapeocalypse - A fast paced reaction game using Angular, WebAudio and WebGL
  • damacreat.io - An iogame similar to agar.io about creatures made of dark matter (circles) consuming dark energy (circles) and other dark matter creatures (circles), which can shoot black holes (circles)

Changelog #

0.8.0 (Dart 2.0+ required) #

Breaking API Changes #

  • removed deprecated code
  • replaced Entity with int, methods previously on Entity need to be called on World, with the int value of the entity as the first parameter
  • removed world.processEntityChanges, it's now done by default after every system
  • Aspect no longer uses static methods, uses named constructors instead (migration: replace Aspect.getAspectF with Aspect.f)
  • methods in Aspect no longer return the aspect, use cascading operator to chain calls
  • improved type safety for world.getManager and world.getSystem, no longer takes a Type as parameter and uses generic methods instead (e.g. world.getManager<TagManager>() instead of world.getManager(TagManager))
  • removed Type parameter in constructor of Mapper, change code from Mapper<Position>(Position, world) to Mapper<Position>(world)

Enhancements #

  • world.destroy() for cleaning up EntitySystems and Managers

Internal #

  • existing entities are processed first, addition of new entities is processed last, makes more sense now that the processing is done after every system

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.8.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter 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]
39
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
69
Learn more about scoring.

We analyzed this package on Jul 2, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.13

Health suggestions

Format lib/src/core/component_manager.dart.

Run dartfmt to format lib/src/core/component_manager.dart.

Maintenance suggestions

Maintain an example.

None of the files in the package's example/ directory matches known example patterns.

Common filename patterns include main.dart, example.dart, and dartemis.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
meta ^1.0.5 1.1.8
Dev dependencies
build_runner ^1.9.0
build_web_compilers ^2.10.0
mockito ^4.0.0
test ^1.2.0