API reference

install

pip install texastoast
pip install "texastoast[sprites]"    # Pillow, for sprite sheets
pip install "texastoast[hardware]"   # smbus2, for I2C on Raspberry Pi
pip install "texastoast[audio]"      # pygame-ce, for a real sound mixer

No extra is required; keyboard-only games work with none of them, and both the hardware and audio layers degrade rather than fail when their extra is absent. Everything below is re-exported from the top-level package:

from texastoast import (
    Config, GameLoop, Game, Scene, SceneStack,
    CanvasRenderer, Camera, SpriteSheet, Renderer, UISurface,
    TileMap, Entity, EntityGroup, AABB,
    InputState, KeyboardInput, MagmaHubInput, CompositeInput,
    InputRecorder, ReplayInput, Player, PlayerManager,
    I2CBus, MagmaHub, ControllerState, HubStats,
    SimBus, simulated_hub, KeyboardHubDriver, HubPoller, scan_buses_async,
    DialogueBox, Menu, HUD, Theme, DEFAULT_THEME, Mixer,
)

Game

Owns the window, the canvas, and the game lifecycle.

Game(title="texastoast", width=640, height=480, fps=30,
     config=None, root=None, max_consecutive_errors=10)

Passing root embeds the game in an existing tkinter app; the caller then owns the main loop and quit() leaves the window standing.

Config & GameLoop

Config

GameLoop

Game builds one for you; you rarely construct it directly.

• .fps, measured frame rate, updated once a second.
• .frame_count, frames since the last measurement.
• .error, the exception that stopped the loop, if one did.
• start() / stop(), the loop reschedules itself via after().

scenes

Modality as a stack instead of a pile of flags. Pushing a scene freezes the scenes below it by construction, so a pause menu needs no paused global and no early-return chain. New in 0.5.0.

Scene

There is no base class to subclass. A scene needs update(dt) and render(); everything else is optional and detected by presence.

class WorldScene:
    def update(self, dt): ...
    def render(self): ...

    # all optional:
    def on_enter(self): ...      # pushed onto the stack
    def on_exit(self): ...       # removed from it
    def on_pause(self): ...      # covered by a push
    def on_resume(self): ...     # re-exposed by a pop
    def handle_key(self, event): ...   # only while this scene is on top

    update_below = True          # the scene underneath keeps updating
    render_below = True          # the scene underneath keeps rendering

SceneStack

stack = SceneStack()

stack.push(scene)          # old top gets on_pause, new scene on_enter
stack.pop()                # top gets on_exit, the exposed scene on_resume
stack.replace(scene)       # exit + enter, no pause/resume
stack.clear()              # on_exit top-down

stack.update(dt)           # applies pending ops, then the active slice
stack.render()             # the visible slice, bottom-to-top
stack.dispatch_key(event)  # -> bool; top scene only

stack.top                  # the current top scene, or None
stack.scenes               # bottom-to-top snapshot
len(stack), bool(stack), scene in stack

Wire it yourself, the stack is a system, not a framework:

game.set_update(stack.update)
game.set_render(stack.render)
game.bind_key("<Key>", stack.dispatch_key)

world

TileMap

TileMap(grid, tile_size=16, solid_tiles=None)
TileMap.from_file(path, tile_size=None, solid_tiles=None)

Entity

Entity(x=0, y=0, width=16, height=16, speed=1.0)

EntityGroup

The update loop, plus tags and painter's-order iteration. Membership is duck-typed: anything with update(dt) qualifies, so timers and particles fit without inheriting from Entity. The group never draws; rendering stays yours. New in 0.5.0.

entities = EntityGroup()
player = entities.add(Entity(x=60, y=60), "player")   # returns the entity
entities.add(npc, "npc", "vendor")                    # tags live in the group

entities.update(dt)                  # calls update(dt) on every member
entities.remove(npc)                 # or npc.alive = False
entities.by_tag("npc")               # -> list
entities.select(lambda e: e.x > 80)  # -> list
entities.sorted_by_y()               # by feet line (y + height)
entities.clear()
len(entities), iter(entities), npc in entities

