simvx.core.scene_tree

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

Module Contents

Classes

ContentScaleMode	How a scene’s space relates to the render target it is presented in.
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_SINGLETON_EVENTS
log

API

simvx.core.scene_tree.RESERVED_SINGLETON_EVENTS

‘events’

simvx.core.scene_tree.log

‘getLogger(…)’

class simvx.core.scene_tree.ContentScaleMode

Bases: enum.StrEnum

How a scene’s space relates to the render target it is presented in.

Set through :attr:SceneTree.content_scale_mode, which documents what each one does to a layout and to the three sizes a game can read.

Initialization

Initialize self. See help(type(self)) for accurate signature.

EXPAND

‘expand’

FIT

‘fit’

__new__(*values)

__add__()

__contains__()

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getitem__()

__getnewargs__()

__getstate__()

__gt__()

__hash__()

__iter__()

__le__()

__len__()

__lt__()

__mod__()

__mul__()

__ne__()

__reduce__()

__reduce_ex__()

__repr__()

__rmod__()

__rmul__()

__setattr__()

__sizeof__()

__str__()

__subclasshook__()

capitalize()

casefold()

center()

count()

encode()

endswith()

expandtabs()

find()

format()

format_map()

index()

isalnum()

isalpha()

isascii()

isdecimal()

isdigit()

isidentifier()

islower()

isnumeric()

isprintable()

isspace()

istitle()

isupper()

join()

ljust()

lower()

lstrip()

partition()

removeprefix()

removesuffix()

replace()

rfind()

rindex()

rjust()

rpartition()

rsplit()

rstrip()

split()

splitlines()

startswith()

strip()

swapcase()

title()

translate()

upper()

zfill()

__deepcopy__(memo)

__copy__()

name()

value()

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, *, input_base: simvx.core.scene_tree.SceneTree | None = None)

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

Build a tree.

Args: screen_size: The render target’s size, (800, 600) by default. input_base: Another tree whose input entries (its actions, device aliases and redefinitions of engine entries) this one is built on, read live, as a branch inherits the entries above it. None, the default, starts from the engine’s entries and the process-wide map alone, which is what an editor hosting a game wants: the choice is made here and never inferred.

A tree owns its input. It has its own

Class:

~simvx.core.input.map.InputMap, its own contexts, its own focus, and its own delivered record of the device elements that actually reached it, which is the only thing its actions resolve from. So an editor and the game it is running never share action state, and neither has to ask for that.

Two things are underneath it and shared. The process-wide device record says what is physically down: Input.is_key_pressed, Input.capabilities, Input.controllers and Input.input_method describe the hardware under the player and say the same thing in every tree. And the process-wide InputMap is the bottom layer of this tree’s, read live, so an action registered before any tree existed, which is what a game’s main() does, is one this tree resolves.

A test that needs the machine clean calls

Func:

simvx.core.input.devices.reset and

Func:

simvx.core.input.capabilities.reset, or Input._reset(), which covers the first.

verify_input_order: bool

False

input_delivered

‘Signal(…)’

script_error

‘Signal(…)’

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 singletons or other long-lived objects keep firing across scene swaps, and those the replaced scene’s nodes held end when it is destroyed. 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.

A backend that paces itself by the engine rather than by a device clock declares :class:~simvx.core.audio_protocol.TreeBoundAudioBackend, and installing hands it this tree: several trees can be alive at once, so it has to be told which one’s ticks are its own.

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()

Return a context manager making this tree’s Input/InputMap the active ones.

Wrap any engine-driven tree work in this. Node code that runs inside the span sees this tree, so Input.pressed(...) reads this tree’s state and InputMap.add_action(...) lands in this tree’s own map rather than the process-wide default. The span is also how InputMap.add_action tells such a registration from a genuinely out-of-band one made while the scene is running.

