tools.compose_gameboard module

GameGirl Color – Pillow-based gameboard compositor.

Layers character sprites, enemies, and items onto scene backgrounds at specified coordinates with z-ordering. # 🎮💀 CORRUPTED CANVAS ENGINE

async tools.compose_gameboard.run(background, sprites=None, width=1024, height=576, ctx=None)[source]

Compose a gameboard by layering sprites over a background and post it.

Entry point for the compose_gameboard tool. It looks up the active game session for the current channel (via game_session.get_session) to scope asset resolution, resolves and downloads the background and each sprite (_resolve_asset_url() then _download_image()), sorts the sprites by z_order so higher layers land on top, runs the Pillow compositing off-thread with _compose_gameboard_sync(), and then uploads the resulting WEBP to the channel through ctx.adapter.send_file, also appending it to ctx.sent_files so the inference layer tracks the attachment. Missing assets are skipped rather than failing the whole board.

Dispatched by tool_loader.py as the compose_gameboard handler (located via getattr(module, "run")); not called directly elsewhere. Side effects include the asset HTTP downloads, the Redis-backed asset/session lookups, and the outbound file send to the channel.

Parameters:

  • background (str) – Background asset name or image URL.

  • sprites (list[dict[str, Any]] | None) – Sprite placements, each with name plus x/y and optional scale and z_order.

  • width (int) – Output canvas width in pixels.

  • height (int) – Output canvas height in pixels.

  • ctx (ToolContext | None) – Tool execution context supplying channel_id, redis, adapter, and sent_files.

Returns:

A JSON object with success and board metadata (and file_url when the upload returned one), or an {"error": ...} object on a missing context, a failed background download, or a compositing/send failure.

Return type:

str