simvx.core.node

Node: Base node class with tree hierarchy, groups, and coroutine support.

Module Contents

Classes

Node	Base node with tree hierarchy, groups, and coroutine support.
Timer	Fires timeout signal after duration. Supports one-shot and repeating.

Data

log

API

simvx.core.node.log

‘getLogger(…)’

class simvx.core.node.Node(name: str = '', **kwargs)

Base node with tree hierarchy, groups, and coroutine support.

Attributes: name: Unique name within the parent’s children. Defaults to the class name. parent: The parent Node, or None if this is the root. children: Ordered collection of child nodes, accessible by name or index. visible: Whether this node (and its descendants) should be drawn. process_mode: Controls processing behaviour during pause (INHERIT, PAUSABLE, PAUSED_ONLY, ALWAYS, DISABLED). script: Optional file path to an attached script. unique_name: When True, the node is registered in the tree for fast lookup via SceneTree.get_unique_node().

Example::

root = Node(name="Root")
child = Node(name="Child")
root.add_child(child)
assert child.parent is root
assert root.children["Child"] is child

Initialization

strict_errors: ClassVar[bool]

True

script_error_raised

‘Signal(…)’

classmethod __init_subclass__(**kwargs)

property name: str

property process_mode: simvx.core.descriptors.ProcessMode

property visible: bool

reset_error() → None

Clear script error flag to re-enable processing.

add_child(node: simvx.core.node.Node) → simvx.core.node.Node

Add a node as a child, reparenting it if already in a tree.

Args: node: The node to add. Removed from its current parent first.

Raises: ValueError: node is self or one of self’s ancestors – either would create a cycle in the scene tree.

remove_child(node: simvx.core.node.Node)

Remove a child node from this node’s children.

reparent(new_parent: simvx.core.node.Node)

Remove from current parent and add to new_parent.

get_node(path: str) → simvx.core.node.Node

Navigate tree by path: ‘Child/GrandChild’ or ‘../Sibling’.

find_child(name: str, recursive: bool = False) → simvx.core.node.Node | None

Find first child with the given name.

find(target: type | str, recursive: bool = True) → simvx.core.node.Node | None

Find first descendant matching target.

Dispatches on the argument type:

• find(NodeClass) returns the first descendant isinstance of NodeClass (recursive by default).

• find("name") returns the first descendant whose name attribute equals the string (recursive by default).

Recursion is depth-first, pre-order. Returns None when no match.

find_all(node_type: type, recursive: bool = True) → list

Find all descendants of type.

walk(*, include_self: bool = True) → collections.abc.Iterator[simvx.core.node.Node]

Iterate this node and all descendants in DFS pre-order.

property path: str

add_to_group(group: str)

Add this node to a named group.

remove_from_group(group: str)

Remove this node from a named group.

is_in_group(group: str) → bool

Check if this node belongs to a named group.

on_ready() → None

Called once after the node and all its children enter the scene tree.

Override to perform initialisation that requires the scene tree – finding sibling nodes, connecting signals, spawning children. The tree property is available. Called after on_enter_tree() and after all children’s on_ready().

Decorate other methods with @on_ready to register additional ready handlers; they fire after the override in declaration order.

Note: Fires again if the node is removed and re-added to the tree.

Example::

def on_ready(self):
    self.sprite = self.get_node("Sprite")
    self.health_changed.connect(self._update_hud)

on_enter_tree() → None

Called when the node enters the scene tree, before on_ready().

Override for setup that must happen the moment the tree reference becomes available. Children have not entered yet at this point, so avoid querying child nodes here – use on_ready() instead.

Example::

def on_enter_tree(self):
    self.add_to_group("enemies")

on_exit_tree() → None

Called when the node is about to leave the scene tree.

Override to clean up resources, disconnect external signals, or persist state. Children have already exited by the time this fires on the parent.

Example::

def on_exit_tree(self):
    self.save_progress()
    self.remove_from_group("enemies")

on_process(dt: float) → None

Called every frame for game logic.

Args: dt: Seconds elapsed since the previous frame (variable timestep).

Override for movement, AI, animation triggers, or any per-frame update. Obeys process_mode – disabled or paused nodes are skipped automatically.

Decorate other methods with @on_process to register additional per-frame handlers; they fire after the override in declaration order. For state held while a button is pressed, poll Input.is_action_pressed("name") from inside on_process.

Example::

def on_process(self, dt):
    self.position += self.velocity * dt

on_physics_process(dt: float) → None

