Skip to the guide
Pixx Suite

Animate · Portrait & dialogue animator · Advanced

Pixxara — Advanced

Pixxara for engine work: how each script export is structured, portrait sheet maps, the Unity JSON format, Yarn round trips, credits, auto-rig details and timing.

Open Pixxara

#What you'll learn

  • How Pixxara turns your dialogue into each engine format, and which format round-trips.
  • How portrait sheets are laid out and how to read their JSON map.
  • The fields in the Unity JSON export, for writing your own dialogue runner.
  • How the auto-rig finds faces, and how to correct it precisely.
  • How timing, blips and credits flow into every export.

#Before you start

  • Read Pixxara — Intermediate first: ids, conditions, variables, tags, cues and frames are assumed.
  • Know which dialogue system your engine uses: Yarn Spinner, Ren'Py, Ink, Godot Dialogic, or your own code.

#How-tos

#How to pick the right script export

  1. Click Export and choose a script format:
    • Yarn Spinner .yarn — Pixxara's round-trip format. Dropping a .yarn file on the stage imports it back.
    • Godot Dialogic .dtl, Ren'Py .rpy and Ink .ink for those engines.
    • Unity JSON — flat, typed JSON for your own runner (see below).
    • Plain JSON — the full dialogue data.
    • Translations CSV — every line id with a column per language.
  2. Exports group lines into readable blocks: a chain of lines starting at the start node, at every choice or jump target, and at any line several others point to. Each block becomes one knot, label or node instead of one per line.
  3. Choices, conditions, variables, expressions and inline tags are carried over in each format's own syntax where it has one.

#How to read the Unity JSON

  1. The export is <project>_unity.json with format: "pixxara-unity", version, start (the first line id).
  2. variables: name, type (float, bool or string) and value as text.
  3. speakers: id, name, color, side, and portraitSheet (<id>_portraits.png).
  4. lines: id, speaker, expression, text (with tags), plainText (without), next, and choices with their text, target and condition.
  5. locales holds translations by language; portraits holds each speaker's sheet map.
  6. A runner only needs to: start at start, show text with the speaker's sheet row for expression, follow next or the chosen choice, and apply variable changes.

#How to use portrait sheets in a game

  1. Each speaker's sheet is <id>_portraits.png with <id>_portraits.json.
  2. One row per expression; columns are the seven mouth shapes closed, small, open, wide, o, e, f, then blink_half and blink_closed.
  3. The JSON map lists expressions (row order) and columns (column order), plus the frame size fw × fh.
  4. To animate talking, step through mouth columns while text types; Pixxara picks the shape from each letter in From letters mode, or alternates open/closed in Simple flaps.
  5. Blink at random intervals using the two blink columns of the current row.

#How to correct the auto-rig precisely

  1. Pixxara finds the face by its skin colour, then looks for the eyes, brows and mouth as gaps in the skin: eyes are the tallest pair of shapes in the upper half, brows a pair just above, the mouth the widest centred shape below.
  2. Glasses, masks and very small faces can confuse it. Turn on Show rig boxes to see what it found.
  3. Edit the boxes' numbers under Portrait, or click Auto-detect after cropping the picture tighter.
  4. For a state that still looks wrong, use Paint a feature: pick the Feature and State and paint it. Painted states are locked, so re-rigging keeps them.

#How to keep credits right

  1. Characters from Pixxava carry their source and credits (for example a body template's maker).
  2. Pixxara adds those credits to everything it sends (meta.credits), to each portrait sheet's JSON (sourceCredits), to the dialogue asset, and as CREDITS.txt in the Everything ZIP.
  3. Include CREDITS.txt in your game's credits screen.

#How to control timing exactly

  1. Text speed sets characters per second; Punctuation pauses add time after commas, full stops and other marks.
  2. [speed=…], [pause=…] and [mute] override timing inside a line.
  3. Pixxara computes one timeline per line (letters, mouth shapes, blips and expression changes). The live preview, the GIF/APNG preview and the blip WAV all come from that same timeline, so they match exactly.

#Workflows

#Writing in Yarn, polishing in Pixxara

  1. Write the first draft in your usual Yarn editor.
  2. Drop the .yarn file on Pixxara's stage. Lines, choices and jumps import into the dialogue.
  3. Add portraits, expressions, voices and cues, then export Yarn again plus the portrait sheets.

#A custom dialogue runner from Unity JSON

  1. Export Unity JSON and the portrait sheets.
  2. Load the JSON in your engine and build a small state machine: current line id, variables, and the sheet frame for speaker + expression + mouth shape.
  3. Strip tags with plainText for subtitles or logs; parse text for wave, shake and colour effects if you support them.

#Ship it with Pixxizi

  1. Send to App → Pixxizi with the whole dialogue.
  2. Pixxizi exports the script and portrait sheets for your engine target alongside your sprites. See Engine hand-offs.
  3. In Flow, any change to the dialogue marks the Pixxizi step Needs re-run.

#Tips and shortcuts

  • A dialogue sent from Pixxara carries its rigs, style, music and languages, so Pixxara → library → Pixxara loses nothing. A dialogue made elsewhere has its speaker pictures auto-rigged on arrival.
  • Expression changes are instant (no tween); use [expr=…] mid-line for reactions.
  • Sound cues live in the project and travel with the dialogue as WAV files.
  • Kerning from library fonts isn't applied while text types; choose fonts that look right without it.
  • Conditions are parsed safely: anything outside the supported operators is flagged, never run.

#Troubleshooting

  • A Ren'Py or Ink export looks split oddly. Blocks start at every line several others point to. Reduce unnecessary jumps into the middle of a chain.
  • A Yarn import has unknown speakers. Add a character for each speaker name in the file, or rename speakers to match your cast.
  • Portrait sheets have the wrong row order. Read the order from the sheet's JSON map.expressions, not from the expression panel.
  • The talking GIF and the engine timing differ. Your engine runs its own text speed. Use the same characters-per-second and pause values as Pixxara.
  • Credits are missing for an imported picture. Only characters that came from Pixxava carry credits. Add your own credits for other art.