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 (Character 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	`SoundHandle entity:PlaySound(SoundAsset sound)`	Play a sound Asset on this Entity, returning a Handle which can be used to stop the sound.
PlaySound	`SoundHandle 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	`SoundHandle 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.
PlaySound	`SoundHandle entity:PlaySound(SoundAsset sound, table properties)`	Play a sound Asset on this Entity, returning a Handle which can be used to stop the sound. Takes a table containing the optional parameters `fadeIn`, `pitch`, `volume` and `groupName`. (Pitch: 1 = Default, 0.5 = half speed, 2 = 2 times faster) (Volume: 0 = Silent, 1 = Full volume)
PlaySound2D	`SoundHandle 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	`SoundHandle 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	`SoundHandle 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.
PlaySound2D	`SoundHandle entity:PlaySound2D(SoundAsset sound, table properties)`	Play a sound Asset on this Entity but without a 3D transform on the sound (useful for UI sounds, stereo music stings, etc). Takes a table containing the optional parameters `fadeIn`, `pitch`, `volume` and `groupName`. (Pitch: 1 = Default, 0.5 = half speed, 2 = 2 times faster) (Volume: 0 = Silent, 1 = Full volume)
PlaySoundAtLocation	`SoundHandle entity:PlaySoundAtLocation(Vector location, SoundAsset sound)`	Play a sound Asset on this Entity at the given location.
PlaySoundAtLocation	`SoundHandle 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	`SoundHandle 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.
PlaySoundAtLocation	`SoundHandle entity:PlaySoundAtLocation(Vector location, SoundAsset sound, table properties)`	Play a sound Asset on this Entity at the given location. Takes a table containing the optional parameters `fadeIn`, `pitch`, `volume` and `groupName`. (Pitch: 1 = Default, 0.5 = half speed, 2 = 2 times faster) (Volume: 0 = Silent, 1 = Full volume)
StopSound	`entity:StopSound(SoundHandle handle)`	Given a sound Handle stop the sound on this Entity.
StopSound	`entity:StopSound(SoundHandle handle, number fadeOut)`	Given a sound Handle stop the sound on this Entity. Fade the sound out over the given fadeOut time.
PlayEffect	`EffectHandle entity:PlayEffect(EffectAsset effect)`	Play a particle effect Asset on this Entity, returning a Handle which can be used to stop the effect.
PlayEffect	`EffectHandle 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	`EffectHandle 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	`EffectHandle 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(EffectHandle handle)`
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(CharacterBase 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
FindWidgetProperty	`object entity:FindWidgetProperty(string propertyName)`	Find a widget 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
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
new_index	`entity.var = object value`
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)