Version: latest - a1.7.0 ⚖️

Base Actor

Base class for all Actor entities

An Actor is an object which can be spawned and destroyed through Lua. Actors support 3D transformations such as translation (location), rotation, and scale.

In nanos world, Actor is the base for several entities, and all those entities share the same Methods and Events described in this page.

info

This is the base class for all Actors we have. You cannot spawn it directly.

Static Functions

tip

Note: The following functions are accessed statically using the specific class with a dot. Example: Character.GetAll().

Returns	Name	Description
table	`GetAll`	Returns a table containing all Actors of the class this is called on (copy)
Actor	`GetByIndex`	Returns a specific Actor of this class at an index (direct)
number	`GetCount`	Returns how many Actors of this class exist (direct)
iterator	`GetPairs`	Returns an iterator with all Actors of this class (direct)

Functions

caution

Note: Some of the following methods don't work with certain Actor classes.

Returns	Name	Description
	`AddImpulse`	Applies a Force in world space to this Actor
	`AttachTo`	Attaches this Actor to another Actor
	`Destroy`	Destroys this Actor
	`Detach`	Detaches this Actor if attached
	`SetCollision`	Sets this Actor's collision type
	`SetForce`	Adds a permanent force to this Actor
	`SetGravityEnabled`	Sets whether gravity is enabled on this Actor
	`SetVisibility`	Sets the Actor visibility
	`SetHighlightEnabled`	Sets whether the highlight is enabled on this Actor, and which highlight index to use
	`SetOutlineEnabled`	Sets whether the outline is enabled on this Actor, and which outline index to use
	`SetLifeSpan`	Sets the time (in seconds) before this Actor is destroyed
	`SetLocation`	Sets this Actor's location in the game world
	`SetNetworkAuthority`	Sets the Player this Actor will have its physics calculated on Network Authority
	`SetRelativeLocation`	Sets this Actor's relative location in local space
	`SetRelativeRotation`	Sets this Actor's relative rotation in local space
	`SetRotation`	Sets this Actor's rotation in the game world
	`SetScale`	Sets this Actor's scale
	`SetValue`	Sets a value in this Actor, which can be accessed by any package
	`TranslateTo`	Smoothly moves this Actor to the specified location
	`RotateTo`	Smoothly rotates this Actor to the specified angle
