`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, WHEN_PAUSED, 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

script_error_raised¶: ‘Signal(…)’

classmethod __init_subclass__(**kwargs)¶

property name: str¶

property process_mode: simvx.core.descriptors.ProcessMode¶

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.

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(node_type: type) → simvx.core.node.Node | None¶: Find first child of type (direct children only).

find_all(node_type: type, recursive: bool = True) → list¶: Find all descendants of type.

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.

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 enter_tree() and after all children’s ready().

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

Example::

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

enter_tree() → None¶

Called when the node enters the scene tree, before 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 ready() instead.

Example::

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

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 exit_tree(self):
    self.save_progress()
    self.remove_from_group("enemies")

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.

Example::

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

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 physics_process(self, dt):
    self.velocity += self.gravity * dt
    self.move_and_slide()

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 draw(self, renderer):
    renderer.draw_circle(self.global_position, 10, color=(1, 0, 0, 1))

input_event(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 input_event(self, event):
    if event.button == MouseButton.LEFT:
        self.selected = True

input(event: simvx.core.events.TreeInputEvent) → None¶

Called for input events propagated through the scene tree.

Args: event: A tree-level input event. Set event.handled = True to stop propagation.

Events travel from leaf nodes to root (front-to-back). If any node marks the event as handled, subsequent nodes receive it only via unhandled_input().

Example::

def input(self, event):
    if event.key == "escape":
        self.pause_menu.show()
        event.handled = True

unhandled_input(event: simvx.core.events.TreeInputEvent) → None¶

Called for input events that no other node has handled.

Args: event: The unhandled tree-level input event.

Use for catch-all bindings such as global shortcuts or debug toggles that should only fire when no UI element consumed the event.

Example::

def unhandled_input(self, event):
    if event.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).

destroy()¶: Schedule this node for removal at the end of the current frame.

queue_free¶: None

property tree: simvx.core.scene_tree.SceneTree¶: The SceneTree this node belongs to.

get_tree() → simvx.core.scene_tree.SceneTree¶: Return 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.

get_settings¶: None

__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¶

process(dt: float)¶

script_error_raised¶: ‘Signal(…)’

classmethod __init_subclass__(**kwargs)¶

property name: str¶

property process_mode: simvx.core.descriptors.ProcessMode¶

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(node_type: type) → simvx.core.node.Node | None¶

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

property path: str¶

add_to_group(group: str)¶

remove_from_group(group: str)¶

is_in_group(group: str) → bool¶

ready() → None¶

enter_tree() → None¶

exit_tree() → None¶

physics_process(dt: float) → None¶

draw(renderer) → None¶

input_event(event: simvx.core.events.InputEvent) → None¶

input(event: simvx.core.events.TreeInputEvent) → None¶

unhandled_input(event: simvx.core.events.TreeInputEvent) → None¶

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

stop_coroutine(gen_or_handle)¶

destroy()¶

queue_free¶: None

property tree: simvx.core.scene_tree.SceneTree¶

get_tree() → simvx.core.scene_tree.SceneTree¶

__getitem__(key: str)¶

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

get_settings¶: None

__repr__()¶

simvx.core.node¶

Module Contents¶

Classes¶

Data¶

API¶

`simvx.core.node`¶