Every tree entry point that runs this tree’s node code opens the span, so the rule holds without the caller doing anything: a tick, a physics step, a mount (set_root, change_scene, add_singleton, Node.add_child), a teardown (change_scene, remove_singleton, Node.remove_child), @on_input dispatch, UI, multi-touch and 3D pick dispatch, a focus or hover change, a layout flush, drawing (on_draw), and the tree’s own screen_resized and quit_requested emits.

What that does not cover is code reaching node methods without going through the tree at all: calling a hook by hand, or emitting a signal the tree owns from outside it. Such a caller wraps the work itself.

_input_span_depth is a re-entrant depth, so spans may nest freely (a change_scene called from on_update or from an @on_input handler mounts inside the span that is already open).

property paused: bool

Whether the scene is suspended: a node runs only if it says so.

A node’s update_mode decides what the pause means for it: PAUSABLE stops, ALWAYS carries on, PAUSED_ONLY runs only while this is True, which is what a pause menu is. The switch reaches input as well as processing, so a paused player neither polls nor hears, and an input_context on a paused node stops declaring and stops hiding until the node wakes.

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 or any inert overlay is open. 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]

The size of the space this scene is laid out in, in engine units.

Under :attr:content_scale_mode EXPAND, the default, that is the render target: a wider window is a wider scene and shows more. Under FIT it is :attr:content_scale_size, the design resolution, whatever the window is doing, because under FIT the scene’s space is design units all the way through.

Assigning says the render target is now this big, which is what a backend does on a resize. Under EXPAND that is the same statement as the one above; under FIT it changes the letterbox and leaves what this reads back alone. The three sizes and which question each answers are set out in :attr:content_scale_mode.

An on_draw that read it is re-captured when it changes.

property window_size: tuple[float, float]

The render target this scene is presented in, in engine units.

The glass, as opposed to :attr:screen_size, which is the space the scene is laid out in. They are the same under EXPAND and differ under FIT.

property content_scale_mode: simvx.core.scene_tree.ContentScaleMode

How the scene’s space relates to the render target it is shown in.

EXPAND (the default) means an engine unit is a logical pixel of the render target: the scene’s space is the window, a wider window shows more world, and a HUD anchored to a screen edge is on the glass. This is what anything with a HUD wants and it is what every backend does.

FIT preserves a design resolution for a fixed playfield: the scene is always :attr:content_scale_size units across, that rect is scaled up uniformly to the largest that fits the window and centred, and the leftover bars belong to no viewport. Under FIT the root viewport’s space is design units: the letterbox is applied once, where input enters, so PointerEvent.position, Input.mouse_position,

Attr:

screen_size and every Control rect are already design units and no consumer transforms anything. A pointer over a bar has a design coordinate outside the design rect and therefore hits nothing, by ordinary geometry rather than by a special case.

What each size answers, which is the thing to be careful about. These three agree under EXPAND and deliberately differ under FIT:

========================== ========================================== app.width the window. The glass, always, because a game placing an OS dialog or remembering a window size needs the real one tree.screen_size the space the scene is laid out in: design units under FIT node.viewport_size the target that node draws into, which is screen_size unless a SubViewport ancestor renders it offscreen ========================== ==========================================

A game that wants a screen-edge HUD wants EXPAND. Under FIT a HUD anchored to an edge lands on the edge of the design rect, not of the glass, which is right for a playfield and wrong for a HUD that wants the whole screen: FIT buys one coherent space at the price of the bars.

property content_scale_size: tuple[float, float]

The design resolution FIT preserves, in engine units.

Defaults to the size the tree was built at, which is the size the game asked its window for, so a game that switches to FIT and says nothing else keeps the layout it authored. Ignored under EXPAND.

property content_scale: float

Render-target units per engine unit: 1.0 under EXPAND.

Under FIT this is how much the design rect is magnified to fill the window, which is what a delta measured on the glass has to be divided by to become a delta in the scene’s space. :meth:window_to_viewport does that for a position; this is for everything else.

