Menu
Lumberyard
Developer Guide (Version 1.12)

ScriptBind_Entity

CryLua is deprecated and will be removed in a future version of Lumberyard.

Lists the entity related Lua script bind functions.

Activate

Activates or deactivates the entity. Activate ignores the update policy and forces an entity to activate or deactivate. All active entities are updated every frame.

Warning

Having too many active entities can affect performance.

Syntax

Entity.Activate(int bActive)

Parameters

Parameter Description
bActive Specify true to make the entity active; false to make it inactive.

ActivateOutput

Syntax

Entity.ActivateOutput()

ActivatePlayerPhysics

Syntax

Entity.ActivatePlayerPhysics(bool bEnable)

AddConstraint

Syntax

Entity.AddConstraint()

AddImpulse

Apply an impulse to the entity. At least four parameters need to be provided for a linear impulse. For an additional angular impulse, at least seven parameters need to be provided.

Syntax

Entity.AddImpulse(ipart, position, direction, linearImpulse, linearImpulseScale, angularAxis, angularImpulse, massScale)

Parameters

Parameter Description
ipart The index of the part that receives the impulse.
position The point (in world coordinates) where the impulse is applied. Set this to (0, 0, 0) to ignore it.
direction The direction in which the impulse is applied.
linearImpulse The force of the linear impulse.
linearImpulseScale Scaling of the linear impulse. (Default: 1.0)
angularAxis The axis on which the angular impulse is applied.
angularImpulse The force of the angular impulse.
massScale Mass scaling of the angular impulse. (Default: 1.0)

AttachChild

Syntax

Entity.AttachChild(ScriptHandle childEntityId, int flags)

AttachSurfaceEffect

Syntax

Entity.AttachSurfaceEffect(int nSlot, const char *effect, bool countPerUnit, const char *form, const char *typ, float countScale, float sizeScale)

AuxAudioProxiesMoveWithEntity

Set whether AuxAudioProxies should move with the entity or not.

Syntax

Entity.AuxAudioProxiesMoveWithEntity(bool const bCanMoveWithEntity)

Returns: nil

Parameters

Parameter Description
bCanMoveWithEntity Boolean parameter to enable or disable

AwakeCharacterPhysics

Syntax

Entity.AwakeCharacterPhysics(int nSlot,const char *sRootBoneName,int nAwake)

AwakeEnvironment

Syntax

Entity.AwakeEnvironment()

AwakePhysics

Syntax

Entity.AwakePhysics(int nAwake)

BreakToPieces

Breaks static geometry in slot 0 into sub objects and spawn them as particles or entities.

Syntax

Entity.BreakToPieces(int nSlot, int nPiecesSlot, float fExplodeImp, Vec3 vHitPt, Vec3 vHitImp, float fLifeTime, bool bSurfaceEffects)

CalcWorldAnglesFromRelativeDir

Syntax

Entity.CalcWorldAnglesFromRelativeDir(Vec3 dir)

CancelSubpipe

Syntax

Entity.CancelSubpipe()

ChangeAttachmentMaterial

Syntax

Entity.ChangeAttachmentMaterial(const char *attachmentName, const char *materialName)

CharacterUpdateAlways

Syntax

Entity.CharacterUpdateAlways(int characterSlot, bool updateAlways)

CharacterUpdateOnRender

Syntax

Entity.CharacterUpdateOnRender(int characterSlot, bool bUpdateOnRender)

CheckCollisions

Syntax

Entity.CheckCollisions()

CheckShaderParamCallbacks

Check all the currently set shader param callbacks on the renderproxy with the current state of the entity.

Syntax

Entity.UpdateShaderParamCallback()

CloneMaterial

Replace material on the slot with a cloned version of the material. Cloned material can be freely changed uniquely for this entity.

Syntax

Entity.CloneMaterial(int slot)

Parameters

Parameter Description
slot ID of the slot on which to clone material.
sSubMaterialName If this is a non empty string this specific sub-material is cloned.

CopySlotTM

Copies the TM (Transformation Matrix) of the slot.

Syntax

Entity.CopySlotTM(int destSlot, int srcSlot, bool includeTranslation)

Parameters

Parameter Description
destSlot Destination slot identifier.
srcSlot Source slot identifier.
includeTranslation True to include the translation, false otherwise.

Counts all outgoing links of the entity.

Syntax

Entity.CountLinks()

Returns: Number of outgoing links.

CreateAuxAudioProxy

Creates an additional AudioProxy managed by the EntityAudioProxy. The created AuxAudioProxy will move and rotate with the parent EntityAudioProxy.

Syntax

Entity.CreateAuxAudioProxy()

Returns: Returns the ID of the additionally created AudioProxy.

CreateBoneAttachment

Syntax

Entity.CreateBoneAttachment(int characterSlot, const char *boneName, const char *attachmentName)

CreateCameraComponent

Create a camera component for the entity. Allows the entity to serve as camera source for material assigned to the entity.

Syntax

Entity.CreateCameraComponent()

CreateDRSProxy

Creates a Dynamic Response System Proxy

Syntax

Entity.CreateDRSProxy()

Returns: Returns the ID of the created proxy.

Creates a new outgoing link for this entity.

Syntax

Entity.CreateLink(const char *name)

Returns: nothing

Parameters

Parameter Description
name Name of the link. Does not have to be unique among all the links of this entity. Multiple links with the same name can coexist.
(optional) targetId If specified, the ID of the entity the link shall target. If not specified or 0 then the link will not target anything. Default value: 0

CreateRenderComponent

Create a render component object for the entity. Allows an entity to be rendered immediately without loading any assets.

Syntax

Entity.CreateRenderComponent()

CreateSkinAttachment

Syntax

Entity.CreateSkinAttachment(int characterSlot, const char *attachmentName)

Damage

Syntax

Entity.Damage()

DeleteParticleEmitter

Deletes particles emitter from 3dengine.

Syntax

Entity.DeleteParticleEmitter(int slot)

