Node

The base object that can be added to a world and saved in a scene.

---

Construct

Construct a node from a given class name. (e.g. "Node3D", "Primitive3D", "Text", "Image")

Alias: New

Sig: node = Node.Construct(className="Node") - Arg: string className The class of the node to create. Default = "Node". - Ret: Node node The newly constructed node.

---

Destruct

Destruct a node and make it unusable.

Sig: Node.Destruct(node) - Arg: Node node The node to be destroyed.

---

DestroyDeferred

Destroy this node at the end of the frame. Usually a safer and more stable option than immediately destroying a node with Destruct.

Alias: Doom Alias: SetPendingDestroy

Sig: Node:DestroyDeferred()

---

IsValid

Check whether a node is valid. This function currently always returns true, but when the engine is compiled using LUA_SAFE_NODE, this function will return true only if the underlying node reference is valid.

Sig: valid = Node:IsValid() - Ret: boolean valid Whether the node is valid.

---

GetName

Get this node's name. A node's name must be unique among all of its siblings.

Sig: name = Node:GetName() - Ret: string name The node's name

---

SetName

Set this node's name. A node's name must be unique among all of its siblings. If a sibling node already has the same name, then SetName() will append a unique identifier so that it can be differentiated.

Sig: Node:SetName(name) - Arg: string name The node's new name

---

SetActive

Control whether the node is active. Active nodes will tick and recursively tick their children. If a parent node is not active, but the child node is active, the child node will never tick.

Sig: Node:SetActive(active) - Arg: boolean active New active status

---

IsActive

Check if the node is currently active. An optional boolean can be passed to check if any ancestor node is inactive, essentially making this node inactive.

Sig: active = Node:IsActive(recurse=false) - Arg: boolean recurse Recursively check ancestors - Ret: boolean active Active status

---

SetVisible

Sets the visibility of the node. Only visible nodes will be rendered. If a node is not visible, none of its children nodes will be rendered either.

Sig: Node:SetVisible(visible) - Arg: boolean visible Visible status

---

IsVisible

Checks if the node is visible. An optional boolean can be passed to check if any ancestor node is not visible, essentially making this node not visible.

Sig: visible = Node:IsVisible(recurse=false) - Arg: boolean recurse Recursively check ancestors - Ret: boolean visible Visible status

---

SetPersistent

Set the persistence of a node. A persistent node will remain in a world when a world is cleared or a new root node is set. It will only be removed if it is explicitly removed. A persistent node will also not be destroyed if its parent is destroyed.

Sig: Node:SetPersistent(persistent) - Arg: boolean persistent Is persistent

---

IsPersistent

Checks if the node is persistent. A persistent node will remain in a world when a world is cleared or a new root node is set. It will only be removed if it is explicitly removed. A persistent node will also not be destroyed if its parent is destroyed.

Sig: persistent = Node:IsPersistent() - Ret: boolean persistent Is persistent

---

GetWorld

Returns the World that the node is currently in. Returns nil if not part of a World.

Sig: world = Node:GetWorld() - Ret: World world Current world

---

GetParent

Returns this node's parent node.

Sig: parent = Node:GetParent() - Ret: Node parent This node's parent node

---

Attach

Attach this node to a new parent node.

Sig: Node:Attach(parent, keepWorldTransform=false, childIndex=0) - Arg: Node parent The new parent. Can be nil. - Arg: boolean keepWorldTransform Option to keep the same world-space transform. Useful when you want to reparent something while keeping it in the same position. - Arg: integer childIndex Where in the parent's child array this node should be placed. If 0, this node will be placed at the end of the parent node's child array.

---

Detach

Detach this node from its parent. This is essentially the same thing as calling Node:Attach(nil).

Sig: Node:Detach(keepWorldTransform=false) - Arg: boolean keepWorldTransform Option to keep the same world-space transform. Useful when you want to reparent something while keeping it in the same position.

---

GetChild

Get a child node by its index.

Sig: child = Node:GetChild(index) - Arg: integer index Which child to get - Ret: Node child The child node. Will be nil if the index is out of range.

---

GetChildByType

Get the first child node of a given type.

