Pixel art export formats

Current editor export choices

• Editable PixelWall project · Free: a losslessly compressed .pixelwall file preserving the v4 document, including frames, layers, clips, palettes, linked images, tilesets, and metadata. Compact files require PixelWall 0.4.1 or later.
• Editable sprite project · Free: a binary sprite file with supported layers, frames and metadata. Review import/export warnings and keep the .pixelwall source.
• Current frame PNG, BMP, or TGA · Free: the active rendered frame at the selected scale. Native projects retain information that raster images flatten.
• Animated GIF · Pro: the chosen clip and playback order with rounded GIF timing and limited color/transparency.
• Sprite atlas PNG · Pro: an atlas PNG plus a separate JSON download describing rectangles, trimming offsets, source IDs, and durations. Allow multiple downloads.
• Game package ZIP · Pro: atlas PNG and JSON, rendered frame PNGs, a native project, a manifest, and independent tileset/map data where present.
• Saved export presets · Pro: keep reusable export options on this device with the Save export preset and Load saved preset controls.

Check that your download finished

“File generated” means PixelWall has created the file in the editor. The browser still needs to save it. A requested download can be blocked or require another click; the editor cannot observe whether the browser finished writing the file.

1. Use the retained download link

   If no download appears, use DOWNLOAD FILE in the “Your download” panel. For an atlas, use both the PNG and JSON links and allow multiple downloads when your browser asks.

2. Check the destination

   Wait for your browser’s download manager to finish, then locate the file in the folder your browser uses. Agents should verify the host’s download result or saved file rather than treating an export response as proof of a completed download.

3. Open the result

   Open a PNG in an image viewer, reopen a .pixelwall backup in PixelWall, or load an atlas with its matching JSON. Keep the editor open until you have confirmed the files you need.

Retrieve exports through automation

In the current editor, window.pixelwall.export() requests browser downloads by default. Pass download:false to generate files without requesting a download. The returned result.exportResult separates the generated artifacts from browser download requests.

generated.status is generated when file creation has finished. Each entry in generated.files includes filename, mime, bytes, and a page-local object URL. generated.completedAt records generation time, not download completion. For a project export, bytes is the compressed file size.

download.status is requested when PixelWall attempted an automatic download click, or not_requested when it did not. Check download.files for each file’s request status, especially for an atlas’s PNG and JSON. These fields record the export’s automatic requests; they do not track later clicks on the retained download links. download.completion is unobservable and download.completedAt remains null.

Fetch the object URLs inside the same editor page. They expire after the next export, dismissal of the download panel, or editor unmount, including a reload or close. They are not public links or filesystem paths and cannot be fetched by a separate terminal process. Copy the bytes through your host’s file-transfer mechanism before they expire.

const result = await window.pixelwall.export({
  format: "png", download: false
});
const handoff = result.exportResult;
for (const file of handoff.generated.files) {
  const response = await fetch(file.url);
  if (!response.ok) throw new Error("Export URL is unavailable");
  const bytes = new Uint8Array(await response.arrayBuffer());
  if (bytes.length !== file.bytes) throw new Error("Incomplete export");
  console.log(file.filename, file.mime, bytes.length);
  // Save bytes using your host’s file-transfer API.
  // Then verify the saved file at its destination.
}

• Read the browser API and exportResult() reference ↗
• Follow the river workflow and timeout recovery example ↗
• Use the CLI to export to an explicit local path ↗

Choose rendered layers and references

For rendered formats, Layers selects Visible layers, Active layer, or Selected layers. Reference layers are omitted by default; enable Include reference layers to put them in the rendered output. Editor previews can still show visible references while you work.

Editable PixelWall and sprite saves retain the whole editable document, including reference layers. Scale, clip, and rendered-layer choices are not a way to flatten or reduce a native project save.

Atlas layout and metadata

Packed, horizontal, vertical, and grid layouts support padding, border extrusion, optional trimming, and optional power-of-two output dimensions. Packing does not rotate entries. The editor’s atlas limit is 8192 pixels per edge; an export fails if the chosen entries and spacing do not fit.

Trimmed frames record sourceSize and spriteSourceSize alongside their atlas frame rectangle. Durations are milliseconds. The JSON is an array of named frame entries, with clip/source information and slices in metadata. Preserve the JSON with the PNG.

Game ZIP uses sprites.png and sprites.json as a matched pair. For a separately downloaded atlas, verify that meta.image matches the PNG filename before loading JSON through an engine that follows that field. Scale changes rendered pixel dimensions; source document coordinates in clips and slices should be interpreted consistently in your own pipeline.

The current atlas metadata is not the classic pixelwall.sprite-atlas v2 schema. The frameTags field includes export-relative from/to ranges, explicit frameIndices, and source frame IDs. Non-contiguous selections use frameIndices; they are not the classic Phaser animation recipes.

Inside a current game package

• manifest.json identifies the native project, atlas, rendered frames, tilesets, maps, clips, slices, and compatibility warnings.
• sprites.png and sprites.json contain the selected frames in timeline order and their atlas metadata.
• A named .pixelwall file preserves the editable source document.
• frames/ contains individual rendered PNGs with source frame IDs and timing listed in the manifest.
• tilesets/ contains independent tileset metadata and tile PNGs. Indexed documents with per-frame palette changes may emit separate palette variants.
• maps/ contains Tiled-compatible orthogonal .tmj maps for frames with tilemap data, grouped by tile dimensions. No map files are invented for a document with no tilemaps.

GIF color and timing

The current encoder preserves up to 255 distinct opaque colors per frame plus transparency. When a frame exceeds that palette, it maps colors to a 216-color RGB grid. Alpha below 128 is transparent; remaining pixels become opaque.

Frame delays round to 10 ms units with a 10 ms minimum; a viewer may display very short delays differently. The current editor checks a 67,108,864-pixel budget over the entire scaled playback sequence. PNG and native project saves preserve original color information more faithfully.

Import and interoperability limits

PixelWall imports its native files, supported editable sprite files, PNG/BMP/TGA images, GIF animations, image sequences, and sprite sheets. A flattened format does not recover original layers. Animated PNG is rejected; use PNG frames or GIF. PNG 16-bit channels are reduced to 8 bits for editing.

PixelWall uses embedded ICC profiles for previews and image export, and converts PNG profile/gamma information when importing. Use Colors → Color profile to assign a profile or convert colors. Unsupported file features produce compatibility notes or a rejected import.

• Read detailed file compatibility notes ↗
• Use a current Tiled package ↗

Classic packages and existing examples

The Phaser and PixiJS sample guides describe the classic editor’s established sprite package schema. Follow those guides using /editor/classic, or adapt your loader to the current atlas JSON. Existing downloadable example packages are labeled by their own contents.

• Open the classic exporter ↗
• Classic Phaser sample ↗
• Classic PixiJS sample ↗

Common questions