Dev » Lua API » node

node

Scene & Nodes 18 Properties 16 Methods

node

The node class wraps Godot Engine scene tree Node instances. It enables inspecting and manipulating scene hierarchy, 3D transforms, visibility, mesh surfaces, materials, textures, and bounding boxes.

Overview Properties (18) Methods (16) Detailed Reference ↓

Overview

Properties (18)

Property	Type	Summary
`active`	`boolean`	Node active processing state.
`childCount`	`number`	Count of direct child nodes.
`globalPosition`	`vector3`	Global 3D world position.
`globalRotation`	`vector3`	Global Euler rotation in degrees.
`globalScale`	`vector3`	Global scale vector.
`isMesh`	`boolean`	Checks if node is a 3D mesh instance.
`isNode3D`	`boolean`	Checks if the node is a 3D spatial node.
`isValid`	`boolean`	Checks if the node instance is valid.
`meshName`	`string`	Mesh resource name if mesh.
`name`	`string`	Node name in the scene tree.
`parent`	`node`	Parent node in scene tree.
`path`	`string`	Absolute scene tree path.
`position`	`vector3`	Local 3D position vector.
`rotation`	`vector3`	Local Euler rotation in degrees.
`scale`	`vector3`	Local scale vector.
`surfaceCount`	`number`	Number of surfaces in mesh.
`type`	`string`	Godot class name.
`visible`	`boolean`	Node visibility state.

Methods (16)

Method Signature	Returns	Summary
`node:findChild(name, [recursive = true])`	`node`	Finds the first child matching name.
`node:findChildren([typeName], [recursive = true])`	`table`	Finds all descendant nodes matching class type.
`node:getAabb([global = false])`	`aabb`	Gets the bounding box of the node meshes.
`node:getAabbByMaterial(material, [global = false])`	`aabb`	Calculates the bounding box of surfaces using the material.
`node:getAabbByTexture(textureName, [global = false])`	`aabb`	Calculates the bounding box of surfaces using the texture.
`node:getChild(indexOrName)`	`node`	Gets a child node by index or name.
`node:getChildren()`	`table`	Gets all direct child nodes.
`node:getMaterialNames()`	`table`	Gets all material resource names in the node.
`node:getMaterials()`	`table`	Gets all material definitions used across node surfaces.
`node:getSurfaceAabb(surfaceIndex, [global = false])`	`aabb`	Gets the bounding box of a specific mesh surface.
`node:getSurfaceMaterial(surfaceIndex)`	`materialdef`	Gets the material definition assigned to a mesh surface.
`node:getSurfaceMaterialName(surfaceIndex)`	`string`	Gets the material resource name of a surface.
`node:getSurfaceTextureName(surfaceIndex)`	`string`	Gets the texture name of a surface.
`node:getTextures()`	`table`	Gets all texture names used by the node.
`node:usesMaterial(material)`	`boolean`	Checks if any surface on the node uses the material.
`node:usesTexture(textureName)`	`boolean`	Checks if any surface on the node uses the texture.

Detailed Reference

# active PROPERTY

↑ Overview

node.active

Node active processing state.

Parameters

None

Returns

boolean

Active state.

Description

Gets or sets whether the node is active.

# childCount PROPERTY

↑ Overview

node.childCount

Count of direct child nodes.

Parameters

None

Returns

number

Direct child count.

Description

Returns the count of direct children in scene tree.

# globalPosition PROPERTY

↑ Overview

node.globalPosition

Global 3D world position.

Parameters

None

Returns

vector3

Global world position.

Description

Gets or sets global world position.

# globalRotation PROPERTY

↑ Overview

node.globalRotation

Global Euler rotation in degrees.

Parameters

None

Returns

vector3

Global Euler angles in degrees.

Description

Gets or sets global Euler angles.

# globalScale PROPERTY

↑ Overview

node.globalScale

Global scale vector.

Parameters

None

Returns

vector3

Global scale vector.

Description

Gets global scale.

# isMesh PROPERTY

↑ Overview

node.isMesh

Checks if node is a 3D mesh instance.

Parameters

None

Returns

boolean

True if node is MeshInstance3D.

Description

Returns true if the node is a MeshInstance3D.

# isNode3D PROPERTY

↑ Overview

node.isNode3D

Checks if the node is a 3D spatial node.

Parameters

None

Returns

boolean

True if inherits Node3D.

Description

Returns true if the node is a 3D spatial node.

# isValid PROPERTY

↑ Overview

node.isValid

Checks if the node instance is valid.

Parameters

None

Returns

boolean

True if Godot node instance is valid.

Description

Returns true if the Godot node exists and has not been freed.

# meshName PROPERTY

↑ Overview

node.meshName

Mesh resource name if mesh.

Parameters

None

Returns

string

Mesh resource name.

Description

Returns the resource name of the assigned mesh.

# name PROPERTY

↑ Overview

node.name

Node name in the scene tree.

Parameters

None

Returns

string

Node name string.

Description

Gets the node name.

# parent PROPERTY

↑ Overview

node.parent

Parent node in scene tree.

Parameters

None

Returns

node

Parent node wrapper or nil.

Description

Returns the parent node wrapper.

# path PROPERTY

↑ Overview

node.path

Absolute scene tree path.

Parameters

None

Returns

string

Node path string.

Description

Returns the absolute path of the node in the scene tree.

# position PROPERTY

↑ Overview

node.position

Local 3D position vector.

Parameters

None

Returns

vector3

Local 3D position.

Description

Gets or sets local position.

# rotation PROPERTY

↑ Overview

node.rotation

Local Euler rotation in degrees.

Parameters

None

Returns

vector3

Local Euler angles in degrees.

Description

Gets or sets local Euler angles.

# scale PROPERTY

↑ Overview

node.scale

