HPL3/SOMA/Scripting/Scripting Api/Entity

Have some helpful descriptions to add to this class? Edit this page and add your insight to the Wiki!

Summary

Return Type	Function and Description
bool	Entity_AddCollideCallback(const tString &in asParentName, const tString &in asChildName, const tString &in asFunction) Add a callback for when entities (objects, areas etc) collide and/or collides with the player
void	Entity_AddForce(const tString &in asEntityName, const cVector3f &in avForce, bool abLocalSpace, bool abOnlyMainBody) Adds force to the entity
void	Entity_AddForceFromEntity(const tString &in asEntityName, const tString &in asForceEntityName, float afForce, bool abOnlyMainBody) Adds force to the entity away from another entity
void	Entity_AddImpulse(const tString &in asEntityName, const cVector3f &in avImpulse, bool abLocalSpace, bool abOnlyMainBody) Adds an impulse to the entity
void	Entity_AddImpulseFromEntity(const tString &in asEntityName, const tString &in asImpulseEntityName, float afImpulse, bool abOnlyMainBody) Adds an impulse to the entity away from another entity
void	Entity_AddTorque(const tString &in asEntityName, const cVector3f &in avTorque, bool abLocalSpace, bool abOnlyMainBody) Adds torque to an entity to provide some angular velocity
bool	Entity_AttachToEntity(const tString &in asName, const tString &in asParentName, const tString &in asParentBodyName, bool abUseRotation, bool abSnapToParent = false, bool abLocked = false) Attaches the entity to another entity
bool	Entity_AttachToSocket(const tString &in asName, const tString &in asParentName, const tString &in asParentSocketName, bool abUseRotation, bool abSnapToParent = true) Attaches the entity to another entity
void	Entity_CallEntityInteract(const tString &in asName, const tString &in asBodyName = "", const cVector3f &in avFocusBodyOffset = cVector3f_Zero, const tString &in asData = "") Calls OnInteract on the specified entity
void	Entity_Connect(const tString &in asName, const tString &in asMainEntity, const tString &in asConnectEntity, bool abInvertStateSent, int alStatesUsed) Creates a connection between two entities
iLuxEntity	Entity_CreateAtEntity(const tString &in asNewEntityName, const tString &in asEntityFile, const tString &in asTargetEntityName, bool abFullGameSave) Creates an entity at another entity
iLuxEntity	Entity_CreateAtEntityExt(const tString &in asNewEntityName, const tString &in asEntityFile, const tString &in asTargetEntityName, bool abFullGameSave, const cVector3f &in avScale, const cVector3f &in avOffsetPosition, const cVector3f &in avOffsetRotation, bool abLocalOffset) Creates an entity at another entity with extra options
void	Entity_Destroy(const tString &in asName) Destroys an entity of a given name
bool	Entity_EntityIsInFront(const tString &in asTargetEntity, const tString &in asForwardEntity) Returns true if the specified entity is in front of the other entity
bool	Entity_Exists(const tString &in asName) Check if an entity exists in the level
bool	Entity_Exists(tID aID) Check if an entity exists in the level
void	Entity_FadeEffectBaseColor(const tString &in asEntityName, const cColor &in aColor, float afTime) Fades the base color of the effects
void	Entity_FadeProcAnimationSpeed(const tString &in asEntityName, const tString &in asAnimationName, float afSpeed, float afTime) Fade the speed of a proc animation
bool	Entity_GetAutoSleep(const tString &in asName) Get if an entity automatically falls asleep when it isnt active
cVector3f	Entity_GetBodyOffset(const tString &in asEntityName) Returns the offset from centre specified in the
bool	Entity_GetCollide(const tString &in asEntityA, const tString &in asEntityB) Checks for collision between two specific entities
cVector3f	Entity_GetDeltaToEntity(const tString &in asEntityA, const tString &in asEntityB) Gets the direction and distance between two entities
bool	Entity_GetVarBool(const tString &in asEntityName, const tString &in asVarName) Get value of an entity boolean variable
cColor	Entity_GetVarColor(const tString &in asEntityName, const tString &in asVarName) Get value of an entity color variable
float	Entity_GetVarFloat(const tString &in asEntityName, const tString &in asVarName) Get value of an entity float variable
int	Entity_GetVarInt(const tString &in asEntityName, const tString &in asVarName) Get value of an entity integer variable
tString	Entity_GetVarString(const tString &in asEntityName, const tString &in asVarName) Get value of an entity string variable
cVector2f	Entity_GetVarVector2f(const tString &in asEntityName, const tString &in asVarName) Get value of an entity vector2f variable
cVector3f	Entity_GetVarVector3f(const tString &in asEntityName, const tString &in asVarName) Get value of an entity vector3f variable
void	Entity_IncVarFloat(const tString &in asEntityName, const tString &in asVarName, float afX) Add a value to the current value of an entity float variable
void	Entity_IncVarInt(const tString &in asEntityName, const tString &in asVarName, int alX) Add a value to the current value of an entity integer variable
void	Entity_IncVarVector2f(const tString &in asEntityName, const tString &in asVarName, const cVector2f &in avX) Add a value to the current value of an entity vector2f variable
void	Entity_IncVarVector3f(const tString &in asEntityName, const tString &in asVarName, const cVector3f &in avX) Add a value to the current value of an entity vector3f variable
bool	Entity_IsActive(const tString &in asName) Get if an entity is active (visible and functioning) or not
bool	Entity_IsInPlayerFOV(const tString &in asEntity) Returns true if the object is within the player's field of view
bool	Entity_IsInteractedWith(const tString &in asName) Checks if the entity is being interacted with
bool	Entity_IsOccluder(const tString &in asName) Get if an entity is an occluder
bool	Entity_IsSleeping(const tString &in asName) Check if an entity is asleep
void	Entity_PlaceAtEntity(const tString &in asEntityName, const tString &in asTargetEntity, const cVector3f &in avOffset = cVector3f_Zero, bool abAlignRotation = false, bool abUseEntFileCenter = false) Places the specified entity at another entity
void	Entity_PlayAnimation(const tString &in asEntityName, const tString &in asAnimation, float afFadeTime = 0.1f, bool abLoop = false, bool abPlayTransition = true, const tString &in asCallback = "") Plays an animation on the entity
bool	Entity_PlayerIsInFront(const tString &in asName) Returns true if the player is in front of the specified entity
void	Entity_PlayProcAnimation(const tString &in asEntityName, const tString &in asAnimation, float afLength, bool abLoop = false, float afAmountFadeTime = 0.1, float afSpeedFadeTime = -1.0f) Plays a procedural animation on the entity
void	Entity_Preload(const tString &in asEntityFile) Preloads an entity
void	Entity_RemoveAllConnections(const tString &in asMainEntity) Removes all connections on an entity
bool	Entity_RemoveCollideCallback(const tString &in asParentName, const tString &in asChildName) Remove a callback for when entities (objects, areas etc) collide and/or collide with the player
void	Entity_RemoveConnection(const tString &in asName, const tString &in asMainEntity) Removes a specific connection on an entity
bool	Entity_RemoveEntityAttachment(const tString &in asName) Removes an attachment to another entity if the entity(ies) has one
void	Entity_SetActive(const tString &in asName, bool abActive) Set if entity is active (visible and functioning) or not
void	Entity_SetAnimationMessageEventCallback(const tString &in asEntityName, const tString &in asCallbackFunc, bool abAutoRemove) Sets a callback for the message events in the currently playing animation
void	Entity_SetAnimationPaused(const tString &in asEntityName, const tString &in asAnimationName, bool abPaused = true) Pause or unpause an animation on the specified entity
void	Entity_SetAnimationRelativeTimePosition(const tString &in asEntityName, const tString &in asAnimationName, float afTimePos) Sets the relative time position of a specific animation
void	Entity_SetAutoSleep(const tString &in asName, bool abX) Sets if the entity should sleep automatically when it need no updating
void	Entity_SetCollide(const tString &in asEntityName, bool abActive) Turn off or on collision for all the bodies in the given entity
void	Entity_SetCollideCharacter(const tString &in asEntityName, bool abActive) Turn off or on character collision for all the bodies in the given entity
void	Entity_SetColorMul(const tString &in asEntityName, const cColor &in aColor) Set the color mul of the entity
void	Entity_SetConnectionStateChangeCallback(const tString &in asEntityName, const tString &in asCallback) Sets the callback for when the connection state changes on an entity
void	Entity_SetEffectBaseColor(const tString &in asEntityName, const cColor &in aColor) Sets the base color of the effects
void	Entity_SetEffectsActive(const tString &in asEntityName, bool abActive, bool abFadeAndPlaySounds) Activates or deactivates the effects on a entity
void	Entity_SetInteractionDisabled(const tString &in asEntityName, bool abX) Sets if the player can interact with an entity or not
void	Entity_SetIsOccluder(const tString &in asName, bool abOccluder) Set if entity is an occluder
void	Entity_SetMaxInteractionDistance(const tString &in asEntityName, float afDistance) Change the max interaction distance of an entity from the default/entity configured distance
void	Entity_SetPlayerInteractCallback(const tString &in asEntityName, const tString &in asCallback, bool abRemoveWhenInteracted) Sets the callback for when the player interacts with a specific entity
void	Entity_SetPlayerLookAtCallback(const tString &in asEntityName, const tString &in asCallback, bool abRemoveWhenLookedAt = true, bool abCheckCenterOfScreen = true, bool abCheckRayIntersection = true, float afMaxDistance = -1, float afCallbackDelay = 0) Sets the callback for when the player looks at or turns away from a specific entity
void	Entity_SetProcAnimationPaused(const tString &in asEntityName, const tString &in asAnimationName, bool abPaused = true) Pause or unpause a procedural animation on the specified entity
void	Entity_SetProcAnimationSpeed(const tString &in asEntityName, const tString &in asAnimationName, float afSpeed) Sets the speed of a proc animation
void	Entity_SetReflectionVisibility(const tString &in asEntityName, bool abVisibleInReflection, bool abVisibleInWorld) Sets whether the entity is drawn in reflections or not, and the real world or not
void	Entity_SetVarBool(const tString &in asEntityName, const tString &in asVarName, bool abX) Sets the value of an entity boolean variable
void	Entity_SetVarColor(const tString &in asEntityName, const tString &in asVarName, const cColor &in aX) Sets the value of an entity color variable
void	Entity_SetVarFloat(const tString &in asEntityName, const tString &in asVarName, float afX) Sets the value of an entity variable
void	Entity_SetVarInt(const tString &in asEntityName, const tString &in asVarName, int alX) Sets the value of an entity integer variable
void	Entity_SetVarString(const tString &in asEntityName, const tString &in asVarName, const tString &in asX) Sets the value of an entity string variable
void	Entity_SetVarVector2f(const tString &in asEntityName, const tString &in asVarName, const cVector2f &in avX) Sets the value of an entity vector2f variable
void	Entity_SetVarVector3f(const tString &in asEntityName, const tString &in asVarName, const cVector3f &in avX) Sets the value of an entity vector3f variable
void	Entity_Sleep(const tString &in asName) Forces the entity to sleep (disabling Update/PostUpdate)
void	Entity_StopAnimation(const tString &in asEntityName) Stops any currently playing animation on the specified entity
void	Entity_StopProcAnimation(const tString &in asEntityName, const tString &in asAnimation, float afFadeTime = 0.1f) Stops a procedural animation on the specified entity
void	Entity_WakeUp(const tString &in asName) Forces the entity to wake up (enabling Update/PostUpdate)

