simvx.core.descriptors

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

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().
Connection	Handle returned by Signal.connect(). Can disconnect and acts as a callable proxy.
Signal	Observable event dispatcher with optional type metadata.
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().

Initialization

__slots__

(‘_gen’, ‘_cancelled’)

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, persist: bool = False, save_version: int | None = None)

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 may fire during __init__ if the Property is passed as a kwarg, so they must be robust to partially-initialised state. Hooks must be O(1) and must not write to other Properties (no recursion guard is enforced). persist: When True, the value is included in SaveManager snapshots. save_version: Optional integer schema version recorded alongside the persisted value.

__slots__

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

__set_name__(owner, name)

__get__(obj, objtype=None)

__set__(obj, value)

__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.Connection(signal: simvx.core.descriptors.Signal, fn: collections.abc.Callable)

Handle returned by Signal.connect(). Can disconnect and acts as a callable proxy.

For bound methods on Nodes (objects exposing _outgoing_connections), the callback is held weakly and the connection auto-cleans when the node is destroyed — matching Godot 4’s signal lifecycle. Other callables (lambdas, free functions, methods on non-Node objects) keep a strong reference.

Initialization

__slots__

(‘_signal’, ‘_fn’, ‘_weak’, ‘_connected’)

disconnect()

Disconnect this callback from the signal.

property connected: bool

__call__(*args, **kwargs)

__bool__()

__repr__()

class simvx.core.descriptors.Signal(*types: type)

Observable event dispatcher with optional type metadata.

Used as a class attribute, Signal is a non-data descriptor: each instance accessing it lazily gets its own Signal copy stored in obj.__dict__. Class-level access (Cls.signal_name) returns the shared signal — useful for global event hubs like Node.script_error_raised.

Example::

class Player(Node):
    health_changed = Signal(int)          # typed: emits one int

p1, p2 = Player(), Player()
p1.health_changed.connect(on_p1)          # instance-scoped
p1.health_changed(50)                     # only p1 listeners fire

Initialization

__slots__

(‘_callbacks’, ‘_types’, ‘_name’)

classmethod __class_getitem__(params) → simvx.core.descriptors.Signal

Bracket syntax: Signal[int], Signal[int, str].

__set_name__(owner, name)

__get__(obj, objtype=None)

connect(fn: collections.abc.Callable, *, once: bool = False) → simvx.core.descriptors.Connection

Subscribe a callback. Returns a Connection handle.

Args: fn: Callback to invoke on emit. once: If True, auto-disconnect after first emit.

disconnect(fn_or_conn)

Remove a previously connected callback or Connection.

__call__(*args, **kwargs)

Emit the signal, calling all connected callbacks with the given arguments.

Connections whose weak target was garbage-collected are skipped and pruned from _callbacks after the dispatch loop.

clear()

Remove all connected callbacks.

emit

None

__repr__()

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.

__getitem__(key)

__iter__()

__len__()

__contains__(item)

__bool__()

__repr__()