simvx.core.scene_tree

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

Module Contents

Classes

SceneTreeTimer	A transient one-shot timer owned by the :class:SceneTree.
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.SceneTreeTimer(seconds: float)

A transient one-shot timer owned by the :class:SceneTree.

Created via :meth:SceneTree.create_timer. Emits timeout once after its delay elapses, then the tree drops it. Lighter than a :class:~simvx.core.Timer node: it lives only on the tree’s timer list, not in the scene graph.

Initialization

__slots__

(‘timeout’, ‘_time_left’)

property time_left: float

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

classmethod current() → simvx.core.scene_tree.SceneTree | None

Return the most recently activated SceneTree, or None.

Activation happens automatically on set_root / change_scene. Used by InputSimulator to deliver scene-tree + UI-tree events without requiring callers to thread a tree reference through.

Held weakly: returns None once the tree has no remaining strong references (e.g. a test dropped it), which is the correct “no active tree” semantics.

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.subscribe(EventCls, handler) to register a handler and tree.events.publish(event) (or publish_deferred) to dispatch. The bus survives change_scene() – subscriptions 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 audio_backend: simvx.core.audio_protocol.AudioBackend | None

The active audio backend, or None if none was initialised.

Returns the union :class:AudioBackend type for backwards compatibility: callers that only need one facet should prefer the narrowed :attr:audio_playback / :attr:audio_streaming /

Attr:

audio_buses properties so the type checker enforces the boundary. Reaching for the underscore-prefixed attribute is engine-private and may change.

The engine sets this during App.run via make_backend. Tests and headless harnesses that don’t initialise audio see None.

install_audio_backend(backend: simvx.core.audio_protocol.AudioPlaybackBackend) → None

Install the audio backend for this tree: the one canonical path.

This is the only supported way to attach a backend; assigning the private _audio_backend slot is no longer part of the contract. Used by App.run / WebApp at startup and by tests that inject a

Class:

NullAudioBackend or a mock.

Semantics mirror startup driver selection in other engines (Godot’s --audio-driver, pyglet’s audio option): a backend is installed once, before the tree starts producing sound. Re-installing shuts the previous backend down first so device handles don’t leak.

Facet conformance is enforced where it is consumed, not here: the

Attr:

audio_playback / :attr:audio_streaming / :attr:audio_buses accessors narrow via isinstance and return None for a backend that doesn’t implement that facet, and callers raise

Class:

AudioCapabilityError on None. Gating here as well would duplicate that boundary and reject legitimate partial backends.

property audio_playback: simvx.core.audio_protocol.AudioPlaybackBackend | None

The active backend narrowed to :class:AudioPlaybackBackend, or None.

Always equals :attr:audio_backend cast to the playback facet when a backend is present: every shipped backend implements playback, including the silent :class:NullAudioBackend.

property audio_streaming: simvx.core.audio_protocol.AudioStreamingBackend | None

The active backend narrowed to :class:AudioStreamingBackend, or None.

Returns None when the active backend doesn’t implement streaming (the Null backend, any future no-device test stub). Callers that need streaming (:class:AudioSynth driver, AudioWorklet feeds) should raise :class:AudioCapabilityError on None.

property audio_buses: simvx.core.audio_protocol.AudioBusBackend | None

The active backend narrowed to :class:AudioBusBackend, or None.

Always equals :attr:audio_backend cast to the bus facet when a backend is present: every shipped backend implements bus + capability advertisement.

audio_listener_3d() → simvx.core.audio_listener.AudioListener3D | None

The active 3D audio listener, lazy-creating one if none exists.

Returns the most recently entered :class:AudioListener3D in the scene. If none has been added, auto-creates a fallback parented to the active Camera3D with a one-time warning. Returns None only if there’s no camera either.

Audio players call this every frame, so the auto-creation is cheap once it’s happened (the cached listener is returned).

audio_listener_2d() → simvx.core.audio_listener.AudioListener2D | None

The active 2D audio listener, lazy-creating one if none exists.

Same contract as :meth:audio_listener_3d but for 2D.

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. _in_processing marks the span so InputMap.add_action can tell a node-callback registration (lands in this tree’s map, works on every backend) from a late out-of-band call (see the web-export warning).

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.

property now: float

Monotonically-increasing scene time, in seconds.

Accumulates dt at the start of every :meth:tick call (after any :attr:simvx.graphics.App.time_scale scaling has been applied), so slow-motion and hitstop also slow this clock. Frozen while

Attr:

paused is True. Resets to 0.0 only by constructing a fresh SceneTree.

Use for time-based animation, slow-mo gating, and any “how long has the scene been running” query: preferable to per-node self._time += dt accumulators because every consumer reads the same monotonic value.

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.

Before the root enters the tree, any input_actions declared on the root (class- or instance-level dict[str, list]) is bulk- registered with this tree’s InputMap. This is the canonical replacement for the wrapper-class + on_ready boilerplate and survives change_scene swaps – every new root’s actions are re-registered automatically.

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.

flush_layout() → None

Reflow every dirty container now, root-first, and expire the rect cache.

Synchronous layout settle: after this returns, container children have their final positions/sizes for this frame, so get_global_rect is valid immediately (no one-tick lag). Called at end-of-tick and, crucially, right when an overlay/popup opens so a freshly-shown dialog can be hit-tested and focus-elected on the same tick. Idempotent and O(1) when no container is dirty.