Function Detail

Entity_AddCollideCallback

bool Entity_AddCollideCallback(const tString &in asParentName,
                               const tString &in asChildName,
                               const tString &in asFunction)

Add a callback for when entities (objects, areas etc) collide and/or collides with the player.
Collision include "uncolliding" (objects just stopped colliding) as well.
Wildcard(s) * can be used in names to check for collisions.
Syntax for callback function: bool FunctionName(const tString &in asParent, const tString &in asChild, int alState).
- asParent Name of the parent entity in the collision.
- asChild Name of the child entity in the collision.
- alState 1 = colliding, -1 = was colliding in previous frame, not anymore.
Return false = callback is removed, true = callback can trigger again.

Parameters

• asParentName (tString) — always "player" for player collisions, else first entity name.
• asChildName (tString) — name of the entity or second entity to check for collision.
• asFunction (tString) — name of the callback function when something collides/uncollides.

Returns:

• bool—.

Entity_AddForce

void Entity_AddForce(const tString &in asEntityName,
                     const cVector3f &in avForce,
                     bool abLocalSpace,
                     bool abOnlyMainBody)

Adds force to the entity.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• avForce (cVector3f) — force to add.
• abLocalSpace (bool) — true = force is added relative to the rotation of the entity - false = force is added in world space
• abOnlyMainBody (bool) — true = force is added only to the main body of the entity - false = force is added to all bodies in the entity

