SpriteGrid

Developer documentation

Looking tools

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

get_statusSpriteGrid statuslooks only

What's open in SpriteGrid: each document's id, name, size, whether it has unsaved changes, its revision and who's working on it; which is shown and which you're working on; the colors and tool; and whether the user is busy (changes wait for them). Start here.

Parameters

Nothing.

Returns
appVersionstringrequired
apiVersionintegerrequired

Goes up when the tools change in a way that could break a caller.

documentslist of objectsrequired
9 fields
idstringrequired

Its id for this session, like "doc-1". Pass it as `document`.

namestringrequired
pathstringrequired

Where it's saved, or null if it never was.

widthintegerrequired
heightintegerrequired
unsavedChangesbooleanrequired

True if it has changes that aren't saved.

revisionintegerrequired

Changes whenever the document does, the user's edits too. Pass it as `expectedRevision` to refuse a change if the document moved on.

activebooleanrequired

True for the document shown in SpriteGrid.

lockedBystring

Who's working on it, if anyone: "you" (it's locked to you), another assistant's name (its changes are refused for you until they're done), or "the user" if they took it over from you (you can't change it again). Null if no one is: changing it locks it to you.

activeDocumentstringrequired

The id of the document shown in SpriteGrid, or null.

workingOnstringrequired

The id of the document you're working on (the one you last changed, made, opened or showed): tools use it when document is left out. Null before you've worked on one: they use the one shown.

foregroundColorstringrequired
backgroundColorstringrequired
activeToolstringrequired
userBusybooleanrequired

True while the user is drawing or dragging: changes wait for them.

dialogOpenbooleanrequired

True while SpriteGrid shows a dialog: changes are refused until it's closed.

describe_documentDescribe a documentlooks only

A document's size, revision, layer tree (top layer first: id, name, type, visibility, opacity, blend mode, lock, where its pixels are), palette, slices with their nine-slice guides, pivots and named points, animation and selection. Look before you change things: the ids it gives are what the other tools take.

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.

Returns
idstringrequired
namestringrequired
pathstringrequired
widthintegerrequired
heightintegerrequired
revisionintegerrequired
unsavedChangesbooleanrequired
activeLayerstringrequired

The id of the layer selected in SpriteGrid, used when a tool's `layer` is left out.

layerslist of objectsrequired

The layer tree, top layer first, as the Layers panel shows it.

16 fields
idstringrequired

The layer's id. Pass it (or the exact name) as `layer`.

namestringrequired
typestringrequired

image, group, fill, text, adjustment, 3d, linked, atlas-group or atlas-instance. Only image layers can be drawn on.

visiblebooleanrequired
opacitynumberrequired

0 to 1.

blendModestringrequired
lockedbooleanrequired
contentBoundsobjectrequired

The smallest rectangle holding its non-transparent pixels (image layers), or null if it's empty.

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.

hasMaskbooleanrequired
effectslist of objectsrequired

Its effects, in the order they're applied, or null if it has none.

6 fields
idstringrequired

This effect's id on the layer. Pass it as `effect` to update_effect or remove_effect.

effectstringrequired

Which effect it is, like "outline" (list_effects has them all).

namestringrequired
enabledbooleanrequired

False if it's turned off.

settingsobjectrequired

Its settings by id: numbers, true/false, colors, a choice by name, a gradient as points, a palette as colors.

animatedSettingslist of stringsrequired

The settings the animation changes from frame to frame (set their values with set_keyframe), or null.

animatedbooleanrequired

True if its pixels change from frame to frame.

pivotobjectrequired

The point it turns and scales around (rotation, scaleX and scaleY keys), in document pixels, or null at the canvas's middle, where it starts.

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.

childrenlist of anythingrequired

A group's layers, top first.

linkedFilestring

A linked layer's file (another SpriteGrid document it shows), else null.

linkProblemstring

A linked layer's link when it's broken: "missing" (the file isn't there; its last picture shows), "loop" (it contains this document) or "unreadable"; else null.

textobject

A text layer's words and style (change them with update_text), else null.

14 fields
textstringrequired

The words, line breaks as \n.

fontstringrequired

The font it names.

drawnInstringrequired

The font it's drawn in while the one it names isn't there, else null.

sizeintegerrequired

The font's size in pixels.

scaleintegerrequired

How many pixels each of the font's pixels becomes, across and down.

colorstringrequired
alignmentstringrequired

left, center or right.

positionobjectrequired

Its anchor: the top of the first line, and its left edge, middle or right edge by the alignment; in a box, the box's top-left corner.

2 fields
xintegerrequired

Pixels from the left edge.

yintegerrequired

Pixels from the top edge.

boxWidthintegerrequired

The width of the box it wraps in, or null for text that only breaks at its line breaks.

letterSpacingintegerrequired

Extra pixels (of the font's) between letters.

lineSpacingintegerrequired

Extra pixels (of the font's) between lines.

boundsobjectrequired

Where it is on the canvas (before any rotation).

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.

rotationnumber

How far it's turned, in degrees clockwise, or null if it isn't.

turnsAroundobject

The point it turns around, in document pixels (it stays put as the text is typed, and moves with the text), or null if it isn't turned.

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.

palettelist of objectsrequired
3 fields
columnintegerrequired
rowintegerrequired
colorstringrequired
sliceslist of objectsrequired
7 fields
idstringrequired

The slice's id. Pass it (or the exact name) as `slice`.

namestringrequired
areaobjectrequired
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.

nineSliceobjectrequired

The nine-slice guides, or null if it isn't a nine-slice.

4 fields
topintegerrequired

Pixels from the top edge to the top guide.

rightintegerrequired

Pixels from the right edge to the right guide.

bottomintegerrequired

Pixels from the bottom edge to the bottom guide.

leftintegerrequired

Pixels from the left edge to the left guide.

colorstringrequired

The color its outline is drawn in, or null for the default.

pivotobject

Where a game turns and places the sprite, in pixels from the slice's top-left corner, or null for none.

2 fields
xnumberrequired

Pixels from the slice's left edge: whole numbers are between pixels, .5 a pixel's middle. It can be negative, or past the slice's width.

ynumberrequired

Pixels from the slice's top edge, the same way.

pointsmap of objects

Its named points (where a game attaches things), by name, in pixels from the slice's top-left corner; null for none.

2 fields
xnumberrequired

Pixels from the slice's left edge: whole numbers are between pixels, .5 a pixel's middle. It can be negative, or past the slice's width.

ynumberrequired

Pixels from the slice's top edge, the same way.

timelineobjectrequired

The animation, or null if there isn't one.

4 fields
frameCountintegerrequired
frameRateintegerrequired
currentFrameintegerrequired

From 0.

trackCountintegerrequired
selectionobjectrequired

The bounds of the user's selection, or null if nothing is selected.

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.

read_pixelsRead pixelslooks only

A region's exact pixels as text: rows of characters with a legend saying which color each stands for ("." is transparent), at most 64×64 at a time. The result can be edited and passed straight back to draw_pixels. For a look at something bigger, use render_preview.

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. Ignored when composite is true.

areaobject

The region to read. Leave it out for the whole canvas (if it's 64×64 or smaller).

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.

compositeboolean

True to read what the canvas shows (all visible layers together) instead of one layer. Drawn on the CPU: effects and adjustment layers aren't in it.

frameinteger

Which animation frame (from 0). Leave it out for the current one.

Returns
areaobjectrequired

The region read.

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.

formatstringrequired

"grid" (characters and a legend) or "hex" (colors separated by spaces).

legendmap of stringsrequired

What each character stands for, in the grid form.

rowslist of stringsrequired

The rows, top to bottom.

colorCountintegerrequired

How many different colors the region has (fully transparent counts as one).

sourcestringrequired

What was read: a layer's name, or "composite".

notestring

Anything the reading leaves out (effects on a composite, say).

render_previewSee the artlooks only

An image of the document (what the canvas shows), one layer, or a slice, scaled up with whole pixels to about 512 pixels across, over a checkerboard where it's transparent. Use it to check your work by eye. With grid: true, a line between every pixel (stronger every 8) helps count them.

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

Show just this layer (id or exact name). Leave it out to see all visible layers together, as the canvas shows them.

slicestring

Show just this slice's rectangle (id or exact name).

areaobject

Show just this region. Leave it out (and slice) for the whole canvas.

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

Which animation frame (from 0). Leave it out for the current one.

scaleinteger

How many screen pixels each document pixel becomes (1 to 32). Leave it out to fit about 512 pixels.

gridboolean

True to draw a line between the pixels.

get_historyUndo historylooks only

The steps that can be undone (newest first) and redone, which of them an assistant made, and whether the document is as it was last saved.

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.

countinteger

How many steps to list each way (1 to 100).

Returns
documentstringrequired
revisionintegerrequired
undolist of objectsrequired

The steps that can be undone, newest first.

3 fields
labelstringrequired

What the step did.

byAssistantbooleanrequired

True if an assistant made it.

assistantstringrequired

The assistant that made it, if one did.

redolist of anythingrequired

The steps that can be redone, next first.

atSavePointbooleanrequired

True if the document is as it was last saved.

capture_windowSee SpriteGrid's windowlooks only

A screenshot of SpriteGrid's whole window, as the user sees it: for seeing the app itself (panels, menus, dialogs). To see the art, use render_preview.

Parameters

Nothing.