mini_arcade_core.backend

Backend module for rendering and input abstraction. Defines the Backend interface and related types. This is the only part of the code that talks to SDL/pygame directly.

Submodules

• mini_arcade_core.backend.backend
• mini_arcade_core.backend.config
• mini_arcade_core.backend.events
• mini_arcade_core.backend.keys
• mini_arcade_core.backend.sdl_map
• mini_arcade_core.backend.types
• mini_arcade_core.backend.utils
• mini_arcade_core.backend.viewport

Classes

AudioProtocol	Interface for audio operations.
Backend	Interface that any rendering/input backend must implement.
CaptureProtocol	Interface for frame capture operations.
InputProtocol	Interface for input operations.
RenderProtocol	Interface for rendering operations.
TextProtocol	Interface for text rendering operations.
WindowProtocol	Represents a game window.

Package Contents

class mini_arcade_core.backend.AudioProtocol

Bases: Protocol

Interface for audio operations.

init(frequency: int = 44100, channels: int = 2, chunk_size: int = 2048)

Initialize audio subsystem.

Parameters:

• frequency (int) – Audio frequency in Hz.

• channels (int) – Number of audio channels (1=mono, 2=stereo).

• chunk_size (int) – Size of audio chunks.

shutdown()

Shutdown the audio subsystem.

load_sound(sound_id: str, path: str)

Load a sound file.

Parameters:

• sound_id (str) – Unique identifier for the sound.

• path (str) – File path to the sound.

play_sound(sound_id: str, loops: int = 0)

Play a loaded sound.

Parameters:

• sound_id (str) – Unique identifier for the sound.

• loops (int) – Number of times to loop the sound.

set_master_volume(volume: int)

Set the master volume.

Parameters:

volume (int) – Volume level (0-128).

set_sound_volume(sound_id: str, volume: int)

Set volume for a specific sound.

Parameters:

• sound_id (str) – Unique identifier for the sound.

• volume (int) – Volume level (0-128).

stop_all()

Stop all currently playing sounds.

class mini_arcade_core.backend.Backend

Bases: Protocol

Interface that any rendering/input backend must implement. mini-arcade-core only talks to this protocol, never to SDL/pygame directly.

Each sub-capability is exposed as a typed protocol attribute so that systems or draw helpers can accept only the slice they need (e.g. RenderProtocol or TextProtocol) instead of the full backend.

Variables:

• (WindowProtocol) (window) – Window management interface.

• (AudioProtocol) (audio) – Audio management interface.

• (InputProtocol) (input) – Input management interface.

• (RenderProtocol) (render) – Rendering interface.

• (TextProtocol) (text) – Text rendering interface.

• (CaptureProtocol) (capture) – Frame capture interface.

window: WindowProtocol

audio: AudioProtocol

input: InputProtocol

render: RenderProtocol

text: TextProtocol

capture: CaptureProtocol

init()

Initialize the backend and open a window. Should be called once before the main loop.

set_viewport_transform(offset_x: int, offset_y: int, scale: float)

Set the viewport transformation.

Parameters:

• offset_x (int) – Horizontal offset.

• offset_y (int) – Vertical offset.

• scale (float) – Scaling factor.

clear_viewport_transform()

Clear the viewport transformation (reset to defaults).

class mini_arcade_core.backend.CaptureProtocol

Bases: Protocol

Interface for frame capture operations.

bmp(path: str | None = None) → bool

Capture the current frame as a BMP file.

Parameters:

path (str | None) – Optional file path to save the BMP. If None, returns bytes.

Returns:

Whether the capture was successful.

Return type:

bool

argb8888_bytes() → tuple[int, int, bytes]

Capture the current frame as raw ARGB8888 bytes.

Returns:

A tuple of (width, height, bytes).

Return type:

tuple[int, int, bytes]

class mini_arcade_core.backend.InputProtocol

Bases: Protocol

Interface for input operations.

poll() → Iterable[mini_arcade_core.backend.events.Event]

Get the list of input events since the last call.

Returns:

Iterable of Event instances.

Return type:

Iterable[Event]

class mini_arcade_core.backend.RenderProtocol

Bases: Protocol

Interface for rendering operations.

set_clear_color(r: int, g: int, b: int)

Set the clear color for the renderer.

Parameters:

• r (int) – Red component (0-255).

• g (int) – Green component (0-255).

• b (int) – Blue component (0-255).

begin_frame()

Begin a new rendering frame.

end_frame()

End the current rendering frame.

draw_rect(x: int, y: int, w: int, h: int, color=(255, 255, 255))

Draw a filled rectangle.

Parameters:

• x (int) – The x-coordinate of the rectangle.

• y (int) – The y-coordinate of the rectangle.

• w (int) – The width of the rectangle.

• h (int) – The height of the rectangle.