Returns:

• void

Entity_AddForceFromEntity

void Entity_AddForceFromEntity(const tString &in asEntityName,
                               const tString &in asForceEntityName,
                               float afForce,
                               bool abOnlyMainBody)

Adds force to the entity away from another entity.

Parameters

• asEntityName (tString) — name of the entity to add force to. Wildcard(s) * are supported.
• asForceEntityName (tString) — name of the entity to push away from.
• afForce (float) — force magnitude, negative attracts the entity to the force entity.
• abOnlyMainBody (bool) — true = force is added only to the main body of the entity - false = force is added to all bodies in the entity

Returns:

• void

Entity_AddImpulse

void Entity_AddImpulse(const tString &in asEntityName,
                       const cVector3f &in avImpulse,
                       bool abLocalSpace,
                       bool abOnlyMainBody)

Adds an impulse to the entity.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• avImpulse (cVector3f) — impulse to add.
• abLocalSpace (bool) — true = impulse is added relative to the rotation of the entity - false = impulse is added in world space
• abOnlyMainBody (bool) — true = impulse is added only to the main body of the entity - false = impulse is added to all bodies in the entity

Returns:

• void

Entity_AddImpulseFromEntity

void Entity_AddImpulseFromEntity(const tString &in asEntityName,
                                 const tString &in asImpulseEntityName,
                                 float afImpulse,
                                 bool abOnlyMainBody)

Adds an impulse to the entity away from another entity.

Parameters

• asEntityName (tString) — name of the entity to add impulse to. Wildcard(s) * are supported.
• asImpulseEntityName (tString) — name of the entity to push away from.
• afImpulse (float) — impulse magnitude, negative attracts the entity to the impulse entity.
• abOnlyMainBody (bool) — true = impulse is added only to the main body of the entity - false = impulse is added to all bodies in the entity

Returns:

• void

Entity_AddTorque

void Entity_AddTorque(const tString &in asEntityName,
                      const cVector3f &in avTorque,
                      bool abLocalSpace,
                      bool abOnlyMainBody)

Adds torque to an entity to provide some angular velocity

Parameters

• asEntityName (tString) — name of the entity to add impulse to. Wildcard(s) * are supported.
• avTorque (cVector3f) — provide a vector3 for the desired direction
• abLocalSpace (bool) — use local space for the entity
• abOnlyMainBody (bool) — true = impulse is added only to the main body of the entity - false = impulse is added to all bodies in the entity

Returns:

• void

Entity_AttachToEntity

bool Entity_AttachToEntity(const tString &in asName,
                           const tString &in asParentName,
                           const tString &in asParentBodyName,
                           bool abUseRotation,
                           bool abSnapToParent = false,
                           bool abLocked = false)

Attaches the entity to another entity. If already attached, it will be removed before attaching to new

Parameters