property presentation_rect: tuple[float, float, float, float]

(x, y, w, h) of the glass the scene’s space is presented into.

In engine units, measured on :attr:window_size. The whole window under EXPAND; under FIT the design rect scaled uniformly and centred, with the letterbox bars in the margin.

The exact inverse of :meth:window_to_viewport, and computed from the same placement, so what a renderer draws and what a pointer hits cannot drift: a point at the rect’s top-left corner converts to (0, 0) in the scene’s space, a point at its bottom-right to

Attr:

screen_size, and a point in a bar to a coordinate outside both.

property screen_insets: tuple[float, float, float, float]

Edges of the scene’s space something is covering, as (left, top, right, bottom).

In screen pixels, measured inward from the edges of :attr:screen_size, and all zero unless a backend says otherwise. A soft keyboard sliding up is a bottom inset, a notch is a top or side one, and a home indicator is a small bottom one.

A node keeping something out of them reads node.viewport_insets instead, which answers in the pixels of the space that node draws in: a Control under :attr:ui_scale gets UI pixels it can use as margins directly, where these would be too large by the factor.

Only a backend that can actually ask the platform writes this, and one that can declares Input.capabilities.screen_insets when it does. A backend that cannot declares nothing and this stays zero, which is the honest answer rather than a gap: zero insets is exactly what a desktop window has.

Assigning takes insets measured on the glass, which is what a platform reports, and is the backend’s door in the way :attr:screen_size is. Under FIT they are converted: the letterbox bars already sit between the window edge and the scene’s, so an inset that only reaches into a bar occludes nothing and arrives here as zero.

A change, and only a change, re-captures every on_draw that read the insets and then fires screen_insets_changed with the new value, which is where code outside on_draw that keeps something clear of them listens. A backend may therefore write them every frame.

property ui_scale: float

How big the interface is drawn, as the player chose it. 1.0 is as authored.

Every Control in this tree is laid out and drawn at this size; the game world is not. A settings slider assigns it and the interface resizes on the next frame, the slider included::

def on_ready(self):
    slider = self.add_child(Slider(1.0, 2.0, value=self.tree.ui_scale))
    slider.value_changed.connect(self._set_ui_scale)

def _set_ui_scale(self, value):
    self.tree.ui_scale = value

The scale lives in the space rather than in the widgets: the outermost control of each interface lays out against screen_size / ui_scale and carries the factor in its transform, so fonts, paddings, minimum sizes and a game’s own hard-coded 40.0 all grow together, and a click finds the control it lands on because hit testing goes through the same transform. Text is laid out at the size it is drawn at rather than laid out small and magnified, so glyphs stay on the pixel grid at fractional factors. Control.viewport_size answers in the divided space, which is the space a control’s on_draw works in.

It is a preference, not a density: an engine unit is already one density-independent pixel, so a 44-unit button is the same physical size on every screen at 1.0 and nothing here should be multiplied by a display’s pixel ratio. It belongs to this tree, so an editor and the game running inside it are scaled independently, and it survives

Meth:

change_scene because the tree does. Keeping it across runs is the game’s job: load it and assign it in the root’s on_ready.

A world node’s on_draw that read it is re-captured when it changes, as every control’s is.

Raises: ValueError: the value is not a finite number above zero.

window_to_viewport(x: float, y: float) → tuple[float, float]

A point on the glass, as a point in the space the scene is laid out in.

The identity under EXPAND. Under FIT it undoes the letterbox, and a point in a bar comes back outside the design rect rather than clamped to its edge: the bars belong to no viewport, so a pointer over one has to hit nothing, and a coordinate that is simply out of range does that without anything having to check for it.

property root: simvx.core.node.Node | None

The current scene’s root node.

A sibling of this tree’s singletons under the tree’s own top node, and the node every scene-facing walk starts from: rendering, 3D submission, saving, hot reload and the editor’s scene panel all begin here, so a singleton is ticked but is not part of the scene.