Parameters

Parameter Description
slot slot number

DeleteThis

Deletes the current entity.

Syntax

Entity.DeleteThis()

DestroyAttachment

Syntax

Entity.DestroyAttachment(int characterSlot, const char *attachmentName)

DestroyPhysics

Syntax

Entity.DestroyPhysics()

DetachAll

Syntax

Entity.DetachAll()

DetachThis

Syntax

Entity.DetachThis()

DisableAnimationEvent

Syntax

Entity.DisableAnimationEvent(int nSlot,const char *sAnimation)

DrawSlot

Enables/Disables drawing of object or character at specified slot of the entity.

Syntax

Entity.DrawSlot(int nSlot,int nEnable)

Parameters

Parameter Description
nSlot Slot identifier.
nEnable 1-Enable drawing, 0-Disable drawing.

EnableBoneAnimation

Syntax

Entity.EnableBoneAnimation(int characterSlot, int layer, const char *boneName, bool status)

EnableBoneAnimationAll

Syntax

Entity.EnableBoneAnimationAll(int characterSlot, int layer, bool status)

EnableDecals

Enables decals.

Syntax

Entity.EnableDecals(int slot, bool enable)

EnableInheritXForm

Enables/Disable entity from inheriting transformation from the parent.

Syntax

Entity.EnableInheritXForm(bool bEnable)

EnableMaterialLayer

Syntax

Entity.EnableMaterialLayer(bool enable, int layer)

EnablePhysics

Syntax

Entity.EnablePhysics(bool bEnable)

EnableProceduralFacialAnimation

Syntax

Entity.EnableProceduralFacialAnimation(bool enable)

ExecuteAudioTrigger

Execute the specified audio trigger and attach it to the entity. The created audio object will move and rotate with the entity.

Syntax

Entity.ExecuteAudioTrigger(ScriptHandle const hTriggerID, ScriptHandle const hAudioProxyLocalID)

Returns: nil

Parameters

Parameter Description
hTriggerID the audio trigger ID handle
hAudioProxyLocalID The ID of the AuxAudioProxy that is local to the EntityAudioProxy. To address the default AuxAudioProxy, pass 1. To address all AuxAudioProxy instances, pass 0.

FadeGlobalDensity

Sets the fade global density.

Syntax

Entity.FadeGlobalDensity(int nSlot, float fadeTime, float newGlobalDensity)

Parameters

Parameter Description
nSlot nSlot identifier.
fadeTime .
newGlobalDensity .

ForceCharacterUpdate

Syntax

Entity.ForceCharacterUpdate(int characterSlot, bool updateAlways)

ForwardTriggerEventsTo

Syntax

Entity.ForwardTriggerEventsTo(ScriptHandle entityId)

FreeAllSlots

Delete all objects on every slot part of the entity.

Syntax

Entity.FreeAllSlots()

FreeSlot

Delete all objects from specified slot.

Syntax

Entity.FreeSlot(int nSlot)

Parameters

Parameter Description
nSlot Slot identifier.

GetAIName

Syntax

Entity.GetAIName()

GetAllAuxAudioProxiesID

Returns the ID used to address all AuxAudioProxy of the parent EntityAudioProxy.

Syntax

Entity.GetAllAuxAudioProxiesID()

Returns: Returns the ID used to address all AuxAudioProxy of the parent EntityAudioProxy.

GetAngles

Gets the angle of the entity.

Syntax

Entity.GetAngles()

GetAnimationLength

Syntax

Entity.GetAnimationLength(int characterSlot, const char *animation)

GetAnimationTime

Syntax

Entity.GetAnimationTime(int nSlot,int nLayer)

GetArchetype

Retrieve the archetype of the entity.

Syntax

Entity.GetArchetype()

Returns: name of entity archetype, nil if no archetype.

GetAttachmentBone

Syntax

Entity.GetAttachmentBone(int characterSlot, const char *attachmentName)

GetAttachmentCGF

Syntax

Entity.GetAttachmentCGF(int characterSlot, const char *attachmentName)

GetBoneAngularVelocity

Syntax

Entity.GetBoneAngularVelocity(int characterSlot, const char *boneName)

GetBoneDir

Syntax

Entity.GetBoneDir()

GetBoneLocal

Syntax

Entity.GetBoneLocal(const char *boneName, Vec3 trgDir)

GetBoneNameFromTable

Syntax

Entity.GetBoneNameFromTable()

GetBonePos

Syntax

Entity.GetBonePos()

GetBoneVelocity

Syntax

Entity.GetBoneVelocity(int characterSlot, const char *boneName)

GetCenterOfMassPos

Gets the position of the entity center of mass.

Syntax

Entity.GetCenterOfMassPos()

GetCharacter

Gets the character for the specified slot if there is any.

Syntax

Entity.GetCharacter(int nSlot)

GetChild

Syntax

Entity.GetChild(int nIndex)

GetChildCount

Syntax

Entity.GetChildCount()

GetCurAnimation

Syntax

Entity.GetCurAnimation()

GetDefaultAuxAudioProxyID

Returns the ID of the default AudioProxy of the parent EntityAudioProxy.

Syntax

Entity.GetDefaultAuxAudioProxyID()

Returns: Returns the ID of the default AudioProxy of the parent EntityAudioProxy.

GetDirectionVector

Syntax

Entity.GetDirectionVector()

GetDistance

Syntax

float Entity.GetDistance(entityId)

Returns: The distance from entity specified with entityId/

GetEntitiesInContact

Syntax

Entity.GetEntitiesInContact()

GetEntityMaterial

Syntax

Entity.GetEntityMaterial()

GetExplosionImpulse

Syntax

Entity.GetExplosionImpulse()

GetExplosionObstruction

Syntax

Entity.GetExplosionObstruction()

GetFlags

Syntax

Entity.GetFlags()

GetFlagsExtended

Syntax

Entity.GetFlagsExtended()

GetGeomCachePrecachedTime

Gets time delta from current playback position to last ready to play frame.

