Callback used for visiting components

See also

IEntity::VisitComponents method

Adds an already created component to the entity

Parameters

pComponent	A shared pointer to the component we want to add, can not be null!
pInitParams	Optional initialization parameters to determine the initial state of the component

Returns

True if the component was added, otherwise false.

Adds flag/s to the current set of entity flags (logical OR).

Parameters

flagsToAdd

Combination of bit flags to add.

Do not use. Provides a way for CGameObject to replace NetEntity with itself.

Assign a pre-created physical entity to this proxy.

Parameters

pPhysEntity	The pre-created physical entity.
nSlot	Slot Index to which the new position will be taken from.

Attaches the child entity to this entity. The child entity will inherit all the transformation of the parent entity.

Parameters

pChildEntity	Child entity to attach.
attachParams	Attachment parameters.

Checks if the specified entity flag is set.

Parameters

flagsToCheck

Combination of bit flags to check.

Removes flag/s from the current set of entity flags (logical AND NOT).

Parameters

flagsToClear

Combination of bit flags to remove.

Creates a new entity component of type ComponentType from a registered factory and adds it to the entity. ComponentType must be a valid IEntityComponent implementation.

Returns

A pointer to the newly created component, otherwise nullptr (and likely an assertion).

Queries an entity component type by interface, and then creates the component inside this entity

Parameters

interfaceId	The GUID of the component we want to add
pInitParams	Optional initialization parameters to determine the initial state of the component

Returns

The newly created entity component pointer (owned by the entity), or null if creation failed.

Creates a specified proxy in the entity.

Parameters

proxy

Proxy interface identifier.

Returns

Valid pointer to the created entity proxy object, or NULL if creation failed.

Helper template function to simplify finding all components implementing the specified component type

Parameters

components	DynArray into which any found components will be stored
bCheckHierarchy	Whether or not we should traverse the inheritance hierarchy for all components, otherwise performs a (much faster) equality check to see if the implementation is ComponentType

Retrieves the entity archetype. Entity archetype contain definition for entity script properties.

Returns

Pointer to the entity archetype interface.

Fast method to get the character at the specified slot.

Parameters

nSlot

Index of the slot.

Returns

Character pointer or NULL if character with this slot does not exist.

Retrieves the attached child entity by index.

Parameters

nIndex

Index of the child entity, must be 0 <= nIndex < GetChildCount().

Returns

Pointer to the child entity interface.

Retrieves the entity class pointer. Entity class defines entity type, what script it will use, etc...

Returns

Pointer to the entity class interface.

Helper template function to simplify finding the first component implementing the specified component type This will traverse the inheritance tree, and is therefore slower than GetComponentByImplementation which simply does an equality check. ex: auto pScriptProxy = pEntity->GetComponent();

Parameters

bCheckHierarchy

Whether or not we should traverse the inheritance hierarchy for all components, otherwise performs a (much faster) equality check to see if the implementation is ComponentType

Return component with the unique GUID.

Parameters

guid	Identifier for the component.

Return first component of the entity with the specified class ID.

Parameters

interfaceID

Identifier for the component implementation.

Returns a number which is incremeting every time the entity components get changed Can be checked with an older one to determine if the entity components have changed

Return all components with the specified class ID contained in the entity.

Parameters

interfaceID

Identifier for the component implementation.

ObjectID that corresponds to editor base objects. This is used for selection and highlighting so it should be set by editor and have a 1-1 correspondence with a baseobject. This is intended as a runtime ID and does not need to be serialized

Entity links.

Gets pointer to the first entity link.

Fast method to get the geom cache render cache at the specified slot.

Parameters

nSlot

Index of the slot.

Returns

IGeomCacheRenderNode pointer or NULL if stat object with this slot does not exist.

Retrieves the globally unique identifier of this entity assigned to it by the Entity System. EntityGuid is guaranteed to be the same when saving / loading entity, it is also same in the editor and in the game.

Returns

The entity globally unique identifier.

Retrieves the runtime unique identifier of this entity assigned to it by the Entity System. EntityId may not be the same when saving/loading entity EntityId is not unique across the network, but can be serialized via the 'eid' compression policy EntityId is mostly used in runtime for fast and unique identification of entities, as the system allows for an O(1) retrieval

