Skip to main content
Version: bleeding-edge 🩸

Base Actor

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

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

ReturnsNameDescription
table of Base Actor GetAllReturns a table containing all Actors of the class this is called on
Base Actor GetByIndexReturns a specific Actor of this class at an index
number GetCountReturns how many Actors of this class exist
iterator GetPairsReturns an iterator with all Actors of this class to be used with pairs()

GetAll​

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

Returns table of Base Actor (copy of table containing all actors)
local ret = Actor.GetAll()

GetByIndex​

Returns a specific Actor of this class at an index

Returns Base Actor (Actor at index)
local ret = Actor.GetByIndex(index)
TypeParameterDefaultDescription
number indexthe index of the Actor

GetCount​

Returns how many Actors of this class exist

Returns number (number of Actors of this class)
local ret = Actor.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().


Returns iterator (Iterator with all Actors of this class)
local ret = Actor.GetPairs()

🦠 Functions​

caution

Some of the following methods may not work on certain Actor classes.

ReturnsNameDescription
AddImpulseApplies a force in world world to this Actor
AttachToAttaches this Actor to any other Actor, optionally at a specific bone
DestroyDestroys this Actor
DetachDetaches this Actor from AttachedTo Actor
SetCollisionSets this Actor's collision type
SetDimensionSets this Actor's Dimension
SetForceAdds a permanent force to this Actor, set to Vector(0, 0, 0) to cancel
SetGravityEnabledSets whether gravity is enabled on this Actor
SetVisibilitySets whether the actor is visible or not
SetHighlightEnabledSets whether the highlight is enabled on this Actor, and which highlight index to use
SetOutlineEnabledSets whether the outline is enabled on this Actor, and which outline index to use
SetLifeSpanSets the time (in seconds) before this Actor is destroyed. After this time has passed, the actor will be automatically destroyed.
SetLocationSets this Actor's location in the game world
SetRotationSets this Actor's rotation in the game world
SetRelativeLocationSets this Actor's relative location in local space (only if this actor is attached)
SetRelativeRotationSets this Actor's relative rotation in local space (only if this actor is attached)
SetScaleSets this Actor's scale
SetNetworkAuthoritySets the Player to have network authority over this Actor
SetValueSets a value in this Actor
TranslateToSmoothly moves this actor to a location over a certain time
RotateToSmoothly rotates this actor to an angle over a certain time
boolean IsBeingDestroyedReturns true if this Actor is being destroyed
boolean IsVisibleReturns true if this Actor is visible
boolean IsGravityEnabledReturns true if gravity is enabled on this Actor
boolean IsInWaterReturns true if this Actor is in water
boolean IsNetworkDistributedReturns true if this Actor is currently network distributed
boolean IsValidReturns true if this Actor is valid (i.e. wasn't destroyed and points to a valid Actor)
table of Base Actor GetAttachedEntitiesGets all Actors attached to this Actor
Base Actor or nilGetAttachedToGets the Actor this Actor is attached to
table GetBoundsGets this Actor's bounds
CollisionTypeGetCollisionGets this Actor's collision type
number GetIDGets the universal network ID of this Actor (same on both client and server)
Vector GetLocationGets this Actor's location in the game world
Rotator GetRotationGets this Actor's angle in the game world
Vector GetForceGets this Actor's force (set by SetForce())
boolean HasNetworkAuthorityReturns true if the local Player is currently the Network Authority of this Actor
boolean HasAuthorityGets if this Actor was spawned by the client side
Vector GetScaleGets this Actor's scale
string GetTypeGets the type of this Actor
any GetValueGets a value stored on this Actor at the given key. Please refer to Entity Values for more information
Vector GetVelocityGets this Actor's current velocity
AddActorTagAdds an Unreal Actor Tag to this Actor
RemoveActorTagRemoves an Unreal Actor Tag from this Actor
table of string GetActorTagsGets all Unreal Actor Tags on this Actor
function SubscribeSubscribes to an Event
UnsubscribeUnsubscribes all callbacks from this Event in this Actor within this Package, or only the callback passed

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)
my_actor:AddImpulse(force, velocity_change?)
TypeParameterDefaultDescription
Vector force
boolean velocity_change?falseWhether 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.

