Overview

Entities represent elements in the world that can move, act and behave logically in the world - as opposed to a rock that won't change over time. Entities by themselves do not contain logic, but can contain Components - user-authored bits of code that can manipulate their parent entity at run time. Examples include light sources, physicalized objects (such as bullets), and players.

Components

Entities themselves cannot contain custom logic. Instead, they can contain Components. For example, a Camera component could be attached to an entity, exposing functionality for rendering a specific viewpoint in the level:

Entities are stored and managed in the Entity System, represented by the IEntitySystem interface, and accessible through gEnv->pEntitySystem. The system is responsible for spawning, managing entities throughout their lifetime, and finally removing them. See IEntitySystem::SpawnEntity for an example on how to spawn entities.

Identifiers

After being spawned, each entity is assigned an entity identifier, represented by the EntityId type definition. Entity identifiers are 32-bit and consist of two parts: a 16-bit salt, used to facilitate re-use of each index without resulting in Entity Identifiers being reused over the lifetime of the application, and a 16-bit index, representing the position of the entity in the entity system’s internal storage. This allows for constant-time retrieval of an entity, as we can simply look up an entity by index in contiguous storage.

This means that despite being a 32-bit unsigned integer, the index is only 16 bits – resulting in a max limit of 65533 entities in the world at any given time (0 and 65534+ are reserved). Any game expecting to exceed this number would need to stream in logical entities using a custom setup tailored for the project.

Globally Unique Identifier

Entities are also assigned globally unique identifiers, noted by the EntityGUID type definition. These identifiers differ from entity IDs in that they are guaranteed to be the same when saving and loading entities – allowing the Editor and other systems to track which entity belongs where.

Transform & Parent / Child Hierarchy

Entities in CRYENGINE have a transform by default, meaning they have location, orientation and scale in relation to their parent (and if no parent, to the world). We can retrieve the world transformation through the following functions:

Similarly, we can change the world transformation easily using

Hierarchy

Entities can be linked together in a hierarchy, ensuring that the entity's position is relative to the parent. This is useful to pair entities together in a parent / child relationship where the child should always follow its parent.

An entity can be linked to a parent at spawn time, or at any point during an during an instance's lifetime.

Once linked, we can retrieve the local-space transformation (relative to the parent) of the entity through the following functions:

The local transformation can be modified using

Slots / Entity Geometry

For more information, see Slots, Geometry and Effects.

Conclusion

This concludes the article on entities. You may also be interested in:

• Components
• Execution Order and Lifecycle
• Networking