Returns

The entity instance's identifier

Returns

the last time (as set by the system timer) when the entity was last seen.

Retrieves the entity axis aligned bounding box in the local entity space.

Parameters

bbox	Output parameter for the bounding box.

Retrieves the parent of this entity if the parent is a local simulation grid

Returns

Pointer to the parent entity interface, or NULL if this entity does not have a parent or the parent is not a local simulation grid.

Retrieves the entity transformation matrix in the local entity space.

Returns

Local space transformation matrix.

Retrieves a custom material set to the entity.

Returns

Pointer to custom material interface or NULL if custom material not set.

Gets entity name.

Returns

Name of the entity.

Returns the network proxy associated with the entity. Use the proxy to modify the entity's network behavior.

Get existing or Create a new initialized component inside the entity.

Parameters

bCheckHierarchy

Whether or not we should traverse the inheritance hierarchy for all components, otherwise performs a (much faster) equality check to see if the implementation is ComponentType

Retrieves the parent of this entity.

Returns

Pointer to the parent entity interface, or NULL if this entity does not have a parent.

Retrieves the TM of the point this entity is attached to if it has a parent.

Note

This can be different from GetParent()->GetWorldTM() when the attachment point is not the pivot.

Returns

World space matrix of the parent attachment transform

Fast method to get the particle em at the specified slot.

Parameters

nSlot

Index of the slot.

Returns

IParticleEmitter pointer or NULL if stat object with this slot does not exist.

Returns

A physical entity assigned to an entity.

Get world bounds of physical object.

Parameters

[out]

bounds

Bounding box in world space.

Retrieves a pointer to the specified proxy interface in the entity.

Parameters

proxy

Proxy interface identifier.

Returns

Valid pointer to the requested entity proxy object, or NULL if such proxy not exist.

Retrieve an actual material used for rendering specified slot. Will return custom applied material or if custom material not set will return an actual material assigned to the slot geometry.

Parameters

nSlot

Slot to query used material from, if -1 material will be taken from the first renderable slot.

Returns

Material used for rendering, or NULL if slot is not rendered.

Retrieve 3D Engine render node, used to render this entity for a given slot. If nSlot is -1 return first existing render node in slots.

Called by networking on the server to serialize entity information in order to replicate the entity (and its components) on a remote host. The data is then deserialized on the remote host via SEntitySpawnParams::pSpawnSerializer. This function will collect information from components by calling IEntityComponent::NetReplicateSerialize.

Retrieves the flags of the specified slot.

Parameters

nSlot

Index of the slot.

Returns

Slot flags, or 0 if specified slot is not valid.

Gets object slot information.

Parameters

nIndex	Index of required slot.
slotInfo	Output variable where description of the slot will be written.

Returns

Local transformation matrix relative to host entity transformation matrix of the object slot.

Parameters

nSlot	- Index of required slot.
bRelativeToParent	- flag specifying whether the local transformation matrix is relative to the parent slot or the entity.

Retrieve slot's custom material (This material Must have been applied before with the SetSlotMaterial).

Parameters

nSlot

Slot to query custom material from.

Returns

Custom material applied on the slot.

Returns

World transformation matrix of the object slot.

Fast method to get the static object at the specified slot.

Parameters

nSlot

Index of the slot; | with ENTITY_SLOT_ACTUAL to disable compound statobj handling.

Returns

StatObj pointer or NULL if stat object with this slot does not exist.

Retrieve sub-object hide mask from slot.

Parameters

nSlot

Slot to apply hide mask to.

Retrieves the entity axis aligned bounding box in the world space.

Parameters

bbox	Output parameter for the bounding box.

Retrieves the entity transformation matrix in the world space.

Returns

World space transformation matrix (Include transformations of all parent entities).

LiveCreate entity manipulation. Process the LiveCreate message with a variable change. This function is used as low-latency update vs updating the whole entity.

Returns

true if handled, false otherwise

Hides this entity, makes it invisible and disable its physics.

Parameters

bHide

If true hide the entity, is false unhides it.

