mini_arcade_core.scenes.systems.builtins¶

Built-in systems for scenes.

Submodules¶

Attributes¶

`Layer`
`TTickContext`

Classes¶

`BaseEntity`	Base entity class.
`RenderPacket`	Minimal render packet for v1.
`BaseIntent`	Base type for scene intent.
`BaseTickContext`	Per-tick execution context passed through a SimScene pipeline.
`BaseWorld`	Base type for scene world state.
`DrawCall`	A draw call for rendering.
`RenderQueue`	A queue of draw operations to be rendered this tick.
`SubmitRenderQueue`	Drawable that submits a RenderQueue from the tick context.
`BaseSystem`	Protocol for a system that operates within a given context.
`Vec2`	Simple 2D vector.
`ActionIntentSystem`	Input system that converts an ActionMap snapshot into scene intent.
`ActionMap`	Mapping of action IDs to concrete binding strategies.
`ActionSnapshot`	Per-frame snapshot for all mapped actions.
`AxisActionBinding`	Axis action sourced from analog axes and optional digital fallbacks.
`DigitalActionBinding`	Digital action sourced from keyboard and/or named buttons.
`CaptureHotkeysConfig`	Per-scene capture workflow configuration.
`CaptureHotkeysSystem`	Handles screenshot/replay/video commands in a reusable way.
`RenderSystemContext`	Structural context contract for render systems.
`InputIntentSystem`	Converts InputFrame -> MenuIntent.
`BaseRenderSystem`	Base rendering system.
`BaseQueuedRenderSystem`	Base class for render systems that build a RenderQueue and submit it.

Package Contents¶

class mini_arcade_core.scenes.systems.builtins.BaseEntity¶

Base entity class.

Variables:

id – The unique ID of the entity.
name – The optional name of the entity.
transform – The transform of the entity.
shape – The shape of the entity.
style – The render style of the entity.
kinematic – The kinematic body of the entity.
collider – The collider specification of the entity.
sprite – The sprite component of the entity.
anim – The animation component of the entity.
life – The life component of the entity.

id: int¶

name: str¶

codename: str¶

transform: mini_arcade_core.spaces.geometry.transform.Transform2D¶

shape: mini_arcade_core.spaces.geometry.shapes.Shape2D¶

z_index: int = 0¶

rotation_deg: float = 0.0¶

style: mini_arcade_core.engine.render.style.RenderStyle | None = None¶

kinematic: mini_arcade_core.spaces.physics.kinematics2d.Kinematic2D | None = None¶

collider: mini_arcade_core.spaces.collision.specs.ColliderSpec | None = None¶

sprite: mini_arcade_core.engine.components.Sprite2D | None = None¶

anim: mini_arcade_core.engine.components.Anim2D | None = None¶

life: mini_arcade_core.engine.components.Life | None = None¶

classmethod from_dict(data: dict) → BaseEntity¶

Create an entity from a dictionary.

Parameters:: data (dict) – The dictionary containing the entity data.
Returns:: The created entity.
Return type:: BaseEntity

class mini_arcade_core.scenes.systems.builtins.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.

ops: tuple[DrawOp, Ellipsis] = ()¶

meta: dict[str, object]¶

static from_ops(ops: Iterable[DrawOp], **meta: object) → RenderPacket¶

Create a RenderPacket from an iterable of DrawOps and optional meta.

Parameters:: ops (Iterable[DrawOp]) – Iterable of DrawOp callables.
Returns:: RenderPacket instance.
Return type:: RenderPacket

class mini_arcade_core.scenes.systems.builtins.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.

class mini_arcade_core.scenes.systems.builtins.BaseTickContext¶

Bases: Generic[TWorld, 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.

Variables:

input_frame – Snapshot of raw/normalized input for this tick.
dt – Delta time (seconds) since previous tick.
world – Scene-owned world state (usually mutated during the tick).
commands – Queue of commands/events emitted by systems.
intent – Optional intent snapshot for this tick (produced by input system).
packet – Optional render packet produced for this tick.
draw_ops – Optional immediate draw operations (debug/overlay/utility).

input_frame: mini_arcade_core.runtime.input_frame.InputFrame¶

dt: float¶

world: TWorld¶

commands: mini_arcade_core.engine.commands.CommandQueue¶

intent: TIntent | None = None¶

packet: mini_arcade_core.engine.render.packet.RenderPacket | None = None¶

draw_ops: list[mini_arcade_core.engine.render.packet.DrawOp] | None = None¶

render_queue: RenderQueue¶

class mini_arcade_core.scenes.systems.builtins.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.

entities: list[mini_arcade_core.engine.entities.BaseEntity]¶

get_entity_by_id(entity_id: int) → mini_arcade_core.engine.entities.BaseEntity | None¶

Get an entity by its ID.

Parameters:: entity_id (int) – The ID of the entity to retrieve.
Returns:: The entity with the specified ID, or None if not found.
Return type:: BaseEntity | None

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].