Assigning re-links the child and runs no lifecycle, which is what assigning to it has always done. Use :meth:set_root to mount a scene (enter + ready) and :meth:change_scene to swap one.

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

Mount root as the current scene.

The root’s input_context, like any node’s, comes into force as it enters, and goes with it when another scene replaces it.

A scene already mounted is carried out first, so its on_exit_tree runs, but it is not destroyed. change_scene remains the call for a swap: it destroys the old scene and also clears popup state and the active 2D camera.

The mount itself runs inside this tree’s input span, so on_enter_tree / on_ready code sees this tree’s Input and InputMap, and any action it registers lands in this tree’s own map.

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

End the current scene and mount new_root in its place.

The old scene is destroyed: every node in it runs on_exit_tree, then is finished exactly as :meth:Node.destroy finishes a node, so its signal connections and EventBus subscriptions end there and then, and none of its nodes can be added to a tree again. A lambda or other strongly held callable it subscribed still fires until it is unsubscribed, as it would after destroy(). To carry state into the next scene, pass values to new_root, not nodes of the old one.

new_root then runs the full _enter_tree / _ready_recursive path, identical to the initial root. Singletons the tree owns are left in place, keeping their groups and unique names; a singleton registered on a node the old scene owned leaves with that scene, and its name binding is dropped. UI popup state and the active 2D camera are cleared.

Called from the scene’s own code, the call does not return. A hook, an input handler, a signal a control emitted or a contact handler that the tree is running for the scene ends that scene where it stands: the code that asked unwinds (its finally blocks run, with the old scene still in place), nothing further in the old scene runs that frame, and the tree then carries the old scene out and mounts new_root from its own frame, never from inside the old scene’s walk. So the first scene change a scene makes is the one that happens; a second node that would have decided otherwise later in the same walk is never reached. A scene changed from on_update starts on the next frame; one changed from an input handler or on_fixed_update runs the rest of the frame.

Called from anywhere else (a singleton, a deferred call, a timer, code outside the frame), it swaps at once and returns with tree.root already the new scene.

The new scene is given no edge for anything already held when it arrived, because that press was delivered to the scene that ended: a held key reads at rest there until it is let go and pressed again.

A change asked for while the old scene is being carried out (from one of its on_exit_tree hooks) is ignored: the change already under way is the one that happens.

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

Doc:

../patterns for a full example.

Raises: ValueError: new_root is the current scene or a node inside it, or has been destroyed or is about to be (a scene an earlier change_scene replaced, kept to come back to). Nothing has changed when it raises.

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.

The reflow itself runs inside this tree’s input span: _do_update_layout is an overridable hook, so a custom container laying itself out sees this tree’s Input and InputMap.

tick(dt: float)

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

Order: singletons’ _process first, in registration order (global nodes, before the scene), 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 singleton pass is also drained in the same flush, keeping the scene’s view of the world consistent.

Singletons and the current scene are siblings under the tree’s own top node, and the scene is always its last child, so every node the tree ticks is reached through exactly one containment path and processes exactly once. A node registered as a singleton and parented into the scene is a scene node that happens to have a name: it processes in its scene position, not ahead of the scene.

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

The tree’s default PhysicsWorld, 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, 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.

The world will not be stepped by this tree again, so any body still in its retirement grace period is released here rather than left holding a node alive (see :meth:retire_physics_node).

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.

retire_physics_node(world: simvx.core.scene_tree.AnyPhysicsWorld, handle: simvx.core.physics.world.BodyHandle) → None

Move a body node out of the live map and into the retirement grace period.

Called by PhysicsObject3D.on_exit_tree immediately before the backend body is destroyed. Destroying a body ENDS every contact and sensor overlap it was in, and the seam reports those closing EXITs on the first drain after the NEXT step (see

Meth:

~simvx.core.physics.world.PhysicsWorld.destroy_body). Dropping the handle->node entry here would leave that dispatch unable to name the peer that went away, so the entry is retired instead: held, with a STRONG reference to the node (the live map is weak, and the game has usually let go of a node it destroyed), until the events it is owed have been dispatched.

