Create a new blank pixel-art canvas (a single tile/sprite surface).

Args: params: canvas_id, width, height, background RGBA. Returns: JSON string confirming creation with canvas_id, width, height.

Load an existing PNG (or other image) file from disk into a new canvas.

Use this to continue editing a sprite that already exists (e.g. a tile already in the user's Unity project) instead of redrawing it from a blank canvas.

Args: params: canvas_id (new id to store it under), file_path (local path to the image). Returns: JSON string: {"canvas_id", "width", "height"}.

Set a single pixel's color on a canvas.

Args: params: canvas_id, x, y, RGBA color. Returns: Confirmation string.

Draw a straight line on a canvas between two points.

Args: params: canvas_id, x0, y0, x1, y1, color, line_width. Returns: Confirmation string.

Draw a rectangle (outline or filled) on a canvas.

Args: params: canvas_id, x0, y0, x1, y1, color, fill. Returns: Confirmation string.

Draw a circle/ellipse (outline or filled) on a canvas.

Args: params: canvas_id, center_x, center_y, radius, color, fill. Returns: Confirmation string.

Flood-fill the contiguous region containing (x, y) with a color.

Args: params: canvas_id, x, y, color. Returns: Confirmation string.

Draw a polygon (outline or filled) from a list of vertex points.

Use this for shapes that draw_rect/draw_circle can't express (roof slopes, tree silhouettes, diagonal terrain edges, etc).

Args: params: canvas_id, points (>=3 [x,y] pairs), color, fill. Returns: Confirmation string.

Erase all drawing on a canvas back to a flat background color.

Args: params: canvas_id, background RGBA (default fully transparent). Returns: Confirmation string.

Mirror a canvas horizontally or vertically in place.

Common for pixel-art symmetry: draw one half of a character/object and flip instead of hand-drawing the mirrored half.

Args: params: canvas_id, direction ('horizontal' or 'vertical'). Returns: Confirmation string.

Copy an existing canvas into a new canvas id.

Useful for repeated/near-identical tiles (grass variants, floor tiles) without redrawing from scratch.

Args: params: source_canvas_id, new_canvas_id. Returns: Confirmation string.

Get lightweight metadata about a canvas without rendering a preview image.

Cheaper than pixelart_get_canvas_preview when the agent only needs to check dimensions or whether anything has been drawn yet.

Args: params: canvas_id. Returns: JSON string: {"width", "height", "non_transparent_pixels", "total_pixels"}.

Remove a canvas from memory once it's no longer needed.

Args: params: canvas_id. Returns: Confirmation string.

List every canvas currently held in memory for this server session.

Use this to recover canvas_id/size context in a long session instead of relying on conversation memory of what was created earlier.

Returns: JSON string: {"canvases": [{"canvas_id", "width", "height"}, ...]}.

Return the current canvas as an upscaled PNG image for visual inspection.

Args: params: canvas_id, scale (nearest-neighbor upscale factor). Returns: Image: PNG preview, upscaled by scale so small pixel art is visible.

Extract the dominant colors currently used on a canvas.

Args: params: canvas_id, n_colors. Returns: JSON string: {"colors": ["#rrggbb", ...]}.

Suggest an ideal size in pixels for ONE tile -- NOT a full tilemap/level image.

Uses a 16-pixel-per-unit (PPU) base-grid convention by default. If category is given (small_prop, character, large_character, structure, large_structure) it takes priority. Otherwise, if a target screen resolution is given, picks a PPU that divides the screen evenly. Falls back to a 16x16 default.

IMPORTANT: the result is one tile's size. A playable tilemap/level is a grid of MANY tiles at this size, not a single canvas this size -- call pixelart_suggest_tilemap_layout next to work out the grid, then pixelart_create_tileset to build it. Never export a single tile-sized canvas as if it were the whole tilemap.

Args: params: category, screen_width, screen_height (all optional). Returns: JSON string: {"tile_width", "tile_height", "ppu", "reasoning", "note"}.

Work out the grid (columns x rows) and total pixel size for a FULL tilemap.

Use this whenever the user wants an actual level/map, not a single tile or asset. Call pixelart_suggest_tile_size first to get tile_width/tile_height, then this tool with either an explicit columns+rows or a target screen/level size in pixels. Build the result with pixelart_create_tileset using the returned columns/rows, filling every slot via pixelart_set_tile -- a tilemap is never a single small canvas.

Args: params: tile_width, tile_height, and either (columns, rows) or (screen_width, screen_height). Returns: JSON string: {"tile_width", "tile_height", "columns", "rows", "total_tiles", "total_map_width_px", "total_map_height_px", "reasoning"}.

Generate a limited, cohesive color palette for pixel art.

Args: params: n_colors, style (forest/desert/ocean/retro/pastel/night/lava/candy, optional). Returns: JSON string: {"colors": ["#rrggbb", ...]}.

Create a blank tileset sheet (grid of equally-sized tile slots).

Args: params: tileset_id, tile_width, tile_height, columns, rows, ppu. Returns: JSON string confirming the grid dimensions.

Place a drawn canvas into a tileset slot.

Args: params: tileset_id, index (row-major slot), canvas_id. Returns: Confirmation string.

Export a tileset to a PNG file plus a JSON metadata sidecar.

The metadata (tile size, grid, PPU, filled slots, palette) is meant to be handed to a downstream engine-integration tool (e.g. an agent calling unity-mcp-server) so it can slice/import the sheet without re-deriving those values.

Args: params: tileset_id, output_dir, name, palette (optional hex list to record). Returns: JSON string: {"png_path", "json_path", "metadata": {...}}.

Remove a tileset from memory once it's no longer needed.

Args: params: tileset_id. Returns: Confirmation string.

List every tileset currently held in memory for this server session.

Returns: JSON string: {"tilesets": [{"tileset_id", "columns", "rows", "tile_width", "tile_height", "filled_tiles"}, ...]}.