Developer documentation

Layers and canvas tools

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

`add_layer`Add a layer

Adds an empty image layer (to draw on), a group (to hold layers), or a linked layer showing another SpriteGrid document (kind "linked" with path: it can't be drawn on, and shows the file as saved, animation and all). Say where with one of above, below or inside; with none, it goes above the selected layer. Returns its id.

Parameters

namestring: Its name. Leave it out for "Layer N", "Group N" or the linked file's name.
kindstring: "image" (the default), "group" or "linked".
pathstring: For kind "linked": the .spritegrid file to link, as a full path. It can't be this document or one that contains it.
abovestring: Put it just above this layer (id or exact name).
belowstring: Put it just below this layer.
insidestring: Put it at the top of this group.
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.

`update_layer`Change a layer

Changes a layer's name, visibility, opacity, blend mode, lock or pivot (the point its rotation and scale keys turn and scale it around) — any of them, in one undo step. What you leave out stays as it is.

Parameters

layerstring

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

namestring

A new name.

visibleboolean

True to show it, false to hide it.

opacitynumber

0 (invisible) to 1 (opaque).

blendModestring

Normal, Multiply, Screen, Overlay, Add, Subtract, Darken, Lighten... (describe_document shows the current one; a wrong name lists them all).

lockedboolean

True to lock it (it can't be drawn on), false to unlock it.

pivotobject

The point it turns and scales around, in document pixels: { "x": 64, "y": 64 } is the middle of a 128×128 canvas, where it starts. Put it at a wheel's middle to spin the wheel with rotation keys. Whole numbers are between pixels; add 0.5 for a pixel's middle.

2 fields

xnumberrequired: Pixels from the left edge: whole numbers are between pixels, add 0.5 for a pixel's middle.
ynumberrequired: Pixels from the top edge, the same way.

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.

`move_layer`Move a layer

Moves a layer (a group with everything in it) above or below another, or to the top of a group. Give exactly one of above, below or inside.

Parameters

layerstring: Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.
abovestring: Just above this layer.
belowstring: Just below this layer.
insidestring: At the top of this group.
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.

`duplicate_layer`Duplicate a layer

Copies a layer (a group with everything in it), just above it, and selects the copy. Returns the copy's id.

Parameters

layerstring: Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.
namestring: The copy's name. Leave it out for "<name> Copy".
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.

`delete_layer`Delete a layerdeletes

Deletes a layer (a group with everything in it). Undo brings it back.

Parameters

layerstring: Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.
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.

`resize_canvas`Resize the canvas

Changes the canvas size without scaling the art: growing adds transparent pixels, shrinking crops. The anchor says where the art stays.

Parameters

widthintegerrequired: The new width, 1 to 4096.
heightintegerrequired: The new height, 1 to 4096.
anchorstring: Where the art stays: top-left (the default), top, top-right, left, center, right, bottom-left, bottom or bottom-right.
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.

`set_palette`Change the palette

Changes the document's palette, in this order: replace swaps in a whole new list of colors, remove takes colors out, add puts colors in the first empty cells (a color already there isn't added again).

Parameters

replacelist of strings: The palette's new colors, in order.
addlist of strings: Colors to add.
removelist of strings: Colors to take out.
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.

add_layerAdd a layer

Parameters

update_layerChange a layer

Parameters

move_layerMove a layer

Parameters

duplicate_layerDuplicate a layer

Parameters

delete_layerDelete a layerdeletes

Parameters

resize_canvasResize the canvas

Parameters

set_paletteChange the palette

Parameters

`add_layer`Add a layer

`update_layer`Change a layer

`move_layer`Move a layer

`duplicate_layer`Duplicate a layer

`delete_layer`Delete a layerdeletes

`resize_canvas`Resize the canvas

`set_palette`Change the palette