SpriteGrid

Developer documentation

How it works

The tools run inside the SpriteGrid you have open, on the documents you see. Nothing works on a copy.

The path of a call#

  1. The assistant's app starts SpriteGrid.Mcp and talks MCP to it over stdio.
  2. SpriteGrid.Mcp is a relay: it passes the bytes to SpriteGrid over a named pipe that only your user on this computer can open, and checks that it's SpriteGrid on the other end. If SpriteGrid isn't running, it starts it.
  3. SpriteGrid runs the MCP server. Each call waits for the app's next frame and runs there, like a click would, so it sees exactly what you see and the canvas shows the change at once.

One change, one undo step#

Everything a call changes is one step in the undo history, labeled "AI: ..." (like "AI: draw pixels on Outline"). An assistant can join its own newest steps into one with combine_steps, so a whole piece of work undoes at once.

Several assistants#

More than one assistant can work at once, each in documents of its own. Changing a document locks it to that assistant; another's changes to it are refused with document_in_use, though anyone can look at it. A lock ends when the assistant calls release_document, disconnects, or makes no call for 20 seconds.

When a call can't be done#

It changes nothing, and says why. The message starts with a code, like layer_locked: "Outline" is locked. Unlock it with update_layer (locked: false) first., so an assistant can tell what went wrong and try again. Error codes lists them all.

What the server tells assistants#

Every assistant gets these conventions when it connects. They hold for all 63 tools.

SpriteGrid is a pixel-art editor, and these tools work on the documents open in it, live: the user sees each change as you make it.

Conventions: coordinates are document pixels, x to the right and y down from the top-left corner; a rectangle is {x, y, width, height}. Colors are "#RRGGBB", "#RRGGBBAA" or "transparent", and set pixels exactly (no blending). Animation frames count from 0. A document is named by the id get_status gives it ("doc-1"), its path or its name; a layer by its id or exact name. Leave the document out for the one you're working on (the one you last changed, made, opened or showed; before that, the one shown in SpriteGrid), and the layer out for the one selected in it.

Every change is one undo step the user can take back (it shows as "AI: ..." in their history). A change that can't be done changes nothing and says why, starting with a code like out_of_bounds.

Several assistants can work in SpriteGrid at once, each in documents of its own. Changing a document locks it to you (so does making or opening one): the user sees you're working on it and can't change it meanwhile, and other assistants' changes to it are refused (document_in_use), so work in another document, or make one with new_document. Anyone can look at any document; get_status says who's working on which. When you've finished with a document, release_document unlocks it; it also unlocks when you disconnect or after 20 seconds without a call from you. If the user takes a document over from you, you can't change it again (document_taken_over).

Start with get_status and describe_document. Draw with draw_pixels (a grid of characters with a legend is the most reliable way to place pixels: write a long run of one character as "R{20}", and give width to have every row's length checked), draw_shape, fill and copy_pixels, and check your work with render_preview. Art made elsewhere, like by a script you wrote, goes in whole with draw_image, from its file. Changes wait while the user is drawing: if you get user_busy, try again shortly. Pass expectedRevision (from describe_document) so you don't draw over something the user just did. When a piece of work is done, combine_steps joins its steps into one undo step for the user. Words go in with add_text: live text in exact pixels, in SpriteGrid's pixel fonts (list_fonts) or the user's, that stays editable (update_text); scale makes a pixel font bigger, crisp.

Animation: set_animation makes one. The drawing tools draw on the frame shown, or on the frame you give them (frame) without changing what's shown. An image layer's frames share one drawing until set_cel gives a frame its own; a frame without one shows the drawing before it, and drawing there is refused (frame_held). repeat_cels repeats a cycle of drawings over the rest of the animation. set_keyframe moves, turns, scales, fades or hides a layer over time, or animates an effect setting, a key or a list of keys at a time; a layer turns and scales around its pivot (update_layer). See it with render_frames. Effects (list_effects, add_effect) draw outlines, shadows, glows and color changes live on a layer; render_preview shows them. Tiles (add_tile) are canvas-sized layer groups placed on a grid of cells for tilemaps: draw on a tile's draw layer, place tiles with set_tiles (a map of characters, like describe_atlas gives) and see the map with render_atlas.

Slices (add_slice) mark sprites for export in a slice sheet (export_slice_sheet). A slice can have a pivot (where a game turns and places the sprite) and named points (where it attaches things, like "grip"): metadata in the sheet's .json, never pixels. Unlike other coordinates they're measured from the slice's top-left corner, in whole or half pixels: (0, 0) is the corner, (0.5, 0.5) the middle of its first pixel, { "x": 3, "y": 24 } the bottom middle of a 6×24 slice. They may lie outside the slice. update_slice leaves out what you don't give; removePivot and removePoints take them away.

Generating: if the user connected a Retro Diffusion account in SpriteGrid, generate draws pixel art from a prompt into an area on a new layer, animate_layer brings a layer's drawing to life, and remove_background clears a layer's background. Each costs a few cents of the user's credit (generation_price says how much, free); list_generation_styles lists the styles.

Tools has every tool, by what it does.