Description

Every object in the game world is an entity. Examples of different things that could be an entity:

Players
Enemies
Walls, floors
Bullets and projectiles
Machines
Collectables
Particle effects
Triggers
Spawners

Entities are containers for objects called entity components which define behaviors. Essentially, and entity is just a collection of entity components, much like a car is a collection of car parts. All the parts work together to provide something that runs. For more information, see the Entity Components page.

In addition to components, Entities have properties that can be defined by components. Properties are variables that can be written to, or read from. For example the physics component will define properties for the entity's location in space. The renderer will read this property to get the location of where to render the entity on the screen. Entities can be queried by their property values as well.

Because FEntity extends the FObject class, it can receive events like all instances of FObject.

Technical Details

Classes

Base Class: FEntity

Extends: FObject

Factory: FEntityFactory

There is only one entity class in firmament. FEntity is typically not extended. Instead, entities get their behaviors from the Entity Component that they are made of.

Entity objects are created via the FEntityFactory's createEntity() method, which takes an entity config object as its only parameter.

Config Object

Like most things in Firmament, entities are created and initialized with config objects. The entity factory takes one of these config objects and creates an entity object out of it.

An entity config object consists of the following:

{
	"typeId":"myType"			//string used as an identifier for the entity's type. Useful for queries.
	,"tags":["tag1","tag2"] 	//array of strings for arbitrary tags for this entity. This is useful for queries.
	,"properties" : {           //object containing entity properties and their values to set
        "angle" : 0
        ,"positionX" : 0
        //...
    }
	,"components":[				//object containing component config objects that make up the entities components
		{
			componentName:"com.myGame.component"	//name or fully qualified class name of the component
			//component-specific config data here
		}
		,{
			//...
		}
	]
}

Creating Entities

Entities are typically created by maps, but can also be created manually in code by using the factory FEntityFactory. In it's simplest form, you just call the static factory method, passing it an entity configuration or json configuration file name:

FEntityFactory.createEntity({
    "typeId": "wall"
    ,"components":{
        "render":{
            "componentName":"sprite"
            ,"image":"asset/wall.png"
        }
        ,"physics":{
            "componentName":"noPhysics"
            ,"width":1
            ,"height":1
        }
    }
});

Or, if the entity is defined in a JSON config file, you can create an entity using that file like so:

FEntityFactory.createEntity("config/entity/wall.json");

Extending

Extending imports all of the values from the json that is being extended. Configurations can be extended by using the "_extends" keyword. Extending provides the following features:

Default values are set by file being extended
Values in the extended file do not need to be set again
Components with the same name override the default (extended) components
Unique components are added unique to config

{
	"typeId":"myType"			//string used as an identifier for the entity's type. Useful for queries.
	,"_extends" : <path to config>
}

Firmament Engine

Entity