Developer documentation

Drawing tools

7 tools. Every change a tool makes is one undo step in SpriteGrid.

`draw_pixels`Draw pixels

Sets pixels exactly, from a grid of characters (best for sprites: rows of text, each character a color from the legend) or a list of single pixels, or both. In the legend, "keep" leaves a pixel as it is and "transparent" clears it. In a row, a character followed by {n} is n of it ("R{20}"), and width has every row's length checked. Every pixel set must be on the canvas. One undo step; nothing changes if anything is wrong. For big art made elsewhere (by a script), draw_image takes the image file instead.

Parameters

documentstring

Which document: its id from get_status (like "doc-1"), its path, or its name. Leave it out for the one you're working on, or the one shown in SpriteGrid before you've worked on one.

layerstring

Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.

gridobject

The pixels as text. Example: { "origin": {"x": 4, "y": 2}, "legend": {".": "keep", "o": "#282a36", "f": "#bd93f9"}, "rows": [".o{2}.", "of{2}o", ".o{2}."], "width": 4 }.

4 fields

originobject

Where the first character of the first row goes, in document pixels.

2 fields

xintegerrequired: Pixels from the left edge.
yintegerrequired: Pixels from the top edge.

legendmap of strings

What each character stands for: a color ("#RRGGBB" or "#RRGGBBAA"), "transparent" (clears the pixel) or "keep" (leaves it as it is). Every character used in the rows needs an entry; { and } can't be one (they write runs). Example: { ".": "keep", "o": "#282a36", "f": "#bd93f9" }.

rowslist of strings

The rows, top to bottom, one character per pixel. A character followed by {n} stands for n of it: "R{12}.{3}o" is 12 R's, 3 dots and an o. Write long runs that way: they're easy to miscount spelled out. Rows can differ in length unless width is given.

widthinteger

How many pixels wide every row is, to have it checked: a row that comes out longer or shorter (runs counted) is refused, instead of its pixels landing in the wrong places. Leave it out to let rows differ.

pixelslist of objects

Single pixels: [{ "x": 0, "y": 0, "color": "#ff0000" }].

3 fields

xintegerrequired: Pixels from the left edge.
yintegerrequired: Pixels from the top edge.
colorstringrequired: "#RRGGBB", "#RRGGBBAA" or "transparent".

frameinteger

Draw on this animation frame (from 0), whichever one SpriteGrid shows: the view stays where it is. Leave it out for the frame shown.

expectedRevisioninteger

The document's revision when you looked at it: if the document has changed since (the user edited it, say), nothing is done and you're told so.

Returns

documentstringrequired

The document's id.

revisionintegerrequired

Its revision after the change.

summarystringrequired

What changed, in a line.

layerstring

The layer changed or made, if there was one.

changedobject

The rectangle of pixels that changed, if any did.

4 fields

xintegerrequired: Left edge, in pixels from the left of the canvas.
yintegerrequired: Top edge, in pixels from the top of the canvas.
widthintegerrequired: Width in pixels.
heightintegerrequired: Height in pixels.

pixelsChangedinteger

How many pixels changed.

slicestring

The slice changed or made, if there was one.

effectstring

The effect changed or added, if there was one.

tilestring

The tile changed or made, if there was one.

`draw_image`Draw an image

Draws an image (PNG, JPG, BMP, GIF...) onto an image layer, its top-left corner at origin: every pixel set exactly as the image has it, see-through ones clearing the layer's unless skipTransparent. Give the image one way: a file (path), an https link (url, like a picture another tool made and hosts) or its bytes as base64 (data). With area, just that part of the image (one frame of a sprite sheet, say). What falls off the canvas is left out. The way to bring in art made elsewhere, like by a script you wrote, without spelling it out as text. One undo step.

Parameters

pathstring

The image file's full path.

urlstring

An https link to the image, downloaded first (at most 20 MB).

datastring

The image file's bytes as base64 (a "data:image/png;base64," prefix is fine).

originobject

Where the image's top-left corner goes. Leave it out for (0, 0).

2 fields

xintegerrequired: Pixels from the left edge.
yintegerrequired: Pixels from the top edge.

areaobject

Just this part of the image, in the image's own pixels. Leave it out for all of it.

4 fields

xintegerrequired: Left edge, in pixels from the left of the canvas.
yintegerrequired: Top edge, in pixels from the top of the canvas.
widthintegerrequired: Width in pixels.
heightintegerrequired: Height in pixels.

skipTransparentboolean

True to leave the layer's pixels alone where the image is see-through.

frameinteger

Draw on this animation frame (from 0), whichever one SpriteGrid shows: the view stays where it is. Leave it out for the frame shown.

documentstring

Which document: its id from get_status (like "doc-1"), its path, or its name. Leave it out for the one you're working on, or the one shown in SpriteGrid before you've worked on one.

layerstring

Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.

expectedRevisioninteger

The document's revision when you looked at it: if the document has changed since (the user edited it, say), nothing is done and you're told so.

Returns

documentstringrequired

The document's id.

revisionintegerrequired

Its revision after the change.

summarystringrequired

What changed, in a line.

layerstring

