simvx.core.descriptors

Descriptors, enums, and type aliases used throughout the engine.

Signal and Connection live in simvx.core.signals.

Module Contents

Classes

CoroutineHandle	Cancellable handle returned by Node.start_coroutine().
ProcessMode	Controls whether a node processes when the SceneTree is paused.
Notification	Notifications dispatched to nodes during lifecycle and property changes.
Collision	Collision info returned by move_and_slide.
Property	Descriptor for editor-visible, serializable node properties.
Child	Declarative child node. Auto-creates and adds during enter_tree.
OnReady	Lazy child lookup, resolved after ready().
Children	List-like container with named child access.

Data

log
Coroutine

API

simvx.core.descriptors.log

‘getLogger(…)’

simvx.core.descriptors.Coroutine

None

class simvx.core.descriptors.CoroutineHandle(gen: simvx.core.descriptors.Coroutine)

Cancellable handle returned by Node.start_coroutine().

The runtime drives coroutines with gen.send(dt) after the initial prime, so coroutines may receive the per-tick delta time via dt = yield. Coroutines that yield without binding the value still work: the sent dt is simply discarded.

Initialization

__slots__

(‘_gen’, ‘_cancelled’, ‘_primed’)

cancel()

Cancel this coroutine. It will be removed on the next tick.

property is_cancelled: bool

class simvx.core.descriptors.ProcessMode

Bases: enum.IntEnum

Controls whether a node processes when the SceneTree is paused.

Set via node.process_mode = ProcessMode.ALWAYS (and similar). The effective mode is resolved by walking up the tree until a non-INHERIT ancestor is found; the resolved value is cached and invalidated on reparent.

Pause the tree with tree.paused = True. When paused, only ALWAYS and PAUSED_ONLY nodes run their process / physics_process.

Because INHERIT walks ancestors, an ALWAYS mode set high in the tree propagates to every INHERIT descendant: defeating the pause for the whole subtree. Set ALWAYS only on leaf nodes or CanvasLayers, never on a game root with gameplay children.

Initialization

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

INHERIT

0

PAUSABLE

1

PAUSED_ONLY

2

ALWAYS

3

DISABLED

4

__abs__()

__add__()

__and__()

__bool__()

__ceil__()

__delattr__()

__dir__()

__divmod__()

__eq__()

__float__()

__floor__()

__floordiv__()

__format__()

__ge__()

__getattribute__()

__getnewargs__()

__getstate__()

__gt__()

__hash__()

__index__()

__int__()

__invert__()

__le__()

__lshift__()

__lt__()

__mod__()

__mul__()

__ne__()

__neg__()

__new__()

__or__()

__pos__()

__pow__()

__radd__()

__rand__()

__rdivmod__()

__reduce__()

__reduce_ex__()

__repr__()

__rfloordiv__()

__rlshift__()

__rmod__()

__rmul__()

__ror__()

__round__()

__rpow__()

__rrshift__()

__rshift__()

__rsub__()

__rtruediv__()

__rxor__()

__setattr__()

__sizeof__()

__str__()

__sub__()

__subclasshook__()

__truediv__()

__trunc__()

__xor__()

as_integer_ratio()

bit_count()

bit_length()

conjugate()

class denominator

class imag

is_integer()

class numerator

class real

to_bytes()

__deepcopy__(memo)

__copy__()

name()

value()

class simvx.core.descriptors.Notification

Bases: enum.IntEnum

Notifications dispatched to nodes during lifecycle and property changes.

Initialization

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

TRANSFORM_CHANGED

‘auto(…)’

VISIBILITY_CHANGED

‘auto(…)’

ENTER_TREE

‘auto(…)’

EXIT_TREE

‘auto(…)’

READY

‘auto(…)’

PARENTED

‘auto(…)’

UNPARENTED

‘auto(…)’

PROCESS

‘auto(…)’

PHYSICS_PROCESS

‘auto(…)’

__abs__()

__add__()

__and__()

__bool__()

__ceil__()

__delattr__()

__dir__()

__divmod__()

__eq__()

__float__()

__floor__()

__floordiv__()

__format__()

__ge__()

__getattribute__()

__getnewargs__()

__getstate__()

__gt__()

__hash__()

__index__()

__int__()

__invert__()

__le__()

__lshift__()

__lt__()

__mod__()

__mul__()

__ne__()

__neg__()

__new__()

__or__()

__pos__()

__pow__()

__radd__()

__rand__()

__rdivmod__()

__reduce__()

__reduce_ex__()

__repr__()

__rfloordiv__()

__rlshift__()

__rmod__()

__rmul__()

__ror__()

__round__()

__rpow__()

__rrshift__()

__rshift__()

__rsub__()

__rtruediv__()

__rxor__()

__setattr__()

__sizeof__()

__str__()

__sub__()

__subclasshook__()

__truediv__()

__trunc__()

__xor__()

as_integer_ratio()

bit_count()

bit_length()

conjugate()

class denominator

class imag

is_integer()

class numerator

class real

to_bytes()

__deepcopy__(memo)

__copy__()

name()

value()

class simvx.core.descriptors.Collision

Bases: typing.NamedTuple

Collision info returned by move_and_slide.

Attributes: normal: Collision normal pointing away from the other body. collider: The other CharacterBody that was hit. position: Contact point on collision surface. depth: Penetration depth.

normal: simvx.core.math.types.Vec2 | simvx.core.math.types.Vec3

None

collider: Any

None

position: simvx.core.math.types.Vec2 | simvx.core.math.types.Vec3

None

depth: float

None

class simvx.core.descriptors.Property(default: Any = _UNSET, *, default_factory: collections.abc.Callable[[], Any] | None = None, range=None, enum=None, hint='', link=False, propagate=False, group='', on_change: str | None = None, coalesce: bool = False, persist: bool = False, save_version: int | None = None, scalar: bool = False)

