Skip to the guide
Pixx Suite

Build · Sprite sheet & texture atlas maker · Advanced

Pixxula — Advanced

Pixxula in depth: how Best fit packs, trimming and duplicate rules, every data format's fields, rotation, Pixxado shadow sheets, PNG8 reduction and project files.

Open Pixxula

#What you'll learn

  • How Best fit packs, how duplicates and trimming are decided, and how to read the result in any engine.
  • The exact fields of each export format, and which engine features each one carries.
  • How rotated frames, pivots and shadow sheets are stored.
  • How the PNG reducer decides how many colours to keep, and what the PNG8 files contain.
  • What a Pixxula project file holds, and how sheets travel to other Pixx apps.

#Before you start

  • Work through Pixxula — Intermediate first: spacing, pivots, tags, slicing and the reducer.
  • Have your engine's documentation for sprite atlases nearby when choosing a format.

#How-tos

#How to understand Best fit packing

  1. Best fit uses the MaxRects method (best short side fit): frames are sorted by their longest side and placed one by one in the free space that fits them most snugly.
  2. Pixxula tries several sheet widths (square-ish sizes and powers of two) and keeps the smallest final sheet.
  3. Padding is added between frames and around the sheet; Extrude pads each frame with copies of its edge pixels. Positions in the data always point at the frame itself.
  4. Sheets can be up to 8192 pixels per side; above 4096 you get a warning because many graphics cards can't load them.

#How to rely on trimming and duplicates

  1. With Trim transparent edges, each frame is cut to its visible pixels. The data keeps spriteSourceSize (where the trimmed image sits in the original frame) and sourceSize (the original frame size).
  2. With Merge identical frames, two frames count as identical only if their trimmed pixels, trim offset and original size all match.
  3. Duplicates share their original's place on the sheet, but every frame keeps its own entry in the data, with its own name and duration, so animations don't lose frames.

#How to choose and read a data format

FormatBest forWhat it contains
JSON (hash) — TexturePacker, Phaser, PixiJSPhaser, PixiJS, most enginesframes keyed by name, each with frame, rotated, trimmed, spriteSourceSize, sourceSize, pivot, duration; animations (tag name → frame names in play order); meta with size, image, frameTags
JSON (array) — TexturePacker, PhaserLoaders that want a listThe same per frame, as an array with filename; meta.frameTags
Aseprite JSON (tags + durations)Aseprite-style loaders, Godot pluginsframes with position, trim and duration; meta.frameTags with from, to, direction
Sparrow / Starling XMLStarling, HaxeFlixel and othersA TextureAtlas with one SubTexture per frame: name, x, y, width, height, the trim as frameX, frameY, frameWidth, frameHeight, and rotated
CSS spritesWeb pagesOne class per frame with background position and size (rotated frames are skipped)
Grid descriptor (cols, rows, cell size)Simple engines with equal cellsimage, size, cell, cols, rows, padding, extrude and each frame's position and duration

Pivots are fractions (0–1) of the original frame size. Durations are in milliseconds.

#How to handle rotated frames

  1. Allow rotation lets Best fit turn frames 90° when that saves space.
  2. A rotated frame is stored turned 90° clockwise, like TexturePacker, and the w/h in the data are the size as stored.
  3. Your engine must read rotated: true and turn the frame back. If it doesn't, keep rotation off.

#How to export shadow sheets from Pixxado

  1. In Pixxado, send the lit sprite and its shadow layer only asset to Pixxula. The shadow attaches to frames with the same base name, frame count and size, in either order; a shadow that arrives first waits as marked frames.
  2. Frames with a shadow show a badge. Remove shadows in the frame panel detaches them.
  3. The export adds <name>_shadow.png, its data in your chosen format, and <name>_shadows.json with each shadow's rectangle and its offset inside the original frame. Draw the shadow sprite under the character at that offset.

#How the PNG reducer decides the colours

  1. The reducer treats transparency as part of the colour, so soft edges are kept; fully clear pixels share one entry.
  2. It tries 256, 128, 64, 32 and 16 colours and keeps the fewest whose quality stays above your target: High 44 dB, Balanced 38 dB (about "looks the same") or Smallest 32 dB. Quality is measured as PSNR, ignoring fully clear pixels.
  3. The file is written as a true PNG8: an indexed PNG with a palette and per-colour transparency.
  4. If the result wouldn't be smaller, the file keeps its original bytes. Already-tiny indexed files may not shrink further.

#Workflows

#Engine-ready atlas with animations and pivots

  1. Import frames, name them <animation>_<n>, tag each animation and set pivots at the feet.
  2. Best fit, Trim transparent edges, Padding (px) 2, Extrude 1, no rotation unless your engine supports it.
  3. Export → JSON (hash) for Phaser or PixiJS: load the atlas, then play animations.<tag>.
  4. For Godot, Unity or GameMaker, send the sheet to Pixxizi, which writes each engine's own files.

#Hitboxes, then packing

  1. Edit per-frame hitboxes in Pixxeta and send the frames to Pixxula; library imports keep their gameplay pivots.
  2. Pack and export. Pixxula keeps pivots; hitbox data travels on through Pixxizi.

#Pixxula in a Flow pipeline

Use Pixxula as the packing step in a Flow (Pixxivi → Pixxeta → Pixxula → Pixxizi). Open in Pixxula loads the previous step's frames; Send result to Flow hands on the packed sheet.

#Tips and shortcuts

  • Send to App sends a packed atlas as an image (it isn't a grid), and frames as a uniform grid sheet so any app can read them.
  • Projects (autosave and Cloud) are a ZIP with project.json (name, settings, tags, frame details) and one PNG per frame in frames/.
  • Your project autosaves on the device; the undo history and the reducer list are not kept after a reload.
  • Grid mode takes either columns or rows; setting one clears the other.

#Troubleshooting

  • Frames don't fit within Max width / Max height. Pixxula uses one sheet only; raise the maximum, trim, lower padding, or split the frames into two projects.
  • Duplicates were merged that shouldn't be. They really are pixel-identical; untick Merge identical frames if your engine needs separate copies.
  • The CSS export is missing some frames. Rotated frames can't be shown with CSS backgrounds; turn off Allow rotation.
  • The shadow didn't attach. The shadow asset must have the same frame count and size and a matching base name.
  • A big reduction froze the page briefly. Very large images (around 4000×4000) are reduced in the page itself; give it a moment.