Home

This tutorial explains how to use Terasology's Entity Component System (ECS).

The Entity Component System (ECS) is a system that Terasology uses to govern in-game objects and their behaviors. The core idea of ECS is that each part of the system is responsible for a different thing. There are 3 core parts of ECS: Entities, Components, and Systems.

Entities

Entities are the part of the model used to represent actual in-game objects. Virtually everything in Terasology is represented by an entity, including all blocks, players, creatures, items (in your inventory and in the physical world), and even some things that aren't physical objects. Entities themselves, however, do not actually directly contain any data or any code. Instead, entities contain components.

Entities are further explained in Creating Entities.

Components

Components are the part of the model used to store data. Entities can indirectly store data through components. Components typically represent "attributes" or "behaviors" that a physical object has. For example, a block which can fall down might have a component called GravityBlock which contains data like the speed of the block falling. The important thing about components is that they can be defined once and reused for many different entities. This makes it easy to reuse code in many different entities with minimal extra typing.

Components are further explained in Creating Components.

Systems

Systems implement the programming logic behind entities. Importantly, systems act on components, not on entities. This means that behavior is defined solely by the components an entity has, not the entity itself. In Terasology, systems primarily react to events, which are explained here. A system sets up methods to listen for events on entities with specific components, then carries out actions on those entities. Multiple systems can also act on the same events and components, so the code behind a system can be extended easily without modifying the original system, which is particularly useful across different modules.

Systems are further explained in Creating Systems.

Why use ECS?

The main appeal of ECS is its modularity. Existing components can be mixed and matched to create completely new entities with very little extra code. Also, any component can be added to any entity, which allows for behaviors to be combined in lots of interesting ways. The lack of repeating code not only allows for faster programming, but it makes the code easier to read and maintain since behaviors are only implemented once. The modularity is also important for Terasology's overall structure of features being added in modules: The ECS structure makes it simple for one module to implement behaviors which many other modules can make use of or extend in many different ways.