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. Connect callbacks and emit to notify.

Children

List-like container with named attribute access.

Data

log

Coroutine

Setting

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.

Initialization

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

INHERIT

0

PAUSABLE

1

WHEN_PAUSED

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, *, range=None, enum=None, hint='', link=False, propagate=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.

Serialization: save_scene calls node.get_properties() and stores any value that differs from default. load_scene passes 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. 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.

__slots__

(‘default’, ‘range’, ‘enum’, ‘hint’, ‘name’, ‘attr’, ‘link’, ‘_propagate’)

__set_name__(owner, name)
__get__(obj, objtype=None)
__set__(obj, value)
__repr__()
simvx.core.descriptors.Setting

None

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.

Initialization

__slots__

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

disconnect()

Disconnect this callback from the signal.

property connected: bool
__call__(*args, **kwargs)
__bool__()
__repr__()
class simvx.core.descriptors.Signal

Observable event dispatcher. Connect callbacks and emit to notify.

Example::

health_changed = Signal()
conn = health_changed.connect(lambda hp: print(f"HP: {hp}"))
health_changed(50)  # prints "HP: 50"
conn.disconnect()

Initialization

__slots__

(‘_callbacks’,)

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.

clear()

Remove all connected callbacks.

emit

None

__repr__()
class simvx.core.descriptors.Children

List-like container with named attribute access.

node.children[0] # by index node.children[‘Camera’] # by name string node.children.Camera # by name attribute 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.

__getattr__(name: str)
__getitem__(key)
__iter__()
__len__()
__contains__(item)
__bool__()
__repr__()