Parameters:

start_id (int) – The starting ID of the range (inclusive).
end_id (int) – The ending ID of the range (inclusive).

Returns:

A list of entities with IDs in the specified range.

Return type:

list[BaseEntity]

class mini_arcade_core.scenes.systems.builtins.DrawCall¶

A draw call for rendering.

drawable: Drawable[TContext]¶

ctx: TContext¶

__call__(backend: mini_arcade_core.backend.backend.Backend) → None¶

mini_arcade_core.scenes.systems.builtins.Layer¶

class mini_arcade_core.scenes.systems.builtins.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.

clear() → None¶: Clear all draw operations from the queue.

rect(*, center, size, color, radius=0.0, layer: Layer = 'world', z: int = 0) → None¶

Push a rectangle draw operation.

Parameters:

center (Vec2) – Center position of the rectangle.
size (Vec2) – Size of the rectangle (width, height).
color (Color) – Color of the rectangle.
radius (float) – Optional corner radius for rounded rectangles (default 0).
layer (Layer) – The layer to draw on (default “world”).
z (int) – The z-index for sorting within the layer (default 0).

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.

Parameters:

a (Vec2) – Starting point of the line.
b (Vec2) – Ending point of the line.
color (Color) – Color of the line.
thickness (float) – Thickness of the line (default 1.0).
dash_length (float | None) – Length of dashes for dashed line (None for solid line).
dash_gap (float | None) – Length of gaps for dashed line (None for solid line).
layer (Layer) – The layer to draw on (default “world”).
z (int) – The z-index for sorting within the layer (default 0).

circle(*, center, radius, color, layer: Layer = 'world', z: int = 0) → None¶

Push a circle draw operation.

Parameters:

center (Vec2) – Center position of the circle.
radius (float) – Radius of the circle.
color (Color) – Color of the circle.
layer (Layer) – The layer to draw on (default “world”).
z (int) – The z-index for sorting within the layer (default 0).

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.

Parameters:

points (list[Vec2]) – List of points defining the polygon vertices.
fill (Color | None) – Fill color for the polygon (None for no fill).
stroke (Color | None) – Stroke color for the polygon edges (None for no stroke).
thickness (int) – Thickness of the stroke (default 1).
closed (bool) – Whether the polygon should be closed (default True).
layer (Layer) – The layer to draw on (default “world”).
z (int) – The z-index for sorting within the layer (default 0).

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.

Parameters:

tex_id (int) – The texture ID to draw.
x (float) – X position to draw the texture.
y (float) – Y position to draw the texture.
w (float) – Width to draw the texture.
h (float) – Height to draw the texture.
angle_deg (float) – Rotation angle in degrees (default 0).
layer (Layer) – The layer to draw on (default “world”).
z (int) – The z-index for sorting within the layer (default 0).

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.

Parameters:

x (float) – X position of the text.
y (float) – Y position of the text.
text (str) – The text string to draw.
color (Color) – The color of the text (default white).
font_size (int | None) – Optional font size (default None for backend default).
align (Literal["left", "center", "right"]) – Text alignment: “left”, “center”, or “right” (default “left”).
layer (Layer) – The layer to draw on (default “ui”).
z (int) – The z-index for sorting within the layer (default 0).

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.

Parameters:

op (Callable[[Backend], None]) – A callable that takes a Backend and performs custom drawing.
layer (Layer) – The layer to draw on (default “debug”).
z (int) – The z-index for sorting within the layer (default 0).

iter_sorted(layers: tuple[Layer, Ellipsis] | list[Layer] | None = None) → list[DrawOperation]¶

Get draw operations sorted by layer/z/seq, optionally filtered by layers.

Parameters:: layers (tuple[Layer, ...] | list[Layer] | None) – Optional tuple or list of layers to include (default all).
Returns:: Sorted list of draw operations for the specified layers.
Return type:: list[DrawOperation]

class mini_arcade_core.scenes.systems.builtins.SubmitRenderQueue¶

