Flambe core

### Philosophy > Flambe mostly uses composition over inheritance. Flambe uses an entity/component system rather than sprawling inheritance hierarchies. The composition pattern also comes up repeatedly in other parts of Flambe's design.

How does the entity-component system work?

An entity is an object in a game. Entities don't do anything on their own, components are attached to them to add data and logic. Entities are also hierarchical -- they can have other entities as children. This hierarchy when combined with the Sprite component, delivers the familiar Flash-like scene graph, but with the flexibility of being able to add other types of components.

Some components override each other if they have a common parent class. Adding a FillSprite to an entity for example will replace its ImageSprite. That's because they both extend Sprite. Since Sprite extends Component, anything that subclasses Sprite will share the "Sprite" namespace. Under the hood, this is implemented by giving a unique ID to each class that directly extends Component.

Entities

The entity is a general purpose object. You can nest Entities inside an Entity (addChild-function) but you can also add Components (add-function). You cannot extend a Entity. The Entities define the hierarchy and order of the 'displaylist'/rendering order.

Components

Components are bits of data and logic that can be added to entities. The component consists of a minimal set of data needed for a specific purpose. In Flambe, every component has 4 important functions:

• onAdded() Called after this component has been added to an entity. owner is available after being added. The order of adding matters, in case you want to grab other components from the owner inside this function.
• onUpdate(deltaTime:Float) Called when this component receives a game update.
• onRemoved() Called just before this component has been removed from its entity.
• dispose() Removes this component from its owning entity.

The game timer is in every component

The onUpdate-function is called when this component receives a 'game' update, with delta time (The time elapsed since the last 'frame'). Flambe is framerate independent, but targeted at 60 FPS (frames per second). All animation/coded motion should be based on time, not frames.

Destruction

This dispose function removes this component from its owning entity. You should override the dispose-function in order to dispose objects yourself, to prevent memory leaks.

Code examples

Add a colored box inside a component class

This is a example to illustrate how to add a entity to the root, with a visual component that displays a blue square of 100x100px.

var mySprite:FillSprite = new FillSprite(0x154d79, 100, 100);
System.root.addChild(new Entity().add(mySprite));

Nesting entities

This is a example to illustrate how to nest two Sprites.

var mySprite:FillSprite = new FillSprite(0x154d79, 100, 100); // blue square
System.root.addChild(new Entity().add(mySprite));

var myNestedSprite:FillSprite = new FillSprite(0xefbf74, 40, 40); // orange square
mySprite.owner.addChild(new Entity().add(myNestedSprite));

Loop through components of an Entity

To iterate over the hierarchy, use the parent, firstChild, next and firstComponent fields. For example:

var child = entity.firstComponent;
while (child != null) 
{
	var next = child.next; 
	
	// do something with child here
	child.fuuuuu();
	
	child = next;
}

Grab a component from a type inside an Entity

You can assume there is a class of given type in the Entity, but to be sure its there, do a null-check. Alternatively you can also choose to check with entity.has(Sprite). In this example an Entity has a Sprite. We try to grab it back out of the Entity.

package;
class MyGame
{
   public function new()
   {
       var entity = new Entity();
       entity.add( new Sprite() ); // add a sprite.
       
       // .. later in code..
       var sprite = entity.get(Sprite); 
       if (sprite != null) 
       { 
           trace('sprite found in entity: ' + sprite);
       }
       else
       {
           trace('Warn: No sprite found.');
       }
   }
}

The fun part of this, is that you can swap the actual Sprite with any other Sprite (like FillSprite, ImageSprite etc..). If you still use entity.get(Sprite), it returns that sprite. That allows you to create loose assumptions, which gives some flexibility.

Get the entity within a component class

You can grab the owner of the component, this is the Entity. The owner is available in the onAdded- function, not in the constructor.

package;
class MyComponent extends Component
{
   override public function onAdded()
   {
       trace( this.owner ); // Entity
   }
}

More info on entity/component system

There are better (non-flambe) articles written by skilled developers about this workflow. Some article describe slightly other implementations of the whole system; some even in other programming languages. It could give a bit more understanding about this interesting concept, but also about code organization and how to get familiar with it.

Wikipedia: Entity component system
Evolve Your Hierarchy
T-Machine Entity Systems
Case study: Bomberman mechanics
Component-based engine design
What is an entity framework