Syntax

Entity.GetGeomCachePrecachedTime()

GetGravity

Syntax

Entity.GetGravity()

GetHelperAngles

Syntax

Entity.GetHelperAngles()

GetHelperDir

Syntax

Entity.GetHelperDir()

GetHelperPos

Syntax

Entity.GetHelperPos()

Returns the link at given index.

Syntax

Entity.GetLink()

Returns: The script table of the entity that the i'th link is targeting or nil if the specified index is out of bounds.

Parameters

Parameter Description
ith The index of the link that shall be returned.

GetLinkName

Returns the name of the link that is targeting the entity with given ID.

Syntax

Entity.GetLinkName(ScriptHandle targetId)

Returns: The name of the i'th link targeting given entity or nil if no such link exists.

Parameters

Parameter Description
targetId ID of the entity for which the link name shall be looked up.
(optional) ith If specified, the i'th link that targets given entity. Default value: 0 (first entity)

GetLinkTarget

Returns the ID of the entity that given link is targeting.

Syntax

Entity.GetLinkTarget(const char *name)

Returns: The ID of the entity that the link is targeting or nil if no such link exists.

Parameters

Parameter Description
name Name of the link.
(optional) ith If specified, the i'th link with given name for which to look up the targeted entity. Default value: 0 (first link with given name)

GetLocalAngles

Syntax

Vec3 Entity.GetLocalAngles(vAngles)

GetLocalBBox

Syntax

Entity.GetLocalBBox()

GetLocalPos

Syntax

Vec3 Entity.GetLocalPos()

GetLocalScale

Syntax

float Entity.GetLocalScale()

GetLodRatio

Syntax

Entity.GetLodRatio()

GetMass

Syntax

Entity.GetMass()

GetMaterial

Syntax

Entity.GetMaterial()

GetMaterialFloat

Change material parameter.

Syntax

Entity.GetMaterialFloat(int slot,int nSubMtlId,const char *sParamName)

Returns: Material parameter value.

Parameters

Parameter Description
slot ID of the slot on which slot to change material.
nSubMtlId Specify submaterial by Id.
sParamName Name of the material parameter.

GetMaterialVec3

Syntax

Entity.GetMaterialVec3(int slot,int nSubMtlId,const char *sParamName)

GetName

Syntax

Entity.GetName()

GetParent

Syntax

Entity.GetParent()

GetParentSlot

Syntax

Entity.GetParentSlot(int child)

GetPhysicalStats

Some more physics related.

Syntax

Entity.GetPhysicalStats()

GetPos

Gets the position of the entity.

Syntax

Entity.GetPos()

GetProjectedWorldBBox

Syntax

Entity.GetProjectedWorldBBox()

GetRawId

Returns entityId in raw numeric format.

Syntax

Entity.GetRawId()

GetScale

Gets the scaling value for the entity.

Syntax

Entity.GetScale()

GetSlotAngles

Gets the slot angles.

Syntax

Entity.GetSlotAngles(int nSlot)

Parameters

Parameter Description
nSlot nSlot identifier.

GetSlotCount

Gets the count of the slots.

Syntax

Entity.GetSlotCount()

GetSlotHelperPos

Syntax

Entity.GetSlotHelperPos(int slot, const char *helperName, bool objectSpace)

GetSlotPos

Gets the slot position.

Syntax

Entity.GetSlotPos(int nSlot)

Parameters

Parameter Description
nSlot nSlot identifier.

GetSlotScale

Gets the slot scale amount.

Syntax

Entity.GetSlotScale(int nSlot)

Parameters

Parameter Description
nSlot nSlot identifier.

GetSlotWorldDir

Gets the World direction of the slot.

Syntax

Entity.GetSlotWorldDir(int nSlot)

Parameters

Parameter Description
nSlot Slot identifier.

GetSlotWorldPos

Gets the World position of the slot.

Syntax

Entity.GetSlotWorldPos(int nSlot)

Parameters

Parameter Description
nSlot Slot identifier.

GetSpeed

Syntax

Entity.GetSpeed()

GetState

Syntax

Entity.GetState()

GetSubmergedVolume

Syntax

Entity.GetSubmergedVolume(int slot, Vec3 planeNormal, Vec3 planeOrigin)

GetTimeOfDayHour

Syntax

Entity.GetTimeOfDayHour()

Returns: current time of day as a float value.

GetTimeSinceLastSeen

Syntax

Entity.GetTimeSinceLastSeen()

GetTouchedPoint

Retrieves point of collision for rigid body.

Syntax

Entity.GetTouchedPoint()

GetTouchedSurfaceID

Syntax

Entity.GetTouchedSurfaceID()

GetTriggerBBox

Syntax

Entity.GetTriggerBBox()

GetUpdateRadius

Syntax

Entity.GetUpdateRadius()

GetVelocity

Syntax

Entity.GetVelocity()

GetVelocityEx

Syntax

Entity.GetVelocityEx()

GetViewDistanceMultiplier

Get the view distance multiplier.

Syntax

Entity.GetViewDistanceMultiplier()

GetVolume

Syntax

Entity.GetVolume(int slot)

GetWorldAngles

Syntax

Vec3 Entity.GetWorldAngles(vAngles)

GetWorldBBox

Syntax

Entity.GetWorldBBox()

GetWorldBoundsCenter

Gets the world bbox center for the entity (defaults to entity position if no bbox present).

Syntax

Entity.GetWorldBoundsCenter()

GetWorldDir

Syntax

Vec3 Entity.GetWorldDir()

GetWorldPos

Syntax

Vec3 Entity.GetWorldPos()

GetWorldScale

Syntax

float Entity.GetWorldScale()

GotoState

Syntax

Entity.GotoState(const char *sState)

HasFlags

Syntax

Entity.HasFlags(int flags)

HasFlagsExtended

Syntax

Entity.HasFlagsExtended(int flags)

Hide

Syntax

Entity.Hide()

HideAllAttachments