Bases: Drawable[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.

Variables:: layers – (tuple[Layer, …] | None): Optional tuple of layers to render from the RenderQueue (default all).

layers: tuple[Layer, Ellipsis] | None = None¶

draw(backend: mini_arcade_core.backend.backend.Backend, ctx: BaseTickContext)¶: Draw to the scene.

class mini_arcade_core.scenes.systems.builtins.BaseSystem¶

Bases: Protocol, Generic[TSystemContext]

Protocol for a system that operates within a given context.

name: str¶

phase: int = 0¶

order: int = 0¶

enabled(ctx: TSystemContext) → bool¶

Determine if the system is enabled in the given context.

Parameters:: ctx (TSystemContext) – The system context.
Returns:: True if the system is enabled, False otherwise.
Return type:: bool

step(ctx: TSystemContext)¶

Perform a single step of the system within the given context.

Parameters:: ctx (TSystemContext) – The system context.

class mini_arcade_core.scenes.systems.builtins.Vec2¶

Simple 2D vector.

Variables:

(float) (y) – X coordinate.
(float) – Y coordinate.

x: float¶

y: float¶

to_tuple() → tuple[float, float]¶

Convert Vex2 to a tuple.

Returns:: Tuple of (x, y).
Return type:: tuple[float, float]

__add__(other: Vec2) → Vec2¶

__mul__(scalar: float) → Vec2¶

__iadd__(other: Vec2) → Vec2¶

__imul__(scalar: float) → Vec2¶

class mini_arcade_core.scenes.systems.builtins.ActionIntentSystem¶

Bases: mini_arcade_core.scenes.systems.base_system.BaseSystem[TContext], Generic[TContext, TIntent]

Input system that converts an ActionMap snapshot into scene intent.

action_map: ActionMap¶

intent_factory: Callable[[ActionSnapshot, TContext], TIntent]¶

name: str = 'action_intent'¶

order: int = 10¶

step(ctx: TContext) → None¶

Perform a single step of the system within the given context.

Parameters:: ctx (TSystemContext) – The system context.

class mini_arcade_core.scenes.systems.builtins.ActionMap¶

Mapping of action IDs to concrete binding strategies.

bindings: Mapping[str, ActionBinding]¶

read(frame: mini_arcade_core.runtime.input_frame.InputFrame) → ActionSnapshot¶

Read the current state of all actions from the input frame.

Parameters:: frame (InputFrame) – The input frame containing raw input states.
Returns:: An ActionSnapshot containing the state of all actions.
Return type:: ActionSnapshot

class mini_arcade_core.scenes.systems.builtins.ActionSnapshot¶

Per-frame snapshot for all mapped actions.

state(action: str) → ActionState¶

Get the ActionState for the given action, or a default if not found.

Parameters:: action (str) – The name of the action to get the state for.
Returns:: The ActionState for the given action, or a default if not found.
Return type:: ActionState

value(action: str, default: float = 0.0) → float¶

Get the normalized value of the action, or a default if not found.

Parameters:

action (str) – The name of the action to get the value for.
default (float) – The default value to return if the action is not found (default 0.0).

Returns:

The normalized value of the action, or the default if not found.

Return type:

float

down(action: str) → bool¶

Check if the action is currently held down.

Parameters:: action (str) – The name of the action to check.
Returns:: True if the action is currently held down, False otherwise.
Return type:: bool

pressed(action: str) → bool¶

Check if the action was pressed this frame.

Parameters:: action (str) – The name of the action to check.
Returns:: True if the action was pressed this frame, False otherwise.
Return type:: bool

released(action: str) → bool¶

Check if the action was released this frame.

Parameters:: action (str) – The name of the action to check.
Returns:: True if the action was released this frame, False otherwise.
Return type:: bool

class mini_arcade_core.scenes.systems.builtins.AxisActionBinding¶

Bases: ActionBinding

Axis action sourced from analog axes and optional digital fallbacks.

axes: tuple[str, Ellipsis] = ()¶

positive_keys: tuple[mini_arcade_core.backend.keys.Key, Ellipsis] = ()¶

negative_keys: tuple[mini_arcade_core.backend.keys.Key, Ellipsis] = ()¶

positive_buttons: tuple[str, Ellipsis] = ()¶

negative_buttons: tuple[str, Ellipsis] = ()¶

deadzone: float = 0.15¶

scale: float = 1.0¶

read(frame: mini_arcade_core.runtime.input_frame.InputFrame) → ActionState¶

Read the current state of this action from the input frame.

Parameters:: frame (InputFrame) – The input frame containing raw input states.
Returns:: The current ActionState for this binding.
Return type:: ActionState

class mini_arcade_core.scenes.systems.builtins.DigitalActionBinding¶

Bases: ActionBinding

Digital action sourced from keyboard and/or named buttons.

keys: tuple[mini_arcade_core.backend.keys.Key, Ellipsis] = ()¶

buttons: tuple[str, Ellipsis] = ()¶

read(frame: mini_arcade_core.runtime.input_frame.InputFrame) → ActionState¶

Read the current state of this action from the input frame.

Parameters:: frame (InputFrame) – The input frame containing raw input states.
Returns:: The current ActionState for this binding.
Return type:: ActionState

class mini_arcade_core.scenes.systems.builtins.CaptureHotkeysConfig¶

Per-scene capture workflow configuration.

screenshot_label: str | None = None¶

replay_file: str | None = None¶

replay_game_id: str = 'mini-arcade'¶

replay_initial_scene: str = 'unknown'¶

replay_fps: int = 60¶

action_toggle_video: str = 'capture_toggle_video'¶

action_toggle_replay_record: str = 'capture_toggle_replay_record'¶

action_toggle_replay_play: str = 'capture_toggle_replay_play'¶

action_screenshot: str = 'capture_screenshot'¶

class mini_arcade_core.scenes.systems.builtins.CaptureHotkeysSystem¶

Bases: mini_arcade_core.scenes.systems.base_system.BaseSystem[CaptureContext]

Handles screenshot/replay/video commands in a reusable way.

services: mini_arcade_core.runtime.services.RuntimeServices¶

action_map: mini_arcade_core.scenes.systems.builtins.actions.ActionMap¶

cfg: CaptureHotkeysConfig¶

name: str = 'capture_hotkeys'¶

order: int = 13¶

step(ctx: CaptureContext) → None¶

Perform a single step of the system within the given context.

Parameters:: ctx (TSystemContext) – The system context.

class mini_arcade_core.scenes.systems.builtins.RenderSystemContext¶

Bases: Protocol

Structural context contract for render systems.

Any scene tick context that provides these attributes will be accepted.

world: mini_arcade_core.scenes.sim_scene.BaseWorld¶

draw_ops: list[mini_arcade_core.scenes.sim_scene.DrawCall] | None¶

render_queue: mini_arcade_core.scenes.sim_scene.RenderQueue¶

packet: mini_arcade_core.engine.render.packet.RenderPacket | None¶

mini_arcade_core.scenes.systems.builtins.TTickContext¶

class mini_arcade_core.scenes.systems.builtins.InputIntentSystem¶

Bases: mini_arcade_core.scenes.systems.base_system.BaseSystem

Converts InputFrame -> MenuIntent.

Variables:

name – Name of the system - default is “base_input”.
order – Execution order of the system - default is 10.

name: str = 'base_input'¶

order: int = 10¶

abstractmethod build_intent(ctx: mini_arcade_core.scenes.sim_scene.BaseTickContext) → mini_arcade_core.scenes.sim_scene.BaseIntent¶: Build the intent

step(ctx: mini_arcade_core.scenes.sim_scene.BaseTickContext)¶: Step the input system to extract menu intent.

class mini_arcade_core.scenes.systems.builtins.BaseRenderSystem¶

Bases: mini_arcade_core.scenes.systems.base_system.BaseSystem[TTickContext], Generic[TTickContext]

Base rendering system.

Variables:

name – Name of the system - default is “base_render”.
order – Execution order of the system - default is 100.

name: str = 'base_render'¶

order: int = 100¶

build_draw_ops(ctx: TTickContext) → list[mini_arcade_core.scenes.sim_scene.DrawCall]¶

Build draw calls for the current tick context.

Parameters:: ctx (BaseTickContext) – The tick context containing world state and other info.
Returns:: A list of draw calls to be executed by the render pipeline.
Return type:: list[DrawCall]

step(ctx: TTickContext) → None¶

Perform a single step of the system within the given context.

Parameters:: ctx (TSystemContext) – The system context.

class mini_arcade_core.scenes.systems.builtins.BaseQueuedRenderSystem¶

Bases: BaseRenderSystem[TTickContext], Generic[TTickContext]

Base class for render systems that build a RenderQueue and submit it. Subclasses can override emit and/or emit_entity hooks.

name: str = 'queued_render'¶

merge_existing_draw_ops: bool = True¶

emit(ctx: TTickContext, rq: mini_arcade_core.scenes.sim_scene.RenderQueue) → None¶

Emit draw calls into the render queue.

Parameters:

ctx (BaseTickContext) – The tick context containing world state and other info.
rq (RenderQueue) – The render queue to emit draw calls into.

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.

build_draw_ops(ctx: TTickContext) → list[mini_arcade_core.scenes.sim_scene.DrawCall]¶

Build draw calls for the current tick context.

Parameters:: ctx (BaseTickContext) – The tick context containing world state and other info.
Returns:: A list of draw calls to be executed by the render pipeline.
Return type:: list[DrawCall]

step(ctx: TTickContext) → None¶

Perform a single step of the system within the given context.

Parameters:: ctx (TSystemContext) – The system context.