boolean	`HasNetworkAuthority`	Gets if the LocalPlayer is currently the Network Authority of this Actor
boolean	`HasAuthority`	Gets if this Actor was spawned by the client side
boolean	`IsBeingDestroyed`	Gets if this Actor is being destroyed
boolean	`IsGravityEnabled`	Gets whether gravity is enabled on this Actor
boolean	`IsVisible`	Gets whether this actor is Visible or not
boolean	`IsInWater`	Gets if this Actor is in water
boolean	`IsNetworkDistributed`	Gets if this Actor is currently Network Distributed
boolean	`IsValid`	Returns if this Actor is valid (i.e. not destroyed)
table	`GetAttachedEntities`	Gets all Actors attached to this Actor
any	`GetAttachedTo`	Gets the Actor this Actor is attached to
table	`GetBounds`	Gets this Actor's bounds
number	`GetCollision`	Gets this Actor's collision type
number	`GetID`	Gets the universal network ID of this Actor
Vector	`GetLocation`	Gets this Actor's location in the game world
Rotator	`GetRotation`	Gets this Actor's angle in the game world
Vector	`GetForce`	Gets this Actor's scale
Vector	`GetScale`	Gets this Actor's scale
string	`GetType`	Gets the type of this Actor
any	`GetValue`	Gets a value stored on this Actor at the given key
Vector	`GetVelocity`	Returns this Actor's current velocity
string	`AddActorTag`	Adds an Unreal Actor Tag to this Actor
string	RemoveActorTag`	Remove an Unreal Actor Tag from this Actor
table	`GetActorTags`	Gets all Unreal Actor Tags from this Actor
function	`Subscribe`	Subscribes to an Event
	`Unsubscribe`	Unsubscribes from an Event

Events

	Name	Description
	`Destroy`	Triggered when an Actor is destroyed
	`Spawn`	Triggered when an Actor is spawned/created
	`ValueChange`	Triggered when an Actor has a value changed with `:SetValue()`

Static Functions Detailed

`GetAll`

Returns a table containing all Actors of the class this is called on

local entities_copy = Player.GetAll()
entities_copy[1] -- Player 1
entities_copy[5] -- Player 5

`GetByIndex`

Returns a specific Actor of this class at an index

local first_character = Character.GetByIndex(1)

Type	Parameter	Description
number	`index`	The index of the Actor

`GetCount`

Returns how many Actors of this class exist

local player_count = Player.GetCount()

`GetPairs`

Returns an iterator with all Actors of this class to be used with pairs(). This is a more performant method than GetAll(), as it will return the iterator to access the Actors directly instead of creating and returning a copy of the Actors table.
Note: Destroying Actors from inside a GetPairs() loop will cause the iterable to change size during the process. If you want to loop-and-destroy, please use GetAll().

for k, player in pairs(Player.GetPairs()) do
    Package.Log(player:GetName() .. " is connected!")
end

Functions Detailed

`AddImpulse`

Applies a force in world world to this Actor (the force is applied client side, by, in most cases, the player closest to this Actor)

entity:AddImpulse(force, velocity_change)

Type	Parameter	Default Value	Description
Vector	`force`		Force to apply
boolean	`velocity_change`	`false`	Whether to ignore mass

`AttachTo`

Attaches this Actor to any other Actor, optionally at a specific bone
AttachmentRule.KeepRelative will keep the current relative position/rotation if already attached.
AttachmentRule.KeepWorld will calculate the new relative position/rotation so the Actor stays at the same position after being attached.
AttachmentRule.SnapToTarget will set the Actor to the same position/rotation as other_actor (or at the bone location) and reset its relative position/rotation to zero.
Setting lifespan_when_detached to 0 will automatically destroy this actor when detached, setting it to 10 will destroy this after 10 seconds when detached.

entity:AttachTo(other_actor, attachment_rule, bone_name, lifespan_when_detached)

Type	Parameter	Default Value	Description
Actor	`other`		Other actor to attach
AttachmentRule	`attachment_rule`	`SnapToTarget`	How to attach
string	`bone_name`	`""`	Which bone to attach to
number	`lifespan_when_detached`	`-1`	Seconds before destroying this Actor when detached

`Destroy`

Destroys this Actor

entity:Destroy()

`Detach`

Detaches this Actor from AttachedTo Actor

entity:Detach()

`SetCollision`

Sets this Actor's collision type

entity:SetCollision(collision_type)

Type	Parameter	Default Value	Description
CollisionType	`collision_type`		Collision Type

`SetForce`

Adds a permanent force to this Actor, set to Vector(0, 0, 0) to cancel

entity:SetForce(force, is_local)

Type	Parameter	Default Value	Description
Vector	`force`		Force to apply
boolean	`is_local`	`true`	Whether to apply the force at local space

`SetGravityEnabled`

Sets whether gravity is enabled on this Actor

entity:SetGravityEnabled(is_enabled)

Type	Parameter	Default Value	Description
boolean	`is_enabled`

`SetVisibility`

Sets whether the actor is visible or not

entity:SetVisibility(is_visible)

Type	Parameter	Default Value	Description
boolean	`is_visible`

`SetHighlightEnabled`

Sets whether the highlight is enabled on this Actor, and which highlight index to use

entity:SetHighlightEnabled(is_enabled, index)

Type	Parameter	Default Value	Description
boolean	`is_enabled`		Whether the highlight should be enabled
number	`index`	`0`	Index to use (should be `0`, `1` or `2`)

`SetOutlineEnabled`

Sets whether the outline is enabled on this Actor, and which outline index to use

entity:SetOutlineEnabled(is_enabled, index)

Type	Parameter	Default Value	Description
boolean	`is_enabled`		Whether the outline should be enabled
number	`index`	`0`	Index to use (should be `0`, `1` or `2`)

`SetLifeSpan`

Sets the time (in seconds) before this Actor is destroyed. After this time has passed, the actor will be automatically destroyed.

entity:SetLifeSpan(seconds)

Type	Parameter	Default Value	Description
number	`seconds`		Seconds before being destroyed

`SetLocation`

Sets this Actor's location in the game world

entity:SetLocation(vector)

Type	Parameter	Default Value	Description
Vector	`location`		New location

`SetNetworkAuthority`

Sets the Player to have network authority over this Actor. This Player will be manually assigned to handle this Actor's physics and share its location with other clients. The authority assignment will still be overridden by the game automatically
Please refer to Network Authority for more information

entity:SetNetworkAuthority(player)

Type	Parameter	Default Value	Description
Player	`player`	`nil`	New player which will assume the Network Authority of this Actor

`SetRotation`

Sets this Actor's rotation in the game world

entity:SetRotation(rotator)

Type	Parameter	Default Value	Description
Rotator	`rotation`		New rotation

`SetRelativeLocation`

Sets this Actor's relative location in local space (only if this actor is attached)

entity:SetRelativeLocation(relative_location)

Type	Parameter	Default Value	Description
Vector	`relative_location`		New relative location

`SetRelativeRotation`

Sets this Actor's relative rotation in local space (only if this actor is attached)

entity:SetRelativeRotation(relative_rotation)

Type	Parameter	Default Value	Description
Rotator	`relative_rotation`		New relative rotation

`SetScale`

Sets this Actor's scale

entity:SetScale(vector)

Type	Parameter	Default Value	Description
Vector	`scale`		New scale

`SetValue`

Sets a value in this Actor, which can be accessed by any package (optionally sync on clients if called from server)
Please refer to Entity Values for more information

entity:SetValue(key, value, sync_on_clients)

Type	Parameter	Default Value	Description
string	`key`		Key
any	`value`		Value
boolean	`sync_on_clients`	`false`	Server side parameter, if enabled will sync this value with all clients

`TranslateTo`

Smoothly moves this actor to a location during a certain time

entity:TranslateTo(location, time, exp)

Type	Parameter	Default Value	Description
Vector	`location`		Location to translate to
number	`time`		Time to interp from current location to target location
number	`exp`	`0`	Exponential used to smooth interp, use `0` for linear movement

`RotateTo`

Smoothly rotates this Actor to an angle during a certain time

entity:RotateTo(rotation, time, exp)

Type	Parameter	Default Value	Description
Rotator	`rotation`		Angle to rotate to
number	`time`		Time to interp from current rotation to target rotation
number	`exp`	`0`	Exponential used to smooth interp, use `0` for linear movement

`IsBeingDestroyed`

Gets if this Actor is being destroyed (you can check this inside events like Drop to see if a Pickable is being dropped because it's going to be destroyed)
Returns boolean

entity:IsBeingDestroyed()

`IsVisible`

Gets whether this actor is visible
Returns boolean

entity:IsVisible()

`IsGravityEnabled`

Gets whether gravity is enabled on this Actor
Returns boolean

entity:IsGravityEnabled()

`IsInWater`

Gets if this Actor is in water
Returns boolean

entity:IsInWater()

`IsNetworkDistributed`

Gets if this Actor is currently network distributed. Only actors being network distributed can have their network authority set Entities have NetworkDistributed automatically disabled when: Attached, Possessed, Grabbed, Picked Up or Driving
Returns boolean

entity:IsNetworkDistributed()

`IsValid`

Gets if this Actor is valid (i.e. wasn't destroyed and points to a valid Actor)
Returns boolean

entity:IsValid()

`GetAttachedEntities`

Gets all Actors attached to this Actor
Returns table

entity:GetAttachedEntities()

`GetAttachedTo`

Gets the Actor this Actor is attached to
Returns any

entity:GetAttachedTo()

`GetBounds`

Gets this Actor's bounds
Returns table in the format {"Origin", "BoxExtent", "SphereRadius"}

entity:GetBounds()

`GetCollision`

Gets this Actor's collision type
Returns number

entity:GetCollision()

`GetID`

Gets the universal network ID of this Actor (same on both client and server)
Returns number

entity:GetID()

`GetLocation`

Gets this Actor's location in the game world
Returns Vector

entity:GetLocation()

`GetRotation`

Gets this Actor's angle in the game world
Returns Rotator

entity:GetRotation()

`GetForce`

Gets this Actor's force (set by SetForce)
Returns Vector

entity:GetForce()

`HasNetworkAuthority`

Gets if the LocalPlayer is currently the Network Authority of this Actor
Returns boolean

entity:HasNetworkAuthority()

`HasAuthority`

Gets if this Actor was spawned by the client side. Returns false if it was spawned by the Server or true if it was spawned by the client
Returns boolean

entity:HasAuthority()

`GetScale`

Gets this Actor's scale
Returns Vector

entity:GetScale()

`GetType`

Gets the type of this Actor
Returns string

entity:GetType()

`GetValue`

Gets a value stored on this Actor at the given key. Please refer to Entity Values for more information
Returns any

entity:GetValue(key, fallback)

Type	Parameter	Default Value	Description
string	`key`		Key
any	`fallback`		Fallback value if key doesn't exist

`GetVelocity`

Returns this Actor's current velocity
Returns Vector

entity:GetVelocity()

`AddActorTag`

Adds an Unreal Actor Tag to this Actor

entity:AddActorTag(tag)

Type	Parameter	Default Value	Description
string	`tag`

`RemoveActorTag`

Remove an Unreal Actor Tag from this Actor

entity:RemoveActorTag(tag)

Type	Parameter	Default Value	Description
string	`tag`

`GetActorTags`

Gets all Unreal Actor Tags from this Actor
Returns table

entity:GetActorTags()

`Subscribe`

Subscribes to an Event

entity:Subscribe(event_name, callback)

Type	Parameter	Default Value	Description
string	`event_name`		Name of the event to subscribe to
function	`function`		Event callback

`Unsubscribe`

Unsubscribes all callbacks from this Event in this Actor within this Package, optionally passing the function to unsubscribe only that callback

entity:Unsubscribe(event_name, callback)

Type	Parameter	Default Value	Description
string	`event_name`		Name of the event to unsubscribe from
function	`function`	`nil`	Optional callback to unsubscribe

Events Detailed

`Destroy`

Triggered when an Actor is destroyed

Vehicle.Subscribe("Destroy", function(self)
    -- called when any vehicle is destroyed
end)

Type	Parameter	Description
Actor	`self`	The Actor which has been destroyed

`Spawn`

Triggered when an Actor is spawned/created

Vehicle.Subscribe("Spawn", function(self)
    -- called when a vehicle is spawned
end)

Type	Parameter	Description
Actor	`self`	The Actor which has been spawned

`ValueChange`

Triggered when an Actor has a value changed with :SetValue()

Vehicle.Subscribe("ValueChange", function(self, key, value)
    -- called when any Vehicle had it's value changed with :SetValue()
end)

Type	Parameter	Description
Actor	`self`	The Actor that just had a value changed
string	`key`	The key used
any	`value`	The value changed

info

Static Functions​

tip

Functions​

caution

Events​

Static Functions Detailed​

GetAll​

GetByIndex​

GetCount​

GetPairs​

Functions Detailed​

AddImpulse​

AttachTo​

Destroy​

Detach​

SetCollision​

SetForce​

SetGravityEnabled​

SetVisibility​

SetHighlightEnabled​

SetOutlineEnabled​

SetLifeSpan​

SetLocation​

SetNetworkAuthority​

SetRotation​

SetRelativeLocation​

SetRelativeRotation​

SetScale​

SetValue​

TranslateTo​

RotateTo​

IsBeingDestroyed​

IsVisible​

IsGravityEnabled​

IsInWater​

IsNetworkDistributed​

IsValid​

GetAttachedEntities​

GetAttachedTo​

GetBounds​

GetCollision​

GetID​

GetLocation​

GetRotation​

GetForce​

HasNetworkAuthority​

HasAuthority​

GetScale​

GetType​

GetValue​

GetVelocity​

AddActorTag​

RemoveActorTag​

GetActorTags​

Subscribe​

Unsubscribe​

Events Detailed​

Destroy​

Spawn​

ValueChange​

Static Functions

Functions

Events

Static Functions Detailed

`GetAll`

`GetByIndex`

`GetCount`

`GetPairs`

Functions Detailed

`AddImpulse`

`AttachTo`

`Destroy`

`Detach`

`SetCollision`

`SetForce`

`SetGravityEnabled`

`SetVisibility`

`SetHighlightEnabled`

`SetOutlineEnabled`

`SetLifeSpan`

`SetLocation`

`SetNetworkAuthority`

`SetRotation`

`SetRelativeLocation`

`SetRelativeRotation`

`SetScale`

`SetValue`

`TranslateTo`

`RotateTo`

`IsBeingDestroyed`

`IsVisible`

`IsGravityEnabled`

`IsInWater`

`IsNetworkDistributed`

`IsValid`

`GetAttachedEntities`

`GetAttachedTo`

`GetBounds`

`GetCollision`

`GetID`

`GetLocation`

`GetRotation`

`GetForce`

`HasNetworkAuthority`

`HasAuthority`

`GetScale`

`GetType`

`GetValue`

`GetVelocity`

`AddActorTag`

`RemoveActorTag`

`GetActorTags`

`Subscribe`

`Unsubscribe`

Events Detailed

`Destroy`

`Spawn`

`ValueChange`