simvx.core.coroutines

Coroutine helpers: parallel, wait, wait_until, wait_signal, next_frame.

Coroutines are driven by the scene tree with gen.send(dt) after the first prime, so helpers that track time can read the per-tick delta via dt = yield and accumulate it. Helpers below follow that convention, which means they correctly respect SceneTree.paused and time scale.

Module Contents

Functions

parallel	Run multiple coroutines simultaneously, finish when all complete.
wait	Pause a coroutine for seconds of scene-tree time.
wait_until	Yield until condition() returns True.
wait_signal	Yield until signal is emitted. Returns signal args.
next_frame	Yield for exactly one frame.
punch_position	Damped-sine impulse on node.position: arcade hit / screen-shake.
punch_rotation	Damped-sine impulse on node.rotation (radians).

API

simvx.core.coroutines.parallel(*coroutines: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.Coroutine

Run multiple coroutines simultaneously, finish when all complete.

Forwards the per-tick dt received via yield to each child coroutine, priming each on its first advance.

simvx.core.coroutines.wait(seconds: float) → simvx.core.descriptors.Coroutine

Pause a coroutine for seconds of scene-tree time.

simvx.core.coroutines.wait_until(condition: collections.abc.Callable[[], bool]) → simvx.core.descriptors.Coroutine

Yield until condition() returns True.

simvx.core.coroutines.wait_signal(signal: simvx.core.signals.Signal) → simvx.core.descriptors.Coroutine

Yield until signal is emitted. Returns signal args.

simvx.core.coroutines.next_frame() → simvx.core.descriptors.Coroutine

Yield for exactly one frame.

simvx.core.coroutines.punch_position(node, amplitude, duration: float, *, frequency: float = 12.0, decay: float = 6.0, attr: str = 'position') → simvx.core.descriptors.Coroutine

Damped-sine impulse on node.position: arcade hit / screen-shake.

Maps to the classic A * sin(2pi * f * t) * exp(-d * t) formula used by Balatro, Claustrowordia and Casual Crusade for card slams and tile hits. The node’s position is offset around its current value each tick and restored exactly to the starting value on completion.

Args: node: Node to shake. The named attribute must support both reads and tuple/Vec2 writes; position is the common case. amplitude: Peak displacement. Pass a scalar for a uniform shake (Vec2(amp, amp)), or a Vec2 / 2-tuple to bias the axis (e.g. (0, 8) for vertical-only). duration: Total duration in seconds. After this many seconds the position is snapped back to the starting value. frequency: Oscillations per second (default 12 Hz – arcade-feel). decay: Exponential decay rate per second (default 6.0). attr: Position attribute name on node (default "position").

Yields: Per-tick dt from the coroutine driver.

simvx.core.coroutines.punch_rotation(node, amplitude: float, duration: float, *, frequency: float = 12.0, decay: float = 6.0, attr: str = 'rotation') → simvx.core.descriptors.Coroutine

Damped-sine impulse on node.rotation (radians).

Twin of :func:punch_position for angular hits – the camera shake rotation, the card-flip wobble, the tile-press lean. Pass amplitude in radians.

Args: node: Node to shake. The attribute must support float read/write. amplitude: Peak angular displacement in radians. duration: Total duration in seconds. frequency: Oscillations per second (default 12 Hz). decay: Exponential decay rate per second (default 6.0). attr: Rotation attribute name on node (default "rotation").

Yields: Per-tick dt from the coroutine driver.