Syntax

Entity.HideAllAttachments(int characterSlot, bool hide, bool hideShadow)

HideAttachment

Syntax

Entity.HideAttachment(int characterSlot, const char *attachmentName, bool hide, bool hideShadow)

HideAttachmentMaster

Syntax

Entity.HideAttachmentMaster(int characterSlot, bool hide)

IgnorePhysicsUpdatesOnSlot

Ignore physics when updating the position of a slot.

Syntax

Entity.IgnorePhysicsUpdatesOnSlot(int nSlot)

Parameters

Parameter Description
nSlot Slot identifier.

InsertSubpipe

Syntax

Entity.InsertSubpipe()

IntersectRay

Syntax

Entity.IntersectRay(int slot, Vec3 rayOrigin, Vec3 rayDir, float maxDistance)

InvalidateTrigger

Syntax

Entity.InvalidateTrigger()

IsActive

Retrieve active status of entity.

Syntax

Entity.IsActive(bActivate)

Returns: true - Entity is active. false - Entity is not active.

IsAnimationRunning

Syntax

Entity.IsAnimationRunning(int characterSlot, int layer)

Returns: nil or not nil

Parameters

Parameter Description
characterSlot Index of the character slot.
layer Index of the animation layer.

IsColliding

Syntax

Entity.IsColliding()

IsEntityInside

Syntax

float Entity.IsEntityInside(entityId)

IsEntityInsideArea

Syntax

Entity.IsEntityInsideArea(int areaId, ScriptHandle entityId)

IsFromPool

Returns if the entity came from an entity pool.

Syntax

Entity.IsFromPool()

Returns: true - Entity is from a pool. (Bookmarked) false - Entity is not from a pool. (Not bookmarked)

IsGeomCacheStreaming

Syntax

Entity.IsGeomCacheStreaming()

Returns: true if geom cache is streaming.

IsHidden

Syntax

Entity.IsHidden()

IsInState

Syntax

Entity.IsInState(const char *sState)

IsPointInsideArea

Syntax

Entity.IsPointInsideArea(int areaId, Vec3 point)

IsSlotCharacter

Checks if the slot is a character.

Syntax

Entity.IsSlotCharacter(int slot)

Parameters

Parameter Description
slot Slot identifier.

IsSlotGeometry

Checks if the slot is a geometry.

Syntax

Entity.IsSlotGeometry(int slot)

Parameters

Parameter Description
slot Slot identifier.

IsSlotLight

Checks if the slot is a light.

Syntax

Entity.IsSlotLight(int slot)

Parameters

Parameter Description
slot Slot identifier.

IsSlotParticleEmitter

Checks if the slot is a particle emitter.

Syntax

Entity.IsSlotParticleEmitter(int slot)

Parameters

Parameter Description
slot Slot identifier.

IsSlotValid

Checks if the slot is valid.

Syntax

Entity.IsSlotValid(int nSlot)

Parameters

Parameter Description
nSlot Slot identifier.

IsUsingPipe

Syntax

Entity.IsUsingPipe()

Returns: True if the entity is running a goalpipe or has it inserted; otherwise, false.

KillTimer

Syntax

Entity.KillTimer()

LoadCharacter

Load CGF geometry into the entity slot.

Syntax

Entity.LoadCharacter(int nSlot,const char *sFilename)

Parameters

Parameter Description
nSlot Slot identifier.
sFilename CGF geometry file name.

LoadCloud

Loads the cloud XML file into the entity slot.

Syntax

Entity.LoadCloud(int nSlot, const char *sFilename)

Parameters

Parameter Description
nSlot Slot identifier.
sFilename Filename.

LoadFogVolume

Loads the fog volume XML file into the entity slot.

Syntax

Entity.LoadFogVolume(int nSlot, SmartScriptTable table)

Parameters

Parameter Description
nSlot Slot identifier.
table Table with fog volume properties.

LoadGeomCache

Load geom cache into the entity slot.

Syntax

Entity.LoadGeomCache(int nSlot,const char *sFilename)

Parameters

Parameter Description
nSlot Slot identifier.
sFilename CAX file name.

LoadLight

Load CGF geometry into the entity slot.

Syntax

Entity.LoadLight(int nSlot,SmartScriptTable table)

Parameters

Parameter Description
nSlot Slot identifier.
table Table with all the light information.

LoadObject

Load CGF geometry into the entity slot.

Syntax

Entity.LoadObject(int nSlot,const char *sFilename)

Parameters

Parameter Description
nSlot Slot identifier.
sFilename CGF geometry file name.

LoadObjectLattice

Load lattice into the entity slot.

Syntax

Entity.LoadObjectLattice(int nSlot)

LoadObjectWithFlags

Load CGF geometry into the entity slot.

Syntax

Entity.LoadObjectWithFlags(int nSlot,const char *sFilename, const int nFlags)

Parameters

Parameter Description
nSlot Slot identifier.
sFilename CGF geometry file name.
nFlags entity load flags

LoadParticleEffect

Loads CGF geometry into the entity slot.

Syntax

Entity.LoadParticleEffect(int nSlot, const char *sEffectName, SmartScriptTable table)

Parameters

Parameter Description
nSlot Slot identifier.
sEffectName Name of the particle effect (Ex: "explosions/rocket").
(optional) bPrime Whether effect starts fully primed to equilibrium state.
(optional) fPulsePeriod Time period between particle effect restarts.
(optional) fScale Size scale to apply to particles
(optional) fCountScale Count multiplier to apply to particles
(optional) bScalePerUnit Scale size by attachment extent
(optional) bCountPerUnit Scale count by attachment extent
(optional) sAttachType string for EGeomType
(optional) sAttachForm string for EGeomForm

LoadSubObject

Load geometry of one CGF node into the entity slot.

Syntax

Entity.LoadSubObject(int nSlot,const char *sFilename,const char *sGeomName)

Parameters

Parameter Description
nSlot Slot identifier.
sFilename CGF geometry file name.
sGeomName Name of the node inside CGF geometry.

