mini_arcade_core.scenes.systems.builtins.movement¶

Reusable movement helpers for scene pipelines.

Attributes¶

`MoveAxis`
`ViewportPolicy`
`TCtx`

Classes¶

`AxisIntentBinding`	Bind one intent value to one entity velocity axis.
`IntentAxisVelocitySystem`	Convert intent values into entity velocity on one axis.
`MotionBinding`	Integrate a group of entities with shared motion options.
`KinematicMotionSystem`	Integrate kinematic entities, with optional drag, spin, and TTL ticking.
`ViewportConstraintBinding`	Apply one viewport policy to a group of entities.
`ViewportConstraintSystem`	Clamp, wrap, or cull entities against the current viewport.
`TurnThrustBinding`	Bind turn/thrust intent values to one entity.
`TurnThrustSystem`	Rotate an entity with turn input and apply forward thrust along
`SteerSeekBinding`	Bind one pursuer entity to a target position.
`SteerSeekGroupBinding`	Bind a group of pursuing entities to a shared target callback.
`SteerSeekSystem`	Steer entities toward a target position each frame.
`MovementProfile`	Reusable set of movement parameters loadable from a YAML mapping.

Functions¶

movement_profile_from_dict(→ MovementProfile)

Build a MovementProfile from a YAML-friendly dictionary.

Module Contents¶

mini_arcade_core.scenes.systems.builtins.movement.MoveAxis¶

mini_arcade_core.scenes.systems.builtins.movement.ViewportPolicy¶

mini_arcade_core.scenes.systems.builtins.movement.TCtx¶

class mini_arcade_core.scenes.systems.builtins.movement.AxisIntentBinding[source]¶

Bases: Generic[TCtx]

Bind one intent value to one entity velocity axis.

entity_getter: Callable[[TCtx], mini_arcade_core.engine.entities.BaseEntity | None]¶

value_getter: Callable[[TCtx], float]¶

axis: MoveAxis¶

speed_getter: Callable[[mini_arcade_core.engine.entities.BaseEntity], float]¶

zero_other_axis: bool = False¶

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]¶

class mini_arcade_core.scenes.systems.builtins.movement.IntentAxisVelocitySystem[source]¶

Bases: Generic[TCtx]

Convert intent values into entity velocity on one axis.

name: str = 'common_axis_velocity'¶

phase: int¶

order: int = 20¶

enabled_when: Callable[[TCtx], bool]¶

bindings: tuple[AxisIntentBinding[TCtx], Ellipsis] = ()¶

step(ctx: TCtx) → None[source]¶: Translate intent axes into kinematic velocity for bound entities.

class mini_arcade_core.scenes.systems.builtins.movement.MotionBinding[source]¶

Bases: Generic[TCtx]

Integrate a group of entities with shared motion options.

entities_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]¶

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]¶

dt_getter: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float]¶

drag: float | None = None¶

drag_getter: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float | None] | None = None¶

spin_attr: str | None = None¶

ttl_step: bool = False¶

class mini_arcade_core.scenes.systems.builtins.movement.KinematicMotionSystem[source]¶

Bases: Generic[TCtx]

Integrate kinematic entities, with optional drag, spin, and TTL ticking.

name: str = 'common_kinematic_motion'¶

phase: int¶

order: int = 30¶

enabled_when: Callable[[TCtx], bool]¶

bindings: tuple[MotionBinding[TCtx], Ellipsis] = ()¶

step(ctx: TCtx) → None[source]¶: Integrate velocity and acceleration for bound entities.

class mini_arcade_core.scenes.systems.builtins.movement.ViewportConstraintBinding[source]¶

Bases: Generic[TCtx]

Apply one viewport policy to a group of entities.

entities_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]¶

policy: ViewportPolicy¶

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]¶

axes: tuple[MoveAxis, Ellipsis] = ('x', 'y')¶

margin: float = 0.0¶

margin_getter: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float]¶

on_cull: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], None] | None = None¶

class mini_arcade_core.scenes.systems.builtins.movement.ViewportConstraintSystem[source]¶

Bases: Generic[TCtx]

Clamp, wrap, or cull entities against the current viewport.

name: str = 'common_viewport_constraints'¶

phase: int¶

order: int = 40¶

enabled_when: Callable[[TCtx], bool]¶