Local scale vector.

Parameters

None

Returns

vector3

Local scale vector.

Description

Gets or sets local scale.

# surfaceCount PROPERTY

↑ Overview

node.surfaceCount

Number of surfaces in mesh.

Parameters

None

Returns

number

Mesh surface count.

Description

Returns the number of material surfaces on the mesh.

# type PROPERTY

↑ Overview

node.type

Godot class name.

Parameters

None

Returns

string

Godot class name string.

Description

Returns class name (e.g. "Node3D", "MeshInstance3D", "CollisionShape3D").

# visible PROPERTY

↑ Overview

node.visible

Node visibility state.

Parameters

None

Returns

boolean

Visibility state.

Description

Gets or sets node visibility.

# findChild METHOD

↑ Overview

node:findChild(name, [recursive = true])

Finds the first child matching name.

Parameters

Parameter	Type	Default	Description
`name`	string		Child name.
`recursive`	boolean	`true`	Search descendants.

Returns

node

Found child node or nil.

Description

Searches descendant nodes for name.

# findChildren METHOD

↑ Overview

node:findChildren([typeName], [recursive = true])

Finds all descendant nodes matching class type.

Parameters

Parameter	Type	Default	Description
`typeName`	string	`""`	Class type filter.
`recursive`	boolean	`true`	Search descendants.

Returns

table

Array of child node objects.

Description

Searches descendants for nodes of typeName.

# getAabb METHOD

↑ Overview

node:getAabb([global = false])

Gets the bounding box of the node meshes.

Parameters

Parameter	Type	Default	Description
`global`	boolean	`false`	World coordinates if true.

Returns

aabb

Bounding box.

Description

Returns the bounding box enclosing the node.

# getAabbByMaterial METHOD

↑ Overview

node:getAabbByMaterial(material, [global = false])

Calculates the bounding box of surfaces using the material.

Parameters

Parameter	Type	Default	Description
`material`	string\|materialdef		Target material.
`global`	boolean	`false`	World coordinates.

Returns

aabb

Bounding box or nil.

Description

Calculates the combined bounds of surfaces with the specified material.

# getAabbByTexture METHOD

↑ Overview

node:getAabbByTexture(textureName, [global = false])

Calculates the bounding box of surfaces using the texture.

Parameters

Parameter	Type	Default	Description
`textureName`	string		Target texture name.
`global`	boolean	`false`	World coordinates.

Returns

aabb

Bounding box or nil.

Description

Calculates the combined bounds of surfaces with the specified texture.

# getChild METHOD

↑ Overview

node:getChild(indexOrName)

Gets a child node by index or name.

Parameters

Parameter	Type	Default	Description
`indexOrName`	number\|string		1-based index or child node name.

Returns

node

Child node or nil.

Description

Finds a direct child node.

# getChildren METHOD

↑ Overview

node:getChildren()

Gets all direct child nodes.

Parameters

None

Returns

table

1-based array of child node objects.

Description

Returns an array of all direct child nodes.

# getMaterialNames METHOD

↑ Overview

node:getMaterialNames()

Gets all material resource names in the node.

Parameters

None

Returns

table

Array of material resource name strings.

Description

Collects unique material names across all mesh surfaces.

# getMaterials METHOD

↑ Overview

node:getMaterials()

Gets all material definitions used across node surfaces.

Parameters

None

Returns

table

Array of unique materialdef descriptors.

Description

Collects unique material definitions used by all mesh surfaces.

# getSurfaceAabb METHOD

↑ Overview

node:getSurfaceAabb(surfaceIndex, [global = false])

Gets the bounding box of a specific mesh surface.

Parameters

Parameter	Type	Default	Description
`surfaceIndex`	number		1-based surface index.
`global`	boolean	`false`	World coordinates.

Returns

aabb

Surface bounding box.

Description

Calculates the bounds of vertices belonging to surface surfaceIndex.

# getSurfaceMaterial METHOD

↑ Overview

node:getSurfaceMaterial(surfaceIndex)

Gets the material definition assigned to a mesh surface.

Parameters

Parameter	Type	Default	Description
`surfaceIndex`	number		1-based surface index.

Returns

materialdef

Material definition descriptor.

Description

Returns the material definition used by the specified surface.

# getSurfaceMaterialName METHOD

↑ Overview

node:getSurfaceMaterialName(surfaceIndex)

Gets the material resource name of a surface.

Parameters

Parameter	Type	Default	Description
`surfaceIndex`	number		1-based surface index.

Returns

string

Material name.

Description

Returns the resource name of the surface material.

# getSurfaceTextureName METHOD

↑ Overview

node:getSurfaceTextureName(surfaceIndex)

Gets the texture name of a surface.

Parameters

Parameter	Type	Default	Description
`surfaceIndex`	number		1-based surface index.

Returns

string

Texture name.

Description

Returns the texture name assigned to the surface.

# getTextures METHOD

↑ Overview

node:getTextures()

Gets all texture names used by the node.

Parameters

None

Returns

table

Array of texture name strings.

Description

Collects unique texture names across all mesh surfaces.

# usesMaterial METHOD

↑ Overview

node:usesMaterial(material)

Checks if any surface on the node uses the material.

Parameters

Parameter	Type	Default	Description
`material`	string\|materialdef		Material ID or definition.

Returns

boolean

True if used.

Description

Returns true if material is used on any mesh surface.

# usesTexture METHOD

↑ Overview

node:usesTexture(textureName)

Checks if any surface on the node uses the texture.

Parameters

Parameter	Type	Default	Description
`textureName`	string		Texture name.

Returns

boolean

True if used.

Description

Returns true if textureName is used on any mesh surface.

Dev

Lua API

Assets

node

node

Overview

Properties (18)

Methods (16)

Detailed Reference