Sig: child = Node:GetChildByType(typeName) - Arg: string typeName The typename of child (e.g. Node3D, Primitive3D, Text, Image...). - Ret: Node child The child node (nil if none of the children match the type).

---

GetNumChildren

Return the number of children this node has.

Sig: numChildren = Node:GetNumChildren() - Ret: integer numChildren Number of children

---

AddChild

Parent the given node to this node. This is equivalent to calling newChild:Attach(thisNode).

Sig: Node:AddChild(newChild, index=0) - Arg: Node newChild The new child node you want to add - Arg: integer index The child index the new node should be placed at. If 0, it will be placed at the end.

---

RemoveChild

Remove a child node.

Sig: Node:RemoveChild(childIndexOrName) - Arg: integer/string childIndexOrName Either an integer index, or a string name to identify which child should be removed.

---

FindChild

Find a child node by its name. An optional recurse argument can be provided to check all children recursively.

Sig: child = Node:FindChild(name, recurse=false) - Arg: string name Name of the child to find - Arg: boolean recurse Whether to recursively search all children. If false (the default value), only the immediate children will be searched. - Ret: Node child The found child node. Will return nil if no child was found.

---

FindChildWithTag

Find the first child node with a given tag. An optional recurse argument can be provided to check all children recursively.

Sig: child = Node:FindChild(tag, recurse=false) - Arg: string tag Tag to search for - Arg: boolean recurse Whether to recursively search all children. If false (the default value), only the immediate children will be searched. - Ret: Node child The found child node. Will return nil if no child was found.

---

FindDescendant

Find a descendant node by name. This is equivalent to calling Node:FindChild(name, true).

Sig: descendant = Node:FindDescendant(name) - Arg: string name Descendant name - Ret: Node descendant Descandant node if found (otherwise nil)

---

FindAncestor

Find an ancestor node by name.

Sig: ancestor = Node:FindAncestor(name) - Arg: string name Ancestor name - Ret: Node ancestor Ancestor node if found (otherwise nil)

---

HasAncestor

Check if the given node is an ancestor of this node.

Sig: hasAncestor = Node:HasAncestor(node) - Arg: Node node Node to check - Ret: boolean hasAncestor True if node was an ancestor of self

---

GetRoot

Return the root ancestor node of this node (i.e. the first node with no parent).

Sig: root = Node:GetRoot() - Ret: Node root The root node of this node's tree

---

IsWorldRoot

Checks to see if this node is the root node of the world it is currently in.

Sig: isRoot = Node:IsWorldRoot() - Ret: boolean isRoot true if node is in a world and is the world's root node, otherwise false.

---

Traverse

Execute a function for this node and it's descendants. An example that prints out all of the node tree's names is given below:

function PrintNodeNames(node)
    Log.Debug(node:GetName())
    return true
end

node:Traverse(PrintNodeNames)

If false is returned by the passed in function, it indicates that the Traverse function should not call the function on its children. Another example where we only print out the names of visible nodes:

function PrintVisibleNodeNames(node)
    if (node:IsVisible()) then
        Log.Debug(node:GetName())
        return true
    end

    return false
end

node:Traverse(PrintVisibleNodeNames)

Sig: Node:Traverse(func, inverted=false) - Arg: function func Function to invoke on each node - Arg: boolean inverted If true invoke function on leaf nodes first, and work backwards to the self node

---

ForEach

Execute a function on this node and its children, similarly to Traverse(), except the passed in function should return true to continue execution on the next node and false to break out of the iteration entirely (not just skip over children).

Sig: success = Node:ForEach(func, inverted=false) - Arg: function func Function to invoke on each node - Arg: boolean inverted If true invoke function on leaf nodes first, and work backwards to the self node - Ret: boolean success If true, all nodes were iterated over. If false, the execution was broken early

---

CreateChild

Construct a new node and parent it to this node.

Sig: child = Node:CreateChild(className) - Arg: string className Class name of node type to construct (e.g. Primitive3D, Image) - Ret: Node child The newly created child (nil if failed or an invalid class name was provided)

---

CreateChildClone

Construct a new node cloned from a source node and parent it to this node.

