mini_arcade_core.scenes.sim_scene

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

Attributes

TWorld
TIntent
TContext
Layer
OperationKind

Classes

EntityIdDomain	Named entity-id allocation domain.
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.EntityIdDomain

Named entity-id allocation domain.

start_id: int

end_id: int

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 - optional camera state (for example camera: Camera2D)

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.

entity_id_domains: ClassVar[dict[str, EntityIdDomain]]

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

__setattr__(name: str, value: object) → None

__post_init__() → None

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]

get_entities_by_tag(tag: str) → list[mini_arcade_core.engine.entities.BaseEntity]

Get entities registered with a normalized tag.

classmethod entity_id_domain(domain_name: str) → EntityIdDomain

Resolve a named entity-id domain declared by the world class.

get_entities_in_domain(domain_name: str) → list[mini_arcade_core.engine.entities.BaseEntity]

Return entities within a named entity-id domain.

allocate_entity_id(start_id: int, end_id: int, *, reserved_ids: Iterable[int] | None = None) → int | None

Allocate the first free entity id within [start_id, end_id].

allocate_entity_id_for(domain_name: str, *, reserved_ids: Iterable[int] | None = None) → int | None

Allocate the first free entity id inside a named domain.

remove_entities_by_ids(entity_ids: Iterable[int]) → None

Remove all entities whose ids match the provided iterable.

compact_tracked_entity_ids(*, attr_name: str, start_id: int, end_id: int, keep_entity: Callable[[mini_arcade_core.engine.entities.BaseEntity], bool] | None = None) → list[int]

Compact a tracked id list and remove entities in the associated id window that no longer satisfy keep_entity.

compact_tracked_entity_ids_for(*, attr_name: str, domain_name: str, keep_entity: Callable[[mini_arcade_core.engine.entities.BaseEntity], bool] | None = None) → list[int]

Compact a tracked id list against a named entity-id domain.

find_entities(*, tag: str | None = None, entity_type: type[mini_arcade_core.engine.entities.BaseEntity] | None = None, predicate: Callable[[mini_arcade_core.engine.entities.BaseEntity], bool] | None = None) → list[mini_arcade_core.engine.entities.BaseEntity]

Query entities by tag, type, and/or predicate.

find_entity(*, tag: str | None = None, entity_type: type[mini_arcade_core.engine.entities.BaseEntity] | None = None, predicate: Callable[[mini_arcade_core.engine.entities.BaseEntity], bool] | None = None) → mini_arcade_core.engine.entities.BaseEntity | None

Return the first entity that matches the query.

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

• intent_channels – Optional per-source intent snapshots for this tick.

• 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

intent_channels: dict[str, object]

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

intent_for(channel: str, default: object | None = None) → object

Return the intent stored for a channel, if present.

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.

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.sim_scene.SimScene(ctx: mini_arcade_core.runtime.context.RuntimeContext)

Bases: Generic[TContext, TWorld]

Simulation-first scene base.

Lifecycle:

• __init__(RuntimeContext): constructs the scene container

• on_enter(): allocate resources, build world, register systems

• tick(input_frame, dt): build per-tick context, run systems, return RenderPacket

Subclasses typically provide:

• build_pipeline() OR register systems in on_enter()

• build_world() (often in on_enter when window size/assets are needed)

Variables:

• context – RuntimeContext for this scene.

• systems – System pipeline

• world – Scene world, often set in on_enter

Tick_context_type:

Type of the tick context

context: mini_arcade_core.runtime.context.RuntimeContext

systems: mini_arcade_core.scenes.systems.system_pipeline.SystemPipeline[TContext]

world: TWorld

capture_config: ClassVar[mini_arcade_core.scenes.systems.builtins.capture_hotkeys.SceneCaptureConfig]

tick_context_type: Type[TContext] | None = None

scene_id: str | None = None

build_pipeline() → mini_arcade_core.scenes.systems.system_pipeline.SystemPipeline[TContext]

Return an empty pipeline by default; scenes can override.

Returns:

Empty pipeline

Return type:

SystemPipeline[TContext]

on_enter()

Called when the scene becomes active (safe place to create world & add systems).

on_exit()

Called when the scene stops being active (cleanup optional).

debug_overlay_lines() → list[str]

Optional extension hook for the built-in debug overlay.

Scenes can override this to expose scene-specific diagnostics.

uses_builtin_escape_handling() → bool

Whether engine-level ESC handling should apply to this scene.

configured_escape_command()

Resolve the configured ESC command for this scene, if any.

scene_runtime_settings()

Resolve per-scene gameplay config from runtime settings.

tick(input_frame: mini_arcade_core.runtime.input_frame.InputFrame, dt: float) → mini_arcade_core.engine.render.packet.RenderPacket

Advance the simulation by dt seconds, processing input_frame.

Parameters:

• input_frame (InputFrame) – Current input frame.

• dt (float) – Delta time since last tick.