Docs · Scripting API

LibreSprite scripting API reference

The complete JavaScript API of LibreSprite 1.3. The list of objects, properties and parameters is extracted from the API source code (src/app/script/api), so it matches the release exactly; the descriptions are ours, checked against the code and our test scripts.

Checked with LibreSprite 1.3Updated November 1, 20262 min read

On this page 3 sections

Global functions
Classes
Notes

Short answer

Where do I start?

Most scripts begin with const s = app.activeSprite;, walk s.layer(i).cel(frame).image, and read or write pixels with getPixel/putPixel and pixelColor. The scripting guide has worked, tested examples.

Global functions

`console.log(...values)`	Print values to the console.
`console.verbose(...values)`	Print only in verbose mode.
`console.assert(cond, msg)`	Print the message if the condition is false.
`storage.get(key, domain)`	Read a stored value.
`storage.set(value, key, domain)`	Store a value (kept in memory for the session).
`storage.unload(key, domain)`	Forget a stored value.
`storage.save(key, domain)`	Write a stored value to a file in the settings folder; returns the path.
`storage.load(key, domain)`	Load a value saved with save().
`storage.decodeBase64(key, domain)`	Decode a stored Base64 string in place.
`storage.fetch(url, key)`	Download a URL into storage; raises `<key>_fetch` when done.
`setTimeout(callback, delay)`	Run a function once after a delay (ms); returns an id.
`setInterval(callback, delay)`	Run a function repeatedly; returns an id.
`clearTimeout(id)`	Cancel a setTimeout.
`clearInterval(id)`	Cancel a setInterval.
`ColorMode.RGB / GRAYSCALE / INDEXED / BITMAP`	Colour-mode constants for `sprite.colorMode`.
`onEvent(name)`	Define this function to receive events: `init`, `<id>_click`, `<id>_change`, `<key>_fetch`.

Classes

App

The application. Global: app.

`.activeFrameNumber`read-only	Current frame, counting from 0.
`.activeLayerNumber`read-only	Current layer, counting from 0 at the bottom.
`.activeImage`read-only	The image of the current cel (current layer and frame). null in batch mode.
`.activeSprite`read-only	The sprite in the current tab (a `Sprite`), or null.
`.activeDocument`read-only	The current document (a `Document`).
`.version`read-only	LibreSprite version, e.g. `"1.3"`.
`.platform`read-only	Operating system, e.g. `"linux"`.
`.open(fn)`	Open a file in a new tab.
`.launch(cmd)`	Open a file or URL with the system’s default handler. Powerful: only in scripts you trust.
`.redraw()`	Refresh the screen after changing pixels.
`.createDialog()`	Create a `Dialog`. Returns null without the interface (batch mode).

Sprite

An open sprite. Global: sprite (always the active one), or app.activeSprite.

`.layerCount`read-only	Number of layers.
`.filename`read-only	File name, if saved.
`.width`read/write	Width in pixels. Setting it resizes the canvas.
`.height`read/write	Height in pixels. Setting it resizes the canvas.
`.colorMode`read-only	Colour mode: compare with `ColorMode.RGB`, `.GRAYSCALE`, `.INDEXED`.
`.selection`read-only	The `Selection`.
`.palette`read-only	The sprite’s `Palette`.
`.layer(i)`	The `Layer` at index i (0 = bottom), or null.
`.commit()`	No-op in 1.3: each change is already its own undo step.
`.resize(w, h)`	Resize the sprite.
`.crop(double, double, double, double)`	No-op in 1.3: kept only so old scripts don’t fail.
`.save()`	Save (like File → Save).
`.saveAs(fileName, asCopy)`	Save under a new name; with `asCopy = true` writes a copy (like Export) and keeps the open file.
`.loadPalette(fileName)`	Load a palette file (.gpl, .pal, .png …) into the sprite.

Layer

A layer, from sprite.layer(i).

`.name`read/write	Layer name.
`.isImage`read-only	True for normal image layers.
`.isBackground`read-only	True for the Background layer.
`.isTransparent`read-only	True if it can have transparent pixels.
`.isVisible`read/write	Visible (eye icon).
`.isEditable`read/write	Editable (padlock open).
`.isMovable`read-only	True if it can be moved in the stack.
`.isContinuous`read-only	True if copied cels are linked by default.
`.flags`read-only	All flags as one number.
`.celCount`read-only	Number of cels in the layer.
`.cel(i)`	The `Cel` in frame i (from 0), or null if that frame is empty.

Cel

One layer in one frame.

`.x`read/write	Horizontal position of the cel image.
`.y`read/write	Vertical position of the cel image.
`.image`read-only	The cel’s `Image`.
`.frame`read-only	Frame number.
`.setPosition(x, y)`	Move the cel image.