The layer changed or made, if there was one.

changedobject

The rectangle of pixels that changed, if any did.

4 fields

xintegerrequired: Left edge, in pixels from the left of the canvas.
yintegerrequired: Top edge, in pixels from the top of the canvas.
widthintegerrequired: Width in pixels.
heightintegerrequired: Height in pixels.

pixelsChangedinteger

How many pixels changed.

slicestring

The slice changed or made, if there was one.

effectstring

The effect changed or added, if there was one.

tilestring

The tile changed or made, if there was one.

`draw_shape`Draw a shape

A one-pixel line between two points, or the rectangle or ellipse with them as opposite corners (both included), outlined or filled. Whole pixels, no anti-aliasing. What falls off the canvas is left out.

Parameters

shapestringrequired

"line", "rectangle" or "ellipse".

fromobjectrequired

One end, or one corner.

2 fields

xintegerrequired: Pixels from the left edge.
yintegerrequired: Pixels from the top edge.

toobjectrequired

The other end, or the opposite corner.

2 fields

xintegerrequired: Pixels from the left edge.
yintegerrequired: Pixels from the top edge.

colorstringrequired

"#RRGGBB", "#RRGGBBAA" or "transparent".

filledboolean

True to fill a rectangle or ellipse, false for just its outline.

frameinteger

Draw on this animation frame (from 0), whichever one SpriteGrid shows: the view stays where it is. Leave it out for the frame shown.

documentstring

Which document: its id from get_status (like "doc-1"), its path, or its name. Leave it out for the one you're working on, or the one shown in SpriteGrid before you've worked on one.

layerstring

Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.

expectedRevisioninteger

The document's revision when you looked at it: if the document has changed since (the user edited it, say), nothing is done and you're told so.

Returns

documentstringrequired

The document's id.

revisionintegerrequired

Its revision after the change.

summarystringrequired

What changed, in a line.

layerstring

The layer changed or made, if there was one.

changedobject

The rectangle of pixels that changed, if any did.

4 fields

xintegerrequired: Left edge, in pixels from the left of the canvas.
yintegerrequired: Top edge, in pixels from the top of the canvas.
widthintegerrequired: Width in pixels.
heightintegerrequired: Height in pixels.

pixelsChangedinteger

How many pixels changed.

slicestring

The slice changed or made, if there was one.

effectstring

The effect changed or added, if there was one.

tilestring

The tile changed or made, if there was one.

`fill`Bucket fill

A bucket fill: starting at a point, the pixels of that color (within the tolerance) become the new color — only those joined to it (left, right, up, down), or every one on the layer if contiguous is false.

Parameters

atobjectrequired

Where to start.

2 fields

xintegerrequired: Pixels from the left edge.
yintegerrequired: Pixels from the top edge.

colorstringrequired

"#RRGGBB", "#RRGGBBAA" or "transparent".

contiguousboolean

True (the default) to fill only pixels joined to the start; false for every matching pixel on the layer.

toleranceinteger

How different a pixel can be and still count as the same color: 0 (exactly) to 255 (anything), on each channel.

frameinteger

Draw on this animation frame (from 0), whichever one SpriteGrid shows: the view stays where it is. Leave it out for the frame shown.

documentstring

Which document: its id from get_status (like "doc-1"), its path, or its name. Leave it out for the one you're working on, or the one shown in SpriteGrid before you've worked on one.

layerstring

Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.

expectedRevisioninteger

The document's revision when you looked at it: if the document has changed since (the user edited it, say), nothing is done and you're told so.

Returns

documentstringrequired

The document's id.

revisionintegerrequired

Its revision after the change.

summarystringrequired

What changed, in a line.

layerstring

The layer changed or made, if there was one.

changedobject

The rectangle of pixels that changed, if any did.

4 fields

xintegerrequired: Left edge, in pixels from the left of the canvas.
yintegerrequired: Top edge, in pixels from the top of the canvas.
widthintegerrequired: Width in pixels.
heightintegerrequired: Height in pixels.

pixelsChangedinteger

How many pixels changed.

slicestring

The slice changed or made, if there was one.

effectstring

The effect changed or added, if there was one.

tilestring

The tile changed or made, if there was one.

`replace_color`Replace a color

Every pixel of one exact color becomes another, on one layer, in a region or all of it. Good for recoloring a sprite.

Parameters

fromstringrequired

The color to replace: "#RRGGBB", "#RRGGBBAA" or "transparent".

tostringrequired

What it becomes: "#RRGGBB", "#RRGGBBAA" or "transparent".

areaobject

Only in this region. Leave it out for the whole layer.

4 fields

xintegerrequired: Left edge, in pixels from the left of the canvas.
yintegerrequired: Top edge, in pixels from the top of the canvas.
widthintegerrequired: Width in pixels.
heightintegerrequired: Height in pixels.

frameinteger

Draw on this animation frame (from 0), whichever one SpriteGrid shows: the view stays where it is. Leave it out for the frame shown.

documentstring

Which document: its id from get_status (like "doc-1"), its path, or its name. Leave it out for the one you're working on, or the one shown in SpriteGrid before you've worked on one.

