Isberg Labs documentation

What Isberg Labs is

Isberg Labs runs from a single folder that you unzip anywhere. The folder carries everything the editors need: the desktop runtime, the bundled game engine, compilers for C, C++ and C#, a Lua 5.4 runtime, a V8 JavaScript runtime, image and audio codecs, mesh and map decoders, and export templates for five platforms. Nothing is downloaded while you work.

All editors open inside one workspace. Each editor is a window you can move, overlap, dock, maximize or pull onto another monitor. Editors share the project's assets, the Inspector, the Output and History docks, and one Undo/Redo history. The whole workspace, with every document and asset, saves as one .isberg project file.

A local MCP server ships in the same folder. It exposes 375 tools that read and write images, scenes, meshes, audio, rigs, levels and RPG projects, and that can drive the real editors through their own controls. See MCP server guide.

At a glance

The twenty editors

Open any editor from the Tools palette on the left side of the workspace. Each row links to its chapter.

The engine underneath

The Game runtime editor, native playtests and native exports run on a heavily modified build of the open-source Godot Engine that is bundled inside the portable folder: a custom 4.7.2 Windows editor and runtime, and official Godot 4.5.2 export templates. It opens and runs native Godot-format projects with GDScript and GDExtension. No separate engine installation is launched or downloaded.

How to read this documentation

• New here? Read Install & first start, then The workspace and Projects, assets & history.
• Each editor has its own chapter, ending with the MCP tools for that editor and, where useful, troubleshooting.
• To ship a game, read Exporting games. RPG Creator and JavaScript projects also have their own delivery sections.
• Buying, trial, activation, devices and offline use are in License.
• Use the search box above the contents list to filter topics. Every heading has a link you can copy.
• Labels in bold are the exact names of buttons, tabs, menus and fields in the app. Monospace marks file names, paths, commands and values you type.

System requirements

Download and verify

1. Download Isberg Labs 0.21 Portable.zip from the Download section of isberglabs.com. The same section shows its SHA-256 checksum.
2. Check that the download is complete and unmodified. In PowerShell, in the download folder:

   Get-FileHash '.\Isberg Labs 0.21 Portable.zip' -Algorithm SHA256

   The hash must match the checksum shown on the Download section (or the first value in the .sha256 file, if you have it).
3. Extract the whole ZIP to a short path you can write to, for example C:\Isberg Labs or D:\Isberg Labs. Deep folders such as Downloads\… can hit the Windows path-length limit. Avoid C:\Program Files: the folder must be writable because it holds your preferences, recovery copies and license.

What is in the portable folder

First start

1. Open Isberg Labs.exe. If Windows SmartScreen warns about an unrecognized app, choose More info, check the file came from isberglabs.com, then Run anyway.
2. The Isberg Labs license window opens on its own. Nothing else starts until this device has a trial or a license.
3. Choose one:
   • Start 14-day free trial to use every feature for 14 days without a key. See Free trial.
   • Paste your key into License key and choose Activate. See Activating a license.
   • Buy a license opens the store page in your browser.
4. When the status shows Active on this device or Free trial — 14 days left, choose Open Isberg Labs. The workspace opens on the Overview.
5. Open an editor from the Tools palette, or choose Game presets to start from a game type. See The workspace and Game presets.

On later starts the studio opens directly, using the saved license check. If an automatic recovery copy of your last session exists, the header shows Restore recovery, which reopens your last session's workspace. See Automatic recovery.

Upgrading to a new version

1. Save your work and close Isberg Labs.
2. Extract the new ZIP into a new folder. Do not extract over the old version.
3. Copy the old folder's Data folder into the new folder. This keeps your preferences, window layout, recovery copy, saved scripts and palettes, and this device's license activation.
4. If you kept projects or exports in the old Projects folder, copy or move them as well.
5. Start the new Isberg Labs.exe and open a project to confirm it works. Keep the old folder until it does.
6. If an MCP client points at the old folder, update the paths in its configuration (see MCP).

Files saved by earlier versions open unchanged, including the earlier names .gbench and .gb*. A recovery copy left by an earlier version is still offered.

Moving to another folder, drive or PC

• Another folder or drive on the same PC: close the studio and move the whole folder. The license stays active because it is bound to the PC, not the folder. Update MCP client paths afterwards.
• Another PC: first open License in the sidebar and choose Deactivate this device, then copy the folder (or extract a fresh ZIP) on the new PC and activate there. A license.json copied from another PC is rejected. See Devices and moving your license.

Uninstalling