Called at a fixed timestep (default 60 Hz) for physics logic.

Args: dt: Fixed time step in seconds (e.g. 1/60).

Override for deterministic physics updates – forces, collision responses, rigid-body integration. Runs independently of the render frame rate.

Example::

def on_physics_process(self, dt):
    self.velocity += self.gravity * dt
    self.move_and_slide()

on_draw(renderer) → None

Called each frame for custom 2D drawing.

Args: renderer: The active draw-command recorder (e.g. Draw2D).

Override to issue immediate-mode draw calls such as draw_line, draw_rect, or draw_text. Called only when visible is True.

Example::

def on_draw(self, renderer):
    renderer.draw_circle(self.world_position, 10, colour=(1, 0, 0, 1))

on_picked(event: simvx.core.events.InputEvent) → None

Called when a 3D mouse-pick event hits this node’s collision shape.

Args: event: The input event containing click position, camera ray, etc.

Override to react to direct interaction with this 3D object – selection, dragging, context menus.

Example::

def on_picked(self, event):
    if event.button == MouseButton.LEFT:
        self.selected = True

on_unhandled_input(event: simvx.core.events.TreeInputEvent) → None

Called for input events that no @on_input handler consumed.

Args: event: The unhandled input event.

Use for catch-all bindings such as global debug toggles or pause menus that should only fire when no other handler returned a truthy value to consume the event. For most input handling use @on_input(...) decorators with explicit filters; the dispatch tables route them directly without walking the tree.

Example::

def on_unhandled_input(self, event):
    if event.key == Key.F3:
        self.toggle_debug_overlay()

start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle

Register a generator coroutine to run each frame. Returns a cancellable handle.

stop_coroutine(gen_or_handle)

Stop and remove a running coroutine (accepts generator or CoroutineHandle).

clear_children()

Destroy all children of this node.

destroy()

Schedule this node for removal at the end of the current frame.

Signal connections made through this node’s bound methods are proactively disconnected so emitters stop dispatching to it on the next emit (Godot 4 behaviour). Lazy weak-ref cleanup in Signal.__call__ covers nodes that are GC’d without destroy().

property app

The App running this node’s scene tree. Available after enter_tree().

property tree: simvx.core.scene_tree.SceneTree

The SceneTree this node belongs to.

__getitem__(key: str)

Shorthand for get_node: self["Child/Path"].

classmethod get_properties() → dict[str, simvx.core.descriptors.Property]

Return all Property descriptors declared on this node class and its bases.

__repr__()

class simvx.core.node.Timer(duration: float = 1.0, one_shot: bool = True, autostart: bool = False, **kwargs)

Bases: simvx.core.node.Node

Fires timeout signal after duration. Supports one-shot and repeating.

Initialization

duration

‘Property(…)’

one_shot

‘Property(…)’

autostart

‘Property(…)’

start(duration: float = 0)

Start or restart the timer, optionally overriding duration.

stop()

Stop the timer and reset time_left to zero.

property stopped: bool

property time_left: float

on_process(dt: float)

strict_errors: ClassVar[bool]

True

script_error_raised

‘Signal(…)’

classmethod __init_subclass__(**kwargs)

property name: str

property process_mode: simvx.core.descriptors.ProcessMode

property visible: bool

reset_error() → None

add_child(node: simvx.core.node.Node) → simvx.core.node.Node

remove_child(node: simvx.core.node.Node)

reparent(new_parent: simvx.core.node.Node)

get_node(path: str) → simvx.core.node.Node

find_child(name: str, recursive: bool = False) → simvx.core.node.Node | None

find(target: type | str, recursive: bool = True) → simvx.core.node.Node | None

find_all(node_type: type, recursive: bool = True) → list

walk(*, include_self: bool = True) → collections.abc.Iterator[simvx.core.node.Node]

property path: str

add_to_group(group: str)

remove_from_group(group: str)

is_in_group(group: str) → bool

on_ready() → None

on_enter_tree() → None

on_exit_tree() → None

on_physics_process(dt: float) → None

on_draw(renderer) → None

on_picked(event: simvx.core.events.InputEvent) → None

on_unhandled_input(event: simvx.core.events.TreeInputEvent) → None

start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle

stop_coroutine(gen_or_handle)

clear_children()

destroy()

property app

property tree: simvx.core.scene_tree.SceneTree

__getitem__(key: str)

classmethod get_properties() → dict[str, simvx.core.descriptors.Property]

__repr__()