HPL3/SOMA/Scripting/Scripting Api/Entity

This page has been automatically generated, but it needs descriptions added to the various fields/functions in order to be complete.

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

HPL3/SOMA/Scripting/Scripting Api/Entity

Contents

Summary

Function Detail

Entity_AddCollideCallback

Entity_AddForce

Entity_AddForceFromEntity

Entity_AddImpulse

Entity_AddImpulseFromEntity

Entity_AddTorque

Entity_AttachToEntity

Entity_AttachToSocket

Entity_CallEntityInteract

Entity_Connect

Entity_CreateAtEntity

Entity_CreateAtEntityExt

Entity_Destroy

Entity_EntityIsInFront

Entity_Exists

Entity_Exists

Entity_FadeEffectBaseColor

Entity_FadeProcAnimationSpeed

Entity_GetAutoSleep

Entity_GetBodyOffset

Entity_GetCollide

Entity_GetDeltaToEntity

Entity_GetVarBool

Entity_GetVarColor

Entity_GetVarFloat

Entity_GetVarInt

Entity_GetVarString

Entity_GetVarVector2f

Entity_GetVarVector3f

Entity_IncVarFloat

Entity_IncVarInt

Entity_IncVarVector2f

Entity_IncVarVector3f

Entity_IsActive

Entity_IsInPlayerFOV

Entity_IsInteractedWith

Entity_IsOccluder

Entity_IsSleeping

Entity_PlaceAtEntity

Entity_PlayAnimation

Entity_PlayerIsInFront

Entity_PlayProcAnimation

Entity_Preload

Entity_RemoveAllConnections

Entity_RemoveCollideCallback

Entity_RemoveConnection

Entity_RemoveEntityAttachment

Entity_SetActive

Entity_SetAnimationMessageEventCallback

Entity_SetAnimationPaused

Entity_SetAnimationRelativeTimePosition

Entity_SetAutoSleep

Entity_SetCollide

Entity_SetCollideCharacter

Entity_SetColorMul

Entity_SetConnectionStateChangeCallback

Entity_SetEffectBaseColor

Entity_SetEffectsActive

Entity_SetInteractionDisabled

Entity_SetIsOccluder

Entity_SetMaxInteractionDistance

Entity_SetPlayerInteractCallback

Entity_SetPlayerLookAtCallback

Entity_SetProcAnimationPaused

Entity_SetProcAnimationSpeed

Entity_SetReflectionVisibility

Entity_SetVarBool

Entity_SetVarColor

Entity_SetVarFloat

Entity_SetVarInt

Entity_SetVarString

Entity_SetVarVector2f

Entity_SetVarVector3f

Entity_Sleep

Entity_StopAnimation

Entity_StopProcAnimation