• asName (tString) — the name of the entity to be attached to another, Wildcard(s) * are supported
• asParentName (tString) — The entity to attach to.
• asParentBodyName (tString) — the local (as it is in ent file) of the body. Use for just using the main body.
• abUseRotation (bool) — if the attached entity should be rotated along witht the parent.
• abSnapToParent (bool) — if the attached entity should snap to the center of the body, or if it should use its relative world position as offset
• abLocked (bool) — if the attached object should be locked to the parent - fixes precision issues

Returns:

• bool—

Entity_AttachToSocket

bool Entity_AttachToSocket(const tString &in asName,
                           const tString &in asParentName,
                           const tString &in asParentSocketName,
                           bool abUseRotation,
                           bool abSnapToParent = true)

Attaches the entity to another entity. If already attached, it will be removed before attaching to new

Parameters

• asName (tString) — the name of the entity to be attached to another, Wildcard(s) * are supported
• asParentName (tString) — The entity to attach to.
• asParentSocketName (tString) — the socket setup in the mesh or model editor. this is attached to a bone in the skeleton
• abUseRotation (bool) — if the attached entity should be rotated along witht the parent.
• abSnapToParent (bool) — if the attached entity should snap to the center of the socket, or if it should use its relative world position as offset

Returns:

• bool—

Entity_CallEntityInteract

void Entity_CallEntityInteract(const tString &in asName,
                               const tString &in asBodyName = "",
                               const cVector3f &in avFocusBodyOffset = cVector3f_Zero,
                               const tString &in asData = "")

Calls OnInteract on the specified entity.

Parameters

• asName (tString) — name of the entity.
• asBodyName (tString) — name of the body to interact with if "" then it's the main body.
• avFocusBodyOffset (cVector3f) — focus point on the body.
• asData (tString) — optional data needed for interaction.

Returns:

• voidtrue if the position is in front of the entity.

Entity_Connect

void Entity_Connect(const tString &in asName,
                    const tString &in asMainEntity,
                    const tString &in asConnectEntity,
                    bool abInvertStateSent,
                    int alStatesUsed)

Creates a connection between two entities.

Parameters

• asName (tString) — name of the connection.
• asMainEntity (tString) — the entity to add the connection to. Wildcard(s) * are supported.
• asConnectEntity (tString) — the entity to connect to the main entity.
• abInvertStateSent (bool) — if the state changes should be sent inverted.
• alStatesUsed (int) — states sent by main entity, 0 = all states, 1 = only max, -1 = only min.

Returns:

• void

Entity_CreateAtEntity

iLuxEntity@ Entity_CreateAtEntity(const tString &in asNewEntityName,
                                  const tString &in asEntityFile,
                                  const tString &in asTargetEntityName,
                                  bool abFullGameSave)

Creates an entity at another entity.

Parameters

• asNewEntityName (tString) — the name of the entity to be created.
• asEntityFile (tString) — the .ent file of the entity to be created.
• asTargetEntityName (tString) — the target entity.
• abFullGameSave (bool) — if ALL properties should be saved for the created entity.

Returns:

• iLuxEntity@—

Entity_CreateAtEntityExt

iLuxEntity@ Entity_CreateAtEntityExt(const tString &in asNewEntityName,
                                     const tString &in asEntityFile,
                                     const tString &in asTargetEntityName,
                                     bool abFullGameSave,
                                     const cVector3f &in avScale,
                                     const cVector3f &in avOffsetPosition,
                                     const cVector3f &in avOffsetRotation,
                                     bool abLocalOffset)

Creates an entity at another entity with extra options.

Parameters

• asNewEntityName (tString) — the name of the entity to be created.
• asEntityFile (tString) — the .ent file of the entity to be created.
• asTargetEntityName (tString) — the target entity.
• abFullGameSave (bool) — if ALL properties should be saved for the created entity.
• avScale (cVector3f) — the scale of the created entity, where cVector3f(1, 1, 1) is the default size.
• avOffsetPosition (cVector3f) — an offset from the target object's position.
• avOffsetRotation (cVector3f) — an offset from the target object's rotation.
• abLocalOffset (bool) — true = offset position and rotation are relative to the target object's rotation, false = offset position and rotation are relative to the world.

Returns:

• iLuxEntity@—new iLuxEntity object.

Entity_Destroy

void Entity_Destroy(const tString &in asName)

Destroys an entity of a given name.

Parameters

• asName (tString) — the name of the entity to be destroyed, can contain wildcards to destroy multiple entities.

Returns:

• void

Entity_EntityIsInFront

bool Entity_EntityIsInFront(const tString &in asTargetEntity,
                            const tString &in asForwardEntity)

Returns true if the specified entity is in front of the other entity.
The function assumes the entity's z-axis points forward. Anything less than 90
degrees offset from the forward vector counts as "in front".

Parameters

• asTargetEntity (tString) — name of the entity to check if in front of the other.
• asForwardEntity (tString) — name of entity which forward vector and position will be checked against.

Returns:

• bool—bool true if the target entity is in front.

Entity_Exists

bool Entity_Exists(const tString &in asName)

Check if an entity exists in the level.

Parameters

• asName (tString) — the name of the entity to search for.

Returns:

• bool—if entity exists.

Entity_Exists

bool Entity_Exists(tID aID)

Check if an entity exists in the level.

Parameters

• aID (tID) — the id of the entity to search for.

Returns:

• bool—if entity exists.

Entity_FadeEffectBaseColor

