Overview

Components represent user-authored code that attach to Entities, known in code by the name IEntityComponent.

Type and Instance GUIDs

As seen in the minimal entity component implementation, each component type has to specify a GUID - used to uniquely identify this component implementation across the engine. This is stored as a CryGUID. Each component's type GUID is defined in its ReflectType function, for reference see the minimal component example.

In addition to the type GUID, each component instance is assigned a GUID. This is mostly used for internal purposes, but can also be used to query components using IEntity::GetComponentByGUID. The instance GUID of a component can be retrieved by calling IEntityComponent::GetGUID.

Generating GUIDs

GUIDs can be generated from Visual Studio by going to Tools -> Create GUID, bringing up the dialog below:

Once open, select 4. Registry Format and click Copy. This will place the generated GUID into your clipboard, ready for usage in the CRYENGINE codebase.

Events

Entities routinely send events of type EEntityEvent, for example ENTITY_EVENT_UPDATE - sent each frame to give components a chance to do per-frame logic.

Components can handle events by overriding the IEntityComponent::ProcessEvent function, and providing a bit-mask of the desired event in IEntityComponent::GetEventMask.

Transform

Each component can contain a transformation, supporting a relative offset of contained render or physical geometry from the parent entity. This is automatically exposed to the Sandbox Editor if EEntityComponentFlags::Transform is applied to the component type in its ReflectType call.

Once exposed, we can manipulate the world transformation of components using the following functions:

In addition, each component can assign itself one entity slot that will be automatically moved with the component's transformation. This is made possible by loading geometry into the slot returned by IEntityComponent::GetOrMakeEntitySlotId.

Creating and Querying Components

Components can be created and queried using two kinds of functions; the Template helpers and low-level functions. The template helpers exist to simplify querying of a component type known at compile-time, while the low-level functions can be used to operate on components not known as the code is written.

We can also get components from an interface type, assuming that the interface implements ReflectType and is added to the implementation via the Schematyc::CTypeDesc<T>::AddBase function.

Template function helpers

The template helpers take one template parameter T that is assumed to be derived from IEntityComponent. This allows for easily querying and creating components of a known type of interface.

Low-level functions

The low-level functions operate on unique component type and instance GUIDs, and will always return an IEntityComponent* that can then be statically cast to the requested type.

Editor Properties

It is often useful to expose component properties too the Editor in order to simplify designer workflow. This can be done by reflecting members in the component implementation's ReflectType implementation, resulting in the properties being shown in the Properties window when an entity with the component is selected:

See the example below:

static void ReflectType(Schematyc::CTypeDesc<CMyComponent>& desc)
{
    /* ...Reflect GUID, set category etc... */
    // Use of multi-character literal to create a unique identifier for this member, in the scope of the component
    const uint32 id = 'floa';
    // Internal name of the property, will be visible in XML files
    const char* szInternalName = "MyParameter";
    // Human readable name, shown in the user interface
    const char* szDisplayName = "My Parameter";
    // Help text / description shown to users when they hover over the property in Editor
    const char* szDescription = "My Parameter Description";
    // Default value of the property
    const float defaultValue = 0.25f;
    desc.AddMember(&CMyComponent::m_floatValue, id, szInternalName, szDisplayName, szDescription, defaultValue);
}

It is also possible to create groups, this is accomplished by creating a struct with a ReflectType function and adding an instance of it as a member to the component's ReflectType function.

Adding Components to Entities

There are three methods of adding a component to an entity:

1. Through the Sandbox Properties panel (see below)
2. By creating a new Schematyc Entity, and adding the component (any instances of this entity in the scene will automatically instantiate the predefined components)
3. Programmatically, using the IEntity interface (see below).

Adding Components Programmatically

Components can be attached to entities through code using the IEntity interface through a set of simple functions:

Registering a Component implementation

In order for IEntity::CreateComponent<T> and IEntity::GetOrCreateComponent<T> to work, component implementations need to be registered into the entity component registry. Additionally, this exposes your component to the Sandbox user interface - allowing direct usage of your component by designers without needing to modify code.

This is achieved by creating a Schematyc package, and registering your components inside it:

static void RegisterComponents(Schematyc::IEnvRegistrar& registrar)
{
  Schematyc::CEnvRegistrationScope scope = registrar.Scope(IEntity::GetEntityScopeGUID());
  {
    Schematyc::CEnvRegistrationScope componentScope = scope.Register(SCHEMATYC_MAKE_ENV_COMPONENT(CMyComponent));
  }
}
 
gEnv->pSchematyc->GetEnvRegistry().RegisterPackage(
  stl::make_unique<Schematyc::CEnvPackage>(
    "{E44AA983-48EF-4567-A545-324AC547A354}"_cry_guid,
    "My Entity Components Package",
    "My Company Name",
    "My Description",
    [this](Schematyc::IEnvRegistrar& registrar){ RegisterComponents(registrar); });

Once done, your component will show up in the 'Add Component' dialog for both selected entities and the Schematyc Editor.

Conclusion

This concludes the article on entity components. You may be interested in:

• Networking
• Execution Order and Lifecycle
• Characters and Animations
• Slots, Geometry and Effects
• Input and Action Mapping
• Physics and Movement
• Audio