Developer documentation

Animation tools

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

`set_animation`Make or change the animation

Makes the document an animation (24 frames at 12 per second unless you say), or changes its length and speed. Then give layers drawings per frame with set_cel, or move them with set_keyframe.

Parameters

frameCountinteger: How many frames, 1 to 9999.
frameRateinteger: Frames per second, 1 to 60.
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.

`remove_animation`Remove the animationdeletes

Takes the animation away: its frames, drawings and keys. Undo brings it all back.

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

`describe_animation`Describe the animationlooks only

The animation in detail: its length, speed and current frame; for each layer that changes over time, the frames where it has a drawing of its own (a letter per drawing, so shared drawings show) and its keyed values.

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

documentstringrequired

revisionintegerrequired

frameCountintegerrequired

frameRateintegerrequired

Frames per second.

currentFrameintegerrequired

The frame shown (from 0): the drawing tools draw on it.

playingbooleanrequired

autoKeybooleanrequired

True if drawing on a frame without its own drawing gives it one (SpriteGrid's Auto-Key). When false, such drawing is refused: use set_cel first.

layerslist of objectsrequired

The layers that change over time, top first.

4 fields

layerstringrequired

The layer's id.

namestringrequired

celslist of objectsrequired

Its drawings over time, or null if it shows one drawing on every frame.

3 fields

frameintegerrequired: The frame it starts on. It shows until the next cel's frame.
drawingstringrequired: Which drawing, as a letter: frames with the same letter share one drawing, so drawing on one changes them all.
emptybooleanrequired: True if the drawing is empty.

propertieslist of objectsrequired

Its animated values, or null.

3 fields

propertystringrequired

x, y (pixels it's moved by), rotation (degrees), scaleX, scaleY, opacity, visible, or an effect's setting.

effectstringrequired

The effect whose setting it is (its id), or null.

keyslist of objectsrequired

3 fields

frameintegerrequired
valueanyrequired: A number, or true/false.
interpolationstringrequired: "linear" (changes steadily to the next key), "hold" (stays until the next key) or "curve" (eased, set in SpriteGrid).

otherTrackslist of stringsrequired

Other animation (3D, camera) this doesn't show in detail, by name, or null.

`go_to_frame`Go to a frame

Shows a frame in SpriteGrid (pausing playback). The drawing tools draw on the frame shown unless you give them a frame. Not an undo step.

Parameters

frameintegerrequired: The frame, from 0.
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

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_cel`Give a frame its own drawing

Gives an image layer its own drawing at a frame, so drawing there (a drawing tool with that frame) changes just that frame. It starts as a copy of what the layer shows there; or empty; or a copy of another frame's drawing (copyFrom); or, with linkTo, the very drawing another frame shows (drawing on either changes both). The first time, the layer's drawing stays on frame 0. Frames without their own drawing show the one before.

Parameters

frameintegerrequired: The frame, from 0.
layerstring: Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.
emptyboolean: True to start it empty.
copyFrominteger: Start it as a copy of the drawing this frame shows.
linkTointeger: Show the very drawing this frame shows (linked: not a 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_cel`Delete a frame's drawingdeletes

Takes a frame's own drawing away: it shows the drawing before it again. Undo brings it back.

Parameters

frameintegerrequired: The frame, from 0.
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.

`repeat_cels`Repeat frames' drawings

Repeats a run of frames' drawings further on, linked (drawing on a repeat changes the frame it repeats), in one undo step: a walk cycle or a spinning wheel drawn once on frames 0–3 fills the whole animation with from 0 and to 3. From start, the frames show from's drawing, then from+1's and so on, times times over, or to the last frame.

Parameters

fromintegerrequired: The first frame to repeat.
tointegerrequired: The last frame to repeat.
startinteger: Where the repeats begin. Leave it out for the frame after to.
timesinteger: How many times over. Leave it out to fill to the last frame (the last repeat can be part of one).
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.

`set_keyframe`Key a value

Sets a layer's value at a frame, or at several in one undo step (keys): x or y (pixels it's moved by), rotation (degrees clockwise, around the layer's pivot), scaleX or scaleY (1 is its size, -1 mirrors), opacity (0 to 1), visible (true/false); or, with effect, a number or true/false setting of that effect. Between keys, numbers change steadily (linear) or stay until the next key (hold). Check it with render_frames.

Parameters

propertystringrequired

x, y, rotation, scaleX, scaleY, opacity or visible; with effect, the setting's id.

frameinteger

The frame, from 0, for one key (with value).

valueany

The value at frame: a number, or true/false for visible and true/false settings.

keyslist of objects

Several keys at once, instead of frame and value: [{ "frame": 0, "value": 0 }, { "frame": 31, "value": 124, "interpolation": "hold" }].

3 fields

frameintegerrequired: The frame, from 0.
valueanyrequired: A number, or true/false for visible and true/false settings.
interpolationstring: "linear" or "hold". Leave it out for the call's interpolation.

layerstring

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

effectstring

An effect on the layer (its id, or its kind like "glow") whose setting to key.

interpolationstring

"linear" (the default for a new key) or "hold", for every key that doesn't say. Leave it out to keep a key's.

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_keyframe`Delete a keydeletes

Takes a key away: the value there comes from the keys around it again. Undo brings it back.

Parameters

frameintegerrequired: The frame, from 0.
propertystringrequired: x, y, rotation, scaleX, scaleY, opacity or visible; with effect, the setting's id.
layerstring: Which layer: its id, or its exact name (describe_document lists them). Leave it out for the layer selected in SpriteGrid.
effectstring: The effect whose setting it is (its id or kind).
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.

`render_frames`See the animationlooks only

The animation's frames side by side in one image (left to right, then down), each scaled up over a checkerboard: the whole picture (with effects and movement) or one layer. At most 64 frames at a time.

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 for the whole picture.
frominteger: The first frame. Leave it out for 0.
tointeger: The last frame. Leave it out for the last one.
scaleinteger: How many screen pixels each document pixel becomes. Leave it out to fit about 1024 pixels.
columnsinteger: Frames per row. Leave it out for about square.

set_animationMake or change the animation

Parameters

remove_animationRemove the animationdeletes

Parameters

describe_animationDescribe the animationlooks only

Parameters

go_to_frameGo to a frame

Parameters

set_celGive a frame its own drawing

Parameters

delete_celDelete a frame's drawingdeletes

Parameters

repeat_celsRepeat frames' drawings

Parameters

set_keyframeKey a value

Parameters

delete_keyframeDelete a keydeletes

Parameters

render_framesSee the animationlooks only

Parameters

`set_animation`Make or change the animation

`remove_animation`Remove the animationdeletes

`describe_animation`Describe the animationlooks only

`go_to_frame`Go to a frame

`set_cel`Give a frame its own drawing

`delete_cel`Delete a frame's drawingdeletes

`repeat_cels`Repeat frames' drawings

`set_keyframe`Key a value

`delete_keyframe`Delete a keydeletes

`render_frames`See the animationlooks only