Increase/or decrease KeepAliveCounter Used as a refcount to prevent deletion when deferring some events (like physics collisions which can refer these entities).

Makes the entity invisible and disable its physics. Different from hide in that the entity is still updated.

Checks if this entity was marked for deletion. If this function returns true, it will be deleted on next frame, and it is pointless to perform any operations on such entity.

Returns

True if entity marked for deletion, false otherwise.

Return values

true	if this entity was loaded from level file.
false	for entities created dynamically.

Returns

true if the matrix returned by GetParentAttachPointWorldTM is valid, otherwise false.

Check if Entity is being Rendered by 3dengine. It doesn't necessary mean that it will be visible on screen but only that 3d engine considers it for a rendering now

Check if the slot with specified index exist.

Parameters

nIndex

Index of required slot.

Stops already started entity timer with this id.

Parameters

nTimerId

Timer ID of the timer started for this entity. (specify IEntity::KILL_ALL_TIMER to stop all timer on this entity)

Loads character to the specified slot, or to next available slot. If same character is already loaded in this slot, operation is ignored. If this slot number is occupied by different kind of object it is overwritten.

Returns

Slot id where the object was loaded, or -1 if loading failed.

#include 

// Load a character definition (.CDF) file into the next available entity slot
void LoadCharacter(IEntity& entity)
{
    // For the sake of this example, load the character definition from /Characters/MyCharacter.cdf
    const char* szCharacterPath = "Characters/MyCharacter.cdf";
    // Load the specified CDF into the next available slot
    const int slotId = entity.LoadCharacter(-1, szCharacterPath);
    // Attempt to query the character instance, will always succeed if the file was successfully loaded from disk
    if (ICharacterInstance* pCharacter = entity.GetCharacter(slotId))
    {
        /* pCharacter can now be used to manipulate and query the rendered character */
    }
}

Loads a fog volume to the specified slot, or to the next available slot.

Returns

Slot id where the fog volume was loaded, or -1 if loading failed.

#include 
#include 

void LoadFogVolume(IEntity& entity)
{
    // Create a SFogVolumeProperties instance to define the fog volume characteristics
    SFogVolumeProperties fogProperties;
    // Render the volume as a box
    fogProperties.m_volumeType = IFogVolumeRenderNode::eFogVolumeType_Box;
    // Render as a 1x1x1m box
    fogProperties.m_size = Vec3(1, 1, 1);
    // Set color to red (range is 0 - 1)
    fogProperties.m_color = ColorF(1, 0, 0, 1);

    // Helpers to convert emission intensity to the engine's format
    const float kiloScale = 1000.0f;
    const float toLightUnitScale = kiloScale / RENDERER_LIGHT_UNIT_SCALE;

    // Specify the desired emitted color, in our case red.
    ColorF emission = ColorF(1, 0, 0, 1);
    // Scale the intensity of the emission
    const float emissionIntensity = 1.f;
    emission.adjust_luminance(emissionIntensity * toLightUnitScale);

    // Apply the calculated emission to the fog properties
    fogProperties.m_emission = emission.toVec3();

    // Load the fog volume into the next available slot
    const int loadedSlotId = entity.LoadFogVolume(-1, fogProperties);
}

Loads geometry cache to the specified slot, or to next available slot. If same geometry cache is already loaded in this slot, operation is ignored. If this slot number is occupied by different kind of object it is overwritten.

Returns

Slot id where the object was loaded, or -1 if loading failed.

#include 

// Load an alembic / geom cache file into the next available entity slot
void LoadGeomCache(IEntity& entity)
{
    // For the sake of this example, load the geometry cache from  /MyGeomCache.cbc
    const char* szGeomCachePath = "MyGeomCache.cbc";
    // Load the alembic definition into the next available slot
    int slotId = entity.LoadGeomCache(-1, szGeomCachePath);
    // Attempt to query the render node, will always succeed if the file was successfully loaded from disk
    if (IGeomCacheRenderNode* pRenderNode = entity.GetGeomCacheRenderNode(slotId))
    {
        /* pRenderNode can now be used to manipulate geom cache playback */
    }
}

