Skip to the guide
Pixx Suite

Create · Pixel illustration & sprite animation · Advanced

Pixxivi — Advanced

Power use of Pixxivi: Aseprite round-trips, sprite sheet JSON, slices and hitboxes, tilemap layers, custom shortcuts, the audio track and plugins.

Open Pixxivi

#What you'll learn

  • Move projects between Pixxivi and Aseprite without losing work, and know what changes on the way.
  • Read the sprite sheet JSON Pixxivi writes, field by field, and mark slices, hitboxes, hurtboxes and anchors for your engine.
  • Build levels with tilemap layers, per-tile collision and terrain, and export them.
  • Drive Pixxivi from the keyboard: the command palette, rebound shortcuts and multi-frame editing.
  • Sync an animation to sound with the audio reference track, and extend Pixxivi with plugins.

#Before you start

  • Work through Pixxivi — Intermediate first: layer groups, tags, templates and sprite sheet export.
  • For the engine sections, have your engine's sprite sheet importer handy (most read Aseprite's JSON).
  • Plugins are JavaScript files. You only need to write code if you want to make your own.

#How-tos

#How to round-trip with Aseprite

  1. Open or drop an .aseprite / .ase file, or choose Import → Import Aseprite file (.aseprite)….
  2. Pixxivi keeps the layer tree (groups, hidden, locked, reference), blend modes, layer and cel opacity, linked cels, tags (direction, repeat, colour), slices with pivots, tilemaps and tilesets, the palette (indexed sprites stay indexed), frame durations and the grid.
  3. To go back, use the Aseprite tab in Export, or File → Export Aseprite file (.aseprite)….
  4. Features Aseprite doesn't have are baked so it shows the same picture: masks and clipping are applied, and static layers become linked cels. Pixxivi lists anything that changes, on import and on export, so read that list before you overwrite an original.

#How to mark slices, hitboxes and pivots

  1. Choose the Slice & hitbox tool (K).
  2. In the tool bar, pick the kind: slice, hitbox, hurtbox or anchor.
  3. Drag a rectangle on the canvas. Its pivot starts at the bottom centre; type new pivot x / pivot y values in the slices panel to put it where your character stands or a weapon is held.
  4. Click a slice to select it, rename it and change its kind. Slices follow canvas flips and rotations.
  5. Export a Sprite sheet with JSON data: each slice is written with its bounds, its pivot and its kind (in the data field).

#How to read the sprite sheet JSON

Choose JSON data → Aseprite-compatible (hash) or (array) in the Sprite sheet export. The file has two parts:

PartWhat it holds
framesOne entry per frame: frame (x, y, w, h on the sheet), rotated (always false), trimmed, spriteSourceSize (where the trimmed image sits inside the original frame), sourceSize (the full frame size) and duration in ms. In hash style the key is the frame's file name; in array style each entry has a filename.
metaimage, size, scale, format, frameTags (name, from, to, direction, repeat, color), layers (name, opacity, blendMode, visible, type) and slices (name, data = the kind, keys[0].bounds and keys[0].pivot).

Coordinates use a top-left origin, whole pixels, with y going down. With trim on, draw each frame at spriteSourceSize.x / y inside a sourceSize box so it doesn't jump around.

#How to build a level with tilemap layers

  1. Choose Layer → New tilemap layer… (or Convert layer to tilemap… for existing art) and set the tile size.
  2. Paint with any brush: you paint into tiles, identical tiles are stored once, and editing one copy updates every copy.
  3. Use the tile stamp (T): Shift-click picks a tile, right-click erases.
  4. In the Tiles panel, mark each tile's collision and terrain.
  5. Export from the Tilemap tab: one tileset PNG per tileset (tiles in a grid, 16 per row) and a _tilemap.json with every tilemap layer's cells per frame (tile index, or −1 for empty), plus each tile's collision and terrain.

#How to rebind shortcuts and drive everything from the keyboard

  1. Press Ctrl+K (or /) for the command palette. Every action in Pixxivi is a command there, including plugin commands.
  2. Press ? for the full shortcut list. Use Filter… to find a command and Rebind to give it new keys.
  3. Combine with frame commands: Home/End first and last frame, Alt+←/Alt+→ step frames, Alt+↑/Alt+↓ change layer, Ctrl+[/Ctrl+] move the layer.

#How to time an animation to sound

  1. Choose File → Add audio reference track… (MP3, WAV, OGG, M4A or FLAC).
  2. A waveform row appears in the timeline. It plays in sync, restarts each loop, and plays a short slice when you step frames.
  3. Adjust the offset and volume, find the loudest hit to line up an impact frame, or set the frame count to the sound's length.
  4. The track is saved in your .pxvi project only, never in image exports.

#How to install or write a plugin

  1. Open Help → Plugins…. Examples adds four samples (scanlines, a spray tool, a plasma generator, a CSS exporter); Install from file adds a .js file.
  2. A plugin calls Pixxivi.registerPlugin({ id, name, version, setup(api) { … } }) and registers commands, effects (Pixxivi builds their settings dialog), generators, drawing tools, exporters or importers.
  3. Every change a plugin makes is one undo step. Switching a plugin off removes everything it added.

#Workflows

#Engine-ready character with hitboxes

  1. Animate and tag each move. Add hitbox slices on attack frames and hurtbox slices on the body, and an anchor for the feet.
  2. Export a Sprite sheet: row per tag, trim, padding 1–2, extrude 1 if your engine filters textures, JSON data: Aseprite-compatible (hash).
  3. For per-frame boxes that change every frame, send All frames (sprite sheet) to Pixxeta and edit hitboxes there; then pack with Pixxula and export for your engine with Pixxizi.

#Aseprite team, Pixxivi on the go

  1. Keep the master file as .aseprite. Open it in Pixxivi on an iPad, edit, and export it back from the Aseprite tab.
  2. Avoid Pixxivi-only features (masks, clipping, static layers) in files that go back to Aseprite, or accept that they get baked.

#Levels from tiles

  1. Draw tiles on a tilemap layer, mark collision and terrain, export the tileset and _tilemap.json.
  2. For full level design with rules and objects, build the level in Pixxori and send it on as a tile map.

#Tips and shortcuts

  • K slice & hitbox, T tile stamp, Shift+L light, Alt+Shift+L toggles the lighting preview.
  • Shift+T tiled (wraparound) mode for seamless textures; Ctrl+Shift+G tile grid; < / > rotate the view 15°.
  • Free transform… (Ctrl+T) uses RotSprite for clean rotations; nearest-neighbour is still available for hard edges.
  • Ctrl+Alt+C canvas size, Ctrl+Alt+I scale sprite, Ctrl+U hue/saturation/brightness.
  • Undo keeps up to 300 steps or 192 MB, whichever comes first, and Pixxivi warns at 768 MB of memory.
  • Over https, Pixxivi installs as an app and works offline; your projects save in the browser first and sync when you're signed in.

#Troubleshooting

  • Aseprite shows a different picture than Pixxivi. Check the change list from the export: masks and clipping are applied and static layers become linked cels.
  • Frames jump around in the engine. You exported with trim. Offset each frame by spriteSourceSize, or export without trim.
  • Texture seams or bleeding in the engine. Add padding and extrude 1, and turn on power of two if your engine needs it.
  • Slices are missing in the JSON. Slices are only written in sprite sheet JSON and Aseprite files, not in GIF, APNG, PNG or frame ZIPs.
  • A plugin broke or won't load. Open Help → Plugins…: a plugin whose setup fails is marked with its error and stays off. Switch it off or remove it.