Skip to content

Entity

Entity is a physical item in the world, viewable in the world tree when editing the game. Entities contain any number of scripts and widgets, and can have a maximum of 1 "physical" component (mesh, light). Additionally there are two special types that derive from Entity (Player and User).

Functions

Function Name Usage Description Notes
IsValid bool Entity.IsValid(Entity entityOrNill) Returns true if the parameter passed to it is a valid entity
IsA bool entity:IsA(table derivedType)
GetName string entity:GetName() Get the name of this Entity.
GetWorld World entity:GetWorld() Get the World from an Entity (currently all entities in a game exist within the same World). Deprecated
RevertClientProperty entity:RevertClientProperty(string propertyName) Revert a property that's been changed on the client back to the server's value for it Client Only
SetPosition entity:SetPosition(Vector position) Set the position of this Entity in 3D space.
AlterPosition number entity:AlterPosition(Vector position, number time) Move from current to position over time.
AlterPosition number entity:AlterPosition(Vector fromPosition, Vector toPosition, number time) Move from fromPosition to toPosition over time.
GetPosition Vector entity:GetPosition() Get the position of this Entity.
SetRotation entity:SetRotation(Rotation rotation) Set the rotation of this Entity.
AlterRotation number entity:AlterRotation(Rotation rotation, number time) Rotate from current to rotation over time.
AlterRotation number entity:AlterRotation(Rotation fromRotation, Rotation toRotation, number time) Rotate from fromRotation to toRotation over time.
GetRotation Rotation entity:GetRotation() Get the rotation of this Entity.
SetRelativePosition entity:SetRelativePosition(Vector position) Set the position of this Entity relative to whatever this entity is parented to.
AlterRelativePosition number entity:AlterRelativePosition(Vector position, number time) Move from current to position over time relative to whatever this entity is parented to.
AlterRelativePosition number entity:AlterRelativePosition(Vector fromPosition, Vector toPosition, number time) Move from fromPosition to toPosition over time relative to whatever this entity is parented to.
GetRelativePosition Vector entity:GetRelativePosition() Get the position of this Entity relative to whatever this entity is parented to.
SetRelativeRotation entity:SetRelativeRotation(Rotation rotation) Set the rotation of this Entity relative to whatever this entity is parented to.
AlterRelativeRotation number entity:AlterRelativeRotation(Rotation rotation, number time) Rotate from current to rotation over time relative to whatever this entity is parented to.
AlterRelativeRotation number entity:AlterRelativeRotation(Rotation fromRotation, Rotation toRotation, number time) Rotate from fromRotation to toRotation over time relative to whatever this entity is parented to.
GetRelativeRotation Rotation entity:GetRelativeRotation() Get the rotation of this Entity relative to whatever this entity is parented to.
GetForward Vector entity:GetForward() Get the forward facing vector of an Entity from its rotation.
GetRight Vector entity:GetRight() Get the right facing vector of an Entity from its rotation.
GetUp Vector entity:GetUp() Get the up facing vector of an Entity from its rotation.
SetForward entity:SetForward(Vector forward) Set the rotation of an Entity to make its front face in a given direction.
SetForward entity:SetForward(Vector forward, Vector up) Set the rotation of an Entity to make its front face in a given direction, and its top point in another.
PlaySound unknown entity:PlaySound(SoundAsset sound) Play a sound Asset on this Entity, returning a Handle which can be used to stop the sound.
PlaySound unknown entity:PlaySound(SoundAsset sound, number fadeIn) Play a sound Asset on this Entity, returning a Handle which can be used to stop the sound. Fades in over the given fadeIn time.
PlaySound unknown entity:PlaySound(SoundAsset sound, number fadeIn, string groupName) Play a sound Asset on this Entity, returning a Handle which can be used to stop the sound. Fades in over the given fadeIn time. Fades out any sound already playing in the GroupName with the given fadeIn time.
PlaySound2D unknown entity:PlaySound2D(SoundAsset sound) Play a sound Asset on this Entity but without a 3D transform on the sound (useful for UI sounds, stereo music stings, etc).
PlaySound2D unknown entity:PlaySound2D(SoundAsset sound, number fadeIn) Play a sound Asset on this Entity but without a 3D transform on the sound (useful for UI sounds, stereo music stings, etc). Fades in over the given fadeIn time.
PlaySound2D unknown entity:PlaySound2D(SoundAsset sound, number fadeIn, string groupName) Play a sound Asset on this Entity but without a 3D transform on the sound (useful for UI sounds, stereo music stings, etc). Fades in over the given fadeIn time. Fades out any sound already playing in the GroupName with the given fadeIn time.
PlaySoundAtLocation unknown entity:PlaySoundAtLocation(Vector location, SoundAsset sound) Play a sound Asset on this Entity at the given location.
PlaySoundAtLocation unknown entity:PlaySoundAtLocation(Vector location, SoundAsset sound, number fadeIn) Play a sound Asset on this Entity at the given location. Fades in over the given fadeIn time.
PlaySoundAtLocation unknown entity:PlaySoundAtLocation(Vector location, SoundAsset sound, number fadeIn, string groupName) Play a sound Asset on this Entity at the given location. Fades in over the given fadeIn time. Fades out any sound already playing in the GroupName with the given fadeIn time.
StopSound entity:StopSound() Given a sound Handle stop the sound on this Entity.
StopSound entity:StopSound(number fadeOut) Given a sound Handle stop the sound on this Entity. Fade the sound out over the given fadeOut time.
PlayEffect unknown entity:PlayEffect(EffectAsset effect) Play a particle effect Asset on this Entity, returning a Handle which can be used to stop the effect.
PlayEffect unknown entity:PlayEffect(EffectAsset effect, bool attached) Play a particle effect Asset on this Entity, returning a Handle which can be used to stop the effect. Optionally the effect is attached to the entity and so all spawned particles are relative to it.
PlayEffectAtLocation unknown entity:PlayEffectAtLocation(Vector location, Rotation rotation, EffectAsset effect) Play a particle effect Asset at a given world location and rotation, returning a Handle which can be used to stop the effect.
PlayEffectAtLocation unknown entity:PlayEffectAtLocation(Vector location, Rotation rotation, EffectAsset effect, bool attached) Play a particle effect Asset at a given world location and rotation, returning a Handle which can be used to stop the effect. Optionally the effect is attached to the entity and so all spawned particles are relative to it.
StopEffect entity:StopEffect()
Clone Entity entity:Clone() Clone the Entity returning the clone. Server Only
AttachTo entity:AttachTo(Entity entityToAttachTo) Attach this Entity to another Entity Server Only
AttachTo entity:AttachTo(Character characterToAttachTo, string socketName) Attach this Entity to a Character entity, using the named socket Server Only
Detach entity:Detach()
ApplyDamage entity:ApplyDamage(number damageAmount, HitResult hitResult, Vector shootDirection, Entity fromEntity) Apply damageAmount damage to the Entity (by calling OnDamage on it on any scripts that override that), also pass a HitResult from a World Raycast function and a shootDirection Vector and fromEntity which will be passed to the OnDamage function.
ApplyDamage entity:ApplyDamage(number damageAmount, HitResult hitResult, Vector shootDirection, Entity fromEntity, table damageModifiers) Apply damageAmount damage to the Entity (by calling OnDamage on it on any scripts that override that), also pass a HitResult from a World Raycast function and a shootDirection Vector and fromEntity which will be passed to the OnDamage function. DamageModifiers is a table of { voxel = <voxelasset>, damageMultiplier = <number> } tables, and/or scripts that have voxel and damageMultiplier properties: { name = "voxel", type = "voxelasset" } and { name = "damageMultiplier", type = "number" }. damageModifiers = { { voxel = <voxelasset>, damageMultiplier = <number> }, { voxel = <voxelasset>, damageMultiplier = <number> }, <script>, <script> }
ApplyDamage entity:ApplyDamage(number damageAmount, Vector shootDirection, Entity fromEntity) Apply damageAmount damage to the Entity (by calling OnDamage on it on any scripts that override that), also pass a shootDirection Vector and fromEntity which will be passed to the OnDamage function.
ApplyDamage entity:ApplyDamage(number damageAmount, Vector shootDirection, Entity fromEntity, table damageModifiers) Apply damageAmount damage to the Entity (by calling OnDamage on it on any scripts that override that), also pass a shootDirection Vector and fromEntity which will be passed to the OnDamage function. DamageModifiers is a table of { voxel = <voxelasset>, damageMultiplier = <number> } tables, and/or scripts that have voxel and damageMultiplier properties: { name = "voxel", type = "voxelasset" } and { name = "damageMultiplier", type = "number" }. damageModifiers = { { voxel = <voxelasset>, damageMultiplier = <number> }, { voxel = <voxelasset>, damageMultiplier = <number> }, <script>, <script> }
GetParent Entity entity:GetParent() Get a parent Entity that this Entity is attached to either within the world tree or using the Attach function.
GetChildren table entity:GetChildren() Get all children directly below this. The order of children is not guaranteed, and may change randomly.
Destroy entity:Destroy() Destroy an Entity. Use with care as any variables referencing that Entity will now be invalid. Server Only
SendToScripts entity:SendToScripts(string eventName, ... args) Call eventName function with the given args on all scripts that have it as a function. If called on the server do it only on the server, if called on a client do it only on that client.
SendToAllClients entity:SendToAllClients(string eventName, ... args) Call eventName on all scripts of this Entity on all clients connected to the server with the given args. Server Only
SendToServer entity:SendToServer(string eventName, ... args) Call eventName on all script of this Entity on the server. Local Only
SendToLocal entity:SendToLocal(string eventName, ... args) Call eventName on all scripts of this Entity on the client that owns the Player or User this script is attached to. Server Only
IsLocal bool entity:IsLocal() See if this Entity is owned by the local client. Local Only
IsClient bool entity:IsClient() Check if this Entity is on the client Deprecated
FindScript Script entity:FindScript(string scriptName) This is alternative to entity.scriptName which is the preferred way of getting a script.
FindScript Script entity:FindScript(string scriptName, bool recursive) This is alternative to entity.scriptName which is the preferred way of getting a script. This can be recursive to find the script on any child entities.
FindScript Script entity:FindScript(ScriptAsset templateRefScript) Find a script by its script asset.
FindScript Script entity:FindScript(ScriptAsset templateRefScript, bool recursive) Find a script by its script asset. This can be recursive to find the script on any child entities.
FindScriptProperty object entity:FindScriptProperty(string propertyName) Find a script with the named property on it and return value from the property
FindAllScripts table entity:FindAllScripts(string scriptName) Find all scripts named scriptName recursively on this entity and all child entities. Most often used where multiple scripts are used to simulate an array of structures.
FindAllScripts table entity:FindAllScripts(ScriptAsset templateRefScript) Find all scripts of the given script asset recursively on this entity and all child entities. Most often used where multiple scripts are used to simulate an array of structures.
FindAllScripts table entity:FindAllScripts(string scriptName, bool recursive) Find all scripts named scriptName on this entity (and optionally recursively on all child entities if recursive flag is set). Most often used where multiple scripts are used to simulate an array of structures.
FindAllScripts table entity:FindAllScripts(ScriptAsset templateRefScript, bool recursive) Find all scripts of the given script asset on this entity (and optionally recursively on all child entities if recursive flag is set). Most often used where multiple scripts are used to simulate an array of structures.
FindWidget Widget entity:FindWidget(string widgetName) This is alternative to entity.widgetName which is the preferred way of getting a widget.
FindWidget Widget entity:FindWidget(string widgetName, bool recursive) This is alternative to entity.widgetName which is the preferred way of getting a widget. This can be recursive to find the widget on any child entities.
FindWidget Widget entity:FindWidget(WidgetAsset widget) Find a widget by its widget asset.
FindWidget Widget entity:FindWidget(WidgetAsset widget, bool recursive) Find a widget by its widget asset. This can be recursive to find the widget on any child entities.
IsLocalReady bool entity:IsLocalReady() When called with an Entity that is owned by a particular client this sees if that Entity has been inited on that client (by calling LocalInit). Server Only
SendTelemetry entity:SendTelemetry(string type, table parametersTable) Send an type of telemetry event to the telemetry server with the given parametersTable for later analysis. Deprecated and will be removed - see Analytics.SendTelemetry Deprecated
PlayTimeline number entity:PlayTimeline(... args) Play a timeline from variable args. Each key on the timeline is a number for time in seconds followed by a Vector and/or Rotation. An optional easing type can be given for each key, which describes how to interpolate between the previous key and this one, from EaseIn, EaseOut, EaseInOut, Linear (default) The easing types can also be set per axis, this is described in one of the examples. Example
PlayTimelineLoop entity:PlayTimelineLoop(... args) Loop a timeline from variable args. See the documentation in the main PlayTimeline function.
PlayTimelinePingPong entity:PlayTimelinePingPong(... args) Loop a timeline back and forth from variable args. See the documentation in the main PlayTimeline function.
PlayRelativeTimeline number entity:PlayRelativeTimeline(... args) Play a timeline, relative to an entity's parent transform, from variable args. See the documentation in the main PlayTimeline function.
PlayRelativeTimelineLoop number entity:PlayRelativeTimelineLoop(... args) Loop a timeline, relative to an entity's parent transform, from variable args. See the documentation in the main PlayTimeline function.
PlayRelativeTimelinePingPong number entity:PlayRelativeTimelinePingPong(... args) Loop a timeline back and forth, relative to an entity's parent transform, from variable args. See the documentation in the main PlayTimeline function.
CancelTimeline entity:CancelTimeline() Cancel any running timeline
GetTemplate Template entity:GetTemplate() Given an entity, get the Template it is an instance of (if there is one). Warning - this will return the template even if lots of things have been adjusted on the instance.
GetVelocity Vector entity:GetVelocity() Get Velocity. Centimeters per second.
SetVelocity entity:SetVelocity(Vector velocity) Set Velocity. Centimeters per second.
GetAngularVelocity Rotation entity:GetAngularVelocity() Get AngularVelocity. Degrees per second.
SetAngularVelocity entity:SetAngularVelocity(Rotation angularVelocity) Set AngularVelocity. Degrees per second.