void Entity_FadeEffectBaseColor(const tString &in asEntityName,
                                const cColor &in aColor,
                                float afTime)

Fades the base color of the effects

Parameters

• asEntityName (tString) — name of the prop. Wildcard(s) * are supported.
• aColor (cColor) — the color all effects will be faded to
• afTime (float) — time the fade takes.

Returns:

• void

Entity_FadeProcAnimationSpeed

void Entity_FadeProcAnimationSpeed(const tString &in asEntityName,
                                   const tString &in asAnimationName,
                                   float afSpeed,
                                   float afTime)

Fade the speed of a proc animation.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• asAnimationName (tString) — name of the animation.
• afSpeed (float) — target speed (measured in full loops per second).
• afTime (float) — time to fade over.

Returns:

• void

Entity_GetAutoSleep

bool Entity_GetAutoSleep(const tString &in asName)

Get if an entity automatically falls asleep when it isnt active

Parameters

• asName (tString) — Name of the entity.

Returns:

• bool—if sleeping or not.

Entity_GetBodyOffset

cVector3f Entity_GetBodyOffset(const tString &in asEntityName)

Returns the offset from centre specified in the .ent file. Only works for props.

Parameters

• asEntityName (tString) — name of the entity.

Returns:

• cVector3f—the offset

Entity_GetCollide

bool Entity_GetCollide(const tString &in asEntityA,
                       const tString &in asEntityB)

Checks for collision between two specific entities. Wildcard(s) * are NOT supported!

Parameters

• asEntityA (tString) — first entity.
• asEntityB (tString) — second entity.

Returns:

• bool—

Entity_GetDeltaToEntity

cVector3f Entity_GetDeltaToEntity(const tString &in asEntityA,
                                  const tString &in asEntityB)

Gets the direction and distance between two entities

Parameters

• asEntityA (tString) — entity to calculate delta from
• asEntityB (tString) — entity to caluclate delta to

Returns:

• cVector3f—delta between the entities, delta = direction * distance = entity_b_pos - entity_a_pos

Entity_GetVarBool

bool Entity_GetVarBool(const tString &in asEntityName,
                       const tString &in asVarName)

Get value of an entity boolean variable.

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the boolean variable.

Returns:

• bool—

Entity_GetVarColor

cColor Entity_GetVarColor(const tString &in asEntityName,
                          const tString &in asVarName)

Get value of an entity color variable.

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the color variable.

Returns:

• cColor—

Entity_GetVarFloat

float Entity_GetVarFloat(const tString &in asEntityName,
                         const tString &in asVarName)

Get value of an entity float variable.

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the float variable.

Returns:

• float—

Entity_GetVarInt

int Entity_GetVarInt(const tString &in asEntityName,
                     const tString &in asVarName)

Get value of an entity integer variable.

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the vector3f variable.

Returns:

• int—

Entity_GetVarString

tString Entity_GetVarString(const tString &in asEntityName,
                            const tString &in asVarName)

Get value of an entity string variable.

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the string variable.

Returns:

• tString—

Entity_GetVarVector2f

cVector2f Entity_GetVarVector2f(const tString &in asEntityName,
                                const tString &in asVarName)

Get value of an entity vector2f variable.

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the vector2f variable.

Returns:

• cVector2f—

Entity_GetVarVector3f

cVector3f Entity_GetVarVector3f(const tString &in asEntityName,
                                const tString &in asVarName)

Get value of an entity vector3f variable.

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the vector3f variable.

Returns:

• cVector3f—

Entity_IncVarFloat

void Entity_IncVarFloat(const tString &in asEntityName,
                        const tString &in asVarName,
                        float afX)

Add a value to the current value of an entity float variable. Wildcard(s) * are supported for EntityName.

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the float variable.
• afX (float) — value to be added to variable.

Returns:

• void

Entity_IncVarInt

void Entity_IncVarInt(const tString &in asEntityName,
                      const tString &in asVarName,
                      int alX)

Add a value to the current value of an entity integer variable. Wildcard(s) * are supported for EntityName. *

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the integer variable.
• alX (int) — value to be added to variable.

Returns:

• void

Entity_IncVarVector2f

void Entity_IncVarVector2f(const tString &in asEntityName,
                           const tString &in asVarName,
                           const cVector2f &in avX)

Add a value to the current value of an entity vector2f variable. Wildcard(s) * are supported for EntityName.

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the vector2f variable.
• avX (cVector2f) — value to be added to variable.

Returns:

• void

Entity_IncVarVector3f

void Entity_IncVarVector3f(const tString &in asEntityName,
                           const tString &in asVarName,
                           const cVector3f &in avX)

Add a value to the current value of an entity vector3f variable. Wildcard(s) * are supported for EntityName.

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the vector3f variable.
• avX (cVector3f) — value to be added to variable.

Returns:

• void

Entity_IsActive

bool Entity_IsActive(const tString &in asName)

Get if an entity is active (visible and functioning) or not.

Parameters

• asName (tString) — Name of the entity.

Returns:

• bool—if active or not.

Entity_IsInPlayerFOV

bool Entity_IsInPlayerFOV(const tString &in asEntity)

Returns true if the object is within the player's field of view. This does not take into account line of sight.

Parameters

• asEntity (tString) — name of the entity to check.

Returns:

• bool—true if the entity is in the player's field of view.

Entity_IsInteractedWith