LoadVolumeObject

Loads volume object.

Syntax

Entity.LoadVolumeObject(int nSlot, const char* sFilename)

Parameters

Parameter Description
nSlot Slot identifier.
sFilename File name of the volume object.

LookAt

Orient the entity to look at a world space position.

Syntax

Entity.LookAt(Vec3 target, Vec3 axis, float angle)

Parameters

Parameter Description
target The position to look at.
axis The correction axis. The quat type is not supported.
angle The correction angle inradians. The quat type is not supported.

MultiplyWithSlotTM

Multiplies with the TM (Transformation Matrix) of the slot.

Syntax

Entity.MultiplyWithSlotTM(int slot, Vec3 pos)

Parameters

Parameter Description
slot Slot identifier.
pos Position vector.

NetPresent

Syntax

Entity.NetPresent()

NoBulletForce

Syntax

Entity.NoBulletForce(bool state)

NoExplosionCollision

Syntax

Entity.NoExplosionCollision()

PassParamsToPipe

Syntax

Entity.PassParamsToPipe()

Physicalize

Create physical entity from the specified entity slot.

Syntax

Entity.Physicalize(int nSlot,int nPhysicsType,SmartScriptTable physicsParams)

Parameters

Parameter Description
nSlot Slot identifier of the entity to physicalize. Specify -1 to use geometries from all slots.
nPhysicsType Type of physical entity to create. For possible values, see the nPhysicsType Keys table later in this section.
physicsParams Table with physicalization parameters. For more information, see the physicsParams Table Keys table later in this section.

nPhysicsType Keys

Physics Type Meaning
PE_AREA Physical Area (Sphere,Box,Geometry or Shape).
PE_ARTICULATED Ragdolls or other articulated physical entities that consist of rigid bodies connected by joints.
PE_LIVING Live physical entity that can move through the physical world and interact with it.
PE_NONE No physics.
PE_PARTICLE A physical particle entity that it has only mass and radius.
PE_RIGID Rigid body physical entity. Can have infinite mass (specified by setting mass to 0).
PE_ROPE A physical representation of a rope. The rope can hang freely or connect two physical entities.
PE_SOFT A system of non-rigidly connected vertices that can interact with the environment. Used for soft body physics like cloth simulation.
PE_STATIC A static, immovable physical entity.
PE_WHEELEDVEHICLE Physical vehicle with wheels.

Note

For more information about physical entity types, see Physical Entities.

physicsParams Table Keys

Physics Parameter Description
area This table must be set when Physics Type is PE_AREA. For more information, see the Area Table Keys table later in this section.
density Object density, only used if mass is not specified or -1.
flags Physical entity flags.
living This table must be set when Physics Type is PE_LIVING. For more information, see the Living Table Keys table later in this section.
mass Object mass, only used if density is not specified or -1.
particle This table must be set when Physics Type is PE_PARTICLE. For more information, see the Particle Table Keys table later in this section.
partid Index of the articulated body part to which the new physical entity will be attached.
stiffness_scale Scale of character joint stiffness (multiplied with stiffness values specified from the exported model)

Particle Table Keys

Particle Parameter Description
accel_lift Acceleration that lifts particle with the current speed
accel_thrust Acceleration along direction of movement
air_resistance The air resistance coefficient, F = kv
constant_orientation (0,1) Keep constant orientation
gravity Gravity force vector to the air
mass Particle mass
min_bounce_vel Minimal velocity at which particle bounces off the surface
no_path_alignment (0,1) Do not align particle orientation to the movement path
no_roll (0,1) Do not roll particle on terrain
no_spin (0,1) Do not spin particle in air
radius Particle pseudo radius
single_contact (0,1) Calculate only one first contact
thickness Thickness when lying on a surface (if 0, the radius is used)
velocity Velocity direction and magnitude vector
water_gravity Gravity force vector when in the water.
water_resistance Water resistance coefficient, F = kv

Living Table Keys

Living Parameter Description
air_resistance Air control coefficient 0..1, 1 - special value (total control of movement)
gravity Vertical gravity magnitude
head_radius Radius of the head
height Vertical offset of collision geometry center
height_eye Vertical offset of the camera
height_head Vertical offset of the head
height_pivot Offset from central ground position that is considered the entity center
inertia Inertia coefficient, the greater the value, the less the inertia; 0 means no inertia.
mass Mass of the player (in kg)
max_climb_angle Player cannot climb surface which slope is steeper than this angle (in radians)
max_jump_angle Player is not allowed to jump towards ground if this angle is exceeded (in radians)
max_vel_ground Player cannot stand on surfaces that are moving faster than this (in radians)
min_fall_angle Player starts falling when slope is steeper than this (in radians)
min_slide_angle If surface slope is more than this angle, player starts sliding (in radians)
size Collision cylinder dimensions vector (x,y,z).

Area Table Keys

Area Parameter Description
box_max Max vector of bounding box, must be specified if type is AREA_BOX
box_min Min vector of bounding box, must be specified if type is AREA_BOX
falloff Ellipsoidal falloff dimensions; 0,0,0 specifies no falloff
gravity Gravity vector inside the physical area
height Height of the 2D area (AREA_SHAPE), relative to the minimal Z in the points table
points A table that contains an indexed collection of vectors in local entity space that define the 2D shape of the area (AREA_SHAPE)
radius Radius of the area sphere; must be specified if type is AREA_SPHERE.
type Type of the area, valid values are: AREA_SPHERE, AREA_BOX, AREA_GEOMETRY, or AREA_SHAPE
uniform Same direction in every point, or always point to the center.

PhysicalizeAttachment

Syntax

Entity.PhysicalizeAttachment(int characterSlot, const char* attachmentName, bool physicalize)

PhysicalizeSlot

Syntax

Entity.PhysicalizeSlot(int slot, SmartScriptTable physicsParams)

PlayFacialAnimation

Syntax