Loads static geometry to the specified slot, or to next available slot. If same object is already loaded in this slot, operation is ignored. If this slot number is occupied by different kind of object it is overwritten with static object.

Parameters

nLoadFlags

See ELoadFlags

See also

ELoadFlags

Returns

Slot id where the object was loaded, or -1 if loading failed.

#include 

// Load a static geometry (.CGF) file into the next available entity slot
void LoadGeometry(IEntity& entity)
{
    // For the sake of this example, load the static geometry from /Objects/MyBrush.cgf
    const char* szGeometryPath = "Objects/MyBrush.cgf";
    // Load the specified CGF into the next available slot
    const int slotId = entity.LoadGeometry(-1, szGeometryPath);
    // Attempt to query the IStatObj pointer, will always succeed if the file was successfully loaded from disk
    if (IStatObj* pStatObj = entity.GetStatObj(slotId))
    {
        /* 
            pStatObj can now be used to query the rendered geometry
            Note that pStatObj does *not* represent an instance, any modifications will modify all instances.
        */
    }
}

Loads a light source to the specified slot, or to next available slot.

Returns

Slot id where the light source was loaded, or -1 if loading failed.

#include 
#include 

// Loads a dynamic point light into the next available entity slot
void LoadPointLight(IEntity& entity)
{
    // Create the CDLight structure
    SRenderLight light;
    // Create a deferred point light that only affects the current area
    light.m_Flags = DLF_DEFERRED_LIGHT | DLF_THIS_AREA_ONLY | DLF_POINT;
    // Emit in a 10 meter radius
    light.m_fRadius = 10.f;
    // Set the color to pure white (RGBA), on a scale of 0 - 1
    light.SetLightColor(ColorF(1.f, 1.f, 1.f, 1.f));

    // Load the light into the next available entity slot
    const int lightSlot = entity.LoadLight(-1, &light);
}

// Loads a dynamic projector light into the next available entity slot
void LoadProjectorLight(IEntity& entity)
{
    // Create the CDLight structure
    SRenderLight light;
    // Create a deferred projector light that only affects the current area
    light.m_Flags = DLF_DEFERRED_LIGHT | DLF_THIS_AREA_ONLY | DLF_PROJECT;
    // Emit at a distance of 10 meters
    light.m_fRadius = 10.f;
    // Set the color to pure white (RGBA), on a scale of 0 - 1
    light.SetLightColor(ColorF(1.f, 1.f, 1.f, 1.f));

    // Load a sample projector texture from the engine assets (included with all projects)
    const char* szProjectedTexturePath = "%ENGINEASSETS%/Textures/Lights/ce_logo_white.dds";
    // Load the texture we want to project onto other objects
    light.m_pLightImage = gEnv->pRenderer->EF_LoadTexture(szProjectedTexturePath, FT_DONT_STREAM);
    // Project in a 90-degree cone
    light.m_fLightFrustumAngle = 90;

    // Load the light into the next available entity slot
    const int lightSlot = entity.LoadLight(-1, &light);
}

Loads a new particle emitter to the specified slot, or to next available slot. If this slot number is occupied by different kind of object it is overwritten.

Returns

Slot id where the particle emitter was loaded, or -1 if loading failed.

#include 
#include 

// Creates a particle emitter into the specified entity slot that emits continuously emits a specific effect
void LoadParticleEmitter(IEntity& entity)
{
    // For the sake of this example, load the particle effect from /Particles/MyEffect.pfx2
    const char* szParticleEffectPath = "Particles/MyEffect.pfx2";
    if (IParticleEffect* pEffect = gEnv->pParticleManager->FindEffect(szParticleEffectPath, "ParticleLoadExample"))
    {
        // Create a new SpawnParams instance to define how our particles should behave
        SpawnParams spawnParams;
        /* The spawn params could be modified here, but we choose to use the default settings set up by the designer in the Particle Editor */

        // Create a particle emitter in the next available slot, using the specified spawn parameters
        const int slotId = entity.LoadParticleEmitter(-1, pEffect, &spawnParams);
    }
}

Moves the contents of a render slot from one entity to another, will also move any associated physics.

