mini_arcade_core.scenes.sim_scene ================================= .. py:module:: mini_arcade_core.scenes.sim_scene .. autoapi-nested-parse:: Simulation scene protocol module. Defines the SimScene protocol for simulation scenes. Attributes ---------- .. autoapisummary:: mini_arcade_core.scenes.sim_scene.TWorld mini_arcade_core.scenes.sim_scene.TIntent mini_arcade_core.scenes.sim_scene.TContext mini_arcade_core.scenes.sim_scene.Layer mini_arcade_core.scenes.sim_scene.OperationKind Classes ------- .. autoapisummary:: mini_arcade_core.scenes.sim_scene.BaseWorld mini_arcade_core.scenes.sim_scene.BaseIntent mini_arcade_core.scenes.sim_scene.Drawable mini_arcade_core.scenes.sim_scene.DrawCall mini_arcade_core.scenes.sim_scene.DrawOperation mini_arcade_core.scenes.sim_scene.RenderQueue mini_arcade_core.scenes.sim_scene.BaseTickContext mini_arcade_core.scenes.sim_scene.SubmitRenderQueue mini_arcade_core.scenes.sim_scene.SimScene Module Contents --------------- .. py:data:: TWorld .. py:data:: TIntent .. py:data:: TContext .. 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:: 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:: Drawable Bases: :py:obj:`abc.ABC`, :py:obj:`Generic`\ [\ :py:obj:`TContext`\ ] A drawable for scenes that can be drawn. .. py:method:: draw(backend: mini_arcade_core.backend.backend.Backend, ctx: TContext) :abstractmethod: Draw to the scene. .. 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:data:: OperationKind .. py:class:: DrawOperation A draw operation for rendering. .. py:attribute:: kind :type: OperationKind .. py:attribute:: layer :type: Layer .. py:attribute:: z :type: int :value: 0 .. py:attribute:: seq :type: int :value: 0 .. py:attribute:: payload :type: object | None :value: None .. 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:: 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:: 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:: SimScene(ctx: mini_arcade_core.runtime.context.RuntimeContext) Bases: :py:obj:`Generic`\ [\ :py:obj:`TContext`\ , :py:obj:`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) :ivar context: RuntimeContext for this scene. :ivar systems: System pipeline :ivar world: Scene world, often set in on_enter :tick_context_type: Type of the tick context .. py:attribute:: context :type: mini_arcade_core.runtime.context.RuntimeContext .. py:attribute:: systems :type: mini_arcade_core.scenes.systems.system_pipeline.SystemPipeline[TContext] .. py:attribute:: world :type: TWorld .. py:attribute:: tick_context_type :type: Type[TContext] | None :value: None .. py:method:: build_pipeline() -> mini_arcade_core.scenes.systems.system_pipeline.SystemPipeline[TContext] Return an empty pipeline by default; scenes can override. :return: Empty pipeline :rtype: SystemPipeline[TContext] .. py:method:: make_world() -> TWorld :abstractmethod: Construct the initial world state for this scene. Called during on_enter. :return: Initial world state :rtype: TWorld .. py:method:: on_enter() Called when the scene becomes active (safe place to create world & add systems). .. py:method:: on_exit() Called when the scene stops being active (cleanup optional). .. py:method:: 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. :param input_frame: Current input frame. :type input_frame: InputFrame :param dt: Delta time since last tick. :type dt: float