The grace period is one step, measured on this tree’s per-world step count, and :meth:_release_retired_physics_nodes ends it. Retirement is never consulted before the live map, so a backend that recycles handles resolves a reused handle to its NEW body.

One STEP, not one frame: a tree that stops stepping keeps the entry until it steps again, so pausing (or clearing auto_physics) immediately after a kill holds that one node for the duration of the pause. It is released on the next step regardless, and by change_scene and by unregistering the world, so it cannot outlive the scene either way.

No-op if the handle is not registered.

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, *, tick_input: simvx.core.input.tick.TickInput | None = None)

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

The node walk runs against one :class:~.input.tick.TickInput, which is what Input answers from inside on_fixed_update: held state as it was when the tick started, and the frame’s edges on the frame’s first tick and no other. Pass tick_input to drive a tick from a recorded or hand-built snapshot instead of from the live record; the physics step below is outside the span, since the solver asks nothing of input.

capture_input(event: simvx.core.input.events.InputEvent) → simvx.core.node.Node | None

The capture phase: offer event root-first to the capture=True handlers, and return who claimed it.

Runs ahead of every control, so a handler here sees a key before the focused text field does, and a claim is the whole of the event: no control, no action and no other handler hears it, and its release is claimed with it. It is how an editor keeps F5 and Ctrl+S whatever has focus and whatever the game it hosts is doing. Root-first, the reverse of the ordinary deepest-first phase, so an outer scope decides before the scopes inside it. Free in a tree where no capture handler was ever registered.

render(renderer)

Draw the scene, then the overlay layer, into renderer.

Runs inside this tree’s input span: on_draw is game code like any other hook, so a handler that reads Input or registers an action sees this tree rather than the process-wide default. That matters for an isolated tree, which is how the editor renders a game in play mode.

input_cast(screen_pos: tuple[float, float] | numpy.ndarray, button: simvx.core.input.controls.DeviceButton = Pointer.PRIMARY, *, source: simvx.core.input.events.InputEvent | None = None, pressed: bool = True) → simvx.core.node.Node | None

Cast a ray from screen_pos through the camera and deliver the hit.

The ray leaves the camera the tree renders through (see

Meth:

_active_camera_3d). The nearest pickable

Class:

CollisionShape3D under it wins, and its owner receives a

Class:

~simvx.core.input.events.PickEvent carrying the whole hit: the node, the world point, the surface normal there and the distance along the ray. Returns that node, or None when the ray reached nothing.

A pickable shape whose owner is a body in a physics world is hit on its real collider, through that world’s raycast. A shape with no body in a world (a free collider, or one on a body whose collision layer is empty and so answers no query) is tested against its bounding sphere,

Attr:

~CollisionShape3D.pick_radius.

pressed says which edge the pick is: a press’s pick reaches the node’s @on_picked handlers for presses, then its on_picked override; a release’s pick (pressed=False) reaches only the handlers declared with edge="release" or "both".

The pointer pipeline calls this in its targeted phase, after the UI has declined the pointer, and passes the pointer event as source: for every press, and for a release only while a node in the tree declares a release pick handler. A game or a tool can cast from anywhere else, which is why it stays public.

group(name, of=None, /)

The members of group name, in the order they joined it, as a new list.

A node joins a group when add_to_group runs while it is in this tree, or when it enters the tree already carrying the group; leaving the group or the tree drops it, and joining again puts it last.

Meth:

Node.destroy drops the node from its groups at once, although it stays in the tree until the end of the frame.

of, a class or a tuple of classes, keeps only the members that are instances of it, and the list is typed as that class, so a group may hold several types and a loop calls the right one’s methods::