Sig: child = Node:CreateChildClone(srcNode, recurse) - Arg: Node srcNode The source node to copy from - Arg: boolean recurse Whether child nodes should be recursively created and copied - Ret: Node child The newly cloned node

---

Clone

Create a copy of node. If the recurse option is set to true, it will copy all child nodes as well.

Sig: node = Node:Clone(srcNode, recurse) - Arg: Node srcNode The source node to copy from - Arg: boolean recurse If true, clone all children nodes as well - Ret: Node node Newly created, cloned node

---

DestroyChild

Destroy a child node based on a given name or index. Note: This function seems excessive. Can we remove it?

Sig: Node:DestroyChild(nameOrIndex) - Arg: string/integer nameOrIndex Name (string) or index (integer) of child node to destroy

---

DestroyAllChildren

Destroy all child nodes.

Sig: Node:DestroyAllChildren()

---

Start

Manually invoke the Start function of the node if it hasn't been started already. Normally a node will have its Start() function called on the first frame it ticks, but sometimes it can be useful to manually invoke Start() to control the order that nodes are started.

Sig: Node:Start()

---

HasStarted

Check if the node has already started (i.e. has had its Start() function called)

Sig: hasStarted = Node:HasStarted() - Ret: boolean hasStarted true if Start() has been called for this node

---

GetNodeId

Get this node's unique ID.

Sig: id = Node:GetNodeId() - Ret: integer id Node's unique identifier

---

EmitSignal

Broadcast a signal by name so that any nodes that are connected to the signal can react. There is no need to create a signal first, you can simple emit any signal by name.

Sig: Node:EmitSignal(signalName, args...) - Arg: string signalName Name of the signal to emit - Arg: args... Any number of arguments that you wish to pass

---

ConnectSignal

Connect a listener to a signal on this node.

The function passed in should be a member function of the node's table. For instance:

function HealthBar:OnHealthChanged(newHp)
    self.quad:SetXRatio(newHp / Player.MaxHp)
end

function HealthBar:Start()
    GetPlayer():ConnectSignal("healthChanged", self, HealthBar.OnHealthChanged)
end

Sig: Node:ConnectSignal(signalName, listener, func) - Arg: string signalName Name of the signal to connect to - Arg: Node listener The node that will be reacting to the signal - Arg: function func The function on the listener node that will be invoked when the signal is emit.

---

DisconnectSignal

Disconnect a listener from a signal on this node.

Sig: Node:DisconnectSignal(signalName, listener) - Arg: string signalName Name of the signal to disconnect from - Arg: Node listener The node that was connected to the signal (and will now be disconnected)

---

IsDestroyed

Check if the node has been destroyed.

Sig: destroyed = Node:IsDestroyed() - Ret: boolean destroyed Is the node destroyed

---

IsPendingDestroy

Check if the node is marked to be destroyed at the end of the frame.

Alias: IsDoomed

Sig: pendingDestroy = Node:IsPendingDestroy() - Ret: boolean pendingDestroy true if marked for destruction

---

EnableTick

Set whether or not this node should tick every frame. Note: I don't think there is any difference between this and SetActive() right now, so this function might be removed in the future.

Sig: Node:EnableTick(enable) - Arg: boolean enable Whether to tick

---

IsTickEnabled

Check if this node will have its Tick() function called. Note: I don't think there is any difference between this and IsActive() right now, so this function might be removed in the future.

Sig: enabled = Node:IsTickEnabled() - Ret: boolean enabled true if can tick

---

GetScene

Return this node's associated Scene. When a scene is instantiated, the newly instantiated root node will hold a reference to the Scene asset which it was instantiated from. GetScene() will return this reference.

Sig: scene = Node:GetScene() - Arg: Scene scene The node's associated scene

---

SetScript

Set the script file on a particular node.

Alias: SetScriptFile

Sig: Node:SetScript(filename) - Arg: string filename Script filename

---

GetNetId

Return the net id associated with this node. A NetId will be assigned to nodes with replication enabled when hosting a session or connected to another session. NetIds are the internal mechanism for referencing the same node across different instances of the game.

Sig: netId = Node:GetNetId() - Arg: integer netId The node's NetId, 0 is an invalid net id

---

GetOwningHost

Return the owning host id. Only useful in net play sessions for determining which player/host should control the node.

