Pixxeta — Advanced

#What you'll learn

• How Pixxeta stores boxes, tracks, pivots, sockets and events, and how pivots inherit.
• The coordinate system of each export format, so your engine code reads the data correctly.
• What the Godot, Unity and GameMaker exports actually generate.
• Exactly what ⇋ Left-facing copies and Auto boxes from rig do.
• How gameplay data travels through the Pixx library without losing anything.

#Before you start

• Read the Pixxeta Intermediate guide first: templates, tracks, interpolation, sockets, events and frame data.
• Know your engine's coordinate system (y-down or y-up) and how it loads sprite sheets.

#How-tos

#How to understand the data model

1. A project has layers (each with a type: Hitbox, Hurtbox, Pushbox, Trigger or Custom), sockets (names), animations (a name, a first and last frame, loop on/off) and per-frame data.
2. Each frame holds its boxes (id, layer, shape, x, y, w, h, polygon points, gameplay fields), its sockets (x, y, angle), its events (name + values) and an optional pivot.
3. A box id shared across frames is a track. Interpolation, timeline rows, Godot shapes and Aseprite slices are all built per track.
4. Pivots inherit: a frame's own pivot wins, otherwise its animation's, otherwise the project's. Use the inherited pivot removes a frame's own pivot.

#How to read each export's coordinates

Socket angles follow the same axes: in Unity's data, angles are negated because y points up.

#How to use the Generic JSON

1. The file's format is pixxeta-gameplay, version 1.
2. It lists frameSize, the sheet (image, size, columns), layers (id, name, type, colour, defaults), sockets and animations.
3. Each animation's frames carry the index, duration (ms), the rect on the sheet, boxes, pivot, sockets and events.
4. frameData repeats the startup, active, recovery, damage, on-hit and on-block numbers per animation.
5. XML is the same data with objects as elements and values as attributes; CSV splits boxes, sockets, events and frame data into tables.

#How to use the Godot 4 export

1. The zip contains one .tscn scene and the sheet, with no extra resource files.
2. The scene has an AnimatedSprite2D with one frame per sheet cell, one Area2D per box layer (its collision layer bit set by type: hit 1, hurt 2, push 3, trigger 4, custom 5), one CollisionShape2D per track, and a Marker2D per socket.
3. An AnimationPlayer turns shapes on and off, moves and resizes them, moves the sockets, and calls _on_frame_event(name, data) on each event frame. Add that method to the scene's script to react to events.

#How to use the Unity and GameMaker exports

1. Unity: JSON plus a PixxetaBoxes.cs component that reads it at runtime (no editor script needed), drives one collider per box and calls OnFrameEvent on the same GameObject with name|json (the event name and its values as JSON) when an event frame plays. Frame durations are in seconds.
2. GameMaker: JSON plus helper functions pixxeta_load, pixxeta_boxes, pixxeta_overlap, pixxeta_events and pixxeta_socket, with positions relative to the pivot.
3. Aseprite / Phaser: Aseprite-style JSON with frame tags per animation and one slice per box track; sockets are exported as 1×1 slices.

#How to mirror a character correctly

1. ⇋ Left-facing copies adds a copy of every animation, named with _left.
2. Boxes, polygons, pivots and sockets are flipped across the frame's width; socket angles become 180° minus the angle.
3. Mirrored box ids get _L, so left and right tracks never mix.
4. Do it last, after the right-facing set is final; re-run it after big changes (delete the old _left animations first).

#How to get the best rig-based boxes

1. Auto boxes from rig works on any asset that came from Pixxava (it carries the character's recipe).
2. Pixxeta finds the feet as the lowest solid row, takes the character's height and proportions from the recipe, then splits each frame into head, torso and legs bands from the feet up.
3. Each band's width is capped around its middle, so a raised sword, a cape or a hat doesn't stretch the box; crouching frames compress the bands.
4. Legs can come out a little short, because thighs above the hip line fall in the torso band. Widen them by hand where it matters.

#Workflows

#Lossless round-trips through the library

1. Send to App puts the gameplay data on the asset in a shared format other apps understand: hit, hurt, collide and trigger boxes, pivots, sockets and events per frame. Pushboxes are shared as collide; triggers and custom boxes as trigger.
2. Pixxeta also stores each box's original layer, type, shape and polygon points inside the box's own data, so sending to Pixxula and back into Pixxeta restores everything exactly.
3. Pixxula keeps the data when packing; Pixxizi turns it into engine files alongside your other assets.

#A data-driven fighting game

1. Apply Fighting-game fighter and set layer defaults for Strike (damage, hitstun, blockstun, priority).
2. For each move, add hit_active windows and cancel_window events; type on hit / on block.
3. Export CSV for the balance spreadsheet and Generic JSON for the game. Keep the Pixxeta cloud project as the source of truth and re-export after every balance pass.

#Projectiles and effects that line up

1. Put muzzle and vfx_origin sockets on the attack frames and aim them.
2. Add spawn_projectile with socket: muzzle and vfx with socket: vfx_origin.
3. Annotate the projectile itself in a second Pixxeta project with the Projectile / spell template.

#Tips and shortcuts

• Polygons: click each corner, then click the first point, double-click or press Enter to close.
• With Select, dragging an empty spot pans; middle-drag pans too. Space is play/pause only.
• Undo keeps the frames themselves by reference, so even mirroring a big project is cheap to undo.
• An Aseprite export opens with tags as animations and slices as boxes: select the JSON and PNG together.

#Troubleshooting

• Boxes are upside down in Unity: Unity's data is y-up from the pivot; don't flip it again in your code.
• Godot events never fire: add _on_frame_event(name, data) to the script on the scene's root.
• Left-facing boxes don't line up: the pivot wasn't centred on the character before mirroring. Set pivots first, then mirror again.
• Another app shows pushboxes as "collide": that's the shared name; they come back as Pushbox when reopened in Pixxeta.
• Rig boxes are missing: the asset didn't come from Pixxava (no recipe). Use Auto boxes → Body parts instead.

#Related guides

• Pixxeta Beginner · Pixxeta Intermediate
• Pixxava · Pixxula · Pixxizi
• Pixx Flow · Cloud projects and your Library