Entity.PlayFacialAnimation(char* name, bool looping)

PreLoadParticleEffect

Pre-loads a particle effect.

Syntax

Entity.PreLoadParticleEffect(const char *sEffectName)

Parameters

Parameter Description
sEffectName Name of the particle effect (Ex: "explosions/rocket").

ProcessBroadcastEvent

Syntax

Entity.ProcessBroadcastEvent()

RagDollize

Syntax

Entity.RagDollize(int slot)

ReattachSoftEntityVtx

Syntax

Entity.ReattachSoftEntityVtx(ScriptHandle entityId, int partId)

RedirectAnimationToLayer0

Syntax

Entity.RedirectAnimationToLayer0(int characterSlot, bool redirect)

RegisterForAreaEvents

Registers the script proxy so that it receives area events for this entity.

Syntax

Entity.RegisterForAreaEvents(int enable)

Parameters

Parameter Description
enable Specify 0 to disable, or any other value to enable.

Removes all links of an entity.

Syntax

Entity.RemoveAllLinks()

Returns: nothing

RemoveAuxAudioProxy

Removes the AuxAudioProxy corresponding to the passed ID from the parent EntityAudioProxy.

Syntax

Entity.RemoveAuxAudioProxy(ScriptHandle const hAudioProxyLocalID)

Returns: nil

Parameters

Parameter Description
hAudioProxyLocalID The ID of the AuxAudioProxy to be removed from the parent EntityAudioProxy.

RemoveDecals

Syntax

Entity.RemoveDecals()

Removes an outgoing link from the entity.

Syntax

Entity.RemoveLink(const char *name)

Returns: nothing

Parameters

Parameter Description
name Name of the link to remove.
(optional) ith If specified, the <i>th link with the name specified that will be removed. Default value: 0 (first link with given name)

RenderAlways

Enables 'always render' on the render node, skipping any kind of culling.

Syntax

Entity.RenderAlways(int enable)

Parameters

Parameter Description
enable Specify 0 to disable, or any other value to enable.

RenderShadow

Syntax

Entity.RenderShadow()

ReplaceMaterial

Syntax

Entity.ReplaceMaterial(int slot, const char *name, const char *replacement)

ResetAnimation

Syntax

Entity.ResetAnimation(int characterSlot, int layer)

ResetAttachment

Syntax

Entity.ResetAttachment(int characterSlot, const char *attachmentName)

ResetMaterial

Syntax

Entity.ResetMaterial(int slot)

ResetPhysics

Syntax

Entity.ResetPhysics()

SelectPipe

Syntax

Entity.SelectPipe()

SetAIName

Syntax

Entity.SetAIName()

SetAngles

Sets the angle of the entity.

Syntax

Entity.SetAngles(Ang3 vAngles)

Parameters

Parameter Description
vAngles Angle vector.

SetAnimateOffScreenShadow

Syntax

Entity.SetAnimateOffScreenShadow(bool bAnimateOffScreenShadow)

SetAnimationBlendOut

Syntax

Entity.SetAnimationBlendOut(int characterSlot, int layer, float blendOut)

SetAnimationEvent

Syntax

Entity.SetAnimationEvent(int nSlot,const char *sAnimation)

SetAnimationFlip

Syntax

Entity.SetAnimationFlip(int characterSlot, Vec3 flip)

SetAnimationKeyEvent

Syntax

Entity.SetAnimationKeyEvent(nSlot, sAnimation, nFrameID, sEvent)

SetAnimationSpeed

Syntax

Entity.SetAnimationSpeed(int characterSlot, int layer, float speed)

SetAnimationTime

Syntax

Entity.SetAnimationTime(int nSlot,int nLayer,float fTime)

SetAttachmentAngles

Syntax

Entity.SetAttachmentAngles(int characterSlot, const char *attachmentName, Vec3 angles)

SetAttachmentCGF

Syntax

Entity.SetAttachmentCGF(int characterSlot, const char *attachmentName, const char* filePath)

SetAttachmentDir

Syntax

Entity.SetAttachmentDir(int characterSlot, const char *attachmentName, Vec3 dir, bool worldSpace)

SetAttachmentEffect

Syntax

Entity.SetAttachmentEffect(int characterSlot, const char *attachmentName, const char *effectName, Vec3 offset, Vec3 dir, float scale, int flags)

SetAttachmentLight

Syntax

Entity.SetAttachmentLight(int characterSlot, const char *attachmentName, SmartScriptTable lightTable, int flags)

SetAttachmentObject

Syntax

Entity.SetAttachmentObject(int characterSlot, const char *attachmentName, ScriptHandle entityId, int slot, int flags)

SetAttachmentPos

Syntax

Entity.SetAttachmentPos(int characterSlot, const char *attachmentName, Vec3 pos)

SetAudioEnvironmentID

Sets the ID of the audio environment that an entity will specify for the entities that it contains.

Syntax

Entity.SetAudioEnvironmentID(ScriptHandle const hAudioEnvironmentID)

Returns: nil

Parameters

Parameter Description
hAudioEnvironmentID audio environment ID

SetAudioObstructionCalcType

Set the Audio Obstruction/Occlusion calculation type on the underlying GameAudioObject.

Syntax

Entity.SetAudioObstructionCalcType(int const nObstructionCalcType, ScriptHandle const hAudioProxyLocalID)

Returns: nil

Parameters

Parameter Description
nObstructionCalcType Obstruction/Occlusion calculation type; Possible values: 0 - ignore Obstruction/Occlusion 1 - use single physics ray 2 - use multiple physics rays (currently 5 per object)
hAudioProxyLocalID The ID of the AuxAudioProxy that is local to the EntityAudioProxy. To address the default AuxAudioProxy, pass 1. To address all AuxAudioProxy instances, pass 0.

SetAudioProxyOffset

Set offset on the audio proxy attached to the entity.

Syntax

Entity.SetAudioProxyOffset(Vec3 const vOffset, ScriptHandle const hAudioProxyLocalID)