for enemy in tree.group("enemies", Enemy):
    enemy.stun()

A runtime_checkable Protocol class as of matches by methods, not by inheritance; mypy refuses one where type[T] is expected, so such a call carries # type: ignore[type-abstract] under mypy (pyright accepts it).

The list is a snapshot: a member an earlier iteration destroys is still visited, as with any copy.

first(name, of=None, /)

The earliest-joined member of name that is an instance of of (any type if omitted), or None.

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 singletons) 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, singleton 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 singletons: dict[str, simvx.core.node.Node]

Read-only view of registered singletons.

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

Register node as a persistent singleton attached to the tree.

An unparented node is mounted as a child of the tree’s own top node: it enters the tree, runs on_ready() immediately, processes ahead of the scene in registration order, and survives change_scene(). Reach for it when a node must outlive the scene that started it: music that keeps playing across a scene change, or a save file held open. Retrieve one via tree.singletons[name]; it is not reachable from the scene root.

It is not a home for the game’s own state. A score belongs to whatever owns the run, and reaching it through a name from anywhere makes every reader of that name a writer of it.

A node the scene already owns may also be given a name. It stays where it is, so it processes in its scene position rather than ahead of the scene, and it leaves with its scene: after a change_scene the name is gone.

A singleton is ticked but not drawn – drawing walks the scene. A global HUD is either a child of the scene or a full-screen overlay.

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

Class:

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

Raises: ValueError: the name is "events"; the name is already bound to a different node; node already holds a different name; or node is a child of some other tree.

remove_singleton(name: str)

Drop a singleton’s name binding, and unmount it if the tree owns it.

A singleton the tree mounted (registered while unparented) is carried out of the tree, so its on_exit_tree runs and anything it registered on the way in is released. A singleton the scene owns keeps its place in the scene: dropping the name is the whole of the operation, because the node is a scene node that happens to have a name.

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

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

clear_delete_queue() → None

Abandon every pending :meth:Node.destroy without running it.

For a teardown that is carrying the whole tree out anyway (a harness dropping its tree): the queued nodes go with it, so the removal they were waiting for is moot. Clears their pending state as well, since a node left marked as destroying would report a removal that is never coming, and puts each one still in this tree back in its groups.

listen_input(event: simvx.core.input.events.InputEvent) → simvx.core.node.Node | None

Offer event to the listener that is hearing input now, before anything else.

An :class:~.input.listener.InputListener in the tree hears every control event of the device types it listens to ahead of the UI and every handler, which is what lets a rebind screen take the next press without the game playing it. The newest listener hears first.

Returns the listener that took the event, or None.

ui_key(event: simvx.core.input.events.KeyEvent) → simvx.core.node.Node | None

Route a key press or release to the UI.

The UI is handed the object the tree received, so a widget reads the physical key and the modifier flags off the same event a broadcast handler sees. Typed characters take :meth:ui_text, pointers

Meth:

ui_pointer and the wheel :meth:ui_scroll.

Returns the node that took the key, or None when the UI let it through. A focused text field swallowing W is what stops the character behind it walking.

Routing runs inside this tree’s input span: on_gui_input, focus signals and the pressed / released handlers reached from here are arbitrary game code, and they see this tree’s Input and InputMap.

ui_text(event: simvx.core.input.events.TextEvent) → simvx.core.node.Node | None

Route a typed character to the UI.

Returns the node that took it, or None. Runs inside this tree’s input span for the same reason :meth:ui_key does.

ui_pointer(event: simvx.core.input.events.PointerEvent) → simvx.core.node.Node | None

Route a pointer to the controls under it.

The UI is handed the object the tree received rather than a flattened copy of it, so a widget reads the phase, the button, the pressure and the pointer id off the same event a broadcast handler sees.

Returns the node that took the pointer, or None when nothing in the UI stops it.

ui_pad(event) → simvx.core.node.Node | None

