mini_arcade_core.scenes.sim_scene¶

Simulation scene protocol module. Defines the SimScene protocol for simulation scenes.

Attributes¶

`TWorld`
`TIntent`
`TContext`
`Layer`
`OperationKind`

Classes¶

`BaseWorld`	Base type for scene world state.
`BaseIntent`	Base type for scene intent.
`Drawable`	A drawable for scenes that can be drawn.
`DrawCall`	A draw call for rendering.
`DrawOperation`	A draw operation for rendering.
`RenderQueue`	A queue of draw operations to be rendered this tick.
`BaseTickContext`	Per-tick execution context passed through a SimScene pipeline.
`SubmitRenderQueue`	Drawable that submits a RenderQueue from the tick context.
`SimScene`	Simulation-first scene base.

Module Contents¶

mini_arcade_core.scenes.sim_scene.TWorld¶

mini_arcade_core.scenes.sim_scene.TIntent¶

mini_arcade_core.scenes.sim_scene.TContext¶

class mini_arcade_core.scenes.sim_scene.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.sim_scene.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.sim_scene.Drawable¶

Bases: abc.ABC, Generic[TContext]

A drawable for scenes that can be drawn.

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

class mini_arcade_core.scenes.sim_scene.DrawCall¶

A draw call for rendering.

drawable: Drawable[TContext]¶

ctx: TContext¶

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

mini_arcade_core.scenes.sim_scene.Layer¶

mini_arcade_core.scenes.sim_scene.OperationKind¶

class mini_arcade_core.scenes.sim_scene.DrawOperation¶

A draw operation for rendering.

kind: OperationKind¶

layer: Layer¶

z: int = 0¶

seq: int = 0¶

payload: object | None = None¶

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