Returns: nil

Parameters

Parameter Description
vOffset The offset vector
hAudioProxyLocalID The ID of the AuxAudioProxy that is local to the EntityAudioProxy. To address the default AuxAudioProxy, pass 1. To address all AuxAudioProxy instances, pass 0.

SetAudioRtpcValue

Set the specified audio RTPC to the specified value on the current entity.

Syntax

Entity.SetAudioRtpcValue(ScriptHandle const hRtpcID, float const fValue, ScriptHandle const hAudioProxyLocalID)

Returns: nil

Parameters

Parameter Description
hRtpcID The audio RTPC ID handle
fValue The RTPC value
hAudioProxyLocalID The ID of the AuxAudioProxy that is local to the EntityAudioProxy. To address the default AuxAudioProxy, pass 1. To address all AuxAudioProxy instances, pass 0.

SetAudioSwitchState

Set the specified audio switch to the specified state on the current Entity.

Syntax

Entity.SetAudioSwitchState(ScriptHandle const hSwitchID, ScriptHandle const hSwitchStateID, ScriptHandle const hAudioProxyLocalID)

Returns: nil

Parameters

Parameter Description
hSwitchID The audio switch ID handle
hSwitchStateID The switch state ID handle
hAudioProxyLocalID The ID of the AuxAudioProxy that is local to the EntityAudioProxy. To address the default AuxAudioProxy, pass 1. To address all AuxAudioProxy instances, pass 0.

SetCharacterPhysicParams

Syntax

Entity.SetCharacterPhysicParams()

SetCloudMovementProperties

Sets the cloud movement properties.

Syntax

Entity.SetCloudMovementProperties(int nSlot, SmartScriptTable table)

Parameters

Parameter Description
nSlot Slot identifier.
table Table property for the cloud movement.

SetColliderMode

Syntax

Entity.SetColliderMode(int mode)

SetCurrentAudioEnvironments

Sets the correct audio environment amounts based on the entity's position in the world.

Syntax

Entity.SetCurrentAudioEnvironments()

Returns: nil

SetDefaultIdleAnimations

Syntax

Entity.SetDefaultIdleAnimations()

SetDirectionVector

Syntax

Entity.SetDirectionVector(Vec3 dir)

SetEnvironmentFadeDistance

Sets the distance over which this entity fades the audio environment for all approaching entities.

Syntax

Entity.SetEnvironmentFadeDistance(float const fEnvironmentFadeDistance)

Returns: nil

Parameters

Parameter Description
fEnvironmentFadeDistance The fade distance in meters.

SetFadeDistance

Sets the distance at which this entity executes fade calculations.

Syntax

Entity.SetFadeDistance(float const fFadeDistance)

Returns: nil

Parameters

Parameter Description
fFadeDistance The fade distance in meters.

SetFlags

Mode: 0: or 1: and 2: xor

Syntax

Entity.SetFlags(int flags, int mode)

SetFlagsExtended

Mode: 0: or 1: and 2: xor

Syntax

Entity.SetFlagsExtended(int flags, int mode)

SetGeomCacheDrawing

Activates or deactivates geom cache drawing.

Syntax

Entity.SetGeomCacheDrawing(bool active)

SetGeomCacheParams

Sets geometry cache parameters.

Syntax

Entity.SetGeomCacheParams(bool looping, const char *standIn, const char *standInMaterial, const char *firstFrameStandIn, const char* firstFrameStandInMaterial, const char* lastFrameStandIn, const char* lastFrameStandInMaterial, float standInDistance, float streamInDistance)

SetGeomCachePlaybackTime

Sets the playback time.

Syntax

Entity.SetGeomCachePlaybackTime(float time)

SetGeomCacheStreaming

Activates/deactivates geom cache streaming.

Syntax

Entity.SetGeomCacheStreaming(bool active, float time)

SetLightColorParams

changes the color related params of an existing light.

Syntax

Entity.SetLightColorParams(int nSlot, Vec3 color, float specular_multiplier)

SetLinkTarget

Specifies the entity that an existing link shall target. Use this function to change the target of an existing link.

Syntax

Entity.SetLinkTarget(const char *name, ScriptHandle targetId)

Returns: nothing

Parameters

Parameter Description
name Name of the link that shall target given entity.
targetId The ID of the entity the link shall target. Pass in NULL_ENTITY to make the link no longer target an entity.
(optional) ith If specified, the <i>th link with given name that targets the specified entity. Default value: 0 (first link with given name)

SetLocalAngles

Syntax

Entity.SetLocalAngles(Ang3 vAngles)

SetLocalBBox

Syntax

Entity.SetLocalBBox(Vec3 vMin,Vec3 vMax)

SetLocalPos

Syntax

Entity.SetLocalPos(Vec3 vPos)

SetLocalScale

Syntax

Entity.SetLocalScale(float fScale)

SetLodRatio

Syntax

Entity.SetLodRatio()

SetMaterial

Syntax

Entity.SetMaterial()

SetMaterialFloat

Change material parameter.

Syntax

Entity.SetMaterialFloat(int slot,int nSubMtlId,const char *sParamName,float fValue)

Parameters

Parameter Description
slot ID of the slot on which to change material.
nSubMtlId Specify sub-material by ID.
sParamName Name of the material parameter.
fValue New material parameter value.

SetMaterialVec3

Syntax

Entity.SetMaterialVec3(int slot,int nSubMtlId,const char *sParamName,Vec3 fValue)

SetName

Syntax

Entity.SetName()

SetParentSlot

Syntax

Entity.SetParentSlot(int child, int parent)

SetPhysicParams

Syntax

Entity.SetPhysicParams()

SetPos

Sets the position of the entity.

Syntax

Entity.SetPos(Vec3 vPos)

Parameters

Parameter Description
vPos Position vector.

SetPublicParam

Sets a shader parameter.

Syntax

Entity.SetPublicParam()

Parameters

Parameter Description
paramName The name of the shader parameter.
value The new value of the parameter.