my_actor:AttachTo(other, attachment_rule?, bone_name?, lifespan_when_detached?, use_absolute_rotation?)
TypeParameterDefaultDescription
Base Actor otherOther actor to attach
AttachmentRuleattachment_rule?SnapToTargetHow to attach
string bone_name?Which bone to attach to
number lifespan_when_detached?-1Seconds before destroying this Actor when detached
boolean use_absolute_rotation?falseWhether to force attached object to use absolute rotation (will not follow parent)

Destroy​

Destroys this Actor
my_actor:Destroy()

Detach​

Detaches this Actor from AttachedTo Actor
my_actor:Detach()

SetCollision​

Sets this Actor's collision type
my_actor:SetCollision(collision_type)
TypeParameterDefaultDescription
CollisionTypecollision_type

SetDimension​

Sets this Actor's Dimension
my_actor:SetDimension(dimension)
TypeParameterDefaultDescription
number dimension

SetForce​

Adds a permanent force to this Actor, set to Vector(0, 0, 0) to cancel
my_actor:SetForce(force, is_local?)
TypeParameterDefaultDescription
Vector force
boolean is_local?trueWhether to apply the force in local space

SetGravityEnabled​

Sets whether gravity is enabled on this Actor
my_actor:SetGravityEnabled(is_enabled)
TypeParameterDefaultDescription
boolean is_enabled

SetVisibility​

Sets whether the actor is visible or not
my_actor:SetVisibility(is_visible)
TypeParameterDefaultDescription
boolean is_visible

SetHighlightEnabled​

Sets whether the highlight is enabled on this Actor, and which highlight index to use
my_actor:SetHighlightEnabled(is_enabled, index?)
TypeParameterDefaultDescription
boolean is_enabled
number index?0Index to use (should be 0, 12)

SetOutlineEnabled​

Sets whether the outline is enabled on this Actor, and which outline index to use
my_actor:SetOutlineEnabled(is_enabled, index?)
TypeParameterDefaultDescription
boolean is_enabled
number index?0Index to use (should be 0, 12)

SetLifeSpan​

Sets the time (in seconds) before this Actor is destroyed. After this time has passed, the actor will be automatically destroyed.
my_actor:SetLifeSpan(seconds)
TypeParameterDefaultDescription
number secondsSeconds before being destroyed

SetLocation​

Sets this Actor's location in the game world
my_actor:SetLocation(location)
TypeParameterDefaultDescription
Vector location

SetRotation​

Sets this Actor's rotation in the game world
my_actor:SetRotation(rotation)
TypeParameterDefaultDescription
Rotator rotation

SetRelativeLocation​

Sets this Actor's relative location in local space (only if this actor is attached)
my_actor:SetRelativeLocation(relative_location)
TypeParameterDefaultDescription
Vector relative_location

SetRelativeRotation​

Sets this Actor's relative rotation in local space (only if this actor is attached)
my_actor:SetRelativeRotation(relative_rotation)
TypeParameterDefaultDescription
Rotator relative_rotation

SetScale​

Sets this Actor's scale
my_actor:SetScale(scale)
TypeParameterDefaultDescription
Vector scale

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
my_actor:SetNetworkAuthority(player?)
TypeParameterDefaultDescription
Player player?nilNew player which will assume the Network Authority of this Actor

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
my_actor:SetValue(key, value, sync_on_clients?)
TypeParameterDefaultDescription
string key
any value
boolean sync_on_clients?falseServer side parameter, if enabled will sync this value with all clients

TranslateTo​

Smoothly moves this actor to a location over a certain time
my_actor:TranslateTo(location, time, exp?)
TypeParameterDefaultDescription
Vector location
number timeTime to interpolate from current location to target location
number exp?0Exponent used to smooth interpolation. Use 0 for linear movement

RotateTo​

Smoothly rotates this actor to an angle over a certain time
my_actor:RotateTo(rotation, time, exp?)
TypeParameterDefaultDescription
Rotator rotation
number timeTime to interpolate from current location to target location
number exp?0Exponent used to smooth interpolation. Use 0 for linear movement

IsBeingDestroyed​

Returns true 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 ()
local ret = my_actor:IsBeingDestroyed()

IsVisible​

Returns true if this Actor is visible

Returns boolean ()
local ret = my_actor:IsVisible()