Image

Pixels of a cel.

`.width`read-only	Width.
`.height`read-only	Height.
`.stride`read-only	Bytes per row.
`.format`read-only	Pixel format (0 = RGB).
`.getPixel(x, y)`	Colour at x, y as a 32-bit number (decode with `pixelColor`).
`.putPixel(x, y, color)`	Set the colour at x, y.
`.clear(color)`	Fill the whole image with a colour.
`.putImageData(data)`	Replace all pixels from a byte array.
`.getImageData()`	All pixels as a byte array (RGBA).
`.getPNGData()`	The image encoded as PNG bytes.

Palette

A palette, from sprite.palette.

`.length`read/write	Number of entries; setting it resizes the palette.
`.get(i)`	Colour of entry i.
`.set(i, a, b, c, d)`	Set entry i: `set(i, color)`, `set(i, r, g, b)` or `set(i, r, g, b, a)`.

Selection

The selection, from sprite.selection.

`.bounds`read-only	Bounding box of the selection, or null.
`.select(x, y, w, h)`	Select a rectangle.
`.selectAll()`	Select everything.
`.deselect()`	Remove the selection.

Document

An open document.

`.sprite`read-only	Its `Sprite`.
`.close()`	Close it (asks to save changes).

PixelColor

Colour helpers. Global: pixelColor (also app.pixelColor).

`.rgba(r, g, b, a)`	Build a colour from red, green, blue, alpha (0–255).
`.rgbaR(c)`	Red of a colour.
`.rgbaG(c)`	Green of a colour.
`.rgbaB(c)`	Blue of a colour.
`.rgbaA(c)`	Alpha of a colour.
`.graya(v, a)`	Build a grayscale colour from value and alpha.
`.grayaV(c)`	Grey value of a grayscale colour.
`.grayaA(c)`	Alpha of a grayscale colour.

Command

Runs menu commands. Global: command (also app.command). Call command.<Name>({params}), e.g. command.Flip({target: "canvas", orientation: "horizontal"}).

`.setParameter(key, value)`	Set a parameter for the next command call (chainable).
`.clearParameters()`	Clear parameters set with setParameter.

Dialog

A script window, from app.createDialog(). Widgets raise events in onEvent.

`.title`read/write	Window title.
`.width`read-only	Width.
`.height`read-only	Height.
`.canClose`read/write	Set to false to hide the close button.
`.addLabel(text, id)`	Add a text label.
`.addButton(text, id)`	Add a button; raises `<id>_click`.
`.addEntry(text, id)`	Add a text field (with a label); raises `<id>_change`.
`.addIntEntry(text, id, min, max)`	Add a number field with min and max; raises `<id>_change`.
`.addImageView(id)`	Add an image preview.
`.addPaletteListBox(id)`	Add a list of palettes; raises `<id>_change`.
`.addBreak()`	Start a new row.
`.get(id)`	The widget with that id.
`.close()`	Close the dialog.

Label

Text in a dialog.

`.text`read/write	The text.
`.id`read-only

Button

A dialog button.

`.text`read/write	Button caption.
`.id`read-only

Entry

A text field.

`.maxsize`read/write	Maximum length.
`.value`read/write	The text (setting it doesn’t raise a change event).
`.id`read-only

IntEntry

A number field.

`.min`read/write	Minimum.
`.max`read/write	Maximum.
`.value`read/write	The number (setting it doesn’t raise a change event).
`.id`read-only

ImageView

An image preview in a dialog.

`.id`read-only
`.putImageData(data, width, height)`	Show RGBA bytes (width × height × 4).

PaletteListBox

A palette list in a dialog.

`.selected`read-only	Name of the selected palette ("" if none).
`.id`read-only
`.addPalette(name)`	Add an entry and return its `Palette`.

Notes

Indexes start at 0: layer 0 is the bottom layer, frame 0 is the first frame.
Colours are 32-bit numbers; always build and read them with pixelColor rather than doing the bit maths yourself.
LibreSprite’s own SCRIPTING.md in the repository is generated by an older tool and lists some members twice; this page is generated from the 1.3 source.
Not available in 1.3: frame durations, tags, creating layers or frames directly (use command.NewLayer(), command.NewFrame()), and slices.

Keep going

ScriptingAutomate LibreSprite with JavaScript: first script to dialogs.Command lineBatch export sprite sheets and run scripts headless.Menu referenceEvery menu command, what it does and its shortcut.

Found something wrong or out of date? Tell us: hello@libresprite.dev. We fix mistakes within a day.

#Global functions

#Classes

App