Usage

Actors are objects that live in the scene and represent everything from a simple static cube to a host of a pawn.

Actors are part of the engine's ECS(Entity Component System). There are a lot of great articles about ECS' but here is a summary

  1. The E stands for Entity. This is the object that is being manipulated, in our case Actors
  2. The C stands for Component. Components are attached to an entity and contain data about it
  3. The S stands for System. Systems are the code responsible for manipulating the data in the components.

In a purist type of ECS, an entity will be an ID that represents a handle in a pool, the component will store data and the system will be a class/collection of functions that modify the components.

The main difference between the purist ECS and our implementation is that we use some OOP concepts with the ECS, which leads to less noticeable separation of systems and data

For example, every gameplay class derives from its respective abstract data type. We use this to allow for easy C++ scripting. We also have systems, embedded as member functions in our components, in order for them to access any data the component holds.

Using the ECS interface

You can access all functions related to the ECS from the ECS interface.

To remove all actors in the scene call

ECS::clear();

To fetch an actor using its identifiers, call:

auto actor = ECS::getActorWithIdentifiers(<name>, <id>, <dev-name>);

To execute a function for every actor in the actor pool call

ECS::each(<a function pointer/lambda that takes an actor pointer>);

To execute a function for every actor with a given component call

ECS::forEveryComponent<Type>(<function pointer/lambda that takes an actor pointer>);

This is it for the ECS interface. You can now use this to grab an actor from the scene.

Using the Actor data type

Now that you have an actor, you can use its member functions to modify its data

To create an actor from scratch, decide on identifiers and call the non-default constructor or the create function of the Actor type

actor.create(<name>, <id>, <devname>);

To add a component to it, call:

auto& component = actor.add<Type>();

To get a reference to a component of a given type stored in the actor, use:

auto& component = actor.get<Type>();

To remove a component call:

actor.remove<Type>();

To check if an actor has a component call:

if (actor.has<Type>()) doStuff();

To destroy an actor, call:

actor.destroy();

Now that you know how to use the ECS, you can start scripting using Gameplay classes, which is discussed in the next chapter

Additional information for game developers

You may already know this, but this game engine uses the entt entity component system library under the hood. This means that the whole actor API is just a light wrapper around entt