IsGravityEnabled​

Returns true if gravity is enabled on this Actor

Returns boolean ()
local ret = my_actor:IsGravityEnabled()

IsInWater​

Returns true if this Actor is in water

Returns boolean ()
local ret = my_actor:IsInWater()

IsNetworkDistributed​

Returns true 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 ()
local ret = my_actor:IsNetworkDistributed()

IsValid​

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

Returns boolean ()
local ret = my_actor:IsValid()

GetAttachedEntities​

Gets all Actors attached to this Actor

Returns table of Base Actor ()
local ret = my_actor:GetAttachedEntities()

GetAttachedTo​

Gets the Actor this Actor is attached to

Returns Base Actor or nil ()
local ret = my_actor:GetAttachedTo()

GetBounds​

Gets this Actor's bounds

Returns table (in the format { Origin: Vector, BoxExtent: Vector, SphereRadius: number })
local ret = my_actor:GetBounds()

GetCollision​

Gets this Actor's collision type

Returns CollisionType ()
local ret = my_actor:GetCollision()

GetID​

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

Returns number ()
local ret = my_actor:GetID()

GetLocation​

Gets this Actor's location in the game world

Returns Vector ()
local ret = my_actor:GetLocation()

GetRotation​

Gets this Actor's angle in the game world

Returns Rotator ()
local ret = my_actor:GetRotation()

GetForce​

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

Returns Vector ()
local ret = my_actor:GetForce()

HasNetworkAuthority​

Returns true if the local Player is currently the Network Authority of this Actor

Returns boolean ()
local ret = my_actor:HasNetworkAuthority()

HasAuthority​

Gets if this Actor was spawned by the client side

Returns boolean (false if it was spawned by the Server or true if it was spawned by the client)
local ret = my_actor:HasAuthority()

GetScale​

Gets this Actor's scale

Returns Vector ()
local ret = my_actor:GetScale()

GetType​

Gets the type of this Actor

Returns string ()
local ret = my_actor:GetType()

GetValue​

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

Returns any (Value at key or fallback if key doesn't exist)
local ret = my_actor:GetValue(key, fallback)
TypeParameterDefaultDescription
string key
any fallbackFallback value if key doesn't exist

GetVelocity​

Gets this Actor's current velocity

Returns Vector ()
local ret = my_actor:GetVelocity()

AddActorTag​

Adds an Unreal Actor Tag to this Actor
my_actor:AddActorTag(tag)
TypeParameterDefaultDescription
string tag

RemoveActorTag​

Removes an Unreal Actor Tag from this Actor
my_actor:RemoveActorTag(tag)
TypeParameterDefaultDescription
string tag

GetActorTags​

Gets all Unreal Actor Tags on this Actor

Returns table of string ()
local ret = my_actor:GetActorTags()

Subscribe​

Subscribes to an Event

Returns function (Callback that was passed (useful for unsubscribing later if your callback is an anonymous function))
local ret = my_actor:Subscribe(event_name, callback)
TypeParameterDefaultDescription
string event_nameName of the event to subscribe to
function callbackFunction to call when the event is triggered

Unsubscribe​

Unsubscribes all callbacks from this Event in this Actor within this Package, or only the callback passed
my_actor:Unsubscribe(event_name, callback?)
TypeParameterDefaultDescription
string event_nameName of the event to unsubscribe from
function callback?nilOptional callback to unsubscribe

πŸš€ Events​

NameDescription
DestroyTriggered when an Actor is destroyed
SpawnTriggered when an Actor is spawned/created
ValueChangeTriggered when an Actor has a value changed with :SetValue()

Destroy​

Triggered when an Actor is destroyed
Actor.Subscribe("Destroy", function(self)

end)
TypeArgumentDescription
Base Actor selfThe Actor which that was destroyed

Spawn​

Triggered when an Actor is spawned/created
Actor.Subscribe("Spawn", function(self)

end)
TypeArgumentDescription
Base Actor selfThe Actor that was spawned

ValueChange​

Triggered when an Actor has a value changed with :SetValue()
Actor.Subscribe("ValueChange", function(self, key, value)

end)
TypeArgumentDescription
Base Actor selfThe Actor that just had a value changed
string keyThe key used
any valueThe value that was set