Sig: hostId = Node:GetOwningHost() - Ret: integer hostId Owning host id

---

SetOwningHost

Set which host should own the node. The owning host id will be replicated to clients, so this function should only be called on the server. Ownership doesn't do anything on it's own, it's up to the game code to handle what ownership means (e.g. only the owning player can tell the player node where to move)

Sig: Node:SetOwningHost(hostId) - Arg: integer hostId The new host id that should own the node

---

SetReplicate

Enable or disable network replication for this node. Note: The replicate flag should probably be set in the Editor via the Properties panel. I don't think setting it at runtime is advised.

Sig: Node:SetReplicate(replicate) - Arg: boolean replicate true to replicate over the network

---

IsReplicated

Check if this node is replicated over the network.

Sig: replicated = Node:IsReplicated() - Ret: boolean replicated true if replicated over the network

---

SetReplicateTransform

Set whether the transform (position/rotation/scale) should be replicated for this node. This is currently only used by 3D nodes, but in the future it might be expanded to work for widgets or 2D nodes. Note: Should probably be set in the editor instead of changed at runtime.

Sig: Node:SetReplicateTransform(replicateTransform) - Arg: boolean replicateTransform true to replicate transform

---

IsTransformReplicated

Check if this node's transform is replicated.

Sig: transformReplicated = Node:IsTransformReplicated() - Ret: boolean transformReplicated true if transform is replicated

---

ForceReplication

Forcefully replicate properties of this node on the next network update, even if nothing has changed.

Sig: Node:ForceReplication()

---

HasTag

Check if a node has a given tag assigned to it. Tags are strings that can be assigned to a node. Nodes can have an unlimited number of tags assigned to them.

Sig: hasTag = Node:HasTag(tag) - Arg: string tag tag - Ret: boolean hasTag true if the node has that tag assigned to it

---

AddTag

Add a tag to this node. Nothing will happen if this node already has the tag assigned to it.

Sig: Node:AddTag(tag) - Arg: string tag Tag to assign

---

RemoveTag

Remove a tag on this node. Does nothing if the tag hasn't been assigned.

Sig: Node:RemoveTag(tag) - Arg: string tag Tag to remove

---

HasAuthority

This function was added to match Unreal functionality, but the server will have network authority on all nodes. This function calls Network.IsAuthority(), it does not really matter which node this function is invoked on.

Sig: hasAuthority = Node:HasAuthority() - Arg: boolean hasAuthority true if this host is a server

---

IsOwned

Check whether this computer host owns this node. In a local game, will return true if node:SetOwningHost(NetHost.Authority) was called on this node. If in a networked game, this function will return true if the OwningHost is equivalent to this computer's host id.

Sig: owned = Node:IsOwned() - Ret: boolean owned true if owned by this host

---

IsLateTickEnabled

Check if late tick is enabled. Late tick means that the node will tick all of its children before it ticks itself. By default, the parent node will tick first.

Sig: lateTick = Node:IsLateTickEnabled() - Ret: boolean lateTick true if node will tick after its children

---

EnableLateTick

Enable late tick on this node. Late tick means that the node will tick all of its children before it ticks itself. By default, the parent node will tick first.

Sig: Node:EnableLateTick(lateTick) - Arg: boolean lateTick true to tick this node after its children

---

IsAlwaysRelevant

Check if this node is always relevant to clients

Sig: alwaysRelevant = Node:IsAlwaysRelevant() - Ret: boolean alwaysRelevant Whether node should always relevant to clients

---

SetAlwaysRelevant

Set whether the node should always be relevant to clients.

Sig: Node:SetAlwaysRelevant(alwaysRelevant) - Arg: boolean alwaysRelevant Whether node should always relevant to clients

---

InvokeNetFunc

Used to invoke a remote procedure call on this node. Up to 8 arguments can be passed.

Sig: Node:InvokeNetFunc(name, arg1, arg2, ... arg8) - Arg: string name name of net func (must exist in GatherNetFuncs())

---

CheckType

Check if this node is of a given type.

Alias: Is

Alias: IsA

Sig: Node:CheckType(className) - Arg: string className type name to check (e.g. "Primitive3D")

---