Skip to main content
Version: bleeding-edge 🩸

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().

ReturnsNameDescription
tableGetAllReturns a table containing all Actors of the class this is called on (copy)
ActorGetByIndexReturns a specific Actor of this class at an index (direct)
numberGetCountReturns how many Actors of this class exist (direct)
iteratorGetPairsReturns an iterator with all Actors of this class (direct)

Functions​

caution

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

ReturnsNameDescription
AddImpulseApplies a Force in world space to this Actor
AttachToAttaches this Actor to another Actor
DestroyDestroys this Actor
DetachDetaches this Actor if attached
SetCollisionSets this Actor's collision type
SetForceAdds a permanent force to this Actor
SetGravityEnabledSets whether gravity is enabled on this Actor
SetVisibilitySets the Actor visibility
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
SetLocationSets this Actor's location in the game world
SetNetworkAuthoritySets the Player this Actor will have its physics calculated on Network Authority
SetRelativeLocationSets this Actor's relative location in local space
SetRelativeRotationSets this Actor's relative rotation in local space
SetRotationSets this Actor's rotation in the game world
SetScaleSets this Actor's scale
SetValueSets a value in this Actor, which can be accessed by any package
TranslateToSmoothly moves this Actor to the specified location
RotateToSmoothly rotates this Actor to the specified angle
booleanHasNetworkAuthorityGets if the LocalPlayer is currently the Network Authority of this Actor
booleanHasAuthorityGets if this Actor was spawned by the client side
booleanIsBeingDestroyedGets if this Actor is being destroyed
booleanIsGravityEnabledGets whether gravity is enabled on this Actor
booleanIsVisibleGets whether this actor is Visible or not
booleanIsInWaterGets if this Actor is in water
booleanIsNetworkDistributedGets if this Actor is currently Network Distributed
booleanIsValidReturns if this Actor is valid (i.e. not destroyed)
tableGetAttachedEntitiesGets all Actors attached to this Actor
anyGetAttachedToGets the Actor this Actor is attached to
tableGetBoundsGets this Actor's bounds
numberGetCollisionGets this Actor's collision type
numberGetIDGets the universal network ID of this Actor
VectorGetLocationGets this Actor's location in the game world
RotatorGetRotationGets this Actor's angle in the game world
VectorGetForceGets this Actor's scale
VectorGetScaleGets this Actor's scale
stringGetTypeGets the type of this Actor
anyGetValueGets a value stored on this Actor at the given key
VectorGetVelocityReturns this Actor's current velocity
stringAddActorTagAdds an Unreal Actor Tag to this Actor
stringRemoveActorTag`Remove an Unreal Actor Tag from this Actor
tableGetActorTagsGets all Unreal Actor Tags from this Actor
functionSubscribeSubscribes to an Event
UnsubscribeUnsubscribes from an Event

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()

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)
TypeParameterDescription
numberindexThe 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)
TypeParameterDefault ValueDescription
VectorforceForce to apply
booleanvelocity_changefalseWhether 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)
TypeParameterDefault ValueDescription
ActorotherOther actor to attach
AttachmentRuleattachment_ruleSnapToTargetHow to attach
stringbone_name""Which bone to attach to
numberlifespan_when_detached-1Seconds 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)
TypeParameterDefault ValueDescription
CollisionTypecollision_typeCollision Type

SetForce​

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

entity:SetForce(force, is_local)
TypeParameterDefault ValueDescription
VectorforceForce to apply
booleanis_localtrueWhether to apply the force at local space

SetGravityEnabled​

Sets whether gravity is enabled on this Actor

entity:SetGravityEnabled(is_enabled)
TypeParameterDefault ValueDescription
booleanis_enabled

SetVisibility​

Sets whether the actor is visible or not

entity:SetVisibility(is_visible)
TypeParameterDefault ValueDescription
booleanis_visible

SetHighlightEnabled​

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

entity:SetHighlightEnabled(is_enabled, index)
TypeParameterDefault ValueDescription
booleanis_enabledWhether the highlight should be enabled
numberindex0Index 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)
TypeParameterDefault ValueDescription
booleanis_enabledWhether the outline should be enabled
numberindex0Index 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)
TypeParameterDefault ValueDescription
numbersecondsSeconds before being destroyed

SetLocation​

Sets this Actor's location in the game world

entity:SetLocation(vector)
TypeParameterDefault ValueDescription
VectorlocationNew 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)
TypeParameterDefault ValueDescription
PlayerplayernilNew player which will assume the Network Authority of this Actor

SetRotation​

Sets this Actor's rotation in the game world

entity:SetRotation(rotator)
TypeParameterDefault ValueDescription
RotatorrotationNew rotation

SetRelativeLocation​

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

entity:SetRelativeLocation(relative_location)
TypeParameterDefault ValueDescription
Vectorrelative_locationNew relative location

SetRelativeRotation​

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

entity:SetRelativeRotation(relative_rotation)
TypeParameterDefault ValueDescription
Rotatorrelative_rotationNew relative rotation

SetScale​

Sets this Actor's scale

entity:SetScale(vector)
TypeParameterDefault ValueDescription
VectorscaleNew 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)
TypeParameterDefault ValueDescription
stringkeyKey
anyvalueValue
booleansync_on_clientsfalseServer 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)
TypeParameterDefault ValueDescription
VectorlocationLocation to translate to
numbertimeTime to interp from current location to target location
numberexp0Exponential 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)
TypeParameterDefault ValueDescription
RotatorrotationAngle to rotate to
numbertimeTime to interp from current rotation to target rotation
numberexp0Exponential 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)
TypeParameterDefault ValueDescription
stringkeyKey
anyfallbackFallback 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)
TypeParameterDefault ValueDescription
stringtag

RemoveActorTag​

Remove an Unreal Actor Tag from this Actor

entity:RemoveActorTag(tag)
TypeParameterDefault ValueDescription
stringtag

GetActorTags​

Gets all Unreal Actor Tags from this Actor

Returns table

entity:GetActorTags()

Subscribe​

Subscribes to an Event

entity:Subscribe(event_name, callback)
TypeParameterDefault ValueDescription
stringevent_nameName of the event to subscribe to
functionfunctionEvent 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)
TypeParameterDefault ValueDescription
stringevent_nameName of the event to unsubscribe from
functionfunctionnilOptional callback to unsubscribe

Events Detailed​

Destroy​

Triggered when an Actor is destroyed

Vehicle.Subscribe("Destroy", function(self)
-- called when any vehicle is destroyed
end)
TypeParameterDescription
ActorselfThe 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)
TypeParameterDescription
ActorselfThe 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)
TypeParameterDescription
ActorselfThe Actor that just had a value changed
stringkeyThe key used
anyvalueThe value changed