Parameters

Parameter Name Usage Description Notes
visible bool visible Set whether any physical aspect of the Entity (generally a mesh or a light) is visible within the world.
onInteract Event onInteract Called when this entity is interacted with by a player, with the player Character and the HitResult passed as arguments, as well as the Entity from which the onInteract event was sent. An alternative to listening for OnInteract in a script on the entity.
onDestroy Event onDestroy Called when this entity is destroyed, with the Entity which sent the event passed as an argument. An alternative to listening for OnDestroy in a script on the entity.

Overrides

Override Name Usage Description Notes
index object entity.var Get a script or widget from the Entity by name, or a mesh, light, etc component on this entity. ie entity.myScript returns a script called myScript, entity.theHud returns a widget named theHud, entity.mesh returns the Mesh of this Entity, entity.light returns the property bag for a light component...

Examples

number entity:PlayTimeline(... args)

The following example shows a simple timeline with three positions over a ten second timeline. This will play once when the code is executed. Each change of position is interpolated with EaseInOut.

self:GetEntity():PlayTimeline(
  0.0,                   -- time of first position
  Vector.New(0, 0, 0),   -- first position
  5.0,
  Vector.New(0, 0, 100),
  "EaseInOut",
  10.0,
  Vector.New(100, 0, 100),
  "EaseInOut"
)
The following example shows a timeline which changes both position and rotation of the script's entity.
self:GetEntity():PlayTimeline(
  0.0,
  Vector.New(0, 0, 0),
  Rotation.New(0, 0, 0),
  1.0,
  Vector.New(0, 0, 100),
  Rotation.New(180, 0, 0)
)
The following example shows a timeline which simulates a bouncing ball by moving linearly in the X axis but using EaseOut on the up movement and EaseIn on the down movement to simulate the top of a bounce.
self:GetEntity():PlayTimeline(
  0.0,
  Vector.New(0, 0, 0),
  1.0,
  Vector.New(100, 0, 100),
  { z = "EaseOut", },
  2.0,
  Vector.New(200, 0, 0),
  { z = "EaseIn", }
)
You can pass the values to PlayTimeline as a table, allowing for procedural generation of a path. This example generates a circlulr path by appending times and positions to a table, and then passes the resulting table to PlayTimeline
local timeline = {}
for time = 0, 8 do
  -- insert time of this keyframe into the timeline table
  table.insert(timeline, time)
  -- insert position into timeline table using some maths to make a circle
  table.insert(timeline,
    Vector.New(
      100 * math.cos(time * math.pi / 4),
      -100 * math.sin(time * math.pi / 4),
      0
       )
  )
end
self:GetEntity():PlayTimeline(timeline)