Parameters

targetIEnt	Entity to receive the new slot info.
nSlot	Index of the slot.

Physicalize entity by creating a PhysicalEntity based on a specified physical parameters

See also

IEntity::PhysicalizeSlot

#include 

// Simple example for physicalizing an entity and all of its slots
void Physicalize(IEntity& entity)
{
    // The SEntityPhysicalizeParams is used to describe how an entity should be physicalized
    SEntityPhysicalizeParams physicalizeParams;
    // The type indicates which IPhysicalEntity implementation to use, in our case we want a rigid entity that can be moved around in the world and influence other entities
    physicalizeParams.type = PE_RIGID;
    // Physical entities can specify either a mass, or a density - but never both. In our case, we specify a mass of 50 kilograms.
    // If density is specified, the mass is calculated based on volume.
    physicalizeParams.mass = 50.f;
    // It is possible to automatically physicalize a specific slot, or all. In our case, we choose to automatically create physics parts for each entity slot in our entity.
    physicalizeParams.nSlot = -1;

    // Call IEntity::Physicalize to create the physical entity
    entity.Physicalize(physicalizeParams);

    // Now query the physical entity, will return a valid entity if Physicalize succeeded.
    if (IPhysicalEntity* pPhysicalEntity = entity.GetPhysicalEntity())
    {
        /* pPhysicalEntity can now be used, valid until entity is dephysicalized */
    }
}

Adds physical geometry to the physical entity tied to this entity, based on the slot (if present) Entity has to have been physicalized with IEntity::Physicalize first.

See also

IEntity::Physicalize

#include 

// Simple example for physicalizing an entity slot
void PhysicalizeSlot(IEntity& entity, const int slotId)
{
    // Entity must have been physicalized using IEntity::Physicalize first
    if (IPhysicalEntity* pPhysicalEntity = entity.GetPhysicalEntity())
    {
        SEntityPhysicalizeParams partPhysicalizeParams;
        // Specify the type of physicalization to use, has to be the same as the entity we are applying to
        partPhysicalizeParams.type = pPhysicalEntity->GetType();
        // Specify the slot identifier inside the physicalization parameters
        partPhysicalizeParams.nSlot = slotId;
        // Mass of this entity in kilograms
        // Note that mass and density cannot be specified at the same time, if density is specified then mass is calculated based on volume
        partPhysicalizeParams.mass = 10.f;

        // Now add the slot geometry to our physical entity
        entity.PhysicalizeSlot(slotId, partPhysicalizeParams);
    }
}

Render a preview of the Entity This method is not used when entity is normally rendered But only used for previewing the entity in the Sandbox Editor

Removes all instances of the specified component type found in the entity

Parameters

checkHierarchy

Whether or not we should traverse the inheritance hierarchy for all components, otherwise performs a (much faster) equality check to see if the implementation is ComponentType

Remove previously created component from the Entity

Parameters

pComponent

Component pointer to remove from the Entity

Removes the first instance of the specified component type found in the entity

Parameters

checkHierarchy

Whether or not we should traverse the inheritance hierarchy for all components, otherwise performs a (much faster) equality check to see if the implementation is ComponentType

Replaces an existing component in the entity with another, without shutting down the existing component Used for reallocating components at run-time while keeping internal state intact Note that this function does not copy any data between the components, that is up to the caller.

Sends event to the entity.

Parameters

event

Event description (event id, parameters).

Saves or loads entity parameters to/from stream using serialization context class.

Parameters

serializer	Serialization context class, provides all the information needed to properly serialize entity contents.
nFlags	Additional custom serialization flags.

Sets character instance of a slot, and creates slot if necessary.

Parameters

nSlot	Index of a slot, or -1 if a new slot need to be allocated.
pCharacter	A pointer to character instance.

Returns

An integer which refers to the slot index which used.

Sets entity flags, completely replaces all flags which are already set in the entity.

Parameters

flags

Flag values which are defined in EEntityFlags.

Sets entity flags, completely replaces all flags which are already set in the entity.

Parameters

flags

- Extended flag values which are defined in EEntityFlagsExtended.

Force local bounds.

Parameters

