#What you'll learn
- How a .pxasset file is put together and how to read one with any zip tool.
- The manifest fields every asset has, and the extra fields for each of the ten kinds.
- The shared metadata apps use to pass hitboxes, pivots, shadows, loops and dialogue along.
- How to build a valid .pxasset yourself, so your own scripts can feed the Pixx apps.
#Before you start
- You know how hand-offs work from Send to App and Working across apps — Intermediate.
- You're comfortable with zip files, PNG images and JSON.
- To get a sample, use Send to App → Download .pxasset in any app, then rename a copy to .zip and open it.
#The file at a glance
A .pxasset is an ordinary zip file. It always contains manifest.json, plus the PNG, WAV or JSON files its kind needs. Pictures are PNG; sounds are 16-bit PCM WAV; all coordinates are pixels from the top-left.
Every manifest has these fields:
| Field | What it holds |
|---|---|
| pixx | Format version, currently 1 |
| kind | One of the ten kinds below |
| name | The asset's name |
| source | The app that made it, such as pixxivi |
| created | When it was made (milliseconds since 1970) |
| w, h | Its size in pixels |
| meta | Free-form extra data (see the meta section below) |
| palette | Optional, on any kind: a name and up to 256 colors as lowercase #rrggbb |
#The ten kinds
| Kind | Files in the zip | Manifest fields |
|---|---|---|
| frames (animation) | frames/0000.png, frames/0001.png… | frames: a list of file + delay (milliseconds, at least 10) |
| image | image.png | image: the file name |
| sheet (sprite sheet) | sheet.png | sheet: file, cols, rows, fw, fh (frame size), count, delays (per frame, or empty) |
| palette | (none) | palette: name + colors (required for this kind) |
| sound | sound.wav | sound: file, rate, duration (seconds), peaks (up to 128 values from 0 to 1, for waveform pictures) |
| dialogue | dialogue.json + dialogue/… (portrait PNGs, voice WAVs) | dialogue: file, images and sounds (each a list of path + file; sounds also rate + duration) |
| pack (game pack) | pack.json + members/0000.pxasset… | pack: file + members (each file, kind, name). Members are whole .pxasset files; packs nest one level deep at most |
| font | font.json + atlas.png | font: file, atlas, glyphs (how many) |
| ui-frame (nine-slice) | frame.json + frame.png | frame: file + image |
| tilemap (level) | map.json + tileset.png | tilemap: file + tileset |
#font.json
| Field | Meaning |
|---|---|
| name, cell (w, h) | Font name and its cell size |
| capHeight, baseline, lineHeight | Vertical metrics in pixels |
| glyphs | One entry per character code: x, y, w, h (its box in atlas.png), xoff, yoff (yoff = glyph top from the top of the line), adv (advance) |
| kerning | Pairs written as "codeA,codeB" with a pixel adjustment |
atlas.png holds white glyphs on a clear background, so apps can tint them.
#frame.json (UI frame)
| Field | Meaning |
|---|---|
| name, w, h | Name and image size (at least 3 × 3) |
| slice | l, t, r, b: how far in from each edge the corners end. They must leave a centre |
| center, edges | stretch or tile |
| padding | l, t, r, b: where content (text) sits inside; defaults to the slice |
#map.json (tilemap)
| Field | Meaning |
|---|---|
| name, tileW, tileH, cols, rows | Name, tile size and map size in tiles |
| tileset | columns and count: the grid of tileset.png |
| layers | Each has name, type and data |
| objects | Each has id, type, name, x, y, w, h (pixels) and props |
| meta | Optional extras such as source (the app) and background (#rrggbb) |
Layer data is one number per cell, row by row (cols × rows numbers):
| Layer type | Cell values |
|---|---|
| tiles | 0 = empty, 1 = the first tile of the tileset, 2 = the second… |
| collision | 0 or 1 |
| height | 0 to 15 |
Layers may also carry visible (true unless set to false) and opacity (0 to 1). Apps that don't use them ignore them.
#Shared meta
These ride in the manifest's meta. An app that doesn't use one keeps it untouched, so it survives a trip through other apps.
| Key | On | Used by | What it holds |
|---|---|---|---|
| gameplay | frames, sheet | Pixxeta, Pixxado, Pixxula, Pixxizi | version 1 and frames: one entry per frame with boxes (each id, type = hit, hurt, collide or trigger, x, y, w, h, optional data), pivot (x, y), sockets (name, x, y, optional angle), events (name, optional data) and an optional shadow (layer). Optional shadowLayers lists id + label |
| loop | sound | Pixxune, Pixxibu, Pixxara, Pixxizi | start, end and optional intro, in seconds |
| bpm | sound | music apps | Tempo, a number |
| stems | sound | music apps | A list of name (+ optional file) |
| credits | any | Pixxava, Pixxara | Who made the base art; travels into exports |
| flow | any | Flow | run, node and parents when the asset was sent as a Flow result |
Gameplay coordinates are pixels inside the frame, from its top-left corner.
#The dialogue script
dialogue.json (made by Pixxara, exported by Pixxizi) holds:
| Field | Meaning |
|---|---|
| version, start | Format version (1) and the id of the first line |
| variables | Starting values, name → value |
| speakers | Each id, name, optional portrait (a path inside the dialogue folder), rig, blip (sound, optional pitch and rate) |
| nodes | Each id, optional speaker, text, expression, choices (text, next, optional if), next, set, cues (type = sound, music or expression, ref, optional at) |
| locales | Optional translations: language → node id → text |
#How-tos
#How to look inside a .pxasset
- In any app, use Send to App → Download .pxasset.
- Copy the file and rename the copy to end in .zip.
- Open it with any zip tool. Start with manifest.json; it names every other file.
#How to build a .pxasset with your own script
- Write your PNGs (or WAVs) at the paths in the table above. For an animation that's frames/0000.png, frames/0001.png and so on.
- Write manifest.json with pixx set to 1, the kind, a name, your tool's name as source, w, h, an empty meta and the kind's own field (for example frames with each file and delay).
- Zip manifest.json and the files together, with the paths exactly as written in the manifest, and give the zip a .pxasset name.
- Open it in a Pixx app with Library → Open a .pxasset file… or by dropping it onto the app.
#How to add hitboxes from your own tool
- Start from a frames or sheet asset.
- In its manifest meta, add gameplay with version 1 and one entry in frames per animation frame, in order.
- Give each entry its boxes, pivot and any sockets or events, in pixels from the frame's top-left.
- Open it in Pixxeta to check the boxes visually, then send it on to Pixxula or Pixxizi; the data travels with the frames.
#How to build a level from your own map editor
- Export your tile images into one tileset.png, in a grid of columns tiles across.
- Write map.json: tile size, map size, the tileset grid, and a tiles layer whose cells are 0 for empty or the tile number plus one.
- Add a collision layer (0 or 1 per cell) if your game needs it, and objects in pixels.
- Zip it as a tilemap asset and open it in Pixxori to edit, or in Pixxizi to export straight to an engine.
#How to check why an asset is refused
- Open the manifest and compare it with the tables above.
- Common causes: an unknown kind, a file listed in the manifest but missing from the zip, a tilemap layer with the wrong number of cells or an out-of-range value, a UI frame whose slices leave no centre, or a pack nested more than one level deep.
- The app's message usually names the field, such as "tilemap layer … needs N cells".
#Workflows
#Generated art into the suite
- A script renders frames from your own generator and writes a frames .pxasset.
- Open it in Pixxivi with Library → Open a .pxasset file… to touch it up, then send it on as usual.
#Round-trip with an external engine tool
- Send a sheet with hitboxes to Pixxizi and export the Generic target: each sprite comes with a JSON file of frames, animations, pivots, hitboxes, sockets and events.
- Your own tool reads that JSON, or the gameplay meta directly from the .pxasset.
#Tips and shortcuts
- Keep name short and readable; apps show it in the Library and use it for exported file names.
- delay values under 10 ms are raised to 10.
- Palettes keep at most 256 colours.
- Unknown keys inside meta are kept as they are, so you can add your own data under your own key.
- Library item ids look like lib-sheet-pixxula-…: kind, then the app that made it.
#Troubleshooting
- "not a Pixx asset". The zip has no manifest.json at its top level, or its kind isn't one of the ten.
- "the asset is missing …". A file named in the manifest isn't in the zip, or its path differs (paths are case-sensitive).
- The animation plays at the wrong speed. Check each frame's delay (milliseconds) or the sheet's delays.
- Hitboxes appear on the wrong frames. gameplay.frames must have one entry per frame, in frame order.
- A tilemap shows the wrong tiles. Tile cells count from 1; 0 is empty. Check tileset.columns against your image width.