1. If you will use the license on another PC, open License and choose Deactivate this device first. (You can also free the slot later from the other PC's license window.)
2. Move any projects you want to keep out of the folder.
3. Close the studio and delete the folder.

There is no installer to undo. Preferences, caches, recovery copies and the license live in the Data folder inside the portable folder, so deleting the folder removes them. Files you saved or exported elsewhere stay where you put them.

Classic interface

Studio uses a classic workstation look: a blue desktop, medium-gray beveled windows, striped title bars, recessed fields, compact tabs and small colored tool icons. Fonts come from the local Windows fonts (Tahoma, with Arial as a fallback); nothing is downloaded.

• The same classic styling is applied to every built-in editor page, including the four nested map editors of the World builder and the dialogs.
• Canvases, game previews, palettes, swatches and other authored colors are never restyled. Game previews and authored scenes keep their own artwork and rendering.
• The integrated native project editor in Game runtime uses a matching local theme with gray surfaces and beveled borders. That theme stays in the portable editor configuration and is never added to your game projects or exports. See Game runtime.
• At smaller window sizes the editor layouts reflow and long menus scroll. The main window opens at 1700 × 1050 by default and cannot be made smaller than 800 × 600.

App header

The header across the top of the window holds the project commands.

Below the header, the workspace bar shows the active editor's group, name and one-line description, followed by the layout and window controls (Layouts, Window controls) and the workspace actions Game presets, Tool options, ▶ Play, Share document, Update asset and Capture ↗ (Workspace actions).

The bottom of the Tools panel holds four more buttons:

Entirely local

A status indicator for the project work done on this computer. License activation and validation still go online; see License.

⌘ MCP connection

Shows how to connect an MCP client: start MCP.cmd from the portable folder, or point your client's configuration at it under the server id gamebench. See MCP server guide.

◉ Feature coverage

Opens the bundled compatibility notes in a dialog. See Compatibility limits.

⚿ License

Opens the license window. During a trial the button reads Trial: N days left; when online validation is needed it shows ⚠ License: validate online. Nothing closes while you work.

Tools palette and Scene tree

The left panel (title Tools; Tools & scene when it floats) has two tabs, Tools and Scene.

Tools palette

The Tools tab lists the Overview and the twenty editors, each with an icon, a short label and a two-digit number. Hover a button to see the full editor name. Click it to open the editor and bring it to the front: in Floating windows it opens in its own window, in docked layouts it opens as a tab in the focused dock.

The Overview page shows the same editors as numbered cards (01 to 20). Click a card to open that editor. An editor loads the first time you open it and then stays loaded, with its document, until you quit.

Scene tree

The Scene tab shows the active editor's document tree, captioned editor / scene.

• It lists the document's objects, nodes, tiles, layers, tracks or sub-editors, up to 250 of each kind. Child items are indented.
• Click an item to select it in the editor (where the editor supports selection) and show its properties in the Inspector.
• For a running Game runtime project, the tree lists the native scene nodes.
• If the active editor has no such list, the tree reads The active editor uses its own document tree. Vertex painter shows its vertex count instead. If the editor has not been opened yet, use Open active editor.

Choosing the Universal workspace layout switches this panel to the Scene tab automatically.

Inspector and Assets

The right panel (title Project; Inspector & assets when it floats) has two tabs, Inspector and Assets.

Inspector

• Focused setting. Click into any field, list or text box in an editor and the Inspector shows it with a Value control. Changing the value there changes the editor's own control ("Live setting from editor").
• All editor settings. Lists every enabled field, list, text box and button of the active editor, including controls inside its nested frames, with a count such as "N live settings/actions from the active editor." Buttons in the list run the editor's action.
• Selected object. After you pick an item in the Scene tree, the Inspector lists its text, number and on/off properties, and vectors of two to four numbers as comma-separated values. IDs and embedded image data are not shown. Open All object properties to edit the complete object as JSON, then press Apply object properties. Each change is one undoable step.
• Native nodes. For a Game runtime node, the Inspector shows Native object properties as JSON. Enter a Native property name and a JSON value, then press Apply native property.

Assets

The Assets tab is the project's shared asset shelf, headed Project assets with the asset count.

• + (Import image) adds an image file (PNG, APNG, JPEG, WebP, GIF, BMP, TIFF or AVIF) as an image asset.
• Find an asset… filters the shelf by name.
• Image assets show a thumbnail; editable documents show ▣. The tooltip gives the image size, or the source editor and revision of a document.
• Click an asset to select it. Double-click it, or press Use selected image, to use it in the active editor:

The shelf, its documents and their links are saved in the project. Sharing, updating, using and removing documents are recorded in the shared history.

Bottom dock

The bottom dock (Files, animation & output when it floats) has five tabs. Click a tab to open its content. The ⌃ button (Expand bottom panel) shows or hides the content in docked layouts and minimizes the window in Floating windows.

Layouts

Choose a layout from the Editor layout list in the workspace bar. The layout, including window positions, is saved in your local preferences and in every project file. Each layout change is also an undoable "Arrange window" step in the shared history.

Working with docks

• Click a tab to show that editor. Drag a tab onto another dock's title bar or tab strip to move it there, or onto an empty part of the desktop to float it.
• Double-click a tab, or a dock's title bar, to maximize the dock. Do it again to restore.
• The × on a tab closes that editor tab. The editor and its document stay loaded and are still saved with the project; open it again from the Tools palette.
• The + at the end of a tab strip opens the Tools palette.
• Drag the divider between two docks to resize them, between 10% and 90% of the space.
• You can have at most eight docks at once.
• In docked layouts the Tools, Inspector/Assets and bottom panels stay fixed at the left, right and bottom of the window. They become windows only in Floating windows. They cannot be dropped into an editor dock ("Utility panels keep their own windows.").

Choosing Floating windows, Single editor, Universal workspace or Quad view first brings any editors you moved to other monitors back into Studio.

Window controls

In Floating windows, every editor and utility panel is a window you can move, overlap, resize, minimize and maximize inside Studio.

Moving windows with the keyboard

Tab to a floating window's title bar, then:

• Arrow keys move the window 10 pixels; hold Alt for 1-pixel steps.
• Shift+arrow keys resize it (Left/Right change the width, Up/Down the height), also in 10-pixel steps or 1-pixel steps with Alt.

Sizes and limits

• Editor windows are at least 240 × 160 pixels, utility panels at least 110 × 100, and no window can be larger than the desktop area.
• When the Studio window gets smaller, windows are pulled back inside the reachable area.
• Up to 48 floating windows are supported.
• Positions, sizes, tab groups, overlap order and minimized and maximized states are saved in local preferences and in .isberg projects. Layouts from older versions still load.
• Native Windows viewports (such as the Game runtime engine view) show only the parts not covered by other windows. They hide briefly while you drag or resize a window, or while a dialog is open.

Workspace actions

Game presets

Opens the Game presets dialog for the active editor. See Game presets.

Tool options

Shows or hides the active editor's detailed control panel; the button is highlighted while it is on. In 3D scene & animation it toggles the side panel of detailed controls, which is hidden by default. In Pixel & animation it shows the side panels as an overlay when the editor window is narrower than 900 pixels (they are hidden automatically at that width). Other editors keep their controls visible and are not affected.

▶ Play

In RPG Creator, starts the RPG playtest. In 3D scene & animation and Level & playtest, sends the current scene or level to Game runtime and runs it as a native game. In every other editor, switches to Game runtime and runs its current project. See Game runtime.

Share document

Adds the active editor's complete editable document to the asset shelf and links the editor to it. See Shared assets.

Update asset

Saves the active editor's current document as a new revision of its linked asset (or of the selected document asset) and updates the other linked editors.

Capture ↗

Adds a picture of the active editor to the asset shelf. In Pixel & animation it adds the current frame with all visible layers composited, named "Sprite N". In other editors it captures the largest canvas, named "Capture N"; if the editor has no canvas, it says "Use this workspace’s export or publish control." Hidden on the Overview.

Editors on other monitors

Any of the twenty editors can leave the Studio window and become a separate Windows desktop window, for example on a second monitor. The Overview and the Tools, Inspector/Assets and bottom panels always stay in Studio ("This panel stays in the main workspace.").

1. Drag the editor's title bar past the outer edge of the Studio window and release it, or click the title-bar ↗ ("Move editor to another screen").
2. The editor opens in its own window, titled "Editor — Isberg Labs", with its current document. Its window inside Studio is locked until it returns.
3. Move the new window with its standard Windows title bar to any monitor. It resizes, minimizes and maximizes independently. Monitors placed left of or above the main screen work too.
4. To bring it back, press ↙ Return to workspace in the window, close it with its Windows ×, choose Gather in Studio, or close its tab in Studio.

• The Windows… list marks detached editors with ↗; choosing one brings its desktop window to the front.
• A detached editor is still part of the same project: Save project includes its latest document, and the shared Undo/Redo, the asset shelf and Ctrl+S work from either window.
• Opening another project, or choosing the Floating windows, Single editor, Universal workspace or Quad view layout, first returns all detached editors to Studio.
• Moving an editor in either direction reloads its view from the current editable document. Temporary view state (such as camera position or selection) and the editor's own local undo stack may reset; the shared history is kept.
• If a monitor is disconnected or rearranged, its windows move to a screen that is still available, keeping their size where possible.

Running games and playback during a move

A live engine session cannot run in two windows at once. When you move an editor, any playback or playtest in it is paused or stopped first. For Game runtime, the active native or web game session stops while the authored project is kept; Studio shows "Runtime project moved. Choose Edit project or Run to resume." Press Edit project or Run in the new window to continue. The same applies when the editor returns. The JavaScript, Music & composition, Sound designer and Parameter sound documents are copied across exactly as they were.

Remembered placement

• Studio remembers each desktop window's monitor, normal position and size, and minimized or maximized state, and the main window's own placement.
• If you quit with editors detached, they reopen in the same places at the next start. The automatic recovery project is opened first so they come back with their documents.
• An editor you returned to Studio stays in Studio at the next start; its last desktop placement is reused the next time you pop it out.
• Placements are stored in desktop-windows.json in the portable Data folder (or your profile folder), not in the project file. Up to 48 editor placements are kept.

Editor settings and preferences

• Editor settings live in each editor. Use Tool options to reveal hidden detail panels, and the Inspector's All editor settings to reach every control of the active editor from one list.
• Local preferences (the current layout and the settings editors keep between sessions) are stored in the portable Data folder, or in your profile folder when you use GAMEBENCH_PROFILE.
• Desktop window placements are stored separately in desktop-windows.json.
• Pixel & animation keeps its palette library, scripts, style cards and Lua extensions in folders inside Data. See Pixel & animation.
• Each project save includes a copy of the local preferences. Opening a project restores that copy, replacing your current local preferences.

Copy the Data folder along with the application folder to keep your preferences on another drive or computer. See Data and Projects folders.

Keyboard shortcuts

These shortcuts are defined by the Studio shell and work in every editor. Ctrl+Z and Ctrl+Y are ignored while you type in a text field or text box, and when Alt is also held.

Shortcuts inside editors

These keys are handled by the editors themselves and work while that editor's canvas or panel has focus (not while you type in a field). In these editors Ctrl+Z and Ctrl+Y always use the shared history, which also records their edits. Pixel & animation has its own menu shortcuts, including Ctrl+O (Open…) and Ctrl+Space (Command palette); see Pixel & animation. The editors in separate pages (Textures & terrain, World builder, Audio workshop) are covered in their chapters.

MCP tools

The workspace tools drive the running desktop app. If it is not running, they start the bundled app without showing it.

• studio_status: active editor, loaded editors and asset shelf.
• studio_switch: switch to a named editor.
• workspace_dock: open, close, split, move, float, set bounds, focus, minimize, restore, maximize or cascade windows. Utility panels are $tools, $project and $bottom; bounds are in workspace pixels.
• workspace_layout: read or replace the complete layout, including floating windows back to front and the maximized group.
• workspace_window: show or hide the bundled editor window.
• workspace_commands: list every setting, action and file control of an editor with stable IDs.
• workspace_execute: set named settings and run a named action.
• workspace_import: load local files into an editor's file control.
• workspace_file_job: inspect or finish a pending export.
• workspace_save / workspace_open: save or restore one editor's complete state as JSON.
• studio_inspect, studio_click, studio_fill, studio_select, studio_canvas: inspect and operate editor controls and canvases.
• studio_capture: capture the workspace as PNG.
• studio_publish: add a local image to the asset shelf or send it to an editor.
• studio_workspace_state: read or replace an editor's structured state.
• studio_capabilities: list tool categories and automation coverage.

Troubleshooting

A window is lost off-screen or behind others

Choose it in the Windows… list, or press Cascade. For a desktop window, use Gather.

"This panel stays in the main workspace."

The Overview and the shared panels cannot move to another monitor. Move an editor instead.

"The detached editor did not finish loading."

The desktop window did not get ready within 45 seconds. The editor stays in Studio; try again.

"Utility panels keep their own windows."

The Tools, Inspector/Assets and bottom panels cannot be docked into an editor group.

"At most eight simultaneous editor docks are supported." / "At most 48 floating panels are supported."

Close or merge docks or windows first.

"Recovery could not be written. Close without saving this workspace?"

Studio could not write its recovery copy while closing. Choose Cancel and save the project yourself, or confirm to close anyway.

Keys do nothing in an editor

Editor shortcuts need the editor's canvas or panel to have focus. Click the canvas first. Shortcuts are ignored while you type in a field.

Open and save

Save project

1. Type a name in the project name field in the header (optional).
2. Press Save project or Ctrl+S.
3. Choose a location. The suggested file name is the project name with .isberg added; characters other than letters, digits, spaces, hyphens and underscores are dropped.

Save project asks for a location every time, so it also serves as "Save as". After a save the header reads Saved locally. Each save first collects the latest state from every editor, including editors on other monitors, and finishes any pending history entries.

• The file is written to a temporary file, verified, and only then moved over the destination. If saving fails or is cancelled, the previous file is kept.
• Several saves to the same file run one after another in the order you started them.

Open project

Press Open project and choose the file. It opens .isberg projects, projects saved by earlier versions (.gbench, .veldryne) and older plain-JSON project files.

• Editors on other monitors are returned to Studio first.
• The project is checked completely before anything changes. The window is locked while the project is restored.
• Editors that are not in the project are reset to their initial state.
• If any editor fails to restore, your previous workspace is put back and the error is shown.

Starting a new project

There is no separate New project command. Each start of Isberg Labs begins an untitled workspace with an empty asset shelf, unless editors were left on other monitors (then the previous session's recovery copy opens; see Automatic recovery). Within an editor, use that editor's own New command (for example New in RPG Creator and Tile modeler, New from template in Level & playtest, New composition in Music & composition).

What an .isberg file contains

Not included: desktop window placements on other monitors, the license record, Studio's caches, and files you merely browsed in the FileSystem tab.

The container

• An .isberg file is a binary container: a header, a JSON manifest protected by a SHA-256 checksum, and content-addressed data blocks. Large text, large number arrays and binary data are stored once as blocks identified by their SHA-256 hash and size, so repeated history copies of the same data do not grow the file.
• The file is self-contained. It needs neither the original source folders nor Studio's block cache (Data\ProjectBlobs), and it never stores absolute cache paths.
• Opening verifies the manifest and every block, even when a matching block already exists in the cache.
• The editor documents inside keep their own version; the container is format version 2. Older plain-JSON projects remain readable.

Automatic recovery

Studio writes a recovery copy of the whole workspace every 45 seconds and again when you close the app. The copy uses the same format as a saved project and is stored as recovery\workspace.isberg in the Data folder (or your profile folder). Copies left by earlier versions (workspace.veldryne, workspace.gbench) are still found.

• With editors on other monitors at quit: at the next start the recovery copy opens automatically, before those editor windows reappear.
• Otherwise: the header shows Restore recovery. Press it to open the copy from the previous session.

When Studio starts, it first keeps the previous session's copy as recovery\workspace.previous.isberg, so the automatic saves of the new session cannot replace it. Restore recovery opens that previous-session copy. It is replaced at the next start.

• If the recovery copy cannot be restored at startup, Studio protects it: automatic saves stop replacing it, and closing reports "The previous workspace could not be restored. Open a project before replacing its recovery copy."
• If the copy cannot be written when you close, Studio asks "Recovery could not be written. Close without saving this workspace?"
• Before closing, Studio shuts down loaded Lua extensions in Pixel & animation and reports any errors.
• Some editors also keep their own autosave, such as Recover Autosaved Sprites… in Pixel & animation (see Pixel & animation).

The recovery copy travels with the portable Data folder. MCP clients can locate and restore it with workspace_recovery.

Data and Projects folders

The portable folder contains two working folders next to Isberg Labs.exe.

Data

Data is the portable profile. Keep it with the application folder to retain your settings. Projects do not depend on it, because .isberg files embed their assets.

Projects

Projects is an empty folder suggested for your projects and exports. The supplied mcp-config.json sets it as the MCP server's working folder through GAMEBENCH_WORKSPACE; see MCP server guide. Studio itself does not require you to use it.

Games you export keep their own saves inside the game's folder; they do not use Studio's Data.

Isolated profiles

Set the GAMEBENCH_PROFILE environment variable to use a different profile folder instead of Data, for example to test with clean preferences or to keep two setups apart. The folder is created if it does not exist; a relative path is resolved from the current folder. Preferences, recovery, the block cache, desktop window placement and the Pixel & animation libraries then live in that folder.

set GAMEBENCH_PROFILE=D:\Isberg profiles\testing
"D:\Isberg Labs 0.21\Isberg Labs.exe"

In PowerShell:

$env:GAMEBENCH_PROFILE = 'D:\Isberg profiles\testing'
& 'D:\Isberg Labs 0.21\Isberg Labs.exe'

Shared assets and linked revisions

Editable documents can move between editors through the asset shelf. A shared document keeps its full editable source, and each editor that uses it is linked to a revision.

1. In the source editor, press Share document. The editor's complete document is added to the shelf ("name is available in project assets.") and the editor is linked to it.
2. Open the target editor, select the document on the Assets tab and double-click it or press Use selected image. The document is converted for that editor, replaces its content and links the editor to the asset.
3. After editing in any linked editor, press Update asset. The asset's revision number goes up and every other linked editor that still holds the previous revision receives the new one.

Conflict protection

• Studio records a fingerprint of what each linked editor received. When you update an asset, an editor whose content no longer matches (because you edited it locally) is not overwritten: its edits are kept and the conflict is recorded on its link.
• Using a document from the shelf by double-click or Use selected image is an explicit replacement and overwrites the target's local edits. Undo restores them.
• Through MCP, applying an asset to an editor with local edits fails with "editor has local edits. Update the shared asset from that editor, or explicitly replace it." unless you pass force.

What can be transferred

Each conversion keeps the full source document inside the result, so a chain of conversions can always go back. Conversions report notes and warnings, which MCP returns as diagnostics. A conversion does not mean the target can run every feature of its source. For all adapter names and options, see asset_document_adapters.

Dependencies and removal

• Assets can declare which other assets they depend on (through MCP, asset_document_dependencies). Missing references are reported as warnings and dependency cycles are refused.
• Removing an asset that others depend on requires force (asset_document_remove). The Assets tab has no remove button; Undo removes a document you just shared.
• Shared documents are embedded in the project, so they do not depend on the file they came from.

Shared Undo/Redo and the History dock

All editors share one history. It records editor changes, asset shelf changes, project name changes and window layout changes as atomic steps.

• Undo and redo with the header ↶ and ↷ buttons, Ctrl+Z and Ctrl+Y (or Ctrl+Shift+Z), or the Undo and Redo buttons of the History tab.
• A step is recorded when you finish a gesture in an editor (release the mouse, change a value, release a key). Typical labels are "Edit editor", "Arrange window", "Apply style preset", "Add shared document", "Update shared document", "Use asset in editor", "Remove shared asset" and "Import editor preset".
• A change that touches several editors (such as an asset update that reaches linked editors) is one step.
• If an operation fails, every editor it touched is put back. If an undo fails part-way, the editors already restored are rolled back and the history position is unchanged.
• The history keeps at most 120 steps and 128 MB; the oldest steps are dropped first. The History tab shows the current size.
• The history, including the redo branch, is saved with the project and restored when you open it.
• Editors on other monitors take part in the same history.

Bundles, archives and ZIP

Project bundles (.isbundle)

A bundle packs a project folder of ordinary files into one hashed JSON file, for example to hand a set of exports and sources to another computer. Bundles are created and unpacked through MCP:

• project_pack packs a folder (or an explicit list of files) into an .isbundle. Every file is stored with its size and SHA-256 hash. Limits: 2,000 files, 192 MB of source data, and a folder scan of at most 20,000 entries (supply a file list for larger folders). Only regular files are included.
• project_unpack checks every path and hash before it writes anything. Existing files are only replaced with overwrite. Bundles named .gbundle from earlier versions still unpack.

A bundle is not a Studio project; use .isberg for the workspace itself.

Project data blocks

workspace_project_archive inspects an .isberg file and imports or exports individual content-addressed data blocks as local files, without sending their bytes through MCP.

ZIP and PCK archives

• archive_inspect and archive_extract_zip read local ZIP and ZIP64 archives with stored, Deflate or Zstandard entries, UTF-8 and CP437 names and self-extracting prefixes. Large archives stream from disk instead of loading into memory.
• Passwords you supply decrypt traditional ZIP encryption and AES (128, 192 or 256-bit). No password search is attempted, and passwords are not logged.
• Extraction refuses unsafe paths (traversal, absolute, device or stream paths), duplicate destinations, symbolic links and existing files, and verifies each file's size and checksum before it is written. Defaults allow up to 1 TiB per entry and in total. Split archives must be joined first; unsupported compression or proprietary encryption is reported, not guessed.
• archive_extract_pck and archive_stage_project read engine PCK packs (versions 1 to 3, also embedded in executables) and stage a folder, ZIP or PCK as a project. Executables are never launched and scripts are not run during extraction.
• Game runtime opens a project folder, project.godot, ZIP or PCK directly. See Game runtime.

The ZIP files that editors export are listed in Archives.

File extensions

Isberg Labs writes its documents with the Isberg extensions below. Every reader also accepts the names used before 0.20. Reference-tool files (such as Aseprite or Laigter files) are import-only; see Isberg documents and import-only formats.

Save dialogs check typed file names: an Isberg document must keep its own extension, an Isberg extension cannot be used for another kind of file, and reference-tool extensions are refused for output. Files you exported earlier are never renamed or deleted. Other editors save descriptive JSON documents, such as .scene3d.json, .level.json, .music.json and .shader-graph.json; see File formats reference.

What the portable folder includes

The portable folder is complete: it needs no installer and no separate Node.js, npm, source editor, external authoring program or API key. It bundles:

• the desktop runtime and its libraries, including a software Vulkan renderer;
• the native game engine with its .NET runtime and C# compiler, a C compiler for GDExtension libraries, Lua 5.4 and its native extension;
• the official export editor and export templates for Windows, macOS, Linux, Android and iOS, plus a portable JDK 17, Android SDK tools and bundletool;
• image libraries, format decoders (including Draco and Zstandard) and a local media encoder for OGG, FLAC, MP3 and MP4;
• the WebAssembly editor and player, and the RPG Creator player runtimes for exported games.

Isberg Labs assumes 64-bit Windows 10 or 11 with the Universal C Runtime that is part of Windows. A static audit of every bundled program file found no missing third-party libraries: dependencies are resolved only from files inside the folder, never from the system PATH or separately installed runtimes. Media Foundation is treated as an optional Windows feature (absent on Windows N and KN editions unless you add the Media Feature Pack).

Exported Windows games are self-contained too. A JavaScript game can read and write only its own Data\Saves\game.json (at most 16 MB). Web-only exports keep saves in the browser's local storage, which persists only for the same browser profile and address.

MCP tools

• workspace_project_save / workspace_project_open: save or open the whole project; large assets never travel through the MCP response.
• workspace_project_begin / workspace_project_job: start a save or open in the background, poll its progress or cancel it.
• workspace_project_archive: inspect an archive; import or export a data block.
• workspace_recovery: locate and optionally restore the recovery project.
• studio_project_state: read or replace the complete project state.
• workspace_history: inspect, undo, redo or clear the shared history.
• asset_documents: list shared assets, revisions, links and dependency warnings.
• asset_document_publish: share or update an editor's document.
• asset_document_apply: open an asset in an editor, with adapter options and optional force.
• asset_document_adapters: list conversion routes and their options.
• asset_document_import / asset_document_export: load an editor-state JSON file as an asset, or write an asset to a file.
• asset_document_dependencies: set dependencies; refuses cycles.
• asset_document_remove: remove an asset.
• project_pack / project_unpack: create or unpack .isbundle files.
• archive_inspect, archive_extract_zip, archive_extract_pck, archive_stage_project: inspect and extract ZIP and PCK archives.

Troubleshooting

"This is not a compatible project."

The file is not an Isberg project (or is damaged). Check that you chose an .isberg, .gbench or older project file.

"Unknown project workspace: …" or "Unknown layout workspace: …"

The project refers to an editor this version does not have. It was probably written by a different version.

"Project manifest checksum mismatch." or "Project archive is truncated."

The file was damaged or only partly copied. Use another copy or the recovery project.

"Project restore failed and rollback reported: …"

Both the project and the return to your previous workspace failed. Do not save over your project file; restart Isberg Labs and open the project again.

"editor has local edits. Update the shared asset from that editor, or explicitly replace it."

The target editor was edited since it last received the asset. Press Update asset in that editor to keep its version, or replace it explicitly.

"Other assets depend on this asset."

Remove the dependency first, or remove with force.

"Asset dependency cycle: …"

The dependencies you set would loop. Change them so no asset depends on itself through others.

Applying a preset

1. Open the editor you want to change and make it the active editor.
2. Press Game presets in the workspace bar. The dialog names the active tool (by its internal ID, for example "Active tool: scene3d").
3. Choose a Game type. The dialog shows the type's description and what applying it will do in this editor. Choosing a type alone changes nothing.
4. Enter a Seed (whole number from 0 to 4294967295; default 1).
5. Press Apply to this tool. The status line reads "Applied. Use project Undo to restore the previous state."

• A preset changes only the active editor. Other editors keep their content, and each editor can carry a different game type.
• The application is one shared-history step named "Apply style preset". Undo restores the previous state.
• The applied recipe (editor, game type, seed and recipe version) is stored with the editor's document and saved in .isberg projects. When you reopen the dialog, it shows that editor's last applied type and seed.
• On the Overview, and in RPG Creator, the button reports "Open a tool to choose its game presets." RPG Creator has its own editable starter adventure and blank projects instead; see RPG Creator.

The ten game types

Each type also defines a four-color palette, movement and jump speeds, surface roughness and metalness, a preview resolution and a fog amount. Dungeon crawler, Survival horror and Stealth count as low-light types, which several editors use for darker lighting. Some editors show slightly different names: the Level editor uses Strategy, Racing circuit and Puzzle exploration, and World builder uses Puzzle / adventure.

What each editor does

These are the nineteen editors with presets and what Apply to this tool changes. "Replaces" means the editor's current content is replaced (Undo restores it).

Seeds

• The seed makes generated content reproducible: the same game type, seed and recipe version create the same result. Change the seed to get a different variation.
• The shared dialog accepts whole numbers from 0 to 4294967295 (default 1). Anything else is refused with "Seed must be an integer from 0 to 4294967295."
• Seeds matter most where content is generated: World builder, Level & playtest, Game runtime and the four audio editors. Avatar stage uses it for blink timing, and JavaScript stores it in the configuration module. Editors that only change palettes or settings ignore it.
• The World builder's own panel accepts text seeds of up to 128 characters (default gamebench-1); the Level editor's Generation seed field is also text.

Exporting and importing presets

The Game presets dialog has three file actions.

• A preset file belongs to one editor. Importing it into another editor fails with "This preset belongs to editor. Open that tool before importing."
• Files larger than 64 MiB are refused ("Preset exceeds 64 MiB. Use a project archive for larger documents."). Use a full project for large documents and for Game runtime projects, so their referenced assets are embedded.

Audio presets and delivery

Audio workshop, Sound designer, Parameter sound and Music & composition each have a Game style & delivery panel with more control than the shared dialog. See Audio for the editors themselves.

• The shared Game presets dialog uses the interface event for the three sound editors. Use the editor's own panel to pick another event.
• Styles change oscillator choice, pitch motion, harmonic intervals, envelopes, filtering and space. Audio workshop's library additionally offers 80 editable game-event entries (ten types × eight events).
• Delivery processing removes the DC offset, converts the sample rate when needed and applies short edge fades (3 ms, or 10 ms with Taper loop edges).
• Parameter sound keeps its own 22.05/44.1 kHz and 8/16-bit controls and legacy setup behavior; the delivery export converts its rendered audio to the chosen format. A higher bit depth cannot recover detail the source already lost.

Music presets and stems

Music presets create editable Foundation, Exploration and Action tracks with genre-specific tempo, notes, rhythm and timbre. In Music & composition, Export synchronized stems ZIP renders the mix and each audible track with a common start, sample rate and length, honoring mute and solo, without per-stem normalization, and includes the composition and a timing manifest (game-music-stems.zip). Cancel render stops it.

Level layouts

The Level & playtest editor generates real geometry, movement settings, pickups, checkpoints and a goal. Its controls are Game style (the list shows the type IDs, such as retro-platformer), Generation seed (default 1), Difficulty (relaxed, standard or challenging; default standard) and Layout scale (0.75 to 2; default 1), followed by Generate game layout. The four neutral templates (blank, platformer, landscape, interior) remain under New from template.

• Generation is undoable. Seed, difficulty, scale and recipe version are saved in the level and survive saving, opening and export.
• The same recipe, seed, difficulty and scale recreate the same level. Seeds vary scenery and cover placement. Difficulty adjusts movement speed and how close you must get to objectives and checkpoints; Retro platformer, Dungeon crawler, Sci-fi shooter and Stealth also change route geometry or obstacle count.
• Checkpoints and goals activate when you come near them in local playtest. Each has a radius and a list of required objects (pickups collected, checkpoints activated, goals completed). Respawn returns you to the last checkpoint and restores health and stamina; falling out of the world does the same. A new playtest resets progress.
• Generating a layout switches to local playtest. The native engine playtest does not implement these checkpoint and goal components; write equivalent scripts in the native project.
• Check level inspects spawn clearance and support, missing, inactive, self-referencing or cyclic requirements, triggers inside colliders, unresolved objects, object and collider budgets, and shapes that use simplified box collision. Export check report saves the result as level.preflight.json (units in metres, Y up).

See Level & playtest for the editor.

World builder styles

World builder has its own preset bar above its four map editors (Town, Buildings, Terrain and Floor plan): Game style, Seed, Generate game preset, Undo preset, Save editable world and Open editable world.

• Generate game preset replaces the active map editor's map. The other three editors keep their work. The shared Game presets dialog does the same for the active map editor.
• Undo preset restores the map from before the last generation, including its edited native state. It keeps one step.
• Town recipes change settlement layout, street density, curvature and width, connectivity, terrain, water, vegetation and map presentation.
• Buildings recipes change district type, zoning, architecture, density, wear, scene lighting and streets.
• Floor plan recipes change dimensions, footprint, floor and basement counts, difficulty, encounters, resources, doors and room vocabulary. Cozy simulation turns combat encounters off.
• Terrain recipes generate distinct terraces, valleys, craters, arenas, marshes, compounds, meadows, tactical terrain, circuits and islands on a fixed two-metre height grid in metre coordinates. Starter roads are graded; Racing includes a closed route; Strategy / tactics has opposing approaches and objective labels (labels only: no teams, navigation or scoring). Height grids, surfaces, props, roads and labels stay editable.
• Save editable world writes all opened map editors, their generated geometry and recipe seeds to gamebench-editable-world.json. Open editable world checks the file and its terrain grid before restoring it. Full project saves include the same data. The per-editor PNG, SVG and OBJ exports do not contain the editable recipe.

See World builder for the map editors.

Limits

MCP tools

• workspace_game_presets: list the game types and their effect in all nineteen editors.
• workspace_game_preset_apply: apply a type to one editor with workspace, style and an optional seed; the same undoable operation as the dialog.
• level_create: create a level from a template or a game style with seed, difficulty and scale.
• level_preflight: check a saved level and optionally write the report.
• world_editor_state: read or replace a map editor's native state.

Layout and workspaces

Open the editor from the studio's Pixel & animation workspace (▦). Its top bar holds the menu bar (File, Edit, Sprite, Layer, Frame, Select, View, Filters, Help), a row of mode buttons, and the ⌘ command palette button.

Mode buttons

Each mode button switches the whole editor view. Everything you build in a mode ends up in the Editor as a document tab.

Editor layout

• Toolbar (left): tool buttons, a block of view toggles, and the primary (left-click) and secondary (right-click) color swatches. See Drawing tools.
• Context bar (above the canvas): the active tool's options on the left; Symmetry, Tiled, ◐ Onion… and ▦ Grid… on the right. While a selection is floating it also shows ⇋, ⇵, Transform…, ✓ and ✕.
• Document tabs: one tab per open sprite. See Documents, tabs and saving.
• Canvas and the status bar: cursor position, sprite size with frame n/N, zoom (plus the pixel ratio when it is not square), the color under the cursor, and status messages.
• Timeline (bottom): frames, layers, cels and tags. Drag its top edge to resize it. See Timeline.
• Panels (right), in this order: Palette, Layers, Color, Body parts (anatomy fix), Fix & clean, Animation, Textures, Tilemap, Slices, Style library, History, Analyze. Click a panel title to collapse or expand it; the editor remembers which panels are open. Animation, Tilemap, Slices, Style library, History and Analyze start collapsed.

Command palette

Open it with Help > Command palette (Ctrl+Space) or the ⌘ button. Every menu item is also a command named Menu: Label (for example File: Export As…), and so are tools, palette actions and commands that have no menu entry. Type words to filter, use ↑/↓ to choose and Enter to run.

• Start the text with = to evaluate an arithmetic expression.
• Start it with > to run JavaScript against the editor (ctx, C, ed). This is trusted local code with full access to the editor.

Help > Developer tools (F12) reminds you that F12 opens the developer console.

Documents, tabs and saving

New sprites

File > New… (Ctrl+N) asks for Width (default 64), Height (default 64), Color mode (rgb, indexed, grayscale) and Pixel ratio (1:1, 2:1, 1:2). An indexed sprite takes the current palette.

Document tabs

• Each tab keeps its own document, undo history, frame and layer, selection, zoom and pan. A dot (•) marks unsaved changes; undoing back to the saved state clears it.
• Click a tab to activate it, middle-click or click × to close it, and drag tabs to reorder them. The mouse wheel scrolls the strip.
• + or a double-click on empty strip space runs File > New….
• File > Close (Ctrl+W) and Close All (Ctrl+Shift+W). View > Next document tab (Ctrl+Tab) and Previous document tab (Ctrl+Shift+Tab).
• Closing a tab with unsaved changes asks Don’t save, Cancel or Save. Quitting asks the same for each changed tab; Cancel stops the quit.
• Closing the last tab opens a fresh 64×64 Untitled sprite. An untouched, blank Untitled tab is replaced by the next document you open.

Opening files

• File > Open… (Ctrl+O) opens any supported file in a new tab. If the file is already open with unsaved changes, that tab is shown instead.
• File > Open Recent… picks from the last 12 files.
• Drop one file on the window to open it. Drop several images to import them as one animation (100 ms per frame, aligned top-left).
• Import warnings (for example about an embedded profile) appear as a toast for a few seconds.

See Opening and importing for every format.

Saving

• File > Save Project (Ctrl+S) writes the editable .isbsprite document: layers, groups, frames, cels, tags, slices, palettes, tilesets, metadata and precision planes. If the tab came from a PNG or another format, you are asked for a new .isbsprite path.
• File > Save Project As… (Ctrl+Shift+S) always asks for a path.
• Older .gbsprite and .pforge documents still open. Aseprite .ase/.aseprite files open but cannot be written; save them as .isbsprite.

Live reload

Open files are watched. When a file changes on disk (for example, an MCP tool wrote it) its tab reloads and the toast reads “Reloaded — file changed on disk (Ctrl+Z to undo)”. The reload is one undo step.

Sprite properties and pixel ratio

Sprite > Properties… (Ctrl+P) shows the size, frame and layer counts and color mode, and lets you edit Pixel aspect ratio, Grid width, Grid height and User data (a plain text string).

Sprite > Pixel ratio sets 1:1 (square pixels), 2:1 (wide pixels) or 1:2 (tall pixels). The canvas stretches pixels on screen; the image data stays one pixel per pixel. The change is undoable.

Undo and history

Edit > Undo (Ctrl+Z) and Redo (Ctrl+Y or Ctrl+Shift+Z). The History panel lists Initial state and every step with its time; click a step to jump to it, or use its ↶ and ↷ buttons. Edit > Undo history… opens the panel.

Autosave and recovery

• Every changed tab is autosaved for crash recovery, by default every 2 minutes. File > Autosave Settings… sets Every N minutes (0 = off).
• Recovery files live in the Data\recovery folder of the portable profile. The 20 most recent sessions are kept. Saving a document deletes its recovery file.
• If recovery files exist at startup, a card titled “Recover unsaved work?” appears. Restore opens a sprite as a new untitled tab; Delete removes that file; Delete all empties the recovery folder; Later closes the card. File > Recover Autosaved Sprites… shows the card again.

Canvas and view

Zoom and pan

• Mouse wheel zooms around the cursor; Shift+wheel pans horizontally.
• View > Fit to window (0), Zoom in, Zoom out. The Zoom tool (Z) zooms in on click and out on right-click or Alt+click.
• Pan with the middle mouse button, by holding Space and dragging, or with the Hand tool (H). Tapping Space without dragging plays or stops the animation.

Grids and snapping

• View > Toggle pixel grid (#) and Toggle tile grid (Ctrl+').
• View > Grid settings… (also ▦ Grid… in the context bar): Width and Height (default 16), Offset X, Offset Y, Color (hex) (default #ffffff), Opacity % (default 22) and Show tile grid. The tile grid is stored in the document.
• View > Snap to grid (Shift+') snaps shapes, selections, moves and reference placement to the tile grid.
• Select > Selection as grid turns the current selection rectangle into the tile grid.

Symmetry

Choose Symmetry in the context bar: off, horizontal, vertical, both, diagonal /, diagonal \, both diagonals or all (8-way). The View menu offers the same modes except both diagonals, plus Symmetry: reset axis to center. Drawing tools, fills and shapes are mirrored. Drag the axis handle above or beside the canvas to move an axis; it snaps to half pixels.

Tiled mode

Tiled in the context bar, or View > Tiled mode: none, x, y or both, wraps drawing across the chosen edges so you can paint seamless tiles. The paint bucket also works outside the canvas in tiled mode.

Palette lock

View > Snap colors to palette (palette lock) (toolbar 🎨) snaps every drawn color to the nearest palette entry. Indexed sprites always snap to their palette.

Onion skin

View > Toggle onion skin (F3) shows neighboring frames. View > Onion skin settings… (or ◐ Onion…) sets:

Preview window

View > Preview window (F7) opens a floating, resizable animation preview. View > Preview: follow current frame (Ctrl+F7) toggles following.

• Title bar: − and + zoom (1–64×), fit, × close.
• Bottom bar: play/pause, follow (plays the tag under the current frame and mirrors the main playback), a tag selector used when not following (all (tags), all frames or one tag), and the frame counter.
• The wheel zooms. Position, size, zoom and follow state are remembered. Playback uses the timeline speed and honors tag repeats.

Drawing tools

Tools that share a toolbar button form a group. Click a group button to use its last tool; right-click it, or hold it down, to open a fly-out with the other tools. The active tool's options appear in the context bar and are remembered between sessions. Tool keys are defaults: you can change them in Keyboard Shortcuts.

Mouse and modifier rules

• The left button uses the primary color; the right button uses the secondary color.
• Shift+click with the pencil, eraser, blur or jumble draws a straight line from the last point.
• X swaps the primary and secondary colors.
• Enter commits a floating selection or finishes a polygon or curve; Esc cancels or deselects.
• Drawing is refused on a hidden or locked layer (or one inside a hidden or locked group), on a reference layer, and on high-precision documents. The status bar says why.

Toolbar toggles

Tool options

Brush, ink, trace and “Only on” options are described in Brushes and inks. The other options are:

Brushes and inks

Brush

• Edit > New brush from selection (Ctrl+B) captures the opaque pixels of the selection or floating selection as a custom brush.
• Edit > Flip brush horizontal, Flip brush vertical, Rotate brush 90° and Reset brush (circle, size 1). With a custom brush the context bar shows ⇋, ⇵ and ⟳ buttons.
• Brush slots: the Slots… menu next to the brush, or Alt+1…9 to recall and Ctrl+Alt+1…9 to save. Slots, including custom image brushes, survive restarts.

Ink

Ink decides how the tool color is applied. Opacity (0–255, default 255) scales it.

Only on

Only on limits where a stroke paints: everything (default), color… (only pixels of the color you pick next to it), opaque px or empty px. An active selection also limits every stroke.

Trace, stabilizer and dynamics

Pencil and eraser have all of these options. Blur and jumble have brush, size, angle and opacity. Shapes and lines have brush, ink and “Only on”.

Selections and transforms

Making selections

• Use the marquee, lasso, polygonal lasso and magic wand tools. Hold Shift to add, Alt to subtract, Ctrl+Shift to intersect; otherwise the tool's Mode applies.
• Ctrl+click a layer row in the Layers panel to select that layer's opaque pixels (Ctrl+Shift+click adds them).

Moving and transforming

• Drag inside a selection to lift and move its pixels (Ctrl with the selection tools, or Alt with the Move tool, moves a copy). The arrow keys nudge the selection by 1 pixel, or 8 with Shift; with the Move tool and no selection they nudge the whole cel.
• Edit > Transform selection (Ctrl+T) shows handles. Drag a handle to scale (Shift keeps the ratio), drag just outside a corner to rotate (Shift snaps to 15°), and drag inside to move. Enter or ✓ commits; Esc or ✕ cancels.
• Edit > Transform selection (numeric)… or Transform…: Scale X %, Scale Y %, Rotate (°), Flip horizontal, Flip vertical.
• Edit > Flip selection horizontal and Flip selection vertical, or ⇋ and ⇵ in the context bar.
• Scaling is nearest-neighbor. Rotations by multiples of 90° are exact; other angles use RotSprite when you release the handle (a fast preview is shown while dragging).
• Switching to a drawing tool commits the floating selection.

Fill, stroke and clear

• Edit > Fill selection (FG) (Alt+Backspace) and Stroke selection (FG) use the primary color.
• Edit > Clear selection (Del) erases the selected pixels.

Clipboard

On indexed sprites the clipboard keeps native palette indices, and on tilemap layers it keeps tile IDs and flips. See Indexed clipboard and Tile clipboard.

Flip and shift pixels

These act on the current cel, inside the selection rectangle if there is one. Shifting wraps pixels around the edges.

Whole-sprite transforms

These Sprite menu items change every frame and layer (and slices) in one undo step and clear the selection.

Layers and groups

The Layers panel lists layers top to bottom. Its header has Blend and Opacity (0–255) for the active layer. Each row has an eye (visibility; Alt+click solos the layer), a lock, a chain for continuous, the name, and badges: REF (reference), BG (background), the blend mode when it is not normal, and the opacity when it is below 100%. A colored left border shows the layer's color tag. Double-click a name to rename it; drag rows to reorder; right-click a row for its menu.

The buttons below the list are + (new layer), +▤ (new group), ⧉ (duplicate), 🗑 (delete), ↑ and ↓ (move), ⤓ (merge down), ⚙ (properties) and ☰ (more).

Layer menu

Alt+↑ and Alt+↓ select the layer above or below. The row menu adds New group from layer, Remove from “group” and a Color tag list.

Blend modes

normal, multiply, screen, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, exclusion, hue, saturation, color, luminosity, addition, subtract, divide.

Groups

• Groups can nest and can be empty. Group rows have their own eye, lock, collapse caret (▸/▾) and member count. Drop a layer onto a group row to move it into the group.
• The group menu: Rename group…, Duplicate group, Expand/Collapse, Show / hide group, Lock / unlock group, Merge group into one layer, Ungroup, Delete group and its layers.
• Hiding or locking a group affects its children without changing their own flags. Collapsing hides its rows.
• Sibling groups may share a name, have an empty name or contain slashes; each group keeps a stable identity that survives renames and .isbsprite saves.
• Ungroup moves the immediate children up one level. Merge group into one layer bakes the group's composite once. Duplicating creates an independent copy and keeps links between frames inside the copy.
• A group composites its children in isolation, and cel z-order is bounded by the group.

Timeline, frames, cels and tags

The timeline shows tags on top, then frame headers, then one row per layer (groups have collapsible rows). Each cell is a cel. Linked cels (one image shared by several frames) are drawn joined. Drag the top edge to resize the timeline.

Controls

• ⏮ first, ◀ previous, ▶ play/stop, ▶| next, ⏭ last; a speed selector (0.25× to 3×); and the checkboxes once (stop at the end), all (ignore tags) and rewind (return to the start frame on stop, on by default).
• Buttons for new frame, new empty frame, delete frames, frame properties, new tag, and ☰ for the frame menu.
• Playback plays the tag under the playhead in its direction and repeat count, unless all is on.

Mouse

• Frame header: click to go there, Shift+click to select a frame range, double-click for frame properties, drag to move frames.
• Cel: click to select; Shift+click to select a cel range; drag a selected range to move cels, Ctrl+drag to copy, Alt+drag to link (links only within one layer). Right-click for the cel menu.
• Tag: click to select its frames, double-click to edit, right-click for Tag properties…, Select tag frames, Play this tag, Direction: … and Delete tag.

Frame menu

Keys: Space play/stop, ← or , previous frame, → or . next frame, Home first, End last. (Arrow keys nudge instead while something is selected or the Move tool is active.)

Tag properties

Name, From frame, To frame (1-based), Direction (Forward, Reverse, Ping-pong, Ping-pong reverse), Repeat (0–999; 0 = ∞) and Color.

Animation helpers

The Animation panel generates and checks frame sets. Most buttons work on the active layer across all frames; generators open a new document.

Timing presets

Frame > Create action from preset… offers the same presets.

With a different frame count, durations are resampled from the preset. LPC sheet export is described in LPC sheets; APNG timing in Animated PNG.

Palettes and color

The Palette panel shows the palette used by the color tools and stored in the document. Palette edits are undoable. The starting palette is endesga-32.

Palette panel

• Swatches: click sets the primary color, right-click the secondary color, Ctrl+click or Shift+click selects entries, double-click edits, drag reorders. Hover shows the index, hex value and role name.
• The Load palette… selector lists the built-in Presets (pico-8, sweetie-16, endesga-32, gameboy, nes, resurrect-32, grayscale-4) and your Saved palettes.
• Buttons: + add the foreground color, ✎ edit the selected entry, 🗑 delete selected entries, ⇅ sort, ◐ gradient between selected entries, ⇄ reverse, Ramp hue-shifted ramp generator, Used select colors used in the sprite.
• A warning appears when the primary color is not in the palette, with an Add button. The footer shows the color count and the sprite's color mode.

Palette menu (☰)

The same actions are available as Palette: … commands in the command palette, including Palette: Sort by hue and the other sort keys.

Color panel

• FG and BG chips choose which color you edit. A saturation/value square and a hue strip, plus R, G, B (0–255), H (0–359), S%, V% and Hex fields. + palette adds the color.
• Harmony: complementary, analogous (default), triadic, split-complementary, tetradic, monochromatic.
• Tints · shades · tones: 7 steps each toward white, black and gray.
• Click a swatch to use it, right-click to set the background, Shift+click to add it to the palette.

Color modes and indexed color

Converting color modes

Sprite > Color mode… (also Color mode: RGB, Color mode: Indexed…, Color mode: Grayscale…) converts every cel of every frame. Linked cels stay linked, off-canvas pixels and cel positions are kept, and the change is one undo step.

Tile images and their metadata are converted together. When a frame palette produces a different converted tile, a tile variant is appended and only the affected placements are remapped.

Exact palette indices

An indexed sprite stores a palette index for every pixel, not just a color. The editor keeps those indices exact:

• Clicking a swatch selects that exact entry. A stroke in that color records its index, so two palette entries with the same RGBA value stay distinct. The eraser writes the transparent index.
• Editing a palette entry with Recolor pixels changes only pixels that use that entry. Pixels whose index is ambiguous are reported and left unchanged.
• Frame-specific palettes (from Aseprite or APNG imports) are kept per frame. Linked cels share their pixels while each frame keeps its own palette.
• Opening an indexed PNG (1, 2, 4 or 8 bits, any filter, interlaced or not) keeps duplicate and unused palette slots, per-entry transparency and the exact index of every pixel.
• For typed index edits without the UI, use pixel_indexed_edit or Lua.

Indexed clipboard

On indexed sprites, Copy, Cut, Paste, Paste as new layer, Paste as new sprite, moving, duplicating, flipping, quarter turns, nearest-neighbor resizing and RotSprite rotation all carry the index plane, not just colors.

• Paste replaces the destination index for each copied pixel, except the transparent index. It never blends palette colors into a third color. The Transparent BG while moving option skips pixels matching the secondary color.
• Pasting into another indexed cel requires matching palette slots (names may differ) and compatible transparent-index use; otherwise the paste is rejected without remapping. Paste as new sprite keeps the source palette. Copy merged always makes a plain RGBA clipboard.
• Copying pixels that have no stored index works only when each color matches a single palette entry. Otherwise use Copy merged or convert the cel to indexed first.
• A background layer has no transparent index, so cut, move and clear are rejected there until you convert it to a normal layer.
• Pasting into an RGB or grayscale sprite uses ordinary RGBA; the status bar says so, and the clipboard keeps its indices for later indexed pastes.
• An image copied from another application replaces the indexed clipboard data.

Color profiles

Color management uses the bundled Little CMS engine; no separate install is needed. PNG files keep their ICC, gamma and related color information when opened, and the stored channel values are not converted on import. When a sprite has an assigned ICC or gamma profile, the main canvas displays its colors through that profile.

Sprite > Color profile… has two fields:

• Conversion changes cel pixels, frame palettes, tilesets and off-canvas pixels, preserving alpha and indexed identity. It is one undo step. A converted grayscale sprite becomes RGB.
• Conversion targets must be RGB ICC profiles. A grayscale ICC profile can only be assigned to a grayscale sprite.
• On export, PNG files are tagged with the assigned ICC or gamma profile without converting stored values; JPEG, WebP, TIFF and AVIF embed the RGB ICC profile; GIF, SVG and CSS exports convert to sRGB first. WebP and AVIF need an RGB profile.

High precision (16-bit and HDR)

Opening a 16-bit PNG or APNG, or a supported OpenEXR file, creates a high-precision sprite. Its authoritative samples are stored separately from the 8-bit preview you see on screen:

• Unsigned16: exact integers 0–65535 in the source encoding.
• Float32: linear sRGB, finite RGB within ±65504 and alpha 0–1.

Undo, .isbsprite saves, linked cels, layer and cel opacity, visibility, z-order, groups and the blend modes normal, multiply, screen, addition, subtract, darken and lighten work on the exact values.

Precision dialog

Sprite > Precision — 16-bit / HDR… On an ordinary sprite it offers only Enable high precision (promotion cannot invent precision that was not in the source). On a precision sprite, Operation offers:

Storage chooses Unsigned16 encoded channels or Float32 linear-sRGB HDR when enabling. The operations act on the current frame and layer.

Formats

• PNG/APNG import decodes every non-indexed 16-bit color type, all filters, Adam7 and transparent keys; APNG blending and disposal are composed on the 16-bit planes.
• PNG16 export writes the current frame. It rejects values outside the chosen encoding instead of clamping. PNG cannot store float samples.
• OpenEXR import accepts single-part, uncompressed scanline RGBA in HALF or FLOAT with linear sRGB/Rec.709 primaries and matching zero-origin windows. Export writes uncompressed FLOAT32 RGBA. EXR uses premultiplied alpha; the editor converts it.

Reference images

• File > Import as Reference Layer… or Layer > New Reference Layer from File… adds the first frame of an image or sprite as a reference layer at the bottom of the stack, named Reference: <file>, at 160/255 opacity. It is scaled to fit and centered on every frame.
• Reference images keep their full source resolution and fractional placement. Select the reference layer and use the Move tool: drag to move, drag the bottom-right handle to resize (Shift keeps the aspect ratio). No resampling happens.
• Layer > Reference cel bounds… sets X, Y, Width and Height exactly, in steps of 1/65536 pixel.
• Any layer can become a reference with Toggle reference layer.
• You cannot draw on a reference layer. Reference layers are shown while editing and picked by the eyedropper (Sample: composite), but they are left out of onion skin and of every image and sheet export.

Tilesets and tilemaps

There are two places to work with tiles. The Tiles mode is a standalone tileset and map workshop. Tilemap layers bring tiles into an ordinary sprite in the Editor, where you draw with the tile brush.

Tiles mode

The left panel builds the tileset, the center is the map, and the right panel shows the tileset palette. Tiles mode has its own undo (Ctrl+Z, Ctrl+Y, 100 steps). Its tileset and map are kept only while the app runs: export them, or store them in a sprite with Tileset → editor or Save into doc.

Map tools: ✎ Paint (B), ⌫ Erase (E), ◩ Fill (G), ▦ Auto (A), ⌖ Pick (I); flips ⇋ X (X), ⇅ Y (Y) and ⤡ D (D, square tiles only); Auto set; grid; Fit (0). Left button paints, right button erases, middle button or Space pans, the wheel zooms (1–32×). In the tileset palette, click a tile to paint with it and double-click a tile of an autotile set to paint with that set; numbers shows tile indices.

How autotiles work

• Each cell painted with the Auto brush remembers its terrain set, and its tile variant follows the neighbors of the same set. A 16-tile set looks at 4 edge neighbors; a 47-tile blob set looks at 8 neighbors, where a corner counts only if both adjacent edges connect. The map border and other sets count as “not connected”.
• Generated variants get a bevel highlight on exposed top and left edges, a shadow on bottom and right edges, a darkened outline and cut corners; the 47 set also shades inner corners.

Tilemap layers

• Layer > New tilemap layer…: Name, Tileset (New empty tileset, the Tiles mode tileset, or an existing one), Tile width and Tile height (1–256). An existing tileset's tile size wins.
• Layer > Convert layer to tilemap…: tile size, Tileset (New tileset or existing), Reuse flipped tiles (X / Y / diagonal) (on). Every cel is cut into tiles; identical and flipped tiles are stored once.
• Layer > Convert tilemap to normal layer keeps the rendered pixels and drops the tile data.
• Tile 0 is always the empty tile. Workspace tile #n becomes layer tile n+1.

Tile brush and Tilemap panel

Select the tile brush (▦) from the toolbar or the Tilemap panel. The left button applies the current mode, the right button erases, Alt+click picks a cell's tile and flips. Painting outside the map grows it.

The Tilemap panel shows the layer, its tileset and the map size, a scrollable tileset strip (tile 0 is drawn as a slash and erases), and:

• Modes: ✎ Tile (paint the selected tile), ⌫ (erase), ⌖ (pick), ▦ Auto (autotile brush).
• Flips ⇋X, ⇅Y, ⤡D (diagonal only for square tiles).
• Auto set selector, +16 and +47 to generate a 16-tile or 47-tile blob set from the selected tile (appended to the layer's tileset).
• The pixel-edit mode, which decides what drawing pixels with any other tool on a tilemap layer does:
  • Manual: edit tile everywhere (default): editing a placed tile changes that tile in the tileset, so every placement updates. Pixels drawn on empty cells become new tiles or reuse a matching one.
  • Auto: reuse / remove unused tiles: the edited cell gets a matching existing tile or a new one, then unused tiles are deleted and IDs renumbered in every layer and frame that uses the tileset.
  • Stack: retain tiles, append edits: every edited cell gets a new tile; existing tiles never change.
• grid and → normal layer. On a normal layer the panel offers + Tilemap layer and Convert layer → tilemap.

Tile clipboard

• On a tilemap layer, Copy, Cut, Paste, moving and duplicating work on tile IDs and flips, not pixels. A selection includes every grid cell it touches; holes stay unselected. Copy without a selection takes the whole tilemap, including off-canvas cells.
• Cut and Clear selection clear placements only; the tiles themselves do not change, even in Manual mode.
• Paste snaps to the grid; drag or arrow keys move by whole cells. Selected empty cells erase the destination. Flips combine with existing flips; square tiles rotate in quarter turns and rectangular tiles in half turns.
• Within the same tileset IDs are kept. Into another tileset, each source tile is matched to an identical destination tile or appended; existing tiles are never overwritten.
• Paste as new layer creates a tilemap layer with the complete source tileset. Paste as new sprite keeps color mode, palette and tilemap.
• Use Copy merged for pixel resizing or free rotation. The system clipboard receives a PNG preview; an image from another app replaces the tile data.

External tilesets

An Aseprite file whose tileset lives in another file resolves that file when it is a relative path inside the project folder (.aseprite, .ase, .isbsprite, .gbsprite or .pforge, tile size must match), and embeds the tiles so the saved .isbsprite is self-contained. Absolute, network and parent-folder paths are refused; nesting is limited to 8 levels and cycles fail. Missing tilesets keep their IDs and produce an import warning.

Tile formats

The batch CLI can put tilesets in a sprite sheet with --export-tileset. TMX/TSX map files are not handled by this editor; see Formats & interchange.

Slices and 9-slice

A slice is a named rectangle with an optional 9-slice center, an optional pivot, a color and user data. Bounds, center and pivot are stored as per-frame keys: a key applies from its frame until the next key, and an empty key hides the slice. Slices are saved in .isbsprite files and read from Aseprite files.

Slice tool

The slice tool (⧈, Shift+C): drag on empty canvas to create a slice, drag inside a slice to move it, drag its bottom-right handle to resize it. Moving or resizing edits the key at the current frame (or creates one).

Slices panel

• The list shows each slice with badges: 9 (9-slice), ⊕ (pivot) and ◆N (N keys).
• The editor fields act at the current frame: Name and color, x y w h, 9-sl (the center rectangle, relative to the slice), pivot (relative to the slice; defaults to bottom center) and User data.
• Keys: one button per key (click to go to that frame), +key (copy the key in effect to the current frame), hide (hide from this frame), −key (delete this frame's key).
• ✎ Draw selects the slice tool, + Selection makes a slice from the selection, + New… asks for Name, X, Y, Width, Height, 9-slice center and Pivot (bottom center). Duplicate and Delete.
• 9-slice preview…, Export slices… and show (draw slices on the canvas).

Menus: Select > New slice from selection, View > Show slices, Sprite > Preview 9-slice at size…, File > Export slices….

9-slice preview

Preview 9-slice at size… asks for Width, Height and Edges / center (stretch or tile), then shows the slice scaled to that size. Open as sprite opens the result as a new document. A slice without a center is scaled as a whole.

For slice export, see Export slices.

Sprite metadata

User data

Plain-text user data can be edited on the sprite (Sprite > Properties…), on layers (Layer properties…) and on slices (Slices panel). Sprites built from PXL code store their ramps in the sprite's user data; clearing it removes those ramps from the PXL filters.

Typed properties

Sprites, groups, layers, cels, tags, slices, tilesets and individual tiles can also carry typed properties in Aseprite's native property model, either as user properties or in named extension namespaces. Aseprite imports keep them, and .isbsprite saves them losslessly.

There is no typed-property editor in the UI. Edit them through Lua (sprite.properties.category = 'player', sprite.properties('org.example.game').speed = 12; see Properties) or the MCP tools pixel_properties_info and pixel_properties_edit. A plain value written from Lua keeps the property's existing type when it fits; otherwise booleans become bool, integers int32 (or uint32), other numbers double, arrays vectors and tables maps. Unknown or malformed property maps are kept unchanged.

Repair workspaces

Grid repair, Pixelizer, Ripper and Video convert an outside image into clean pixel art. Every one is deterministic: the same input and settings give the same result. Each re-runs live when you change a setting. Send to Editor opens the result as a new single-layer document tab, and Export PNG saves it directly.

Repair workflow

1. In Grid repair, load the enlarged or blurry art and let it find the true pixel grid. Strip a fake checkerboard first if one is baked in. Then Send to Editor, or use Export report… to get a reusable recipe.
2. In the Editor, run Sprite > Auto-repair anatomy… and read the open items it reports.
3. Fix the remaining parts by hand: stamp clean hands, feet, eyes and mouths from Body parts (anatomy fix), draw limbs, mirror halves.
4. Clean up with Fix & clean (orphans, outline, pixel-perfect, Clean all).
5. Open Analyze and click Analyze + critique; fix every listed item until the verdict is SHIP.
6. Run the same recipe over a folder in Batch.

For agents, pixel_guide returns the same workflow with anatomy and animation rules.

Grid repair

Load image… accepts PNG, APNG, JPEG, WebP, GIF, BMP, TIFF and AVIF. The grid is detected on load and the found size and offsets are written into the fields; edit them to override.

The report shows the detected size, confidence, offsets, how irregular the fitted grid is, and every step. If the size is wrong, type the pixel size and offsets yourself and watch the magenta grid line up.

The Extra cleanup (pixelpipe) block adds:

Pixelizer

Turns photos, renders and illustrations into pixel art. Load image…, then:

Texture Ripper

Load photo…, then click the four corners of a surface seen in perspective (top-left, top-right, bottom-right, bottom-left); drag points to adjust. The quad is unwarped into a flat texture.

• Output width, Output height: 128 (4–2048).
• Make seamless (tileable): cross-fades each edge with the opposite edge (this adds blended colors).
• Pixelize to width (0 = off, up to 512) with Colors (16).
• Reset points; preview tiled shows the result 2×2.

Video

Load video… (MP4, WebM, MOV, MKV) samples frames, pixelizes them with one shared palette so colors do not flicker, and sends them to the timeline.

• Start (s) (0), End (s) (set to the first 3 seconds on load), Sample FPS (8, 1–30), Width (px) (96, 8–512), Colors (16), Dither (none, bayer2, bayer4), Remove background (off), Remove flicker (on).
• Extract frames samples at most 120 frames. Send to Editor opens them as one layer with frames of 1000/FPS ms. Export GIF writes a 3× enlarged GIF.

Fix & clean, anatomy and critique

Apply to

Fix & clean, the Filters and palette-swap variants share one target list: Current cel, All frames of layer, All layers (this frame), All layers & frames and, when the timeline has a range, Timeline range. Locked layers are skipped and linked cels are processed once. Fixes apply to the selection rectangle when there is one.

Fix & clean panel

Body parts

The Body parts (anatomy fix) panel builds clean parts procedurally, with exact finger counts and a 1-px outline lit from the top-left.

• Colors: Colors: from selection (select the old part first to match its colors), Colors: from whole sprite or Colors: from primary color. flip mirrors the part.
• Use stamp tool selects the Stamp tool (◈, P): click to place the part. With horizontal symmetry on, both sides are placed.
• Draw limb selects the Limb tool: drag from joint to joint. thick (3, 1–16) sets the limb width.
• Copy as spec part and Insert into spec hand the part to the Spec workspace.

Auto-repair anatomy

Sprite > Auto-repair anatomy… detects hands, feet and eyes and repairs them on the current layer. Each step has a checkbox (all on by default):

• Snap upscaled art to its pixel grid (only when a grid is detected; the result then opens as a new document).
• Isolate the subject: drop background debris and background-only colors.
• Paired parts: mirror the better hand, foot or eye onto the worse one (for symmetric sprites).
• Remove noise inside detected parts.
• Repair the outline locally around detected parts.
• Rebuild hopeless hands procedurally (automatic only for confident, paired, very noisy parts).

Options: rebuild all hands as fist or open hand, force pair mirroring, and Apply to (current cel or all frames of the layer). The live preview shows before (detected parts) and after, and the report lists each fix and each open item. Anything the tool is unsure about is left unchanged and reported as an open item; fix those by hand. Apply is one undo step.

Analyze and critique

The Analyze panel (or Sprite > Analyze) inspects the current frame. Choose as (auto, item, prop, character, boss, block, tile, scene, freeform) and click Analyze + critique.

• The verdict is ✓ SHIP when no major check fails and fewer than 3 minor checks fail; otherwise ✗ FIX, with a numbered fix list and coordinates where possible.
• Checks include: not empty, palette budget for the type, near-duplicate colors, hard alpha, isolated pixels, filler noise, edge padding, readable silhouette, outline consistency, near-symmetry, paired features level and equal, jaggies, pillow shading, banding, anti-aliasing at small sizes and 1-px anatomy. Blocks and tiles must fill every pixel and tile seamlessly.
• The report also shows size, color count, outline color, grid size and confidence, symmetry and ramps. Silhouette view shows a flat silhouette.
• Copy grid for client copies a compact palette-index text grid (sprites up to 128×128; at most 36 colors). Auto-repair… opens the repair dialog.

Style library

The Style library panel studies a reference to learn its rendering rules, never its content. Study current sprite or Study image… reports true size, colors, value range, dither share, outline share and ramps, then saves a style card under a name. Each card has Apply palette, Notes (do/don't rules such as palette size, outline style and dithering), Copy notes and ✕. Learned palettes lists the card palettes. Cards are shared with the MCP style_* tools.

Filters and textures

Filter dialogs

Each filter opens a dialog with its parameters, Apply to (see targets), Selection only (on when a selection exists; only selected pixels change) and Live preview (current frame only). OK applies to every targeted cel as one undo step. The last values are remembered per filter.

Ramp fields accept a hex list and have Palette and From FG buttons. Color fields have FG and BG buttons.

Palette-swap variants

Filters > Palette-swap variants… groups the sprite's colors into hue ramps and makes recolored variants that keep the shading. Source of new colors: hue (rotate hues) or palette (map ramps onto ramps from the current palette); Variants (6, 1–24); Hue step (°, 0 = even); Keep grays / outline (on). Click a thumbnail to preview it on the canvas. Apply recolors the sprite; Export variants… writes variant_01.png…, variants_sheet.png and variants.json to a folder.

PXL lighting filters

These apply to the current cel (or all frames when All frames is checked) and to the selection when there is one.

• Lighting (PXL)…: Lamps as x,y,r,#color,power,z; …, Ambient 0..1 (0.2), Sky light 0..1 (0), Sky color, Cell px (1), Smooth cells, Opaque pixels block light, Relief (none, dome, bevel, luma).
• Normal map from sprite (PXL)…: Shape (dome, bevel, luma), Depth (1), Bevel width (2). Opens the normal map (green up, flat #8080ff) as a new document. File > Export normal map (_n.png)… writes it directly.
• Glow (PXL)…: Glow colors (hex, comma), Radius px (6), Strength (0.5), Mode (color screens a glow color; ramp stays in the palette), Ramp steps (ramp mode) (2), Bands (0 = smooth).
• Shade / Light region (PXL ramps)…: Mode (shade/light), Ramp steps (1), Density 0..1 (1; below 1 uses Bayer dither).

Ramp-based filters use the PXL ramps stored in the sprite, then the palette's ramps, then ramps extracted from the frame.

Textures panel

The Textures panel fills the selection (or the cel) with generated texture. Fill chooses the kind; the other rows appear as needed.

• Colors takes a hex list dark to light (transparent erases, keep leaves pixels); FG+BG, Ramp ▸ (next palette ramp) and Default fill it. + part captures the selection as a part. Paint on: anywhere, opaque pixels, empty pixels or FG color.
• Apply fills the selection or cel; New sprite creates a new sprite with the texture.
• Seamless check (also View > Seamless check (shift by half)) shifts the frame by half with wrap so the borders meet in the middle; toggle it off after fixing seams. Make tileable (also Filters > Make tileable (dithered seams)) cross-fades the borders with ordered dither, adding no new colors. View > Seamless score… reports the seam ratio.
• Filters > Texture recipe… applies a recipe with Recipe, Tile size, Seed and Ramp (recipe default, Textures panel colors, from FG color). The Edit menu has Fill with noise (Textures), Fill with Voronoi (Textures), Dither fill (Textures), Gradient dither fill (Textures) and Scatter parts (Textures).

Art as code: Spec

A sprite spec is a JSON text (with // and /* */ comments allowed) that describes a sprite as shapes grouped into parts and layers, color ramps, and poses. Each part is rasterized, shaded from the light direction, outlined and colored with its ramp. Frames are pose overrides of the same parts, so animation is a clean redraw rather than resampled pixels. Specs save as <name>.pfspec.json.

Spec mode

• The template selector holds Examples (ninja, slime) and Character templates: Chibi (head 40–50%), Heroic (head 1/3–1/4), Tall tactical 48–64px (head 18–24%), Realistic (1/6–1/8 heads). Facing: front, three-quarter, side, back. New from template loads or generates it.
• Template options: hair (short, long, spiky, bald), hands (fist, glove, hand), feet (boot, shoe, bare), height in px (16–128; empty = preset default), and six colors: skin, hair, outfit, pants, accent, boots.
• Load spec…, Save spec… (keeps comments), Format (reformats; drops comments), Send to editor (opens the rendered sprite as a new document) and 4-dir walk set (renders the selected template in three facings into a document with idle_* and walk_* tags for down, left, right and up; left is the mirrored side view).
• The editor re-renders 250 ms after you stop typing. The status line shows size, frames, layers, tags and pivot, or the errors with line and column; click an error to jump to it.
• The preview has play/pause, a tag selector, zoom (zoom: fit, 4x–12x), onion, and a frame strip.

Spec format

• Tone letters: o outline, d shadow, b base, l highlight, w white, k dark/pupil, s secondary, S secondary shadow.
• Part fields: name, ramp or color, z, clip (keep only pixels inside another part), light, outline, flat, pivot, and one shape inline or shapes: [...].
• Shapes: rect, ellipse (x, y, w, h); circle (cx, cy, r); capsule (x0, y0, x1, y1, r, or a points chain); polygon, triangle (points); pixels and ascii (rows of characters: . empty, a tone letter, - erase); part (procedural hand_open, fist, foot, eye, mouth, head). Any shape can take tone or erase: true.
• Poses target a part, a layer or * (the whole sprite) with dx, dy, rotate, scale, flip, pivot, hide or any shape parameter. Values may be expressions over params such as "-bob*2" (numbers, names, + - * / ( )).
• The rendered document gets the spec's layers, frames with durations, tags, a slice named pivot and a 16×16 grid.

{
  "name": "slime", "size": [32, 32], "margin": 12, "pivot": [16, 29], "outline": "#1a1020",
  "ramps": { "goo": ["#1a1020", "#2e7d5b", "#4fbf6f", "#a6f08a"], "eye": { "w": "#f4f0e8", "k": "#1a1020" } },
  "params": { "sx": 1, "sy": 1, "lift": 0 },
  "layers": [ { "name": "body", "parts": [
    { "name": "goo", "ramp": "goo", "shapes": [
      { "shape": "ellipse", "x": 6, "y": 12, "w": 20, "h": 20 },
      { "shape": "rect", "x": 0, "y": 29, "w": 32, "h": 8, "erase": true } ] },
    { "name": "eyes", "ramp": "eye", "outline": false, "clip": "goo", "shapes": [
      { "shape": "rect", "x": 12, "y": 19, "w": 2, "h": 3, "tone": "k" },
      { "shape": "rect", "x": 18, "y": 19, "w": 2, "h": 3, "tone": "k" } ] } ] } ],
  "actions": [ { "tag": "bounce", "frames": 6, "durations": [100, 60, 80, 160, 80, 120],
    "keys": { "sx": [1.25, 0.9, 0.85, 1.0, 0.9, 1.2], "sy": [0.75, 1.15, 1.2, 1.0, 1.1, 0.8], "lift": [0, -4, -9, -11, -6, 0] },
    "pose": { "body": { "scale": ["sx", "sy"], "pivot": [16, 29], "dy": "lift" } } } ]
}

MCP: spec_render and spec_template.

Art as code: PXL

PXL is a small JavaScript-based language for pixel art, written in *.px.js files. It is evaluated locally and deterministically (seeded random, no network). One file can define many sprites, animations, scenes and sheets.

Code mode

• Code column: Open… (the file is watched and re-renders when it changes on disk), Save (Ctrl+S), Build (Ctrl+Enter), auto (rebuild 400 ms after typing), and Templates… (basics, forge, lighting, normals, shop, tackle, moon_bakery, moon_bakery_flat, moon_bakery_3d, neon_noodle_3d, outpost, cave, grotto, no_magic). Loading a template keeps your previous code; Code: Restore code replaced by a template brings it back.
• Errors read file:line:col: asset > layer > op: message; click one to jump to it. One broken asset does not stop the others.
• Assets column: each built asset with its kind (sprite, anim, scene, sheet). Send to editor opens the selected asset as a document with layers, frames, tags, palette and ramps. Export assets… writes every output to a folder.
• Preview column: zoom with the wheel (Fit), hover to inspect a pixel's palette key, and replay the build step by step (⏮ ◀ ▶ ▶| ⏭, a step slider and list). Checkboxes grid, changes, animate and follow edits. Click a palette chip to use the color.
• File > Open… on a .px.js file loads it in Code mode. Commands: Code: Build PXL (Ctrl+Shift+B), Code: Open .px.js…, Code: Send asset to editor.

pal({ k: "#1b1630", g: "#8ccf63", G: "#4c8a44", t: "#2a5560", w: "#fff6e0", r: "#e2585e", R: "#a63a4c" })
ramps("ktGg", "kRr")                   // dark -> light, drives shade()/light()

// Symmetric: write the left half, mirror it, outline it.
sprite("slime", { mx: true, outline: "k" }, `
  ....ggg
  ..ggGGg
  .ggGwGg
  gggkwgg
  gggkkgg
  tgggggg
  .tttttt`)
sprite("slime_red", { base: "slime", swap: { g: "r", G: "R" } })   // variant: 1 line

anim("bob", { base: "slime", fps: 6 }, frame(), frame(grid(4, 3, "kk")), frame({ hold: 2 }))

Language reference

Regions (where, clip) are [cx, cy, r] circles, [x, y, w, h] rectangles, longer coordinate lists (polygons) or (x, y) => bool functions.

Outputs

Export assets…, the CLI build command and pxl_build write sprites/<name>.png (plus _n.png normal maps), scenes/, anims/<name>.png strips with .json and .gif, sheets with TexturePacker-style JSON, and enlarged previews in _preview/. With layers: true each layer is also written separately. A document sent to the editor carries its ramps in the sprite's user data, which the PXL filters use.

PXL command line

From the portable folder, with ELECTRON_RUN_AS_NODE set as described in Running the batch CLI:

& '.\Isberg Labs.exe' '.\resources\app\cli\pxl.js' build '.\Projects\art.px.js' --out '.\Projects\out'
& '.\Isberg Labs.exe' '.\resources\app\cli\pxl.js' ascii '.\Projects\art.px.js' slime
& '.\Isberg Labs.exe' '.\resources\app\cli\pxl.js' list '.\Projects\art.px.js'

• build <art.px.js> [--out DIR] [--only a,b] [--scale N] [--no-preview]: writes all outputs (default folder <art file dir>\out).
• ascii <art.px.js> <name>: prints an asset's palette keys with rulers (every frame for animations).
• list <art.px.js>: lists assets, groups and sheets with file and line.
• Exit codes: 0 success, 1 build errors, 2 usage error.

Opening and importing

Formats you can open

Use File > Open…, File > Import File (any format)… or drag and drop.

Import Sprite Sheet

File > Import Sprite Sheet… cuts a sheet into frames. Choose a source with Browse… (image or Aseprite file; its first frame) or Current sprite.

The preview outlines the cells. Import opens a new single-layer RGB document; palette and indexed identity are not kept on this path (opening an indexed PNG directly keeps them).

Image sequences

• File > Import Image Sequence (files)… or (folder)… (the folder's images only, not subfolders). Files are sorted naturally (frame2 before frame10).
• Then set Frame duration (ms) (100) and Align (top-left, center, bottom). Mixed sizes are placed on a canvas of the largest width and height. Animated inputs contribute all their frames.
• A sequence of single-layer indexed PNGs stays indexed when the files share a transparent index and color profile; bottom alignment is not allowed for it.

Import as layers

• File > Import as New Layer… (or Layer > New Layer from File…) adds a layer above the current one, named after the file. Larger images shrink to fit; a single frame becomes one linked cel in every frame; an animation maps frame by frame.
• File > Import as Reference Layer… (or Layer > New Reference Layer from File…): see Reference images.
• Sheet, sequence-to-layer and layer imports refuse 16-bit and HDR sources; open those as documents.

Exporting

Exports write standard image files and never change the document. Reference layers are never exported. Reference formats (.ase, .aseprite, .pforge) are import-only.

File menu

Export As

The preview shows the first output and lists the file names. Settings are remembered.

File name tokens

The File path may contain {title}, {layer}, {tag}, {frame}, {tagframe}, {group}, {index}, {duration} and {extension}. Digits set padding and start: {frame001} counts 001, 002…; {frame00} counts 00, 01…. Without tokens, still formats with several images get the frame index appended. Characters not allowed in file names become _; duplicate names get _1, _2.

Animated PNG

• Writes real APNG: every selected frame as a full-canvas frame, with exact delays and the play count.
• Indexed sprites keep one global palette without renumbering, merging duplicates or dropping unused slots, as long as every frame's pixels still match their stored indices and all frames share one palette.
• When slot identity is ambiguous, frame palettes differ, or compositing creates new colors, the frame is written as exact RGB/RGBA (never quantized) and the export toast lists the reason.
• Unedited imported delays stay exact; edited millisecond delays must be exactly representable, otherwise the export is rejected rather than rounded.
• Profiles, text, physical size and safe ancillary data are copied; image-specific EXIF, timestamps and histograms are not.

Export Sprite Sheet

• The sheet PNG is written as a palette PNG when it has 256 colors or fewer.
• JSON hash/array data follows the Aseprite layout (frames, frameTags, layers, slices). TexturePacker adds animations by tag. Godot writes a .tres SpriteFrames resource with one animation per tag plus a notes file. Phaser and Unity add notes files.
• Packed sheets fail with “Sprites don't fit …” when a fixed size is too small.

Export slices

File > Export slices… (or the Slices panel button) asks for Scale (1–16) and Also write slices.json (on), then a folder. Each slice visible at the current frame is cropped from the composite and saved as <slice name>.png; slices.json lists names, colors and keys in the Aseprite layout.

LPC sheets

File > Export LPC sheet… builds an 832×1344 Liberated Pixel Cup sheet (13 × 21 cells of 64×64) from tags named <action>_<direction>, such as walk_down or slash-left, plus a .json description.

Directions are up, left, down, right (aliases north/back, west, south/front, east); a tag without a direction fills down. A missing left or right row is mirrored from the other side. Frames are centered with the feet on y = 58; other frame counts are resampled by timing. Content larger than 64×64 fails.

Batch workspace

The Batch mode runs a re-runnable recipe over many files. The same recipe JSON works here, in the legacy CLI (--recipe) and in io_batch. Multi-frame inputs are processed as one animation with a shared grid, palette and trim box.

1. Input: Add files… (images, Aseprite and Isberg sprites) or Add folder…; Clear empties the list.
2. Recipe: pick an operation and click Add step. Each step can be enabled, moved (↑ ↓) or removed (✕). Load recipe…, Save recipe… and Preview first (process the first file without writing).
3. Output: Folder, Format (PNG (multi-frame → sequence), Animated GIF, Animated WebP, Isberg sprite (.isbsprite), Sprite sheet + JSON, SVG), File name ({title}; tokens {title} and {index}), Scale (1–32) and Layers: Flatten (else keep layers, tags, linked cels).
4. Run batch (or Stop). Each result card shows before/after; click it to open the result in the Editor. A recipe.json is written next to the results.

Palette parameters take a preset name (pico-8, sweetie-16, endesga-32, gameboy, nes, resurrect-32, grayscale-4) or a hex list. Without Flatten, multi-layer inputs keep their layers and links, but tilemap layers become normal layers.

Lua scripting

The editor runs the real Lua 5.4 interpreter, bundled as WebAssembly. Tables, closures, metatables, coroutines, integer operators and the math, string, table, utf8 and coroutine libraries all work. The host API follows the shape of Aseprite's scripting API but is a partial subset: app.apiVersion is 0, and app.capabilities lists what is supported. Collections and frame numbers are 1-based; pixel coordinates, palette indices and tile indices are 0-based; frame durations are in seconds.

Running scripts

1. Choose File > Scripts > Open scripts folder. It opens the Data\scripts folder of the portable profile.
2. Put .lua (or JavaScript .js) files there.
3. Choose File > Scripts > Rescan scripts. Rescan again after editing a script; Lua source is read at scan time.
4. Run the script from File > Scripts; Lua entries are named <file name> (Lua). Script entries are also commands in the command palette and can get shortcuts.

Cancel running Lua script stops the script and discards its edits. A script that fails to load shows as ⚠ name (failed). When the scripts folder does not exist yet, three examples are created: lua-color-ramp.lua, outline-all-frames.js and random-palette-shift.js.

local sprite = app.sprite
app.transaction('Checker layer', function()
  local layer = sprite:newLayer()
  layer.name = 'Lua checker'
  local image = Image(sprite.width, sprite.height)
  for pixel in image:pixels() do
    local value = (pixel.x + pixel.y) % 2 == 0 and 220 or 80
    pixel(app.pixelColor.rgba(value, value, value, 255))
  end
  sprite:newCel(layer, app.frame, image, Point(0, 0))
  app.layer = layer
end)

How a run works

• Each run uses a fresh Lua VM and a copy of the active sprite. A successful run becomes one undo entry.
• The result is discarded on an uncaught error, a timeout or cancellation, and also when, during the run, you switch or edit the sprite, change the timeline frame, layer or range, change the pixel selection, or change the view that the script also changed. Changing only the foreground or background color is kept unless the script changed the same color.
• app.transaction can be nested. On error it restores the changes in place and keeps existing object handles; catch the error with pcall to continue.
• Pixel edits keep the editor zoom and pan unless the script changes the view.
• Sprites created by the script open as new tabs. print(...) writes to the developer console as [Lua] …; the last line appears in the finish toast.
• Scripts and extensions share one execution slot; only one Lua callback runs at a time. Waiting for dialog input does not count against the time limit.

Where Lua runs

Limits

JavaScript user scripts

.js files in the same folder are ES modules with full access to the editor. They can export title, menu = [{ label, run(ctx) }], run(ctx) or a default function that registers commands and menu items. Their registrations are removed on rescan. JavaScript scripts are not sandboxed; run only code you trust.

Lua API reference

Everything listed here is implemented; anything not listed raises an “Unsupported” error naming the missing member. Read-only members are marked (r).

Globals and constructors

Constants

app

Sprite

Layer, Frame and Cel

Group handles stay distinct even when groups share a name. Renaming or reparenting a group updates its descendants; a failed transaction restores handles, paths and metadata. Group opacity and blendMode read nil and cannot be set.

Image

Images store native RGBA32, index8 or gray-alpha16 data; indexed images keep duplicate palette colors distinct. To crop, use Image(image, rect). Indexed drawImage needs an indexed source, normal blending and full opacity.

Palette, Selection and Range

Tag, Slice, Tileset and Tile

Properties

Sprite, Layer (including groups), Cel, Tag, Slice, Tileset and Tile have properties. Read with p.key, write with p.key = value, delete with p.key = nil; nested tables and arrays come back as writable proxies; #p and pairs(p) work. p('namespace') returns a named extension namespace (one level deep). Large 64-bit integers stay exact as decimal strings. rawset and table.insert do not change host properties.

Editor and value types

• Editor (UI only): sprite (r), zoom (1/64 to 256, fractional), scroll (the sprite point at the view center, fractional), mousePos and spritePos (r, last known pointer positions). View changes commit with the run and roll back with a failed transaction.
• Color: red, green, blue, alpha, gray, index, hex, rgbaPixel (r), grayPixel (r), hue/hsvHue, saturation/hsvSaturation, value/hsvValue, hslHue, hslSaturation, lightness/hslLightness.
• Point supports ==, +, -; Rectangle has isEmpty, origin, size, contains, intersects, intersect, union.

Precision extensions

These are Isberg Labs extensions, not part of Aseprite's API.

• sprite:setPrecision('uint16' | 'float32' | 'uint8'). 'uint16' can become 'float32'; float to uint16 is refused; 'uint8' explicitly reduces precision.
• On cel images of a precision sprite: image.precisionMode, getPixel16(x, y)/drawPixel16(x, y, {r, g, b, a}) (integers 0–65535) and getPixelFloat/drawPixelFloat (linear sRGB, alpha 0–1).
• Byte image methods, image copies, newCel, resize, crop, flatten, palette changes and most commands refuse precision sprites. Transactions, saves and MCP keep the exact values.

app.command

The newer commands reject unknown parameters; pixel commands reject an active group. In an extension, app.command can also call the extension's own registered command ids.

Lua dialogs

In the editor, Dialog creates real local windows. Dialog(), Dialog('title') or Dialog{title=, onclose=fn}; every widget method returns the dialog, so calls can be chained.

if not app.isUIAvailable then return end
local dialog = Dialog('Layer name')
dialog:entry{id='name', label='Name', text='New layer'}
dialog:button{id='ok', text='Create'}
dialog:button{text='Cancel'}
dialog:show()
if dialog.data.ok then app.sprite:newLayer().name = dialog.data.name end

Widgets

All widgets accept id, label, visible, enabled and focus.

Dialog methods and properties: show{wait=, bounds=} (modal by default), close(), modify{id=…, fields…} (also modify{title=}), repaint(), data (read a copy; assigning merges), bounds and sizeHint (r). The title bar close button and Esc close the dialog. Each non-button widget takes its own row; consecutive buttons share one.

Named tabs

Add pages with dialog:tab{id='page1', text='Page 1'} followed by their widgets, and close the group with dialog:endtabs{id='pages', selected='page1', onchange=fn}. Fields on hidden pages keep their values. dialog.data.pages holds the selected tab id, and modify{id='pages', selected='page2'} switches pages.

Shades and file controls

• shades in pick mode calls onclick with the clicked color and mouse button. In sort mode you reorder colors by dragging or Alt+←/→; data holds the new order. modify{colors=…} replaces the list.
• file opens the native single-file open or save chooser. entry=true allows typing the path; open=false needs save=true; up to 32 filetypes. The chosen path goes into data and runs onchange. Choosing a path never reads or writes the file and grants Lua no file access. Cancelling leaves the path unchanged.

Canvas and GraphicsContext

local dialog = Dialog('Preview')
dialog:canvas{id='view', width=64, height=32,
  onpaint=function(ev)
    local gc = ev.context
    gc.color = Color('#243447')
    gc:fillRect(Rectangle(0, 0, gc.width, gc.height))
    gc.color = Color('#f0c070')
    gc:fillText('Local Lua', 2, 8)
  end,
  onmousedown=function(ev)
    if ev.button == MouseButton.LEFT then
      app.image:drawPixel(math.floor(ev.x), math.floor(ev.y), app.fgColor)
      dialog:repaint()
    end
  end}
dialog:button{text='Done'}:show()

• The context is only valid inside onpaint. Drawing is recorded and shown after the callback succeeds; show() paints every canvas and repaint() repaints them.
• Mouse callbacks onmousedown, onmouseup, onmousemove, ondblclick, onwheel get x, y (canvas coordinates), button, pressure, deltaX, deltaY and altKey, ctrlKey, shiftKey, metaKey, spaceKey. Key callbacks onkeydown, onkeyup get key, code, repeatCount and the modifiers; keys the canvas handles do not reach the editor.
• Images are drawn as an 8-bit preview; indexed and grayscale palettes are resolved and precision data is not changed. Text uses a local 12-px monospace font.
• A document change made in a dialog callback is one undo step; a failed callback discards its changes.

Lua extensions

Extensions are Aseprite-style script packages that stay loaded. Each runs in its own persistent Lua worker: init(plugin) registers commands and menus, command callbacks keep their Lua closure state, and exit(plugin) runs when the extension is unloaded or the app closes normally.

Installing and managing

• File > Scripts > Extensions > Install local Lua extension… accepts a .lua file, a package.json (directory package), a .zip or an .aseprite-extension. The source is validated, then copied to Data\lua-plugins\<name> in the portable profile; nothing is downloaded or installed into Windows. Installing a name that is already loaded reloads it.
• Open extensions folder shows that folder. Unload extension… runs exit and disables the extension, so it does not load at the next start.
• Enabled extensions load at startup (up to 16). Their commands appear in the extension's submenu (File > Scripts > Extensions > name) or in the menu their group maps to, in the command palette, and in Keyboard Shortcuts.

Packaging

{
  "name": "local-tools",
  "displayName": "Local Tools",
  "version": "1.0.0",
  "categories": ["Scripts"],
  "contributes": { "scripts": [{ "path": "./main.lua" }] }
}

• name must start with a letter or digit and may contain letters, digits, ., _ and - (up to 128 characters); version is required. A standalone .lua gets a generated manifest with version 0.0.0.
• Only contributes.scripts is used; themes, palettes, languages, native libraries and other contributions are ignored. Scripts initialize in manifest order and exit in reverse order.
• Script paths may start with ./ but must match case exactly and cannot be absolute, use drives or backslashes, or leave the package.
• ZIP archives may use stored or deflate entries and one enclosing folder. Encrypted, split, ZIP64, symlink and special entries are refused. Archives are read in memory, never extracted.

Plugin object

function init(plugin)
  plugin.preferences.count = plugin.preferences.count or 0
  plugin:newCommand{
    id='MyCommand', title='My local command', group='file_scripts',
    onclick=function()
      plugin.preferences.count = plugin.preferences.count + 1
      app.sprite:newLayer().name = 'Run '..plugin.preferences.count
    end,
    onenabled=function() return app.sprite ~= nil end
  }
end
function exit(plugin)
  plugin.preferences.lastExit = 'clean'
end

Register commands and menus during init. Menu groups file_scripts and file go to the extension's own submenu; edit, sprite, layer, frame, select, view, filters and help go to those menus. Any other Aseprite group id is placed in the extension's submenu.

• Each callback receives a fresh atomic copy of the current sprite; fetch app.sprite and other handles again inside every callback, because handles from earlier callbacks expire.
• A successful document change is one undo step. An uncaught error, timeout or cancellation ends the extension's session and discards that callback's document and preference changes; reinstall or restart to resume from the last saved preferences.
• Moving the Pixel editor into its own desktop window, or gathering it back, restarts the extensions: preferences and exit edits carry over, closures and open dialogs are recreated.

Modeless dialogs

In an installed extension, Dialog:show{wait=false} returns immediately and opens a window that stays open. Each later click, change or close callback runs against the currently selected sprite with its own time limit and undo step, and the editor stays usable in between.

function init(plugin)
  plugin:newCommand{id='PaintTool', title='Paint tool', onclick=function()
    local dlg = Dialog{title='Persistent paint tool'}
    dlg:entry{id='name', text='Painted'}
    dlg:button{text='Apply', onclick=function()
      app.layer.name = dlg.data.name
      app.image:drawPixel(0, 0, Color('#ff8844'))
    end}
    dlg:button{text='Close'}:show{wait=false}
  end}
end

• modify, data, bounds, close and onclose work across callbacks. A modeless callback may open a modal dialog and continue after it.
• Editing a sprite while its callback runs discards that callback's result. Use onclick rather than onchange for check boxes and radio buttons in modeless dialogs.
• Open windows are not restored after a reload.

Timers and events

• Timer{interval=seconds, ontick=fn} with start(), stop() and read-only interval and isRunning. Intervals run from 1/60 to 3600 seconds. Each tick is one atomic, cancellable callback; missed ticks are dropped, and ticks wait while you draw or transform a selection.
• app.events:on(name, fn) returns a listener id; app.events:off(id) or off(fn) removes it. Supported names: sitechange (sprite, layer or frame change), fgcolorchange, bgcolorchange. Callbacks get no event argument; repeated pending events are merged.
• Not supported: beforesitechange, beforecommand, aftercommand, Sprite.events.