Developer documentation
Atlas tools
5 tools. Every change a tool makes is one undo step in SpriteGrid.
describe_atlasDescribe the atlaslooks only
The document's tiles (id, name, the layer to draw each on, how many cells show it, tiles nested in it) and the map of where they're placed, a character per cell. The map can be edited and passed back to set_tiles.
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.
Returns
documentstringrequiredrevisionintegerrequiredcellWidthintegerrequiredA cell's size, in pixels: the canvas's size.
cellHeightintegerrequiredtileslist of objectsrequired6 fields
idstringrequiredThe tile's id (it's a layer group). Pass it (or the exact name) as `tile`.
namestringrequireddrawLayerstringrequiredThe layer inside it to draw on: pass it as `layer` to the drawing tools.
cellsintegerrequiredHow many cells show it.
symbolstringrequiredThe character standing for it in `map`.
containslist of stringsrequiredThe tiles shown inside it (
nest_tile), by name, or null.
mapobjectrequiredWhere the tiles are placed, a character per cell (see each tile's symbol; "." is empty), or null if no cell has a tile.
3 fields
originobjectrequiredThe cell of the first row's first character. Leave it out for column 0, row 0.
2 fields
columnintegerrequiredCells from the left; 0 is the canvas's own cell, and it can be negative.
rowintegerrequiredCells from the top; 0 is the canvas's own cell, and it can be negative.
legendmap of stringsrequiredWhat each character stands for: a tile (its id or exact name), "empty" to clear the cell, or "keep" to leave it as it is.
rowslist of stringsrequiredRows of characters, one character per cell, top row first.
notestringrequired
add_tileAdd a tile
Makes a tile: a group of layers the size of the canvas, with an empty layer to draw on (returned as layer; the tile's own id is tile). Places it on cells if you give them. The first tile turns the document into an atlas.
Parameters
namestringIts name. Leave it out for "Atlas Group N".
cellslist of objectsCells to place it on.
2 fields
columnintegerrequiredCells from the left; 0 is the canvas's own cell, and it can be negative.
rowintegerrequiredCells from the top; 0 is the canvas's own cell, and it can be negative.
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.expectedRevisionintegerThe 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
documentstringrequiredThe document's id.
revisionintegerrequiredIts revision after the change.
summarystringrequiredWhat changed, in a line.
layerstringThe layer changed or made, if there was one.
changedobjectThe rectangle of pixels that changed, if any did.
4 fields
xintegerrequiredLeft edge, in pixels from the left of the canvas.
yintegerrequiredTop edge, in pixels from the top of the canvas.
widthintegerrequiredWidth in pixels.
heightintegerrequiredHeight in pixels.
pixelsChangedintegerHow many pixels changed.
slicestringThe slice changed or made, if there was one.
effectstringThe effect changed or added, if there was one.
tilestringThe tile changed or made, if there was one.
set_tilesPlace tiles
Puts tiles on cells or clears cells, from a map (rows of characters, one per cell, like describe_atlas gives) and/or a list of cells, in one undo step. At most 4096 cells a call.
Parameters
mapobjectExample: { "origin": {"column": 0, "row": 0}, "legend": {"g": "Grass", "w": "Water", ".": "keep", "x": "empty"}, "rows": ["gggw", "ggww"] }.
3 fields
originobjectrequiredThe cell of the first row's first character. Leave it out for column 0, row 0.
2 fields
columnintegerrequiredCells from the left; 0 is the canvas's own cell, and it can be negative.
rowintegerrequiredCells from the top; 0 is the canvas's own cell, and it can be negative.
legendmap of stringsrequiredWhat each character stands for: a tile (its id or exact name), "empty" to clear the cell, or "keep" to leave it as it is.
rowslist of stringsrequiredRows of characters, one character per cell, top row first.
cellslist of objectsSingle cells: [{ "column": 2, "row": -1, "tile": "Grass" }]; tile null clears the cell.
3 fields
columnintegerrequiredrowintegerrequiredtilestringrequiredA tile (its id or exact name), or null to clear the cell.
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.expectedRevisionintegerThe 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
documentstringrequiredThe document's id.
revisionintegerrequiredIts revision after the change.
summarystringrequiredWhat changed, in a line.
layerstringThe layer changed or made, if there was one.
changedobjectThe rectangle of pixels that changed, if any did.
4 fields
xintegerrequiredLeft edge, in pixels from the left of the canvas.
yintegerrequiredTop edge, in pixels from the top of the canvas.
widthintegerrequiredWidth in pixels.
heightintegerrequiredHeight in pixels.
pixelsChangedintegerHow many pixels changed.
slicestringThe slice changed or made, if there was one.
effectstringThe effect changed or added, if there was one.
tilestringThe tile changed or made, if there was one.
nest_tileNest a tile
Shows one tile inside another, on top of its layers (a flower tile inside a grass tile, say): a live copy, so drawing on the first changes both. Returns the new layer's id.
Parameters
tilestringrequiredThe tile to show (id or exact name).
intostringrequiredThe tile to show it in.
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.expectedRevisionintegerThe 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
documentstringrequiredThe document's id.
revisionintegerrequiredIts revision after the change.
summarystringrequiredWhat changed, in a line.
layerstringThe layer changed or made, if there was one.
changedobjectThe rectangle of pixels that changed, if any did.
4 fields
xintegerrequiredLeft edge, in pixels from the left of the canvas.
yintegerrequiredTop edge, in pixels from the top of the canvas.
widthintegerrequiredWidth in pixels.
heightintegerrequiredHeight in pixels.
pixelsChangedintegerHow many pixels changed.
slicestringThe slice changed or made, if there was one.
effectstringThe effect changed or added, if there was one.
tilestringThe tile changed or made, if there was one.
render_atlasSee the atlaslooks only
An image of the atlas, scaled up over a checkerboard, effects included: the grid (the tiles as placed, cropped to the cells in use), a sheet of every tile once, or one tile.
Parameters
whatstring"grid" (the default), "sheet" or "tile".
tilestringThe tile to show, for "tile".
scaleintegerHow many screen pixels each pixel becomes. Leave it out to fit about 1024 pixels.
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.