Descriptor for editor-visible, serializable node properties.

Declares a typed, validated property that the editor inspector can display and that the scene serializer persists automatically.

Args: default: Default value. Type is inferred from this (float, str, bool, Vec2, …). range: (lo, hi) clamp bounds for numeric values. enum: Allowed values list: the editor renders a dropdown. hint: Tooltip / description shown in the inspector. link: When True, the resolved value is the sum of this node’s stored value and the parent’s value (numeric / vector types), or the parent’s value for other types. Useful for cumulative offsets that propagate down the tree. propagate: When True, bool/enum Properties inherit disabling values from parents. persist: When True, the value is included in SaveManager snapshots. save_version: Optional integer schema version recorded alongside the persisted value.

Serialization: simvx.core.scene_io walks node.get_properties() and emits any value that differs from default into the .py scene file. Loading passes those stored values as kwargs to the node constructor, which feeds them through __set__ for validation.

Usage::

class Player(Node2D):
    speed = Property(5.0, range=(0, 20), hint="Movement speed")
    mode  = Property("walk", enum=["walk", "run", "fly"])

Initialization

Create an editor-visible property descriptor.

Args: default: Default value for the property. Mutually exclusive with default_factory. Mutable containers (list, dict, set, bytearray) are rejected here because a single shared instance would alias across every owning object: pass default_factory instead. default_factory: Zero-arg callable invoked the first time each instance reads the property. The result is cached on the instance, matching functools.cached_property and dataclasses.field(default_factory=...) semantics. range: Optional (min, max) tuple for numeric clamping. enum: Optional list of allowed values. hint: Description shown in the editor inspector. link: When True, child values are offset from the parent’s value. propagate: When True, bool/enum Settings inherit disabling values from parents. group: Inspector section name for grouping. Empty string = default “Properties” section. on_change: Name of a bound method to invoke on the owning instance after a successful value change (i.e. when the new value differs from the old). Hooks fired during __init__ are deferred until __init__ returns, then dispatched once each (deduplicated by (property, hook) pair) so the hook always sees a fully constructed object. After construction, hooks fire synchronously inside __set__ (unless coalesce=True: see below). coalesce: When True and on_change is set, post-init hook calls fire at most once per scene-tree frame. Multiple writes within one tick collapse to a single deferred call drained at the end of :meth:SceneTree.tick: useful for expensive handlers like HUD rasterisation that don’t care about intermediate values (Tower Defence: coins -= 1 repeated five times in one frame rasterised the HUD text five times). The owning object must be attached to a SceneTree (obj._tree set); for tree-less owners the flag is ignored and hooks fire synchronously. persist: When True, the value is included in SaveManager snapshots. save_version: Optional integer schema version recorded alongside the persisted value. scalar: When True, reject array-like values (numpy ndarray with ndim >= 1, Vec2/Vec3, list, tuple, dict, set) at assignment with a clear TypeError. Plain Python numbers, numpy scalar types (np.float32, np.int64 etc.), and 0-d numpy arrays are accepted. Use for properties that semantically represent a single number (e.g. Camera2D.zoom) so a stray Vec2 doesn’t leak into downstream math and produce visual glitches.

__slots__

(‘default’, ‘default_factory’, ‘range’, ‘enum’, ‘hint’, ‘name’, ‘attr’, ‘link’, ‘_propagate’, ‘group…

__set_name__(owner, name)

__get__(obj, objtype=None)

__set__(obj, value)

try_decrement(obj, amount: float | int) → bool

Atomically decrement the property if it would not go negative.

Returns True and assigns current - amount when the result is non-negative; returns False and leaves the value untouched otherwise. Resolves the “currency / mana / HP gate” pattern that every game-with-currency reinvents:

Before::

if player.coins >= cost:
    player.coins -= cost
    purchase()

After::

if Player.coins.try_decrement(player, cost):
    purchase()

Reads-via-__get__ so parent-link offsets are respected; writes the raw stored value (no parent contribution) via __set__ so any on_change hook and range/enum validation still fire. amount must be numeric and non-negative.

__repr__()

class simvx.core.descriptors.Child(node_type: type, *args, **kwargs)

Declarative child node. Auto-creates and adds during enter_tree.

Usage: class Player(Node3D): camera = Child(Camera3D, fov=90) health_bar = Child(Node2D, name=”HealthBar”)

Initialization

__set_name__(owner, name)

__get__(obj, objtype=None)

__set__(obj, value)

class simvx.core.descriptors.OnReady(path_or_callable)

Lazy child lookup, resolved after ready().

Usage: class Game(Node): player = OnReady(“Player”) # lookup by name camera = OnReady[“MainCamera”] # class_getitem syntax score = OnReady(lambda n: n.find(ScoreDisplay)) # callable

Initialization

classmethod __class_getitem__(key)

OnReady[“ChildName”] syntax.

__set_name__(owner, name)

__get__(obj, objtype=None)

class simvx.core.descriptors.Children

List-like container with named child access.

node.children[0] # by index node.children[‘Camera’] # by name string for c in node.children: # iteration len(node.children) # count

Initialization

__slots__

(‘_list’, ‘_names’, ‘_snapshot’, ‘_dirty’)

safe_iter() → list

Return a snapshot safe for iteration during mutation. Avoids per-frame copy when children are unchanged.

move_first(node) → None

Move node to index 0 (drawn first, hit-tested last). No-op if absent.

move_last(node) → None

Move node to the end (drawn last, hit-tested first). No-op if absent.

__getitem__(key)

__iter__()

__len__()

__contains__(item)

__bool__()

__repr__()