simvx.core.scene_tree

SceneTree — Central manager for the node tree, groups, input routing, and UI focus.

Module Contents

Classes

SceneTree

Central manager for the node tree, groups, input routing, and UI focus.

Data

RESERVED_AUTOLOAD_EVENTS
log

API

simvx.core.scene_tree.RESERVED_AUTOLOAD_EVENTS

‘events’

simvx.core.scene_tree.log

‘getLogger(…)’

class simvx.core.scene_tree.SceneTree(screen_size=None, *, isolated_input: bool = False)

Central manager for the node tree, groups, input routing, and UI focus.

Owns the root node and drives per-frame process / physics_process / draw traversals. Also manages pause state, scene changes, and the UI input pipeline (mouse, keyboard, popups).

Initialization

property app

The App instance running this tree (set by graphics backend).

property events: simvx.core.event_bus.EventBus

Engine-provided typed event bus.

Use tree.events.connect(EventCls, handler) to register a typed handler and tree.events.emit(event) (or emit_deferred) to publish. The bus survives change_scene() – connections held by autoloads or other long-lived objects keep firing across scene swaps. Deferred events queued during a frame are dispatched at the start of the next process() tick, before any node _process runs.

property input

The Input instance for this tree (per-tree isolation).

property input_map

The InputMap instance for this tree (per-tree isolation).

activate_input()

Context manager to make this tree’s Input/InputMap the active ones.

Use this when processing the tree so that game code calling Input.is_action_pressed(...) sees this tree’s input state.

property is_running: bool

Whether the tree is actively being ticked by its driving app.

Set to False by :meth:quit (or the graphics backend’s app quit()), signalling the main loop to exit at the end of the current frame.

quit() → None

Request a clean shutdown of the running tree.

Emits :attr:quit_requested and flips :attr:is_running to False. The driving app polls this state and exits its loop at the end of the current frame. Safe to call from node callbacks or signal handlers.

property screen_size: tuple[float, float]

set_root(root: simvx.core.node.Node)

Set the root node of the scene tree.

change_scene(new_root: simvx.core.node.Node)

Swap the active root with new_root.

The old root receives _exit_tree; new_root then runs the full _enter_tree / _ready_recursive path, identical to the initial root. Autoloads are left in place and their groups and unique-name entries are re-registered on the rebuilt tree. Pending deletes, UI popup state, and the active 2D camera are cleared.

Use this for title → gameplay → game-over navigation. See

Doc:

../patterns for a full example.

process(dt: float)

Run process callbacks and coroutines on all nodes for one frame.

Order: autoloads’ _process first (Godot-style global singletons), then self.events.flush_deferred() so deferred events queued during the previous frame (process, physics, or input) reach all subscribers before scene logic runs, then the scene root’s _process. Anything emit_deferred’d during this frame’s autoload pass is also drained in the same flush, keeping the scene’s view of the world consistent.

physics_process(dt: float)

Run physics_process callbacks on all nodes, then auto-step physics.

propagate_input(event) → None

Propagate an input event through the node tree.

Walks the tree front-to-back (children before parents, reversed child order). Each node’s input() is called until event.handled is set. unhandled_input() is called on all remaining nodes regardless.

draw(renderer)

push_popup(control)

Register a control as an active popup (drawn on top, receives input first).

pop_popup(control)

Unregister a popup control.

input_cast(screen_pos: tuple[float, float] | numpy.ndarray, button: simvx.core.input.enums.MouseButton = MouseButton.LEFT)

Cast a ray from screen_pos through the camera into the scene. Finds the nearest pickable CollisionShape3D and delivers an InputEvent to its parent node.

get_group(name: str) → list[simvx.core.node.Node]

Get all nodes in a group.

property autoloads: dict[str, simvx.core.node.Node]

Read-only view of registered autoloads.

add_autoload(name: str, node: simvx.core.node.Node)

Register node as a persistent singleton attached to the tree.

The node enters the tree and runs ready() immediately. Unlike a regular child, it is not reachable via the scene root — retrieve it via tree.autoloads[name]. Autoloads survive change_scene(), making them the canonical home for global state (score, settings, audio manager). See :doc:../patterns.

The name "events" is reserved for the engine-provided

Class:

~simvx.core.event_bus.EventBus; use tree.events instead.

remove_autoload(name: str)

Unregister and tear down an autoload. Calls _exit_tree on the node.

get_unique(name: str) → simvx.core.node.Node | None

Get a unique node by name. Returns None if not found.

ui_input(mouse_pos: tuple[float, float] | numpy.ndarray = None, button: int = 0, pressed: bool = True, key: str = '', char: str = '')

Route UI input events to controls.

touch_input(finger_id: int, action: int, x: float, y: float)

Route multi-touch events to controls with touch_mode=’multi’.