bool Entity_IsInteractedWith(const tString &in asName)

Checks if the entity is being interacted with.

Parameters

• asName (tString) — name of the entity.

Returns:

• bool—if the entity is being interacted with

Entity_IsOccluder

bool Entity_IsOccluder(const tString &in asName)

Get if an entity is an occluder

Parameters

• asName (tString) — Name of the entity.

Returns:

• bool—if entity is an occluder

Entity_IsSleeping

bool Entity_IsSleeping(const tString &in asName)

Check if an entity is asleep

Parameters

• asName (tString) — Name of the entity.

Returns:

• bool—if sleeping or not.

Entity_PlaceAtEntity

void Entity_PlaceAtEntity(const tString &in asEntityName,
                          const tString &in asTargetEntity,
                          const cVector3f &in avOffset = cVector3f_Zero,
                          bool abAlignRotation = false,
                          bool abUseEntFileCenter = false)

Places the specified entity at another entity. Optionally aligning its rotation with the target entity.

Parameters

• asEntityName (tString) — name of the entity.
• asTargetEntity (tString) — entity to place at.
• avOffset (cVector3f) — world offset from the target entity to place at.
• abAlignRotation (bool) — if true the entity will be given the same rotation as the target entity.
• abUseEntFileCenter (bool) — if true the entity's center specified in the ent file will be used for placement (only works for props).

Returns:

• void

Entity_PlayAnimation

void Entity_PlayAnimation(const tString &in asEntityName,
                          const tString &in asAnimation,
                          float afFadeTime = 0.1f,
                          bool abLoop = false,
                          bool abPlayTransition = true,
                          const tString &in asCallback = "")

Plays an animation on the entity
Syntax for callback function: void Func(const tString &in asEntityName, const tString &in asAnimName)

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• asAnimation (tString) — name of the animation to play.
• afFadeTime (float) — time to fade in animation.
• abLoop (bool) — if the animation should loop.
• abPlayTransition (bool) — If a transition animation (given such exist) should be be played before.
• asCallback (tString) — (optional) name of callback function.

Returns:

• void

Entity_PlayerIsInFront

bool Entity_PlayerIsInFront(const tString &in asName)

Returns true if the player is in front of the specified entity.
The function assumes the entity's z-axis points forward. Anything less than 90
degrees offset from the forward vector counts as "in front".

Parameters

• asName (tString) — name of the entity to check if in front of the other.

Returns:

• bool—true if the target entity is in front.

Entity_PlayProcAnimation

void Entity_PlayProcAnimation(const tString &in asEntityName,
                              const tString &in asAnimation,
                              float afLength,
                              bool abLoop = false,
                              float afAmountFadeTime = 0.1,
                              float afSpeedFadeTime = -1.0f)

Plays a procedural animation on the entity

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• asAnimation (tString) — name of the animation to play.
• afLength (float) — time it takes to play the animation (can be negative to play it in reverse!)
• abLoop (bool) — if the animation should loop.
• afAmountFadeTime (float) — time to fade in animation.
• afSpeedFadeTime (float) — time to fade in the speed of the animation (use this for looping animations to avoid skipping).

Returns:

• void

Entity_Preload

void Entity_Preload(const tString &in asEntityFile)

Preloads an entity

Parameters

• asEntityFile (tString) — name of the entity file to preload

Returns:

• void

Entity_RemoveAllConnections

void Entity_RemoveAllConnections(const tString &in asMainEntity)

Removes all connections on an entity.

Parameters

• asMainEntity (tString) — the entity to remove all connections on. Wildcard(s) * are supported.

Returns:

• void

Entity_RemoveCollideCallback

bool Entity_RemoveCollideCallback(const tString &in asParentName,
                                  const tString &in asChildName)

Remove a callback for when entities (objects, areas etc) collide and/or collide with the player.
Wildcard(s) * can be used in names.

Parameters

• asParentName (tString) — always "player" for player callbacks, else first entity name.
• asChildName (tString) — name of the entity or second entity.

Returns:

• bool—.

Entity_RemoveConnection

void Entity_RemoveConnection(const tString &in asName,
                             const tString &in asMainEntity)

Removes a specific connection on an entity.

Parameters

• asName (tString) — name of the connection to remove.
• asMainEntity (tString) — the entity to remove the connection from. Wildcard(s) * are supported.

Returns:

• void

Entity_RemoveEntityAttachment

bool Entity_RemoveEntityAttachment(const tString &in asName)

Removes an attachment to another entity if the entity(ies) has one.

Parameters

• asName (tString) — the name of the entity to be no longer attached to another, Wildcard(s) * are supported

Returns:

• bool—

Entity_SetActive

void Entity_SetActive(const tString &in asName,
                      bool abActive)

Set if entity is active (visible and functioning) or not.

Parameters

• asName (tString) — Name of the entity, Wildcard(s) * are supported
• abActive (bool) — true = entity becomes active - false = entity becomes inactive

Returns:

• void

Entity_SetAnimationMessageEventCallback

void Entity_SetAnimationMessageEventCallback(const tString &in asEntityName,
                                             const tString &in asCallbackFunc,
                                             bool abAutoRemove)

Sets a callback for the message events in the currently playing animation.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• asCallbackFunc (tString) — the callback function. Syntx void Func(const tString &in asEntityName, const tString &in asAnimName, int alMessageEventID) (last arg is for future usage)
• abAutoRemove (bool) — If the callback is removed once triggered.

