mini_arcade_core.scenes.systems.builtins ======================================== .. py:module:: mini_arcade_core.scenes.systems.builtins .. autoapi-nested-parse:: Built-in systems for scenes. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/mini_arcade_core/scenes/systems/builtins/actions/index /autoapi/mini_arcade_core/scenes/systems/builtins/animation/index /autoapi/mini_arcade_core/scenes/systems/builtins/capture_hotkeys/index Attributes ---------- .. autoapisummary:: mini_arcade_core.scenes.systems.builtins.Layer mini_arcade_core.scenes.systems.builtins.TTickContext Classes ------- .. autoapisummary:: mini_arcade_core.scenes.systems.builtins.BaseEntity mini_arcade_core.scenes.systems.builtins.RenderPacket mini_arcade_core.scenes.systems.builtins.BaseIntent mini_arcade_core.scenes.systems.builtins.BaseTickContext mini_arcade_core.scenes.systems.builtins.BaseWorld mini_arcade_core.scenes.systems.builtins.DrawCall mini_arcade_core.scenes.systems.builtins.RenderQueue mini_arcade_core.scenes.systems.builtins.SubmitRenderQueue mini_arcade_core.scenes.systems.builtins.BaseSystem mini_arcade_core.scenes.systems.builtins.Vec2 mini_arcade_core.scenes.systems.builtins.ActionIntentSystem mini_arcade_core.scenes.systems.builtins.ActionMap mini_arcade_core.scenes.systems.builtins.ActionSnapshot mini_arcade_core.scenes.systems.builtins.AxisActionBinding mini_arcade_core.scenes.systems.builtins.DigitalActionBinding mini_arcade_core.scenes.systems.builtins.CaptureHotkeysConfig mini_arcade_core.scenes.systems.builtins.CaptureHotkeysSystem mini_arcade_core.scenes.systems.builtins.RenderSystemContext mini_arcade_core.scenes.systems.builtins.InputIntentSystem mini_arcade_core.scenes.systems.builtins.BaseRenderSystem mini_arcade_core.scenes.systems.builtins.BaseQueuedRenderSystem Package Contents ---------------- .. py:class:: BaseEntity Base entity class. :ivar id: The unique ID of the entity. :ivar name: The optional name of the entity. :ivar transform: The transform of the entity. :ivar shape: The shape of the entity. :ivar style: The render style of the entity. :ivar kinematic: The kinematic body of the entity. :ivar collider: The collider specification of the entity. :ivar sprite: The sprite component of the entity. :ivar anim: The animation component of the entity. :ivar life: The life component of the entity. .. py:attribute:: id :type: int .. py:attribute:: name :type: str .. py:attribute:: codename :type: str .. py:attribute:: transform :type: mini_arcade_core.spaces.geometry.transform.Transform2D .. py:attribute:: shape :type: mini_arcade_core.spaces.geometry.shapes.Shape2D .. py:attribute:: z_index :type: int :value: 0 .. py:attribute:: rotation_deg :type: float :value: 0.0 .. py:attribute:: style :type: mini_arcade_core.engine.render.style.RenderStyle | None :value: None .. py:attribute:: kinematic :type: mini_arcade_core.spaces.physics.kinematics2d.Kinematic2D | None :value: None .. py:attribute:: collider :type: mini_arcade_core.spaces.collision.specs.ColliderSpec | None :value: None .. py:attribute:: sprite :type: mini_arcade_core.engine.components.Sprite2D | None :value: None .. py:attribute:: anim :type: mini_arcade_core.engine.components.Anim2D | None :value: None .. py:attribute:: life :type: mini_arcade_core.engine.components.Life | None :value: None .. py:method:: from_dict(data: dict) -> BaseEntity :classmethod: Create an entity from a dictionary. :param data: The dictionary containing the entity data. :type data: dict :return: The created entity. :rtype: BaseEntity .. py:class:: RenderPacket Minimal render packet for v1. It is intentionally backend-agnostic: each op is a callable that knows how to draw itself using the Backend instance. Later you can replace DrawOp with typed primitives + passes. .. py:attribute:: ops :type: tuple[DrawOp, Ellipsis] :value: () .. py:attribute:: meta :type: dict[str, object] .. py:method:: from_ops(ops: Iterable[DrawOp], **meta: object) -> RenderPacket :staticmethod: Create a RenderPacket from an iterable of DrawOps and optional meta. :param ops: Iterable of DrawOp callables. :type ops: Iterable[DrawOp] :return: RenderPacket instance. :rtype: RenderPacket .. py:class:: BaseIntent Base type for scene intent. Intent is a per-frame snapshot produced by the input layer and consumed by simulation systems. It should: - be independent from raw device events (keyboard/gamepad/mouse) - use normalized values (e.g. axis -1..+1, booleans for actions) - represent desired actions for *this tick only* (not persistent state) Scenes define their own intent dataclass inheriting from this base. .. py:class:: BaseTickContext Bases: :py:obj:`Generic`\ [\ :py:obj:`TWorld`\ , :py:obj:`TIntent`\ ] Per-tick execution context passed through a SimScene pipeline. This is the "shared envelope" for one simulation tick: input snapshot + timing, the mutable world state, an outbox for commands, and the per-tick intent and render output produced by systems. :ivar input_frame: Snapshot of raw/normalized input for this tick. :ivar dt: Delta time (seconds) since previous tick. :ivar world: Scene-owned world state (usually mutated during the tick). :ivar commands: Queue of commands/events emitted by systems. :ivar intent: Optional intent snapshot for this tick (produced by input system). :ivar packet: Optional render packet produced for this tick. :ivar draw_ops: Optional immediate draw operations (debug/overlay/utility). .. py:attribute:: input_frame :type: mini_arcade_core.runtime.input_frame.InputFrame .. py:attribute:: dt :type: float .. py:attribute:: world :type: TWorld .. py:attribute:: commands :type: mini_arcade_core.engine.commands.CommandQueue .. py:attribute:: intent :type: TIntent | None :value: None .. py:attribute:: packet :type: mini_arcade_core.engine.render.packet.RenderPacket | None :value: None .. py:attribute:: draw_ops :type: list[mini_arcade_core.engine.render.packet.DrawOp] | None :value: None .. py:attribute:: render_queue :type: RenderQueue .. py:class:: BaseWorld Base type for scene world state. The world is the single object that represents *everything the scene owns*: - gameplay state (entities, score, cooldowns, flags) - simulation variables (timers, direction, RNG state if needed) - cached runtime resources (texture ids, sound ids, animations) - debug/UI overlay state Define one world dataclass per scene by inheriting from this class. The engine will create it during scene init and provide it to systems each tick. .. py:attribute:: entities :type: list[mini_arcade_core.engine.entities.BaseEntity] .. py:method:: get_entity_by_id(entity_id: int) -> mini_arcade_core.engine.entities.BaseEntity | None Get an entity by its ID. :param entity_id: The ID of the entity to retrieve. :type entity_id: int :return: The entity with the specified ID, or None if not found. :rtype: BaseEntity | None .. py:method:: get_entities_by_id_range(start_id: int, end_id: int) -> list[mini_arcade_core.engine.entities.BaseEntity] Get entities with IDs in the specified range [start_id, end_id]. :param start_id: The starting ID of the range (inclusive). :type start_id: int :param end_id: The ending ID of the range (inclusive). :type end_id: int :return: A list of entities with IDs in the specified range. :rtype: list[BaseEntity] .. py:class:: DrawCall A draw call for rendering. .. py:attribute:: drawable :type: Drawable[TContext] .. py:attribute:: ctx :type: TContext .. py:method:: __call__(backend: mini_arcade_core.backend.backend.Backend) -> None .. py:data:: Layer .. py:class:: RenderQueue A queue of draw operations to be rendered this tick. Scenes/systems can push draw operations to this queue during the tick, and the engine will sort and render them after the tick. This is a more flexible alternative to building a full RenderPacket for simple scenes that just want to emit draw calls. .. py:method:: clear() -> None Clear all draw operations from the queue. .. py:method:: rect(*, center, size, color, radius=0.0, layer: Layer = 'world', z: int = 0) -> None Push a rectangle draw operation. :param center: Center position of the rectangle. :type center: Vec2 :param size: Size of the rectangle (width, height). :type size: Vec2 :param color: Color of the rectangle. :type color: Color :param radius: Optional corner radius for rounded rectangles (default 0). :type radius: float :param layer: The layer to draw on (default "world"). :type layer: Layer :param z: The z-index for sorting within the layer (default 0). :type z: int .. py:method:: line(*, a, b, color, thickness=1.0, dash_length: float | None = None, dash_gap: float | None = None, layer: Layer = 'world', z: int = 0) -> None Push a line draw operation, with optional dashed line parameters. :param a: Starting point of the line. :type a: Vec2 :param b: Ending point of the line. :type b: Vec2 :param color: Color of the line. :type color: Color :param thickness: Thickness of the line (default 1.0). :type thickness: float :param dash_length: Length of dashes for dashed line (None for solid line). :type dash_length: float | None :param dash_gap: Length of gaps for dashed line (None for solid line). :type dash_gap: float | None :param layer: The layer to draw on (default "world"). :type layer: Layer :param z: The z-index for sorting within the layer (default 0). :type z: int .. py:method:: circle(*, center, radius, color, layer: Layer = 'world', z: int = 0) -> None Push a circle draw operation. :param center: Center position of the circle. :type center: Vec2 :param radius: Radius of the circle. :type radius: float :param color: Color of the circle. :type color: Color :param layer: The layer to draw on (default "world"). :type layer: Layer :param z: The z-index for sorting within the layer (default 0). :type z: int .. py:method:: poly(*, points: list[mini_arcade_core.spaces.math.vec2.Vec2], fill: mini_arcade_core.backend.types.Color | None, stroke: mini_arcade_core.backend.types.Color | None, thickness: int = 1, closed: bool = True, layer: Layer = 'world', z: int = 0) -> None Push a polygon draw operation. :param points: List of points defining the polygon vertices. :type points: list[Vec2] :param fill: Fill color for the polygon (None for no fill). :type fill: Color | None :param stroke: Stroke color for the polygon edges (None for no stroke). :type stroke: Color | None :param thickness: Thickness of the stroke (default 1). :type thickness: int :param closed: Whether the polygon should be closed (default True). :type closed: bool :param layer: The layer to draw on (default "world"). :type layer: Layer :param z: The z-index for sorting within the layer (default 0). :type z: int .. py:method:: texture(*, tex_id: int, x: float, y: float, w: float, h: float, angle_deg: float = 0.0, layer: Layer = 'world', z: int = 0) -> None Push a texture draw operation. :param tex_id: The texture ID to draw. :type tex_id: int :param x: X position to draw the texture. :type x: float :param y: Y position to draw the texture. :type y: float :param w: Width to draw the texture. :type w: float :param h: Height to draw the texture. :type h: float :param angle_deg: Rotation angle in degrees (default 0). :type angle_deg: float :param layer: The layer to draw on (default "world"). :type layer: Layer :param z: The z-index for sorting within the layer (default 0). :type z: int .. py:method:: text(*, x: float, y: float, text: str, color: mini_arcade_core.backend.types.Color = (255, 255, 255, 255), font_size: int | None = None, align: Literal['left', 'center', 'right'] = 'left', layer: Layer = 'ui', z: int = 0) -> None Push a text draw operation. :param x: X position of the text. :type x: float :param y: Y position of the text. :type y: float :param text: The text string to draw. :type text: str :param color: The color of the text (default white). :type color: Color :param font_size: Optional font size (default None for backend default). :type font_size: int | None :param align: Text alignment: "left", "center", or "right" (default "left"). :type align: Literal["left", "center", "right"] :param layer: The layer to draw on (default "ui"). :type layer: Layer :param z: The z-index for sorting within the layer (default 0). :type z: int .. py:method:: custom(*, op: Callable[[mini_arcade_core.backend.backend.Backend], None], layer: Layer = 'debug', z: int = 0) -> None Push a custom draw operation defined by a callable that takes the backend. :param op: A callable that takes a Backend and performs custom drawing. :type op: Callable[[Backend], None] :param layer: The layer to draw on (default "debug"). :type layer: Layer :param z: The z-index for sorting within the layer (default 0). :type z: int .. py:method:: iter_sorted(layers: tuple[Layer, Ellipsis] | list[Layer] | None = None) -> list[DrawOperation] Get draw operations sorted by layer/z/seq, optionally filtered by layers. :param layers: Optional tuple or list of layers to include (default all). :type layers: tuple[Layer, ...] | list[Layer] | None :return: Sorted list of draw operations for the specified layers. :rtype: list[DrawOperation] .. py:class:: SubmitRenderQueue Bases: :py:obj:`Drawable`\ [\ :py:obj:`BaseTickContext`\ ] Drawable that submits a RenderQueue from the tick context. This is a utility for simple scenes that want to build a RenderQueue directly in their tick context and have it rendered without needing a full RenderPacket. :ivar layers: (tuple[Layer, ...] | None): Optional tuple of layers to render from the RenderQueue (default all). .. py:attribute:: layers :type: tuple[Layer, Ellipsis] | None :value: None .. py:method:: draw(backend: mini_arcade_core.backend.backend.Backend, ctx: BaseTickContext) Draw to the scene. .. py:class:: BaseSystem Bases: :py:obj:`Protocol`, :py:obj:`Generic`\ [\ :py:obj:`TSystemContext`\ ] Protocol for a system that operates within a given context. .. py:attribute:: name :type: str .. py:attribute:: phase :type: int :value: 0 .. py:attribute:: order :type: int :value: 0 .. py:method:: enabled(ctx: TSystemContext) -> bool Determine if the system is enabled in the given context. :param ctx: The system context. :type ctx: TSystemContext :return: True if the system is enabled, False otherwise. :rtype: bool .. py:method:: step(ctx: TSystemContext) Perform a single step of the system within the given context. :param ctx: The system context. :type ctx: TSystemContext .. py:class:: Vec2 Simple 2D vector. :ivar x (float): X coordinate. :ivar y (float): Y coordinate. .. py:attribute:: x :type: float .. py:attribute:: y :type: float .. py:method:: to_tuple() -> tuple[float, float] Convert Vex2 to a tuple. :return: Tuple of (x, y). :rtype: tuple[float, float] .. py:method:: __add__(other: Vec2) -> Vec2 .. py:method:: __mul__(scalar: float) -> Vec2 .. py:method:: __iadd__(other: Vec2) -> Vec2 .. py:method:: __imul__(scalar: float) -> Vec2 .. py:class:: ActionIntentSystem Bases: :py:obj:`mini_arcade_core.scenes.systems.base_system.BaseSystem`\ [\ :py:obj:`TContext`\ ], :py:obj:`Generic`\ [\ :py:obj:`TContext`\ , :py:obj:`TIntent`\ ] Input system that converts an ActionMap snapshot into scene intent. .. py:attribute:: action_map :type: ActionMap .. py:attribute:: intent_factory :type: Callable[[ActionSnapshot, TContext], TIntent] .. py:attribute:: name :type: str :value: 'action_intent' .. py:attribute:: order :type: int :value: 10 .. py:method:: step(ctx: TContext) -> None Perform a single step of the system within the given context. :param ctx: The system context. :type ctx: TSystemContext .. py:class:: ActionMap Mapping of action IDs to concrete binding strategies. .. py:attribute:: bindings :type: Mapping[str, ActionBinding] .. py:method:: read(frame: mini_arcade_core.runtime.input_frame.InputFrame) -> ActionSnapshot Read the current state of all actions from the input frame. :param frame: The input frame containing raw input states. :type frame: InputFrame :return: An ActionSnapshot containing the state of all actions. :rtype: ActionSnapshot .. py:class:: ActionSnapshot Per-frame snapshot for all mapped actions. .. py:method:: state(action: str) -> ActionState Get the ActionState for the given action, or a default if not found. :param action: The name of the action to get the state for. :type action: str :return: The ActionState for the given action, or a default if not found. :rtype: ActionState .. py:method:: value(action: str, default: float = 0.0) -> float Get the normalized value of the action, or a default if not found. :param action: The name of the action to get the value for. :type action: str :param default: The default value to return if the action is not found (default 0.0). :type default: float :return: The normalized value of the action, or the default if not found. :rtype: float .. py:method:: down(action: str) -> bool Check if the action is currently held down. :param action: The name of the action to check. :type action: str :return: True if the action is currently held down, False otherwise. :rtype: bool .. py:method:: pressed(action: str) -> bool Check if the action was pressed this frame. :param action: The name of the action to check. :type action: str :return: True if the action was pressed this frame, False otherwise. :rtype: bool .. py:method:: released(action: str) -> bool Check if the action was released this frame. :param action: The name of the action to check. :type action: str :return: True if the action was released this frame, False otherwise. :rtype: bool .. py:class:: AxisActionBinding Bases: :py:obj:`ActionBinding` Axis action sourced from analog axes and optional digital fallbacks. .. py:attribute:: axes :type: tuple[str, Ellipsis] :value: () .. py:attribute:: positive_keys :type: tuple[mini_arcade_core.backend.keys.Key, Ellipsis] :value: () .. py:attribute:: negative_keys :type: tuple[mini_arcade_core.backend.keys.Key, Ellipsis] :value: () .. py:attribute:: positive_buttons :type: tuple[str, Ellipsis] :value: () .. py:attribute:: negative_buttons :type: tuple[str, Ellipsis] :value: () .. py:attribute:: deadzone :type: float :value: 0.15 .. py:attribute:: scale :type: float :value: 1.0 .. py:method:: read(frame: mini_arcade_core.runtime.input_frame.InputFrame) -> ActionState Read the current state of this action from the input frame. :param frame: The input frame containing raw input states. :type frame: InputFrame :return: The current ActionState for this binding. :rtype: ActionState .. py:class:: DigitalActionBinding Bases: :py:obj:`ActionBinding` Digital action sourced from keyboard and/or named buttons. .. py:attribute:: keys :type: tuple[mini_arcade_core.backend.keys.Key, Ellipsis] :value: () .. py:attribute:: buttons :type: tuple[str, Ellipsis] :value: () .. py:method:: read(frame: mini_arcade_core.runtime.input_frame.InputFrame) -> ActionState Read the current state of this action from the input frame. :param frame: The input frame containing raw input states. :type frame: InputFrame :return: The current ActionState for this binding. :rtype: ActionState .. py:class:: CaptureHotkeysConfig Per-scene capture workflow configuration. .. py:attribute:: screenshot_label :type: str | None :value: None .. py:attribute:: replay_file :type: str | None :value: None .. py:attribute:: replay_game_id :type: str :value: 'mini-arcade' .. py:attribute:: replay_initial_scene :type: str :value: 'unknown' .. py:attribute:: replay_fps :type: int :value: 60 .. py:attribute:: action_toggle_video :type: str :value: 'capture_toggle_video' .. py:attribute:: action_toggle_replay_record :type: str :value: 'capture_toggle_replay_record' .. py:attribute:: action_toggle_replay_play :type: str :value: 'capture_toggle_replay_play' .. py:attribute:: action_screenshot :type: str :value: 'capture_screenshot' .. py:class:: CaptureHotkeysSystem Bases: :py:obj:`mini_arcade_core.scenes.systems.base_system.BaseSystem`\ [\ :py:obj:`CaptureContext`\ ] Handles screenshot/replay/video commands in a reusable way. .. py:attribute:: services :type: mini_arcade_core.runtime.services.RuntimeServices .. py:attribute:: action_map :type: mini_arcade_core.scenes.systems.builtins.actions.ActionMap .. py:attribute:: cfg :type: CaptureHotkeysConfig .. py:attribute:: name :type: str :value: 'capture_hotkeys' .. py:attribute:: order :type: int :value: 13 .. py:method:: step(ctx: CaptureContext) -> None Perform a single step of the system within the given context. :param ctx: The system context. :type ctx: TSystemContext .. py:class:: RenderSystemContext Bases: :py:obj:`Protocol` Structural context contract for render systems. Any scene tick context that provides these attributes will be accepted. .. py:attribute:: world :type: mini_arcade_core.scenes.sim_scene.BaseWorld .. py:attribute:: draw_ops :type: list[mini_arcade_core.scenes.sim_scene.DrawCall] | None .. py:attribute:: render_queue :type: mini_arcade_core.scenes.sim_scene.RenderQueue .. py:attribute:: packet :type: mini_arcade_core.engine.render.packet.RenderPacket | None .. py:data:: TTickContext .. py:class:: InputIntentSystem Bases: :py:obj:`mini_arcade_core.scenes.systems.base_system.BaseSystem` Converts InputFrame -> MenuIntent. :ivar name: Name of the system - default is "base_input". :ivar order: Execution order of the system - default is 10. .. py:attribute:: name :type: str :value: 'base_input' .. py:attribute:: order :type: int :value: 10 .. py:method:: build_intent(ctx: mini_arcade_core.scenes.sim_scene.BaseTickContext) -> mini_arcade_core.scenes.sim_scene.BaseIntent :abstractmethod: Build the intent .. py:method:: step(ctx: mini_arcade_core.scenes.sim_scene.BaseTickContext) Step the input system to extract menu intent. .. py:class:: BaseRenderSystem Bases: :py:obj:`mini_arcade_core.scenes.systems.base_system.BaseSystem`\ [\ :py:obj:`TTickContext`\ ], :py:obj:`Generic`\ [\ :py:obj:`TTickContext`\ ] Base rendering system. :ivar name: Name of the system - default is "base_render". :ivar order: Execution order of the system - default is 100. .. py:attribute:: name :type: str :value: 'base_render' .. py:attribute:: order :type: int :value: 100 .. py:method:: build_draw_ops(ctx: TTickContext) -> list[mini_arcade_core.scenes.sim_scene.DrawCall] Build draw calls for the current tick context. :param ctx: The tick context containing world state and other info. :type ctx: BaseTickContext :return: A list of draw calls to be executed by the render pipeline. :rtype: list[DrawCall] .. py:method:: step(ctx: TTickContext) -> None Perform a single step of the system within the given context. :param ctx: The system context. :type ctx: TSystemContext .. py:class:: BaseQueuedRenderSystem Bases: :py:obj:`BaseRenderSystem`\ [\ :py:obj:`TTickContext`\ ], :py:obj:`Generic`\ [\ :py:obj:`TTickContext`\ ] Base class for render systems that build a RenderQueue and submit it. Subclasses can override ``emit`` and/or ``emit_entity`` hooks. .. py:attribute:: name :type: str :value: 'queued_render' .. py:attribute:: merge_existing_draw_ops :type: bool :value: True .. py:method:: emit(ctx: TTickContext, rq: mini_arcade_core.scenes.sim_scene.RenderQueue) -> None Emit draw calls into the render queue. :param ctx: The tick context containing world state and other info. :type ctx: BaseTickContext :param rq: The render queue to emit draw calls into. :type rq: RenderQueue .. py:method:: emit_entity(_ctx: TTickContext, rq: mini_arcade_core.scenes.sim_scene.RenderQueue, entity: mini_arcade_core.engine.entities.BaseEntity) -> None Emit a single entity into the render queue. Subclasses can override this hook for entity-specific rendering, then delegate back to ``super().emit_entity`` for default behavior. .. py:method:: build_draw_ops(ctx: TTickContext) -> list[mini_arcade_core.scenes.sim_scene.DrawCall] Build draw calls for the current tick context. :param ctx: The tick context containing world state and other info. :type ctx: BaseTickContext :return: A list of draw calls to be executed by the render pipeline. :rtype: list[DrawCall] .. py:method:: step(ctx: TTickContext) -> None Perform a single step of the system within the given context. :param ctx: The system context. :type ctx: TSystemContext