Writing your own nodes
For programmers. A Logic Node is an ordinary GDScript class: outputs are signals, inputs are methods. Write one and it shows up in Add Child Node, the Logic I/O panel, Trace and the warnings, with no registration.
A complete example
A light switch with Turn On, Turn Off and Toggle inputs, and an On Switched output:
@tool
@icon("res://my_icons/LightSwitch.svg")
class_name LogicLightSwitch
extends LogicNode
## Turns a light on and off from logic.
## Output: the light was turned on or off.
signal on_switched(activator: Node)
## The light to control.
@export var light: Light3D
## Input: turn the light on.
func turn_on(activator: Variant = null) -> void:
if _receive(&"turn_on", activator):
_set_on(true, activator)
## Input: turn the light off.
func turn_off(activator: Variant = null) -> void:
if _receive(&"turn_off", activator):
_set_on(false, activator)
## Input: flip the light.
func toggle(activator: Variant = null) -> void:
if _receive(&"toggle", activator) and light:
_set_on(not light.visible, activator)
func _set_on(on: bool, activator: Variant) -> void:
if light and light.visible != on:
light.visible = on
_fire(on_switched, activator)
func _logic_warnings() -> PackedStringArray:
var warnings := super()
if light == null:
warnings.append("Pick a Light to control.")
return warnings
The rules
| Part | How to write it |
|---|---|
| The class | @tool, a class_name, and extends LogicNode (or another Logic Node, such as LogicMove). @tool is needed for warnings and the panel to work in the editor. |
| Outputs | Signals that take one activator: Node argument. Name them on_something, which shows as "On Something". |
| Inputs | Public methods that take activator: Variant = null and return nothing. Methods that start with _, take more than one argument, or return a value aren't listed as inputs. |
| Start of every input | if _receive(&"input_name", activator):. It returns false when the node is disabled or in the editor, and handles Trace. |
| Firing | _fire(on_something, activator). Pass the activator you received so it travels down the chain. |
| Startup | Override _logic_ready() instead of _ready(). It runs in the game only, after the node's connections are wired. |
| Warnings | Override _logic_warnings(), call super() and append your messages. |
| Tooltips | Write a ## doc comment above each signal and input. The panel shows it as the tooltip, minus a leading "Output:" or "Input:". It's also what the Inspector and Godot's built-in help show. |
| Waiting | Use await LogicCore.wait(self, seconds) rather than a SceneTreeTimer, so delays count physics ticks like the built-in nodes. |
Your class also gets its own badge toggle under View > Gizmos, and new instances are placed in front of the editor camera like the built-in nodes.
Subclassing a built-in node
To make, say, a door that always uses the same speed and offset, extend LogicMove and set the defaults in _init(). It keeps every input, output and setting of Move.