layerstring

Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.

expectedRevisioninteger

The document's revision when you looked at it: if the document has changed since (the user edited it, say), nothing is done and you're told so.

Returns

documentstringrequired

The document's id.

revisionintegerrequired

Its revision after the change.

summarystringrequired

What changed, in a line.

layerstring

The layer changed or made, if there was one.

changedobject

The rectangle of pixels that changed, if any did.

4 fields

xintegerrequired: Left edge, in pixels from the left of the canvas.
yintegerrequired: Top edge, in pixels from the top of the canvas.
widthintegerrequired: Width in pixels.
heightintegerrequired: Height in pixels.

pixelsChangedinteger

How many pixels changed.

slicestring

The slice changed or made, if there was one.

effectstring

The effect changed or added, if there was one.

tilestring

The tile changed or made, if there was one.

`clear_pixels`Clear pixels

Makes a region of a layer transparent, or all of it.

Parameters

areaobject

The region to clear. Leave it out to clear the whole layer.

4 fields

xintegerrequired: Left edge, in pixels from the left of the canvas.
yintegerrequired: Top edge, in pixels from the top of the canvas.
widthintegerrequired: Width in pixels.
heightintegerrequired: Height in pixels.

frameinteger

Draw on this animation frame (from 0), whichever one SpriteGrid shows: the view stays where it is. Leave it out for the frame shown.

documentstring

Which document: its id from get_status (like "doc-1"), its path, or its name. Leave it out for the one you're working on, or the one shown in SpriteGrid before you've worked on one.

layerstring

Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.

expectedRevisioninteger

The document's revision when you looked at it: if the document has changed since (the user edited it, say), nothing is done and you're told so.

Returns

documentstringrequired

The document's id.

revisionintegerrequired

Its revision after the change.

summarystringrequired

What changed, in a line.

layerstring

The layer changed or made, if there was one.

changedobject

The rectangle of pixels that changed, if any did.

4 fields

xintegerrequired: Left edge, in pixels from the left of the canvas.
yintegerrequired: Top edge, in pixels from the top of the canvas.
widthintegerrequired: Width in pixels.
heightintegerrequired: Height in pixels.

pixelsChangedinteger

How many pixels changed.

slicestring

The slice changed or made, if there was one.

effectstring

The effect changed or added, if there was one.

tilestring

The tile changed or made, if there was one.

`copy_pixels`Copy pixels

Copies a region to another place, on the same layer or another, turned and mirrored if asked: draw one corner of a frame, then copy it to the other three flipped. Turning happens before mirroring.

Parameters

areaobjectrequired

The region to copy.

4 fields

xintegerrequired: Left edge, in pixels from the left of the canvas.
yintegerrequired: Top edge, in pixels from the top of the canvas.
widthintegerrequired: Width in pixels.
heightintegerrequired: Height in pixels.

toobjectrequired

Where the copy's top-left corner goes.

2 fields

xintegerrequired: Pixels from the left edge.
yintegerrequired: Pixels from the top edge.

fromLayerstring

The layer to copy from (id or exact name). Leave it out for the selected layer.

toLayerstring

The layer to copy to. Leave it out for the same layer.

rotateinteger

Degrees clockwise: 0, 90, 180 or 270.

flipHorizontalboolean

True to mirror it left to right.

flipVerticalboolean

True to mirror it top to bottom.

skipTransparentboolean

True to leave the destination alone where the copy is transparent.

frameinteger

Draw on this animation frame (from 0), whichever one SpriteGrid shows: the view stays where it is. Leave it out for the frame shown.

fromFrameinteger

Copy what the source layer shows on this frame. Leave it out for the frame drawn on.

documentstring

Which document: its id from get_status (like "doc-1"), its path, or its name. Leave it out for the one you're working on, or the one shown in SpriteGrid before you've worked on one.

expectedRevisioninteger

The document's revision when you looked at it: if the document has changed since (the user edited it, say), nothing is done and you're told so.

Returns

documentstringrequired

The document's id.

revisionintegerrequired

Its revision after the change.

summarystringrequired

What changed, in a line.

layerstring

The layer changed or made, if there was one.

changedobject

The rectangle of pixels that changed, if any did.

4 fields

xintegerrequired: Left edge, in pixels from the left of the canvas.
yintegerrequired: Top edge, in pixels from the top of the canvas.
widthintegerrequired: Width in pixels.
heightintegerrequired: Height in pixels.

pixelsChangedinteger

How many pixels changed.

slicestring

The slice changed or made, if there was one.

effectstring

The effect changed or added, if there was one.

tilestring

The tile changed or made, if there was one.

draw_pixelsDraw pixels

Parameters

draw_imageDraw an image

Parameters

draw_shapeDraw a shape

Parameters

fillBucket fill

Parameters

replace_colorReplace a color

Parameters

clear_pixelsClear pixels

Parameters

copy_pixelsCopy pixels

Parameters

`draw_pixels`Draw pixels

`draw_image`Draw an image

`draw_shape`Draw a shape

`fill`Bucket fill

`replace_color`Replace a color

`clear_pixels`Clear pixels

`copy_pixels`Copy pixels