viewport_getter: Callable[[TCtx], tuple[float, float]]¶

bindings: tuple[ViewportConstraintBinding[TCtx], Ellipsis] = ()¶

step(ctx: TCtx) → None[source]¶: Apply clamp, wrap, or cull viewport policies to bound entities.

class mini_arcade_core.scenes.systems.builtins.movement.TurnThrustBinding[source]¶

Bases: Generic[TCtx]

Bind turn/thrust intent values to one entity.

turn_getter should return a signed float (negative=left, positive=right). thrust_getter should return a float (0 = no thrust, positive = forward).

entity_getter: Callable[[TCtx], mini_arcade_core.engine.entities.BaseEntity | None]¶

turn_getter: Callable[[TCtx], float]¶

thrust_getter: Callable[[TCtx], float]¶

turn_speed_deg: float = 240.0¶

thrust_accel: float = 280.0¶

max_speed: float = 330.0¶

forward_offset_deg: float = -90.0¶

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]¶

class mini_arcade_core.scenes.systems.builtins.movement.TurnThrustSystem[source]¶

Bases: Generic[TCtx]

Rotate an entity with turn input and apply forward thrust along its heading. Typical for Asteroids-style ship controls.

Phase: CONTROL (20), order 20.

name: str = 'common_turn_thrust'¶

phase: int¶

order: int = 20¶

enabled_when: Callable[[TCtx], bool]¶

bindings: tuple[TurnThrustBinding[TCtx], Ellipsis] = ()¶

step(ctx: TCtx) → None[source]¶: Apply turn and thrust for bound entities.

class mini_arcade_core.scenes.systems.builtins.movement.SteerSeekBinding[source]¶

Bases: Generic[TCtx]

Bind one pursuer entity to a target position.

target_getter returns the position the entity should steer towards, or None when no target is available (entity keeps current heading).

entity_getter: Callable[[TCtx], mini_arcade_core.engine.entities.BaseEntity | None]¶

target_getter: Callable[[TCtx], tuple[float, float] | None]¶

max_steer_deg: float = 180.0¶

thrust_accel: float = 200.0¶

max_speed: float = 300.0¶

forward_offset_deg: float = -90.0¶

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]¶

class mini_arcade_core.scenes.systems.builtins.movement.SteerSeekGroupBinding[source]¶

Bases: Generic[TCtx]

Bind a group of pursuing entities to a shared target callback.

entities_getter: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]]¶

target_getter: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], tuple[float, float] | None]¶

max_steer_deg: float = 180.0¶

thrust_accel: float = 200.0¶

max_speed: float = 300.0¶

forward_offset_deg: float = -90.0¶

predicate: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool]¶

class mini_arcade_core.scenes.systems.builtins.movement.SteerSeekSystem[source]¶

Bases: Generic[TCtx]

Steer entities toward a target position each frame.

The entity rotates toward the target (capped by max_steer_deg/s) and accelerates along its heading by thrust_accel.

Phase: CONTROL (20), order 22.

name: str = 'common_steer_seek'¶

phase: int¶

order: int = 22¶

enabled_when: Callable[[TCtx], bool]¶

bindings: tuple[SteerSeekBinding[TCtx], Ellipsis] = ()¶

group_bindings: tuple[SteerSeekGroupBinding[TCtx], Ellipsis] = ()¶

step(ctx: TCtx) → None[source]¶: Steer and thrust toward targets for bound entities.

class mini_arcade_core.scenes.systems.builtins.movement.MovementProfile[source]¶

Reusable set of movement parameters loadable from a YAML mapping.

A profile can feed TurnThrustBinding or SteerSeekBinding parameters so games define tuning in data files instead of Python code.

turn_speed_deg: float = 240.0¶

thrust_accel: float = 280.0¶

max_speed: float = 330.0¶

drag: float | None = None¶

forward_offset_deg: float = -90.0¶

max_steer_deg: float = 180.0¶

mini_arcade_core.scenes.systems.builtins.movement.movement_profile_from_dict(raw: Mapping[str, Any] | None) → MovementProfile[source]¶

Build a MovementProfile from a YAML-friendly dictionary.

Missing keys fall back to MovementProfile defaults. Unrecognised keys are silently ignored.

Example YAML:

movement:
  turn_speed_deg: 200
  thrust_accel: 320
  max_speed: 400
  drag: 0.98