SetRegisterInSectors

Syntax

Entity.SetRegisterInSectors()

SetScale

Sets the scaling value for the entity.

Syntax

Entity.SetScale(float fScale)

Parameters

Parameter Description
fScale The scale amount.

SetScriptUpdateRate

Syntax

Entity.SetScriptUpdateRate(int nMillis)

SetSelfAsLightCasterException

Makes the entity render node a caster exception for the light loaded in nLightSlot.

Syntax

Entity.SetSelfAsLightCasterException(int nLightSlot)

Parameters

Parameter Description
nLightSlot Slot where the light is loaded.

SetSlotAngles

Sets the slot angles.

Syntax

Entity.SetSlotAngles(int nSlot, Ang3 v)

Parameters

Parameter Description
nSlot nSlot identifier.
v Angle to be set.

SetSlotHud3D

Setup flags for use as 3D HUD entity.

Syntax

Entity.SetSlotHud3D(int nSlot)

Parameters

Parameter Description
nSlot Slot identifier.

SetSlotPos

Sets the slot position.

Syntax

Entity.SetSlotPos(int slot,Vec3 v)

Parameters

Parameter Description
slot slot identifier.
v Position to be set.

SetSlotPosAndDir

Sets the slot position and direction.

Syntax

Entity.SetSlotPosAndDir(int nSlot, Vec3 pos, Vec3 dir)

Parameters

Parameter Description
nSlot nSlot identifier.
pos Position to be set.
dir Direction to be set.

SetSlotScale

Sets the slot scale amount.

Syntax

Entity.SetSlotScale(int nSlot,float fScale)

Parameters

Parameter Description
nSlot Slot identifier.
fScale Scale amount for the slot.

SetSlotWorldTM

Sets the World TM (transformation matrix) of the slot.

Syntax

Entity.SetSlotWorldTM(int nSlot, Vec3 pos, Vec3 dir)

Parameters

Parameter Description
nSlot Slot identifier.
pos Position vector.
dir Direction vector.

SetStateClientside

Syntax

Entity.SetStateClientside()

SetTimer

Syntax

Entity.SetTimer()

SetTriggerBBox

Syntax

Entity.SetTriggerBBox(Vec3 vMin,Vec3 vMax)

SetUpdatePolicy

Changes the update policy for the entity. Update policy controls when an entity becomes active or inactive (for example, when visible or when in close proximity).

Note

Because all active entities are updated every frame, having too many active entities can affect performance.

Syntax

Entity.SetUpdatePolicy(int nUpdatePolicy)

Parameters

Parameter Description
nUpdatePolicy Update policy constant. See the following table for possible values.

nUpdatePolicy Possible Values

Update Policy Meaning
ENTITY_UPDATE_NEVER Never update this entity.
ENTITY_UPDATE_IN_RANGE Activate entity when in specified radius.
ENTITY_UPDATE_POT_VISIBLE Activate entity when potentially visible.
ENTITY_UPDATE_VISIBLE Activate entity when visible in frustum.
ENTITY_UPDATE_PHYSICS Activate entity when physics awakes, deactivate when physics go to sleep.
ENTITY_UPDATE_PHYSICS_VISIBLE Same as ENTITY_UPDATE_PHYSICS, but also activates when visible.
ENTITY_UPDATE_ALWAYS

Entity is always active and updated every frame.

Note

For update policies that require a radius, use SetUpdateRadius.

SetUpdateRadius

Syntax

Entity.SetUpdateRadius()

SetVelocity

Syntax

Entity.SetVelocity(Vec3 velocity)

SetVelocityEx

Syntax

Entity.SetVelocityEx(Vec3 velocity, Vec3 angularVelocity)

SetViewDistanceMultiplier

Set the view distance multiplier.

Syntax

Entity.SetViewDistanceMultiplier()

SetViewDistUnlimited

Syntax

Entity.SetViewDistUnlimited()

SetVolumeObjectMovementProperties

Sets the properties of the volume object movement.

Syntax

Entity.SetVolumeObjectMovementProperties(int nSlot, SmartScriptTable table)

Parameters

Parameter Description
nSlot Slot identifier.
table Table with volume object properties.

SetWorldAngles

Syntax

Entity.SetWorldAngles(Ang3 vAngles)

SetWorldPos

Syntax

Entity.SetWorldPos(Vec3 vPos)

SetWorldScale

Syntax

Entity.SetWorldScale(float fScale)

StartAnimation

Syntax

Entity.StartAnimation()

StopAnimation

Syntax

Entity.StopAnimation(int characterSlot, int layer)

StopAudioTrigger

Stop the audio event generated by the trigger with the specified ID on this entity.

Syntax

Entity.StopAudioTrigger(ScriptHandle const hTriggerID, ScriptHandle const hAudioProxyLocalID)

Returns: nil

Parameters

Parameter Description
hTriggerID The audio trigger ID handle
hAudioProxyLocalID The ID of the AuxAudioProxy that is local to the EntityAudioProxy. To address the default AuxAudioProxy, pass 1. To address all AuxAudioProxy instances, pass 0.

ToGlobal

Syntax

Entity.ToGlobal(int slotId, Vec3 point)

ToLocal

Syntax

Entity.ToLocal(int slotId, Vec3 point)

TriggerEvent

Syntax

Entity.TriggerEvent()

UnSeenFrames

Syntax

Entity.UnSeenFrames()

UpdateAreas

Syntax

Entity.UpdateAreas()

UpdateLightClipBounds

Update the clip bounds of the light from the linked entities.

Syntax

Entity.UpdateLightClipBounds(int nSlot)

Parameters

Parameter Description
nSlot Slot identifier.

UpdateSlotPhysics

Syntax

Entity.UpdateSlotPhysics(int slot)

VectorToGlobal

Syntax

Entity.VectorToGlobal(int slotId, Vec3 dir)

VectorToLocal

Syntax

Entity.VectorToLocal(int slotId, Vec3 dir)

On this page: