Empty Node

Basic 2D transform node with position, rotation, scale, and hierarchy grouping.

Type: Node · Category: Core & 2D · Also found as: node, empty

A plain node: a transform (position, rotation, scale) and children. Use it to group nodes - move the group and everything under it moves - or as the root of a scene or a component, or to hold a script that has nothing to draw.

-- A spinning group: everything under this node turns with it.
local Spinner = {}
Spinner.properties = { speed = { type = "float", default = 90 } } -- degrees per second

function Spinner:update(dt)
    self.node.rotation = self.node.rotation + self.speed * dt
end

return Spinner

Properties

No reflected properties of its own: its settings are described above.

Plus the common properties every node has.

Lua methods

Call them on the node (self.node in its script, or self.node:get_node("path")). Every node also has the Node methods.

Node:get_type()

Gets the concrete runtime type of the node (e.g. “Node”, “TextureNode”, “DynamicBodyNode”, “CameraNode”).

if self.node:get_type() == "DynamicBodyNode" then Log.info("physics body") end

Returns string

Node:get_name()

Gets the display/debug name of the node.

Log.info("Spawned " .. self.node:get_name())

Returns string

Node:set_name(name)

Sets the display/debug name of the node.

self.node:set_name("Enemy_" .. tostring(index))

• name string

Node:get_position()

Gets the local position of the node.

local x, y = self.node:get_position()

Returns number x Local X position, number y Local Y position

Node:set_position(x, y)

Sets the local position of the node.

self.node:set_position(320, 180)

• x number Local X position
• y number Local Y position

Node:translate(dx, dy)

Translates the node position by the given delta offset.

self.node:translate(self.speed * dt, 0)

• dx number Delta X
• dy number Delta Y

Node:get_rotation()

Gets the local rotation of the node in degrees.

local angle = self.node:get_rotation()

Returns number rotation Rotation in degrees

Node:set_rotation(degrees)

Sets the local rotation of the node in degrees.

self.node:set_rotation(90)

• degrees number Rotation in degrees

Node:rotate(degrees)

Rotates the node by delta degrees.

self.node:rotate(180 * dt)

• degrees number Delta degrees

Node:get_scale()

Gets the local scale factor of the node.

local sx, sy = self.node:get_scale()

Returns number sx Scale X, number sy Scale Y

Node:set_scale(sx, sy)

Sets the local scale factor of the node.

self.node:set_scale(-1, 1)

• sx number Scale X
• sy? number Scale Y (defaults to sx if omitted)

Node:get_global_position()

Gets the world-space global position of the node calculated from parent transforms.

local gx, gy = self.node:get_global_position()

Returns number x Global world X position, number y Global world Y position

Node:get_global_rotation()

Gets the world-space global rotation of the node in degrees.

local world_angle = self.node:get_global_rotation()

Returns number rotation Global world rotation in degrees

Node:is_enabled()

Checks if the node is actively updated in the scene loop.

if not self.node:is_enabled() then return end

Returns boolean

Node:set_enabled(enabled)

Enables or disables updates for the node and its children.

Scene.find_node("Enemy"):set_enabled(false)

• enabled boolean

Node:is_visible()

Checks if the node is rendered in the scene draw loop.

local shown = self.node:is_visible()

Returns boolean

Node:set_visible(visible)

Sets whether the node is rendered.

self.node:get_node("Shield"):set_visible(true)

• visible boolean

Node:get_parent()

Gets the parent node, or nil if this is a root node.

local parent = self.node:get_parent(); if parent then Log.info(parent:get_name()) end

Returns Node?

Node:get_children()

Returns an array of all direct child nodes.

for _, child in ipairs(self.node:get_children()) do child:set_visible(false) end

Returns Node[]

Node:add_tag(tag)

Adds a tag (group) to the node; false when it already has it.

self.node:add_tag("enemies")

• tag NodeTag|string

Returns boolean

Node:remove_tag(tag)

Removes a tag (group) from the node; returns false when it did not have it.

local removed = self.node:remove_tag("enemies")

• tag NodeTag|string

Returns boolean removed

Node:has_tag(tag)

Checks whether the node has the given tag (group).

if other:has_tag("player") then self:collect() end

• tag NodeTag|string

Returns boolean

Node:get_tags()

Returns an array of all tags (groups) on the node.

for _, tag in ipairs(self.node:get_tags()) do Log.info(tag) end

Returns string[]

Node:get_child(name)

Finds a direct child node by its exact name.

local sprite = self.node:get_child("Sprite")

• name NodeName|string

Returns Node?

Node:get_node(path)

Finds a node by path relative to this one: “Gun”, “Body/Gun”, “../Player”, “.” (self).

local gun = self.node:get_node("Body/Gun")

• path string Relative node path

Returns Node? node The node, or nil if there is none

Node:add_child(child)

Reparents a child node under this node.

local item = Scene.find_node("Key"); self.node:add_child(item)

• child Node

Node:remove_child(child)

Detaches a child node from this node.

self.node:remove_child(self.node:get_child("Shield"))

• child Node

Node:destroy()

Removes this node and all its children from the active scene (at the end of the frame, so it’s safe from its own update).

self.node:destroy()

Node:queue_free()

Removes this node and its children at the end of the frame (= destroy).

if self.health <= 0 then self.node:queue_free() end

Node:connect(event, handler)

Connects a handler to an event of this node (from any script). Handlers are removed automatically when the connecting script or this node is destroyed. A script also receives its own node’s events as methods named on_<event> (e.g. function MyScript:on_timeout() end).

self.conn = timer:connect("timeout", function(value, source) self:fire() end)

• event NodeEvent|ProjectEvent|string Event name (custom ones: the project’s emit names)
• handler fun(value: any, source: Node) Called with the event value and this node

Returns integer id Connection id for disconnect

Node:disconnect(id)

Removes a connection made with connect.

local removed = timer:disconnect(self.conn)

• id integer Connection id

Returns boolean removed

Node:emit(event, value)

Raises a custom event on this node: calls the node script’s on_<event> method and every handler connected to that event name.

self.node:emit("health_changed", self.health)

• event ProjectEvent|string Event name (the project’s custom events complete)
• value? any Value passed to handlers

Node:get_property(path)

Reads an Inspector property by its path (vectors and colours as tables); “script.” reads a field of the node’s script.

local value = self.node:get_property("position")

• path NodeProperty|string

Returns any

Node:set_property(path, value, y)

Sets an Inspector property by its path: vectors as {x, y} or x, y; colours as {r, g, b[, a]} 0..1 or “#rrggbb[aa]”; enums by name; “script.” a field of the node’s script.

self.node:set_property("position", 100, 50)

• path NodeProperty|string
• value any
• y? number

Node:set_shader(shader)

Sets the node’s shader: a built-in or a project fragment shader (.fs). nil removes it.

self.node:set_shader("builtin:flash")

• shader BuiltinShader|string|nil

Node:set_shader_param(name, x, y, z, w)

Sets a shader parameter (a uniform of the shader): a number, up to four numbers, a table {r, g, b, a} / {x, y}, or a texture path.

self.node:set_shader_param("amount", 0.8)

• name string
• x number|number[]|string
• y? number
• z? number
• w? number

Node:get_shader_param(name)

Gets a shader parameter (its value, else the shader’s default): up to four numbers, or the texture path.

local amount = self.node:get_shader_param("amount")

• name string

Returns number|string|nil x, number? y, number? z, number? w

Node:set_blend_mode(mode)

Sets how the node is blended with what’s behind it.

self.node:set_blend_mode("additive")

• mode BlendMode

Node:get_script()

The node’s script instance - the self its script sees: read or change its fields and call its methods (enemy:get_script():take_damage(10)). nil when the node has no script.

local enemy = Scene.find_node("Enemy"); enemy:get_script():take_damage(10)

Returns table?

Node:set_paused(paused)

Pauses this node and its children (except “always” ones).

Scene.find_node("Enemies"):set_paused(true)

• paused boolean

Node:is_paused()

Checks whether the node is paused, by itself, a parent or the game.

if self.node:is_paused() then return end

Returns boolean paused By itself, a parent or the game

Node:set_pause_mode(mode)

Sets how the node reacts to pausing: inherit from its parent, pausable, or always running.

self.node:set_pause_mode("always")

• mode "inherit"|"pausable"|"always"

Node:set_collision_layer(…)

The collision layers this body’s shapes are on: project layer names (Project Settings > Physics), “LayerN” or numbers 1-16; several or a table.

self.node:set_collision_layer("player")

• ... CollisionLayer|string|integer|table

Node:set_collision_mask(…)

The collision layers this body’s shapes collide with.

self.node:set_collision_mask("world", "enemies")

• ... CollisionLayer|string|integer|table

In a scene file

{
  "type": "Node",
  "name": "EmptyNode",
  "position": [
    0,
    0
  ]
}