rendering

CanvasRenderer

CanvasRenderer(canvas, width, height)

Camera

Camera(width=640, height=480, x=0.0, y=0.0, smoothing=0.1)
camera.follow(target_x, target_y, map_width=0, map_height=0, dt=dt)

Passing map_width and map_height clamps the view to the map edges. smoothing is a per-frame factor calibrated at 30 fps, converted to a time constant and integrated over dt, so the camera lags by the same distance at any frame rate.

• set_position(x, y), snap, no smoothing.
• world_to_screen(wx, wy) / screen_to_world(sx, sy)
• is_visible(x, y, w, h), cull test.

SpriteSheet

Crops frames out of a sprite sheet image. Requires the [sprites] extra (Pillow).

input

Every input source returns the same InputState snapshot, so game code never knows whether it is reading a keyboard or a controller.

InputState

Booleans up down left right a b start select, plus derived .dx / .dy (−1, 0, or 1) and .is_any_direction.

KeyboardInput

keyboard = KeyboardInput(game.root)
state = keyboard.poll()      # a copy, so you can diff against last frame

Also is_pressed(button) and destroy(), which removes every binding it installed; pair it with game.on_close(keyboard.destroy).

MagmaHubInput & CompositeInput

MagmaHubInput reads a Magma Hub controller over I2C. CompositeInput merges several sources, so a game can accept the controller when it is plugged in and the keyboard when it is not:

inputs = CompositeInput(MagmaHubInput(hub), KeyboardInput(game.root))

InputRecorder & ReplayInput

Record any input source to a .ttrec file and play it back. The format stores the I2C protocol's button bitmask, so one recording replays two ways: through the engine as an input source, or through the full hardware stack via the simulator. New in 0.4.0.

recorder = InputRecorder(controls, "session.ttrec")   # transparent wrapper
recorder.start()
game.on_close(recorder.stop)

replay = ReplayInput("session.ttrec")
replay.advance(dt)      # deterministic manual clock — for tests
replay.start()          # or wall-clock playback
replay.poll()           # -> InputState

players

Seats for multi-controller games: join by button press, hotplug handling, and a returning controller that reclaims its own seat. New in 0.5.0.

manager = PlayerManager(max_players=4,
                        join_buttons=("a", "start"),
                        on_join=lambda p: ...,
                        on_leave=lambda p: ...)

manager.add_source(keyboard)   # the keyboard is claimable like any pad
manager.add_hub(poller)        # one seat candidate per hub controller

def update(dt):
    manager.update()                       # join scan + hotplug watch
    for player in manager.joined_players:
        state = player.poll()              # a Player IS an InputSource

ui widgets

All three are frame-driven: call render() every frame and they draw nothing while inactive. Each owns a canvas tag and redraws only its own items.

DialogueBox

DialogueBox(canvas, width=640, height=480, box_height=100,
            padding=12, font=("Courier", 12), speed=0.03)

• show(text, speaker="", on_complete=None), start the typewriter.
• update(dt), advance it; call from update().
• dismiss(), finish the line, or close the box if already finished.
• .active, .waiting, .displayed, state and the text so far.

Menu

Menu(canvas, width=640, height=480, font=("Courier", 14),
     selected_color="#e94560", normal_color="#ffffff",
     disabled_color="#555555", item_padding=8)
menu.show(items, on_select=None, on_cancel=None, title="", selected=0)

• move_up() / move_down(), skip disabled entries automatically.
• confirm() / cancel(), fire the callbacks.
• set_enabled(index, enabled), hide(), .active, .selected_index.

HUD

hud = HUD(game.canvas, width=320, height=240, padding=8)
hud.add_stat("health", "HP", value=80, max_value=100, color="#e94560")
hud.add_text("score", "Score: 0", 290, 8, fill="#fdd835")
hud.set_stat("health", 55)
hud.set_text("score", "Score: 120")

Also remove_text(key) and clear(). Each stat draws a labelled bar with a value readout; each text is free-floating at the coordinates you give it.

Theme