[out]	bounds	Bounding box in local space.
	bDoNotRecalculate	When set to true entity will never try to recalculate local bounding box set by this call.

Sets entity transformation matrix in the local entity space.

Parameters

tm	Local space transformation matrix (Non unifrorm scale is not supported).

Assigns a custom material to the entity.

Parameters

pMaterial

Pointer to custom material interface.

Changes the entity name. Entity name does not have to be unique, but for the sake of easier finding entities by name it is better to not assign the same name to different entities.

Parameters

sName

New name for the entity.

Attaches child slot to the parent slot. This will form hierarchical transformation relationship between object slots.

Parameters

nParentIndex	Index of the parent slot (Child slot will be attached to this one).
nChildIndex	Index of the child slot.

Sets an existing particle emitter to the specified slot, or the next available slot. If this slot number is occupied by different kind of object it is overwritten.

Returns

Slot id where the particle emitter was loaded, or -1 if loading failed.

Sets the flags of the specified slot.

Parameters

nSlot	Index of the slot, if -1 apply to all existing slots.
nFlags	Flags to set.

Assigns a custom material to the specified object slot.

Parameters

nSlot	Index of the slot, if -1 assign this material to all existing slots.
pMaterial	Pointer to custom material interface.

Sets static object of a slot, creates slot if necessary

Parameters

nSlot	Index of a slot, or -1 if a new slot need to be allocated; | with ENTITY_SLOT_ACTUAL to disable compound statobj handling.
pStatObj	Pointer to the new static object.
mass	New mass of the slot, negative value to keep the current.

Returns

Integer which refer to the slot index which used

Assign sub-object hide mask to slot.

Parameters

nSlot

Slot to apply hide mask to.

Starts the entity timer. Entity timers are owned by entity, every entity can have it`s own independent timers, so TimerId must not be unique across multiple entities. When timer finishes entity system will signal to the entity once with an event ENTITY_EVENT_TIME. Multiple timers can be started simultaneously with different timer ids. If some timer is not yet finished and another timer with the same timerID is set, the new one will override old timer, and old timer will not send finish event.

Parameters

nTimerId	Timer ID, multiple timers with different IDs are possible. (specify IEntity::CREATE_NEW_UNIQUE_TIMER_ID to let the system generate a new and unique Id)
nMilliSeconds	Timer timeout time in milliseconds.

Returns

the (generated) timerId

Sets entity transformation matrix in the world space.

Parameters

tm	World space transformation matrix (Non unifrorm scale is not supported).

Parameters

nSlot

- Index of the slot.

Returns

true if character is to be updated, otherwise false.

Parameters

[out]

partId

Set to the child's partId.

Returns

An attached child entity that corresponds to the physical part partId.

Used to update the stored mask for a certain component, from IEntityComponent::GetEventMask For example, changing IEntityComponent::GetEventMask to return ENTITY_EVENT_UPDATE and then calling GetEventMask will result in the component and its entity being updated the next frame.

#include 

class CMyEventComponent final : public IEntityComponent
{
public:
    // Provide a virtual destructor, ensuring correct destruction of IEntityComponent members
    virtual ~CMyEventComponent() = default;

    static void ReflectType(Schematyc::CTypeDesc& desc) { /* Reflect the component GUID in here. */}

    // Override the ProcessEvent function to receive the callback whenever an event specified in GetEventMask is triggered
    virtual void ProcessEvent(const SEntityEvent& event) override
    {
        // Check if this is the update event
        if (event.event == ENTITY_EVENT_UPDATE)
        {
            // The Update event provides delta time as the first floating-point parameter
            const float frameTime = event.fParam[0];

            /* Handle update logic here */
        }
    }

    // As an optimization, components have to specify a bitmask of the events that they want to handle
    // This is called once at component creation, and then only if IEntity::UpdateComponentEventMask is called, to support dynamic change of desired events (useful for disabling update when you don't need it)
    virtual uint64 GetEventMask() const override { return BIT64(ENTITY_EVENT_UPDATE); }
};

Calls a callback on all of the components in the entity This is a more efficient way to operate on components then using GetComponents method as it is not require temporary allocations