Developer documentation
Documents and files tools
10 tools. Every change a tool makes is one undo step in SpriteGrid.
new_documentNew document
Makes a new, empty document of a size (one transparent layer) and shows it. It's yours to work on: locked to you, like a document you've changed. Returns its id.
Parameters
widthintegerrequiredWidth in pixels, 1 to 4096.
heightintegerrequiredHeight in pixels, 1 to 4096.
Returns
idstringrequiredIts id for this session, like "doc-1". Pass it as `document`.
namestringrequiredpathstringrequiredWhere it's saved, or null if it never was.
widthintegerrequiredheightintegerrequiredunsavedChangesbooleanrequiredTrue if it has changes that aren't saved.
revisionintegerrequiredChanges whenever the document does, the user's edits too. Pass it as `expectedRevision` to refuse a change if the document moved on.
activebooleanrequiredTrue for the document shown in SpriteGrid.
lockedBystringWho'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.
open_documentOpen a file
Opens a SpriteGrid document (.spritegrid) or an image (PNG, JPG, BMP...) and shows it, locked to you like a document you've changed. If it's open already, just shows it. Returns its id.
Parameters
pathstringrequiredThe file's full path.
Returns
idstringrequiredIts id for this session, like "doc-1". Pass it as `document`.
namestringrequiredpathstringrequiredWhere it's saved, or null if it never was.
widthintegerrequiredheightintegerrequiredunsavedChangesbooleanrequiredTrue if it has changes that aren't saved.
revisionintegerrequiredChanges whenever the document does, the user's edits too. Pass it as `expectedRevision` to refuse a change if the document moved on.
activebooleanrequiredTrue for the document shown in SpriteGrid.
lockedBystringWho'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.
switch_documentShow a document
Shows an open document in SpriteGrid, making it the one your tools use when document is left out. It doesn't lock it: changing it does.
Parameters
documentstringrequiredWhich 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
idstringrequiredIts id for this session, like "doc-1". Pass it as `document`.
namestringrequiredpathstringrequiredWhere it's saved, or null if it never was.
widthintegerrequiredheightintegerrequiredunsavedChangesbooleanrequiredTrue if it has changes that aren't saved.
revisionintegerrequiredChanges whenever the document does, the user's edits too. Pass it as `expectedRevision` to refuse a change if the document moved on.
activebooleanrequiredTrue for the document shown in SpriteGrid.
lockedBystringWho'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.
release_documentDone with a document
Say you've finished with a document: it unlocks, so the user and other assistants can change it again. Changing a document (or making or opening one) locks it to you; it also unlocks when you disconnect or after 20 seconds without a call from you.
Parameters
documentstringWhich 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.
save_documentSave
Saves a document to its file, or to a new .spritegrid file (which it's saved as from then on). A document opened from an image is saved back to that image unless you give a path. Replacing a file that isn't the document's own needs overwrite: true.
Parameters
documentstringWhich 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.pathstringA full path ending in .spritegrid. Leave it out to save to the document's own file.
overwritebooleanTrue to replace a file that's already there.
Returns
documentstringrequiredThe document's id.
fileslist of stringsrequiredThe files written, full paths.
summarystringrequiredWhat was written, in a line.
close_documentClose a documentdeletes
Closes a document. One with unsaved changes stays open unless discardChanges is true (and then its changes are lost).
Parameters
documentstringWhich 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.discardChangesbooleanTrue to close it even with unsaved changes, losing them.
export_imageExport a PNG
Writes a PNG of the document as the canvas shows it (effects and all), one layer, or a slice, at a frame, optionally scaled up by a whole number. SpriteGrid shows the document while exporting it.
Parameters
pathstringrequiredA full path ending in .png.
scaleintegerHow many times bigger, 1 to 16 (each pixel becomes a block).
layerstringExport just this layer (id or exact name), without effects.
slicestringExport just this slice's rectangle (id or exact name).
frameintegerWhich animation frame (from 0). Leave it out for the current one.
overwritebooleanTrue to replace a file that's already there.
documentstringWhich 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
documentstringrequiredThe document's id.
fileslist of stringsrequiredThe files written, full paths.
summarystringrequiredWhat was written, in a line.
export_sprite_sheetExport a sprite sheet
Writes every frame of the animation into one PNG, in rows: columns across (about square if left out), with padding between.
Parameters
pathstringrequiredA full path ending in .png.
columnsintegerFrames per row. Leave it out for about square.
paddingintegerTransparent pixels between frames.
powerOfTwobooleanTrue to make the sheet's sides powers of two.
overwritebooleanTrue to replace a file that's already there.
documentstringWhich 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
documentstringrequiredThe document's id.
fileslist of stringsrequiredThe files written, full paths.
summarystringrequiredWhat was written, in a line.
export_slice_sheetExport a slice sheet
Packs the document's slices into a PNG sheet, with a .json saying where each slice went, and its nine-slice guides, pivot and points if it has them (see add_slice). With groups, writes one sheet per layer group named (each drawn on its own, same layout) into a folder: sheet_<group>.png each (a character a file name can't have becomes _, and a repeated name gets _2, _3), and sheet_meta.json.
Parameters
pathstringrequiredA full path ending in .png, or with groups, the folder to write into.
groupslist of stringsLayer groups (names or ids) to make a sheet of each.
paddingintegerTransparent pixels between slices.
powerOfTwobooleanTrue to make the sheet's sides powers of two.
jsonbooleanTrue (the default) to write the .json of where each slice went.
overwritebooleanTrue to replace files that are already there.
documentstringWhich 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
documentstringrequiredThe document's id.
fileslist of stringsrequiredThe files written, full paths.
summarystringrequiredWhat was written, in a line.
export_atlasExport the atlas
Writes the atlas to a PNG, effects baked in: the grid (the tiles as placed), a sheet of every tile once, or one tile.
Parameters
pathstringrequiredA full path ending in .png.
whatstring"grid" (the default), "sheet" or "tile".
tilestringThe tile to export, for "tile".
scaleintegerScale up by a whole number, 1 to 16.
overwritebooleanTrue to replace a file that's already there.
documentstringWhich 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
documentstringrequiredThe document's id.
fileslist of stringsrequiredThe files written, full paths.
summarystringrequiredWhat was written, in a line.