tick(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.

property physics_world: simvx.core.physics.world.PhysicsWorld

The tree’s default PhysicsWorld (new seam), created lazily on first access.

Bodies with no PhysicsRoot ancestor resolve here. Lazy so non-physics scenes never allocate a world. Backend follows the selection precedence (no node override -> project physics_backend setting > auto-discovered native > Builtin), gravity -Y. Tree-scoped: it persists across change_scene (like events) and is released only by quit() / GC.

property has_physics_world: bool

True iff a default world has been lazily created (no allocation).

property physics_world_2d: simvx.core.physics.world2d.Physics2DWorld

The tree’s default 2D PhysicsWorld (T2f), created lazily on first access.

The 2D sibling of :attr:physics_world. 2D bodies with no PhysicsRoot2D ancestor resolve here. Lazy so non-2D-physics scenes never allocate it. Backend follows the selection precedence (no node override -> project physics_backend setting > auto-discovered native > Builtin), gravity Vec2(0, -9.81) (Y-up). Tree-scoped: persists across change_scene, released by quit() / GC.

register_physics_world(world: simvx.core.physics.world.PhysicsWorld) → None

Register a PhysicsRoot’s isolated world so physics_tick steps it.

Idempotent: a world already present is not added twice (defends against re-entrant enter_tree). Called from PhysicsRoot.on_enter_tree.

unregister_physics_world(world: simvx.core.physics.world.PhysicsWorld) → None

Unregister a PhysicsRoot’s world (PhysicsRoot.on_exit_tree). No-op if absent.

register_physics_body(world: simvx.core.physics.world.PhysicsWorld, handle: simvx.core.physics.world.BodyHandle, node: simvx.core.node.Node) → None

Register a body node for post-step transform read-back.

Called by PhysicsBody3D.on_enter_tree for non-static bodies. Marks the world’s membership dirty so the next sync rebuilds the bulk order + buffer. Weak reference: a GC’d node auto-drops.

unregister_physics_body(world: simvx.core.physics.world.PhysicsWorld, handle: simvx.core.physics.world.BodyHandle) → None

Unregister a body node (PhysicsBody3D.on_exit_tree). No-op if absent.

Drops the whole per-world _BodySync once empty so idle worlds cost nothing.

register_physics_node(world: simvx.core.physics.world.PhysicsWorld, handle: simvx.core.physics.world.BodyHandle, node: simvx.core.node.Node) → None

Register a body node in the collision-event handle->node map.

Called by PhysicsBody3D.on_enter_tree for ALL modes (static included), so :meth:_dispatch_contact_events can resolve both sides of a contact pair. Mode-independent: unlike register_physics_body this map never changes on a mode flip. Weak reference: a GC’d node auto-drops.

unregister_physics_node(world: simvx.core.physics.world.PhysicsWorld, handle: simvx.core.physics.world.BodyHandle) → None

Unregister a body node from the collision-event map. No-op if absent.

Drops the whole per-world map once empty so idle worlds cost nothing.

interpolate_physics(alpha: float) → None

Write the render pose of every captured new-world body: lerp(prev, cur, alpha).

alpha is the fixed-step fraction physics_accum / physics_dt in [0, 1). Position lerps linearly; rotation slerps (shortest-arc, Quat.slerp). A sleeping body has prev == cur, so it lerps to a constant (correct, cheap). No-op when physics_interpolation is False (driver still calls it; the raw write already happened in _sync_physics_world during physics_tick).

physics_tick(dt: float)

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

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

Dispatch an input event to registered @on_input handlers.

Looks up handlers via the typed dispatch tables (built when nodes carrying @on_input-decorated methods enter the tree). The traversal is O(handlers per event), not O(nodes): nodes without any input handlers cost nothing.

A handler returning a truthy value marks the event consumed: on_unhandled_input only fires if nothing consumed the event. event.handled is also flipped True so callers can short-circuit.

render(renderer)

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.

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

Return one node from name (any member), or None if empty.

call_group(name: str, method: str, *args) → None

Call method(*args) on every node in name that defines it.

Convenience for the common broadcast (for n in tree.get_group(...): n.method(...)). Nodes lacking method are skipped, so mixed-type groups are safe.

create_timer(seconds: float) → simvx.core.scene_tree.SceneTreeTimer

Create a one-shot timer that emits timeout after seconds.

Returns immediately with a :class:SceneTreeTimer; connect its timeout signal to run code after the delay. The timer is owned and ticked by the tree (right after autoloads) and discarded once it fires, so it needs no Node in the scene and no manual cleanup. Honours tree.paused. For delays inside a coroutine, prefer wait(seconds).

call_deferred(method: collections.abc.Callable[..., Any], *args: Any) → None

Queue method(*args) to run at the end of this frame (escape hatch).

The tree-level counterpart to :meth:Node.call_deferred, for code that has no node to defer from (plugins, autoload helpers, non-node systems). Same discouraged-escape-hatch guidance applies: prefer a safe-by-default path (destroy, Property(coalesce=True), events.publish_deferred) when one exists. method is a callable, never a string.

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 on_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: simvx.core.input.enums.MouseButton | None = None, pressed: bool = True, key: str = '', char: str = '')

Route UI input events to controls.

button is a MouseButton for press/release, None for keyboard / char / pure mouse-move events.

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

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