Returns:

• void

Entity_SetAnimationPaused

void Entity_SetAnimationPaused(const tString &in asEntityName,
                               const tString &in asAnimationName,
                               bool abPaused = true)

Pause or unpause an animation on the specified entity.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• asAnimationName (tString) — name of the animation.
• abPaused (bool) — true to pause, false to resume

Returns:

• void

Entity_SetAnimationRelativeTimePosition

void Entity_SetAnimationRelativeTimePosition(const tString &in asEntityName,
                                             const tString &in asAnimationName,
                                             float afTimePos)

Sets the relative time position of a specific animation.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• asAnimationName (tString) — name of the animation.
• afTimePos (float) — a value between 0 and 1, where 0 is the start of the animation and 1 is the end.

Returns:

• void

Entity_SetAutoSleep

void Entity_SetAutoSleep(const tString &in asName,
                         bool abX)

Sets if the entity should sleep automatically when it need no updating

Parameters

• asName (tString) — Name of the entity, Wildcard(s) * are supported
• abX (bool) — true = Entity will sleep automatically - false = entity will not sleep automatically

Returns:

• void

Entity_SetCollide

void Entity_SetCollide(const tString &in asEntityName,
                       bool abActive)

Turn off or on collision for all the bodies in the given entity.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• abActive (bool) — true = collision on, false = collision off.

Returns:

• void

Entity_SetCollideCharacter

void Entity_SetCollideCharacter(const tString &in asEntityName,
                                bool abActive)

Turn off or on character collision for all the bodies in the given entity.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• abActive (bool) — true = collision on, false = collision off.

Returns:

• void

Entity_SetColorMul

void Entity_SetColorMul(const tString &in asEntityName,
                        const cColor &in aColor)

Set the color mul of the entity

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• aColor (cColor) — color to set color mul to

Returns:

• void

Entity_SetConnectionStateChangeCallback

void Entity_SetConnectionStateChangeCallback(const tString &in asEntityName,
                                             const tString &in asCallback)

Sets the callback for when the connection state changes on an entity
Syntax for callback function: void FunctionName(string &in asEntityName, int alState).

Parameters

• asEntityName (tString) — the name of the entity to get the callback. Wildcard(s) * are supported.
• asCallback (tString) — the name of the callback function.

Returns:

• void

Entity_SetEffectBaseColor

void Entity_SetEffectBaseColor(const tString &in asEntityName,
                               const cColor &in aColor)

Sets the base color of the effects

Parameters

• asEntityName (tString) — name of the prop. Wildcard(s) * are supported.
• aColor (cColor) — the color all effects will be multiplied with

Returns:

• void

Entity_SetEffectsActive

void Entity_SetEffectsActive(const tString &in asEntityName,
                             bool abActive,
                             bool abFadeAndPlaySounds)

Activates or deactivates the effects on a entity.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• abActive (bool) — true = activates effects - false = deactivates effects.
• abFadeAndPlaySounds (bool) — if effects should fade in/out and sounds play.

Returns:

• void

Entity_SetInteractionDisabled

void Entity_SetInteractionDisabled(const tString &in asEntityName,
                                   bool abX)

Sets if the player can interact with an entity or not.

Parameters

• asEntityName (tString) — name of the entity, Wildcard(s) * are supported
• abX (bool) — true = interaction disabled - false = interaction enabled.

Returns:

• void

Entity_SetIsOccluder

void Entity_SetIsOccluder(const tString &in asName,
                          bool abOccluder)

Set if entity is an occluder

Parameters

• asName (tString) — Name of the entity, Wildcard(s) * are supported
• abOccluder (bool) — true = object is occluder

Returns:

• void

Entity_SetMaxInteractionDistance

void Entity_SetMaxInteractionDistance(const tString &in asEntityName,
                                      float afDistance)

Change the max interaction distance of an entity from the default/entity configured distance.

Parameters

• asEntityName (tString) — name of the entity, Wildcard(s) * are supported
• afDistance (float) — distance in meters that the entity can be interacted from.

Returns:

• void

Entity_SetPlayerInteractCallback

void Entity_SetPlayerInteractCallback(const tString &in asEntityName,
                                      const tString &in asCallback,
                                      bool abRemoveWhenInteracted)

Sets the callback for when the player interacts with a specific entity.
Syntax for callback function: void FunctionName(string &in asEntityName).

Parameters

• asEntityName (tString) — the name of the entity to get the callback. Wildcard(s) * are supported.
• asCallback (tString) — the name of the callback function.
• abRemoveWhenInteracted (bool) — if the callback should be removed after it has been called.

Returns:

• void

Entity_SetPlayerLookAtCallback

void Entity_SetPlayerLookAtCallback(const tString &in asEntityName,
                                    const tString &in asCallback,
                                    bool abRemoveWhenLookedAt = true,
                                    bool abCheckCenterOfScreen = true,
                                    bool abCheckRayIntersection = true,
                                    float afMaxDistance = -1,
                                    float afCallbackDelay = 0)

Sets the callback for when the player looks at or turns away from a specific entity.
Syntax for callback function: void FunctionName(const tString &in asEntityName, int alState). alState is 1 if the player looks at the entity and -1 if the player stops looking.

Parameters

