mini_arcade_core.scenes.systems.builtins.movement ================================================= .. py:module:: mini_arcade_core.scenes.systems.builtins.movement .. autoapi-nested-parse:: Reusable movement helpers for scene pipelines. Attributes ---------- .. autoapisummary:: mini_arcade_core.scenes.systems.builtins.movement.MoveAxis mini_arcade_core.scenes.systems.builtins.movement.ViewportPolicy mini_arcade_core.scenes.systems.builtins.movement.TCtx Classes ------- .. autoapisummary:: mini_arcade_core.scenes.systems.builtins.movement.AxisIntentBinding mini_arcade_core.scenes.systems.builtins.movement.IntentAxisVelocitySystem mini_arcade_core.scenes.systems.builtins.movement.MotionBinding mini_arcade_core.scenes.systems.builtins.movement.KinematicMotionSystem mini_arcade_core.scenes.systems.builtins.movement.ViewportConstraintBinding mini_arcade_core.scenes.systems.builtins.movement.ViewportConstraintSystem mini_arcade_core.scenes.systems.builtins.movement.TurnThrustBinding mini_arcade_core.scenes.systems.builtins.movement.TurnThrustSystem mini_arcade_core.scenes.systems.builtins.movement.SteerSeekBinding mini_arcade_core.scenes.systems.builtins.movement.SteerSeekGroupBinding mini_arcade_core.scenes.systems.builtins.movement.SteerSeekSystem mini_arcade_core.scenes.systems.builtins.movement.MovementProfile Functions --------- .. autoapisummary:: mini_arcade_core.scenes.systems.builtins.movement.movement_profile_from_dict Module Contents --------------- .. py:data:: MoveAxis .. py:data:: ViewportPolicy .. py:data:: TCtx .. py:class:: AxisIntentBinding Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Bind one intent value to one entity velocity axis. .. py:attribute:: entity_getter :type: Callable[[TCtx], mini_arcade_core.engine.entities.BaseEntity | None] .. py:attribute:: value_getter :type: Callable[[TCtx], float] .. py:attribute:: axis :type: MoveAxis .. py:attribute:: speed_getter :type: Callable[[mini_arcade_core.engine.entities.BaseEntity], float] .. py:attribute:: zero_other_axis :type: bool :value: False .. py:attribute:: predicate :type: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool] .. py:class:: IntentAxisVelocitySystem Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Convert intent values into entity velocity on one axis. .. py:attribute:: name :type: str :value: 'common_axis_velocity' .. py:attribute:: phase :type: int .. py:attribute:: order :type: int :value: 20 .. py:attribute:: enabled_when :type: Callable[[TCtx], bool] .. py:attribute:: bindings :type: tuple[AxisIntentBinding[TCtx], Ellipsis] :value: () .. py:method:: step(ctx: TCtx) -> None Translate intent axes into kinematic velocity for bound entities. .. py:class:: MotionBinding Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Integrate a group of entities with shared motion options. .. py:attribute:: entities_getter :type: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]] .. py:attribute:: predicate :type: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool] .. py:attribute:: dt_getter :type: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float] .. py:attribute:: drag :type: float | None :value: None .. py:attribute:: drag_getter :type: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float | None] | None :value: None .. py:attribute:: spin_attr :type: str | None :value: None .. py:attribute:: ttl_step :type: bool :value: False .. py:class:: KinematicMotionSystem Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Integrate kinematic entities, with optional drag, spin, and TTL ticking. .. py:attribute:: name :type: str :value: 'common_kinematic_motion' .. py:attribute:: phase :type: int .. py:attribute:: order :type: int :value: 30 .. py:attribute:: enabled_when :type: Callable[[TCtx], bool] .. py:attribute:: bindings :type: tuple[MotionBinding[TCtx], Ellipsis] :value: () .. py:method:: step(ctx: TCtx) -> None Integrate velocity and acceleration for bound entities. .. py:class:: ViewportConstraintBinding Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Apply one viewport policy to a group of entities. .. py:attribute:: entities_getter :type: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]] .. py:attribute:: policy :type: ViewportPolicy .. py:attribute:: predicate :type: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool] .. py:attribute:: axes :type: tuple[MoveAxis, Ellipsis] :value: ('x', 'y') .. py:attribute:: margin :type: float :value: 0.0 .. py:attribute:: margin_getter :type: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], float] .. py:attribute:: on_cull :type: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], None] | None :value: None .. py:class:: ViewportConstraintSystem Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Clamp, wrap, or cull entities against the current viewport. .. py:attribute:: name :type: str :value: 'common_viewport_constraints' .. py:attribute:: phase :type: int .. py:attribute:: order :type: int :value: 40 .. py:attribute:: enabled_when :type: Callable[[TCtx], bool] .. py:attribute:: viewport_getter :type: Callable[[TCtx], tuple[float, float]] .. py:attribute:: bindings :type: tuple[ViewportConstraintBinding[TCtx], Ellipsis] :value: () .. py:method:: step(ctx: TCtx) -> None Apply clamp, wrap, or cull viewport policies to bound entities. .. py:class:: TurnThrustBinding Bases: :py:obj:`Generic`\ [\ :py:obj:`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). .. py:attribute:: entity_getter :type: Callable[[TCtx], mini_arcade_core.engine.entities.BaseEntity | None] .. py:attribute:: turn_getter :type: Callable[[TCtx], float] .. py:attribute:: thrust_getter :type: Callable[[TCtx], float] .. py:attribute:: turn_speed_deg :type: float :value: 240.0 .. py:attribute:: thrust_accel :type: float :value: 280.0 .. py:attribute:: max_speed :type: float :value: 330.0 .. py:attribute:: forward_offset_deg :type: float :value: -90.0 .. py:attribute:: predicate :type: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool] .. py:class:: TurnThrustSystem Bases: :py:obj:`Generic`\ [\ :py:obj:`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. .. py:attribute:: name :type: str :value: 'common_turn_thrust' .. py:attribute:: phase :type: int .. py:attribute:: order :type: int :value: 20 .. py:attribute:: enabled_when :type: Callable[[TCtx], bool] .. py:attribute:: bindings :type: tuple[TurnThrustBinding[TCtx], Ellipsis] :value: () .. py:method:: step(ctx: TCtx) -> None Apply turn and thrust for bound entities. .. py:class:: SteerSeekBinding Bases: :py:obj:`Generic`\ [\ :py:obj:`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). .. py:attribute:: entity_getter :type: Callable[[TCtx], mini_arcade_core.engine.entities.BaseEntity | None] .. py:attribute:: target_getter :type: Callable[[TCtx], tuple[float, float] | None] .. py:attribute:: max_steer_deg :type: float :value: 180.0 .. py:attribute:: thrust_accel :type: float :value: 200.0 .. py:attribute:: max_speed :type: float :value: 300.0 .. py:attribute:: forward_offset_deg :type: float :value: -90.0 .. py:attribute:: predicate :type: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool] .. py:class:: SteerSeekGroupBinding Bases: :py:obj:`Generic`\ [\ :py:obj:`TCtx`\ ] Bind a group of pursuing entities to a shared target callback. .. py:attribute:: entities_getter :type: Callable[[TCtx], Iterable[mini_arcade_core.engine.entities.BaseEntity]] .. py:attribute:: target_getter :type: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], tuple[float, float] | None] .. py:attribute:: max_steer_deg :type: float :value: 180.0 .. py:attribute:: thrust_accel :type: float :value: 200.0 .. py:attribute:: max_speed :type: float :value: 300.0 .. py:attribute:: forward_offset_deg :type: float :value: -90.0 .. py:attribute:: predicate :type: Callable[[TCtx, mini_arcade_core.engine.entities.BaseEntity], bool] .. py:class:: SteerSeekSystem Bases: :py:obj:`Generic`\ [\ :py:obj:`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. .. py:attribute:: name :type: str :value: 'common_steer_seek' .. py:attribute:: phase :type: int .. py:attribute:: order :type: int :value: 22 .. py:attribute:: enabled_when :type: Callable[[TCtx], bool] .. py:attribute:: bindings :type: tuple[SteerSeekBinding[TCtx], Ellipsis] :value: () .. py:attribute:: group_bindings :type: tuple[SteerSeekGroupBinding[TCtx], Ellipsis] :value: () .. py:method:: step(ctx: TCtx) -> None Steer and thrust toward targets for bound entities. .. py:class:: MovementProfile 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. .. py:attribute:: turn_speed_deg :type: float :value: 240.0 .. py:attribute:: thrust_accel :type: float :value: 280.0 .. py:attribute:: max_speed :type: float :value: 330.0 .. py:attribute:: drag :type: float | None :value: None .. py:attribute:: forward_offset_deg :type: float :value: -90.0 .. py:attribute:: max_steer_deg :type: float :value: 180.0 .. py:function:: movement_profile_from_dict(raw: Mapping[str, Any] | None) -> MovementProfile Build a :class:`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