simvx.core.decorators

Lifecycle hook decorators for Node subclasses.

A node’s per-frame, lifecycle, and input behaviour is defined by methods named on_ready, on_process, on_physics_process, on_input, on_unhandled_input, on_enter_tree, on_exit_tree, on_draw, and on_picked. Subclasses override these directly to define one “primary” handler per hook.

The decorators in this module mark additional methods (with arbitrary names) as extra handlers for the same hooks, allowing concerns to be split across methods without forcing one monolithic override::

class Player(Node):
    def on_process(self, dt):           # primary override (always fires first)
        self.position += self.velocity * dt

    @on_process
    def update_animation(self, dt):     # additional handler (fires after override)
        self._frame += dt * self.fps

    @on_input(action="jump")            # filtered input handler
    def jump(self, event):
        self.velocity.y = -300
        return True                     # truthy return consumes the event

    @on_input(key=Key.S, ctrl=True)     # raw key with modifiers
    def save(self, event):
        self.tree.save_game()

The decorators are bare-or-called: @on_process and @on_process() are both valid. @on_input(...) requires the call form when filters are passed; bare @on_input is the all-events catch-all.

All hook collection happens once in :meth:Node.__init_subclass__: runtime dispatch is a tuple iteration, never a name lookup.

Module Contents

Functions

on_input	Mark a method as an input event handler with optional filters.
collect_hooks	Collect lifecycle and input handlers declared on cls and its bases.

Data

on_ready
on_process
on_physics_process
on_enter_tree
on_exit_tree
on_draw
on_picked
on_unhandled_input
__all__

API

simvx.core.decorators.on_ready

‘_make_simple(…)’

simvx.core.decorators.on_process

‘_make_simple(…)’

simvx.core.decorators.on_physics_process

‘_make_simple(…)’

simvx.core.decorators.on_enter_tree

‘_make_simple(…)’

simvx.core.decorators.on_exit_tree

‘_make_simple(…)’

simvx.core.decorators.on_draw

‘_make_simple(…)’

simvx.core.decorators.on_picked

‘_make_simple(…)’

simvx.core.decorators.on_unhandled_input

‘_make_simple(…)’

simvx.core.decorators.on_input(*args: Any, **kwargs: Any) → Any

Mark a method as an input event handler with optional filters.

Filters (mutually exclusive: pass at most one): action: action name (str). Fires when the input event matches the action’s bindings on the active InputMap. key: a :class:Key enum value, or a tuple of Keys (any-of match). button: a :class:MouseButton enum value (mouse button events). motion: True to receive mouse-motion events. scroll: True to receive scroll events. joy_button: a :class:JoyButton enum value (gamepad button events). joy_axis: a :class:JoyAxis enum value (gamepad axis events).

State filter: released: True matches release events; default False matches press events. Ignored for motion/scroll/joy_axis.

Modifier filters (key/button/joy_button only): ctrl, shift, alt, meta: True requires the modifier pressed, False (default) requires it not pressed, None ignores it. Tuple-of-keys is any-of; modifiers AND across the match.

Bare @on_input is the catch-all: fires for every input event, regardless of filter. Use sparingly; prefer specific filters so the SceneTree dispatch tables can route directly.

Truthy return value marks the event consumed: subsequent on_unhandled_input handlers do not fire for this event.

simvx.core.decorators.collect_hooks(cls: type, primary_methods: collections.abc.Iterable[str]) → tuple[dict[str, tuple[str, ...]], tuple[tuple[str, dict[str, Any]], ...]]

Collect lifecycle and input handlers declared on cls and its bases.

Walks the MRO most-derived-last (matching Property.__set_name__):

• Decorated methods (@on_process etc.) are gathered in declaration order across the MRO.

• Same-named primary overrides (def on_process(self, dt):) are treated as implicit primary handlers and pinned to index 0 of their bucket: users do not need to apply @on_process to their own on_process override for it to fire.

Returns (hooks, input_handlers): hooks: dict mapping hook name (e.g. "process") to an ordered tuple of method names. The primary override, if present, is always first. input_handlers: tuple of (method_name, filter_dict) pairs in declaration order across the MRO.

simvx.core.decorators.__all__

[‘on_ready’, ‘on_process’, ‘on_physics_process’, ‘on_input’, ‘on_unhandled_input’, ‘on_enter_tree’, …