factoriax.playground.play.game_ui

Reusable game UI: menus, hotbar, click regions, and event dispatch.

Extracted from factoriax.playground.play.main so that both the play loop and the debugger can share the same input handling and menu rendering without duplicating code. GameUI owns a PlayState internally and translates pygame events into GameUIResult values that the caller can act on.

GameUI does NOT step the environment, manage the pygame window, or handle recording. Those responsibilities remain with the caller.

class factoriax.playground.play.game_ui.GameUI(params: EnvParams, kb_lookup: dict[tuple[int, int], frozenset[str]], *, ctrl_lookup: dict[str, frozenset[str]] | None = None, welcome_open: bool = True)

Reusable game UI component for menus, hotbar, and input dispatch.

Owns a PlayState internally. Callers feed it pygame events and the current EnvState. It returns rendered overlays and action intents via GameUIResult.

Parameters:

• kb_lookup – Key lookup table from

• welcome_open – Whether to show the welcome screen initially

handle_event(event: Event, state: EnvState) → GameUIResult

Process a single pygame event and return the result.

The caller is responsible for acting on the result: stepping the environment if result.action is set, resetting if result.reset is True, and quitting if result.quit is True.

Parameters:

• event – Pygame event to process.

• state – Current environment state.

has_menu_open() → bool

Report whether any menu or overlay is open.

property play_state: PlayState

Access the internal PlayState for reading UI flags.

render_frame(state: EnvState, ui_w: int, ui_h: int, tile_px: int, world_ox: int, world_oy: int, achievements: Array | None = None) → tuple[ndarray, list[ClickRegion]]

Draw one frame, with every open overlay.

The function draws the world first, and then each open menu over it.

Parameters:

• state – Current environment state.

• ui_w – UI canvas width.

• ui_h – UI canvas height.

• tile_px – Tile pixel size.

• world_ox – World X offset within canvas.

• world_oy – World Y offset within canvas.

• achievements – Achievement flags from the wrapper state. Required when the achievement menu is open.

set_window_transform(win_ox: int, win_oy: int, win_scale: int) → None

Update the window-to-canvas coordinate transform.

Parameters:

• win_ox – Window X offset of the canvas origin.

• win_oy – Window Y offset of the canvas origin.

• win_scale – Integer scale factor from canvas to window pixels.

update_hover(state: EnvState) → None

Update the tile highlight to the tile the player faces.

Call once per frame after event processing.

Parameters:

state – Current environment state.

class factoriax.playground.play.game_ui.GameUIResult(action: int | None = None, state: EnvState | None = None, quit: bool = False, reset: bool = False)

Result of processing a single pygame event through GameUI.