• color (tuple[int, int, int] | tuple[int, int, int, int]) – The color of the rectangle as an (R, G, B) or (R, G, B, A) tuple.

draw_line(x1: int, y1: int, x2: int, y2: int, color=(255, 255, 255), thickness: int = 1)

Draw a line between two points.

Parameters:

• x1 (int) – The x-coordinate of the start point.

• y1 (int) – The y-coordinate of the start point.

• x2 (int) – The x-coordinate of the end point.

• y2 (int) – The y-coordinate of the end point.

• color (tuple[int, int, int] | tuple[int, int, int, int]) – The color of the line as an (R, G, B) or (R, G, B, A) tuple.

set_clip_rect(x: int, y: int, w: int, h: int)

Set the clipping rectangle.

Parameters:

• x (int) – The x-coordinate of the clipping rectangle.

• y (int) – The y-coordinate of the clipping rectangle.

• w (int) – The width of the clipping rectangle.

• h (int) – The height of the clipping rectangle.

clear_clip_rect()

Clear the clipping rectangle.

create_texture_rgba(w: int, h: int, pixels: bytes, pitch: int | None = None) → int

Create a texture from RGBA pixel data.

Parameters:

• w (int) – The width of the texture.

• h (int) – The height of the texture.

• pixels (bytes) – The pixel data in RGBA format.

• pitch (int | None) – The number of bytes in a row of pixel data. If None, defaults to w * 4.

destroy_texture(tex: int) → None

Destroy a texture.

Parameters:

tex (int) – The texture ID to destroy.

draw_texture(tex: int, x: int, y: int, w: int, h: int, angle_deg: float = 0.0)

Draw a texture at the specified position and size.

Parameters:

• tex (int) – The texture ID.

• x (int) – The x-coordinate to draw the texture.

• y (int) – The y-coordinate to draw the texture.

• w (int) – The width to draw the texture.

• h (int) – The height to draw the texture.

• angle_deg (float) – Clockwise rotation angle in degrees around texture center.

draw_texture_tiled_y(tex_id: int, x: int, y: int, w: int, h: int)

Draw a texture repeated vertically to fill (w,h). Assumes you can resolve tex_id -> pygame.Surface, and supports scaling width.

Parameters:

• tex_id (int) – The texture ID.

• x (int) – The x-coordinate to draw the texture.

• y (int) – The y-coordinate to draw the texture.

• w (int) – The width to draw the texture.

• h (int) – The height to draw the texture.

draw_circle(x: int, y: int, radius: int, color=(255, 255, 255))

Draw a filled circle.

Parameters:

• x – Center x

• y – Center y

• radius – Radius in pixels

• color – (R,G,B) or (R,G,B,A)

draw_poly(points: list[tuple[int, int]], color=(255, 255, 255), filled: bool = True)

Draw a polygon defined by a list of points.

Parameters:

• points (list[tuple[int, int]]) – List of (x, y) tuples defining the vertices of the polygon.

• color (tuple[int, int, int] | tuple[int, int, int, int]) – The color of the polygon as an (R, G, B) or (R, G, B, A) tuple.

• filled (bool) – Whether to draw a filled polygon or just the outline.

class mini_arcade_core.backend.TextProtocol

Bases: Protocol

Interface for text rendering operations.

measure(text: str, font_size: int | None = None, font_name: str | None = None) → tuple[int, int]

Measure the width and height of the given text.

Parameters:

• text (str) – The text to measure.

• font_size (int | None) – The font size to use for measurement.

• font_name (str | None) – Optional named font configured by the backend.

Returns:

A tuple containing the width and height of the text.

Return type:

tuple[int, int]

draw(x: int, y: int, text: str, color=(255, 255, 255), font_size: int | None = None, font_name: str | None = None)

Draw the given text at the specified position.

Parameters:

• x (int) – The x-coordinate to draw the text.

• y (int) – The y-coordinate to draw the text.

• text (str) – The text to draw.

• color (tuple[int, int, int] | tuple[int, int, int, int]) – The color of the text as an (R, G, B) or (R, G, B, A) tuple.

• font_size (int | None) – The font size to use for drawing.

• font_name (str | None) – Optional named font configured by the backend.

class mini_arcade_core.backend.WindowProtocol

Bases: Protocol

Represents a game window.

width: int

height: int

set_title(title: str)

Set the window title.

Parameters:

title (str) – New window title.

resize(width: int, height: int)

Resize the window.

Parameters:

• width (int) – New width in pixels.

• height (int) – New height in pixels.

size() → tuple[int, int]

Get the window size.

Returns:

Tuple of (width, height) in pixels.

Return type:

tuple[int, int]

drawable_size() → tuple[int, int]

Get the drawable size of the window.

Returns:

Tuple of (width, height) in pixels.

Return type:

tuple[int, int]