All three widgets take a theme=. Before 0.5.0 the palette was string literals scattered across the widget files; now it is one frozen dataclass.

from dataclasses import replace
from texastoast import DEFAULT_THEME, Theme

ocean = replace(DEFAULT_THEME, primary="#4fc3f7", selection_fill="#112233")
dialogue = DialogueBox(renderer, theme=ocean)
menu = Menu(renderer, theme=ocean)
hud = HUD(renderer, theme=ocean)

ocean.font(10, "bold")   # -> ("Courier", 10, "bold") in the theme's family

Fields: primary, text, dim_text, label_text, disabled, box_fill, box_outline, outline_width, selection_fill, bar_fill, bar_outline, font_family.

audio

Sound with the same degradation contract as the rest of the engine: no method ever raises into your frame, and a machine with no audio device runs the game identically, just silently. New in 0.5.0.

mixer = Mixer()                    # best backend available; never raises
game.on_close(mixer.close)

mixer.load("jump", "assets/jump.wav")
mixer.load("theme", "assets/theme.wav", volume=0.6)
mixer.play_music("theme")          # one music slot; loops; replaces previous
mixer.play("jump")                 # fire-and-forget SFX
mixer.play("jump", volume=0.4)     # per-play override
mixer.set_master_volume(0.8)       # effective = master x load x override
mixer.stop_music(); mixer.stop_all()
mixer.backend_name                 # which tier won

i2c hardware

For magmacrunch's Raspberry Pi cabinets. Requires the [hardware] extra (smbus2) and real hardware; on any other machine the classes import fine and simply report nothing connected, which is what lets CompositeInput fall back to the keyboard.

• I2CBus, a thin smbus2 wrapper. probe(addr) checks one address; backend= injects a simulator.
• MagmaHub, the controller hub on the bus. scan_buses() probes only the four candidate addresses; stats reports poll counts and latency.
• ControllerState, one controller's raw button state.
• HubPoller, polls a hub on a daemon thread and duck-types its read surface, so poll() never blocks a frame on a loose wire.

hardware dev kit

You should not need the hardware to build for the hardware. SimBus implements the smbus2 surface that I2CBus calls, so injecting it runs the real stack, protocol handshake, hub, ControllerState parsing, input adapters, against imaginary controllers. New in 0.4.0.

from texastoast import simulated_hub
from texastoast.i2c.protocol import BTN_A

hub, sim = simulated_hub()      # a real MagmaHub over a simulated bus
sim.press(BTN_A)
hub.poll()[0].a                 # True — no wires involved

sim.fail_next_reads(3)          # a loose wire, on demand
sim.set_read_delay(0.05)        # a slow bus
sim.disconnect_hub(0x08)        # a hotplug
sim.reconnect_hub(0x08)

The simulator is deliberately strict about the protocol: a block read with no preceding select-write raises, exactly as the Pico firmware refuses it. A lenient fake would keep passing even if the engine stopped sending the handshake.

texastoast-bench

A console script installed with the package, live per-controller button state, raw protocol bytes, connection status, poll latency and read-error rates.

texastoast-bench            # scan for hubs; simulator mode if none answer
texastoast-bench --sim      # force the simulator (keyboard drives controller 0)
texastoast-bench --record session.ttrec

magmascript binding

Installing texastoast alongside magmascript 3.2+ registers the engine as the texastoast domain, aliased tt. Neither package depends on the other; discovery is through an entry point.

g = tt.game({"title": "hello from magmascript", "width": 400, "height": 300, "fps": 30})
r = tt.renderer(g, 400, 300)
kb = tt.keyboard(g)
world = tt.tilemap([[1,1,1,1,1],[1,0,0,0,1],[1,1,1,1,1]], 20, [1])
player = tt.entity({"x": 40, "y": 30, "width": 14, "height": 14, "speed": 100})

update = fn(dt) {
    s = kb.poll()
    player.move(s.dx, s.dy, dt, world)
    if s.a { player.speed = 220 } else { player.speed = 100 }
    r.camera.follow(player.center_x, player.center_y, world.width, world.height, dt)
}