Compact projects and version compatibility
PixelWall 0.4.1 saves native .pixelwall backups in a losslessly compressed container identified by PWPZ. Compression changes how the project is stored, while keeping layers, frames, linked images, palettes, tilesets, and metadata editable. It does not flatten the artwork or reduce image quality.
The web editor, desktop app, and CLI read both compact files and supported legacy JSON projects. Older PixelWall versions cannot read the compact container. Update the receiving desktop app or CLI to 0.4.1 or later before sharing a new .pixelwall backup.
Compression savings depend on the artwork. Large flat-color areas and repeated data often compress well; a particular size reduction is not guaranteed. A smaller file also does not raise the editor’s document or memory limits.
Export readable JSON for another tool
Use the current CLI’s export --format json command when a tool needs a readable project payload. This writes the document as plain JSON and leaves the compact source file unchanged. Renaming a .pixelwall file to .json does not decompress or convert it.
Run this command from the extracted CLI folder, using your own project and output paths. JSON export removes the compressed container; it does not downgrade the document schema or make newer features compatible with every older editor. Check that the receiving tool supports the document and inspect a reopened copy before relying on it.
node pixelwall.mjs export river.pixelwall --format json --out river.json
node pixelwall.mjs inspect river.jsonWhat editable files preserve
Native PixelWall documents retain layers and groups, frames and cels, linked image references, color mode and palettes, clips, slices, independent tilesets, tilemap data, and metadata. Linked cels reference shared image records.
Supported binary sprite structures include RGBA, grayscale and indexed cel data; layers and groups; linked cels; frame timing and tags; slices, pivots, and user metadata; and supported embedded tilemap/tileset data. Preservation of a record does not guarantee every external application interprets it identically.
Unsupported structures can be rejected or reported as compatibility notes. External tilesets need available pixel data for rendered/game-package output. Unchanged source metadata may be retained where supported, but arbitrary unknown features are not guaranteed to survive every edit.
For an external tileset, use Tiles → Choose source & embed to select the matching sprite source. The editor verifies its grid and color mode and embeds it as one undoable edit. It never follows external paths automatically.
Color mode and profile limits
PixelWall keeps pixel values in the document’s working profile, with sRGB as the default. Embedded ICC profiles drive color conversion for previews and exported images. Assign changes how values are interpreted; Convert changes values to preserve appearance. PNG import converts embedded ICC or gamma information to sRGB. The current profile engine supports RGB and gray profiles.
RGBA stores color and alpha. Grayscale stores equal RGB channels with alpha. Indexed mode keeps palette indices, per-frame palettes and the transparent index. Conversion preserves linked cels when their effective palettes agree and separates them when palette changes require different pixels.
PNG imports support common bit depths and interlacing. Sixteen-bit channels become eight-bit editing values. Animated PNG is rejected; import a PNG sequence or GIF instead. GIF import preserves rendered animation frames and timing rather than the source layer structure.
Raster and 3D boundaries
PNG, BMP, TGA and GIF are rendered images, so they flatten editable layers. Some BMP/TGA variants have limited alpha, palette, or compression support; read the actual import error or warning rather than assuming every historical variant is supported.
PixelWall’s text tool rasterizes a bitmap font or command-supplied bitmap glyphs; it is not a full typography engine. Its motion and particles produce editable 2D frames. 3D model import/rendering is deferred.
Scripting compatibility
Choose Lua 5.4 in the Scripts panel to edit and run scripts using supported sprite-editing APIs. Images support pixel and byte access, crop/copy, nearest resizing, flips and compositing. Colors support RGB, gray, indexed, HSV and HSL values. Palette objects follow per-frame palette keys; ColorQuantization can generate colors, and ChangePixelFormat converts RGBA, indexed, or grayscale artwork. Blocking dialogs retain script variables across user input. Each successful run is undoable; failed or cancelled scripts leave staged artwork unapplied. Time and memory limits and unsupported API errors are explicit. Extension packages can provide palettes and explicit Lua command sessions; persistent plug-ins and advanced widgets are not supported.
Scripts can create and edit tilesets, insert or delete tiles, and assign tilesets to tilemap layers. ColorSpace values can assign working profiles or convert sprite colors. Imported ICC profiles are available to the script; arbitrary file and network access are unavailable.
Capacity and practical checking
The document engine accepts canvas sides from 1 to 65,535 pixels, with at most 4,194,304 canvas pixels, up to 256 layers including groups, and up to 2048 frames. A document may store at most 16,777,216 image pixels across its distinct images. Linked cels share image data. Browser canvas limits and available memory can be lower, especially for very wide sprites. Check representative artwork on your device.
Large layers, long clips, many palette variants, and scaled exports can hit memory or format budgets before the document validation maximum. Check a representative import, edit, export, and reopen cycle for the features your project uses.