Route a controller button or axis to UI navigation.

The pad’s half of ui_key: the UI resolves it through the same navigation actions a key goes through, so a controller can move focus, activate what it lands on and dismiss a dialog. Runs inside this tree’s input span for the same reason :meth:ui_key does.

Returns the node the pad’s press moved, activated or dismissed, or None when navigation did nothing with it.

ui_scroll(event: simvx.core.input.events.ScrollEvent) → simvx.core.node.Node | None

Route a wheel notch to the controls under it.

The UI receives the event the tree does, rather than a key named after it: a notch carries a position and a magnitude, and a key carries neither. Routing runs inside this tree’s input span for the same reason

Meth:

ui_key does.

Returns the control that took the notch, or None.

flush_pointer_motion() → None

Deliver the frame’s accumulated pointer motion, from every router.

Motion is coalesced into one event per frame carrying the frame’s total (:meth:InputRouter.flush_motion <simvx.core.input.router.InputRouter.flush_motion>), and this is where the frame spends it: at the top of the input phase, before physics, so a fixed tick reads a pointer position that is this frame’s. Several routers can feed one tree, and each holds its own device’s motion.

cancel_capture(pointer_id: int, event: simvx.core.input.events.PointerEvent)

Take a captured pointer back, telling whoever held it it was taken.

input_handover(*, pointers: bool = True, keys: bool = True) → None

Input is leaving this tree. Close what it was holding, press nothing.

Called by whatever stops feeding the tree: a :class:SceneHost that stops forwarding, is hidden, leaves its tree or loses the focus, and an editor pausing the game it runs. Leaving a tree is a handover rather than a switch, and the two differ in what they leave behind. A switch simply stops delivering, and everything the tree was holding stays held for ever: the filed form of that is a game paused in the editor whose character walks into a wall on resume with nothing touching the keyboard.

So the pointers in flight are cancelled, whoever holds one is told the gesture is over, the hover is left, and every open action closes with a real release edge. Nothing is pressed on arrival either: what the player is still physically holding does not count again until they let go and press.

Per kind: pointers is the mouse, the fingers and the pens; keys is the keyboard, the text session and the controllers. A host losing focus hands over the keys and leaves a drag in flight alone. The handover reaches every host inside this tree too, and never touches the device record.

Deliberately not :meth:InputRouter.focus_lost <simvx.core.input.router.InputRouter.focus_lost>, which replays device releases. A window that lost focus will not see the key come up, so replaying it is the truth; here the key is still down under the player’s finger and device state must go on saying so.

property focus_active: bool

Whether the keyboard reaches this tree now.

A window’s tree has it while the window has the operating system’s focus; a hosted tree while its :class:SceneHost holds focus in a tree that has it and is forwarding. A tree whose keyboard went elsewhere keeps its focused widget, drawn as it was, with this False.

hit_test(point: tuple[float, float], *, pointer_type: simvx.core.input.enums.PointerType | str = PointerType.MOUSE, source_id: int = 0) → simvx.core.node.Node | None

What point would hit: the nearest control under it, else the pickable body its ray meets.

Writes no state: no hover, no focus, no pick delivered. The same answer the pointer pipeline acts on, so code that crosses a host boundary (a drag session, a tooltip) asks the tree on the far side the question it would ask its own. pointer_type matters because a finger hits a touch target anywhere in its grown area.

property drag_threshold: dict[simvx.core.input.enums.PointerType, float]

How far a pointer travels from its press before the motion is a drag, per pointer type.

The default every node inherits; node.drag_threshold overrides it for a subtree. Assigning a map replaces the types it names and keeps the rest.

property focus_owner: simvx.core.node.Node | None

The node holding keyboard focus, or None. Read-only: grab_focus() and release_focus() move it.

property focus_reason: simvx.core.input.enums.FocusReason

Why keyboard focus last moved: a click, Tab, a direction, hover, an overlay, code, or the owner leaving.