• asEntityName (tString) — the name of the entity to get the callback. Wildcard(s) * are supported.
• asCallback (tString) — the name of the callback function. If set to will remove a previously set callback
• abRemoveWhenLookedAt (bool) — if the callback should be removed after it has been called.
• abCheckCenterOfScreen (bool) — if the entity counts as looked at only when at the center of the screen.
• abCheckRayIntersection (bool) — if the entity counts as looked at only if there is a clear line of sight to it. Note that this can return false negatives, especially when not checking center of screen.
• afMaxDistance (float) — max distance at which the entity must be for the callback to be triggered.
• afCallbackDelay (float) — time the player needs to look at the entity for the entity to trigger (in seconds).

Returns:

• void

Entity_SetProcAnimationPaused

void Entity_SetProcAnimationPaused(const tString &in asEntityName,
                                   const tString &in asAnimationName,
                                   bool abPaused = true)

Pause or unpause a procedural animation on the specified entity.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• asAnimationName (tString) — name of the animation.
• abPaused (bool) — true to pause, false to resume

Returns:

• void

Entity_SetProcAnimationSpeed

void Entity_SetProcAnimationSpeed(const tString &in asEntityName,
                                  const tString &in asAnimationName,
                                  float afSpeed)

Sets the speed of a proc animation.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• asAnimationName (tString) — name of the animation.
• afSpeed (float) — speed to set.

Returns:

• void

Entity_SetReflectionVisibility

void Entity_SetReflectionVisibility(const tString &in asEntityName,
                                    bool abVisibleInReflection,
                                    bool abVisibleInWorld)

Sets whether the entity is drawn in reflections or not, and the real world or not.

Parameters

• asEntityName (tString) — name of the prop. Wildcard(s) * are supported.
• abVisibleInReflection (bool) — whether the entity is drawn in reflections
• abVisibleInWorld (bool) — whether the entity is drawn in the real world

Returns:

• void

Entity_SetVarBool

void Entity_SetVarBool(const tString &in asEntityName,
                       const tString &in asVarName,
                       bool abX)

Sets the value of an entity boolean variable. Wildcard(s) * are supported for EntityName. *

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the boolean variable.
• abX (bool) — new value for the variable.

Returns:

• void

Entity_SetVarColor

void Entity_SetVarColor(const tString &in asEntityName,
                        const tString &in asVarName,
                        const cColor &in aX)

Sets the value of an entity color variable. Wildcard(s) * are supported for EntityName. *

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the color variable.
• aX (cColor) — new value for the variable.

Returns:

• void

Entity_SetVarFloat

void Entity_SetVarFloat(const tString &in asEntityName,
                        const tString &in asVarName,
                        float afX)

Sets the value of an entity variable. Wildcard(s) * are supported for EntityName. *

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the string variable.
• afX (float) — new value for the variable.

Returns:

• void

Entity_SetVarInt

void Entity_SetVarInt(const tString &in asEntityName,
                      const tString &in asVarName,
                      int alX)

Sets the value of an entity integer variable. Wildcard(s) * are supported for EntityName. *

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the integer variable.
• alX (int) — new value for the variable.

Returns:

• void

Entity_SetVarString

void Entity_SetVarString(const tString &in asEntityName,
                         const tString &in asVarName,
                         const tString &in asX)

Sets the value of an entity string variable. Wildcard(s) * are supported for EntityName. *

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the string variable.
• asX (tString) — new value for the variable.

Returns:

• void

Entity_SetVarVector2f

void Entity_SetVarVector2f(const tString &in asEntityName,
                           const tString &in asVarName,
                           const cVector2f &in avX)

Sets the value of an entity vector2f variable. Wildcard(s) * are supported for EntityName. *

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the vector2f variable.
• avX (cVector2f) — new value for the variable.

Returns:

• void

Entity_SetVarVector3f

void Entity_SetVarVector3f(const tString &in asEntityName,
                           const tString &in asVarName,
                           const cVector3f &in avX)

Sets the value of an entity vector3f variable. Wildcard(s) * are supported for EntityName. *

Parameters

• asEntityName (tString) — name of the entity.
• asVarName (tString) — name of the vector3f variable.
• avX (cVector3f) — new value for the variable.

Returns:

• void

Entity_Sleep

void Entity_Sleep(const tString &in asName)

Forces the entity to sleep (disabling Update/PostUpdate). Has no effect if it is already sleeping

Parameters

• asName (tString) — Name of the entity, Wildcard(s) * are supported

Returns:

• void

Entity_StopAnimation

void Entity_StopAnimation(const tString &in asEntityName)

Stops any currently playing animation on the specified entity.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.

Returns:

• void

Entity_StopProcAnimation

void Entity_StopProcAnimation(const tString &in asEntityName,
                              const tString &in asAnimation,
                              float afFadeTime = 0.1f)

Stops a procedural animation on the specified entity.

Parameters

• asEntityName (tString) — name of the entity. Wildcard(s) * are supported.
• asAnimation (tString) — name of the entity. Wildcard(s) * are supported.
• afFadeTime (float) — the time it takes to fade out.

Returns:

• void

Entity_WakeUp

void Entity_WakeUp(const tString &in asName)

Forces the entity to wake up (enabling Update/PostUpdate). Has no effect if it is already awake

Parameters

• asName (tString) — Name of the entity, Wildcard(s) * are supported

Returns:

• void