Advanced

PaperZD

Build 2D character animation in PaperZD by asking: flipbooks from a sprite sheet, animation sources, Animation Blueprints, state machines, playable characters and a play check.

PaperZD by Critical Failure Studio is the animation system most Paper2D games use: animation graphs and state machines for flipbook characters. It is free on Fab and on GitHub.

With the PaperZD extension, Ultimate Engine CoPilot builds those setups for you, from a sprite sheet to a character that walks and attacks in play.

It was tested with PaperZD 2.2.4 on Unreal Engine 5.7.

What you need

PaperZD, installed and enabled in your project. It uses Unreal’s own Paper2D plugin, which PaperZD enables with it.
A sprite sheet for your character, or existing flipbooks.

Plus Ultimate Engine CoPilot with the PaperZD extension switched on.

Without PaperZD the extension does nothing harmful. Every PaperZD tool answers with one message that says whether the plugin is installed, enabled and loaded, and what to do next.

Setting it up

Install PaperZD from Fab or GitHub and enable it in your project. Restart the editor if Unreal asks.
In the CoPilot, open Settings > Extensions and switch on PaperZD. It is off by default.
Ask the AI to check the PaperZD status. It reports whether PaperZD was found and, if not, what is missing.

What you can ask for

“Here is my knight sprite sheet, 6 columns by 13 rows. Make flipbooks for idle, walk and attack in four directions and set up PaperZD for it.”
“Add a state machine with Idle, Walk and Attack. Walk when the character is moving, back to Idle when it stops, and Attack plays once then returns to Idle.”
“Make the animations face the way the character is moving.”
“Make a playable character with WASD to move and Space to attack, with a camera behind it, and a game mode that spawns it.”
“Add a footstep sound to the walk animation.”
“Swap the character to the red palette while the game is running.”

Behind those requests the AI can:

Cut a sprite sheet into animations. One call turns a sheet into sprites, flipbooks, animation sequences, an animation source and an Animation Blueprint. Animations with several directions become one multi-directional sequence.
Build the animation graph. Play sequence, state machine, direction, override slot, select by bool, number or enum, random player and cached animation nodes, and connect them.
Build state machines. States, conduits and jumps, with transitions that fire on a variable, when the current animation finishes, always or never, with a priority and an optional transitional sequence.
Add notifies. Custom events, sounds and Niagara or particle effects on a timeline, with custom notifies becoming functions you can fill in.
Add skins. Replacement flipbooks per animation, for outfits or palette swaps, applied while the game runs.
Make characters. A new PaperZD character driven by the Animation Blueprint, or hook an existing actor up. It can also add a PaperZD track to a Level Sequence.
Check it in play. Read which sequence is playing, how far along it is and the values of the animation variables, and play, stop or jump to an animation to test a transition by hand.

Mistakes it avoids

PaperZD has a few traps that compile cleanly and still do nothing. The AI knows them:

A new transition’s rule is “never” until it is set, so the character would never leave Idle.
A variable a rule reads has to be written somewhere, usually in the Animation Blueprint’s tick. A clean compile does not prove the rule ever changes, so the AI checks in play.
A sequence only plays in an Animation Blueprint of its own animation source, so it keeps each character’s assets together.
States and transitions are compiled in one batch at the end of a group of edits, not after every one.
The sprite sheet grid is read left to right from the top, so the AI counts cells the same way PaperZD does.

Tips and tricks

These come from building a small playable village with PaperZD and the CoPilot: a hero, a villager, skeleton enemies and wandering wolves. It was tested with PaperZD 2.2.4 on Unreal Engine 5.7.

The three that matter most:

Tell the AI the real row layout of your sheet. Number the rows from 0, say which rows are animations and which row is something else, and open the first frame of each flipbook to check.
Never rotate the actor. A flipbook is a flat card, so the direction has to come from which animation plays, not from turning the actor.
Do not trust a clean compile. Ask for a play test that reports the current animation and its variables.

Describe the sheet exactly

The AI cannot see which row of your sheet holds which animation. You have to tell it.

A sheet exported from PixelLab has 6 columns and 13 rows of 92 pixel cells, with four directions in every animation in the order south, west, east, north. Row 0 is a row of rotation poses, not an animation.
The export comes with a layout file that lists which row holds which animation. Use it. The order differs from character to character: in the village the hero and the mage had walk first, the skeleton attack first and the wolf idle first.
Count from 0 and name the rotation row. In one session the prompt said “rows 1 to 4 are the walk”. The AI counted from 1, so every animation was one row off and the hero faced the wrong way.

Write the rows like this:

Each sheet is 6 columns by 13 rows of 92 pixel cells. Number the rows from 0. Row 0 is the rotation row, skip it. Rows 1 to 4 are the walk (south, west, east, north, 6 frames), rows 5 to 8 the attack, rows 9 to 12 the idle (4 frames).

Settings that matter

Pixel art on. The textures use nearest filtering and no mips, so the pixels stay sharp.
Pivot at bottom centre. The feet stay on the same spot in every frame.
Frames per second. Ask for the speeds you want. The AI used 15 for everything, which looped a 4-frame idle in about a quarter of a second. Idle 6, walk 12 and attack 14 looked right.
Direction order. A multi-directional sequence runs clockwise from up: north, east, south, west.
Values on a placed actor win. A cooldown or speed set on an actor in the level beats the Blueprint default, so check the placed copies when a change seems to do nothing.

Keep the sprite facing the camera

This is the setup that stopped the sprite turning, tilting or going edge-on:

Turn off actor rotation. Controller yaw off, orient rotation to movement off, controller desired rotation off. Left on, the card turns with the actor and can go edge-on.
Spawn with yaw 0. A spawn yaw of 180 makes the card lean away from a camera fixed in the world.
Fix the spring arm to the world. Pawn control rotation off, inherit pitch, yaw and roll off, collision test off. A pitch of -40 and a yaw of -90 worked.
Tilt the card once. With the camera looking down 40 degrees, give the sprite a roll of -40, and lift it so the feet touch the floor.
Move in world axes, not along the actor’s forward or right vector.
Show the direction with Set Directionality. Feed it a Vector2D variable called Facing. Write Facing every tick from the velocity and keep the last value when the character stops.

With that camera the keys map like this:

D moves along +X, Facing (1, 0).
W moves along -Y, Facing (0, 1).
A moves along -X, Facing (-1, 0).
S moves along +Y, Facing (0, -1).

If left and right or up and down come out swapped, flip the sign of that part of Facing. Do not rotate the actor to compensate.

Test it in play

A transition does nothing until its rule can change. A new rule is “never”, and a rule that reads a variable needs something to write that variable, usually the Animation Blueprint’s tick. Ask for a play test that reports the current animation.
Give Facing a starting value. It is only written while the character moves, so an attack before the first step reads zero. A default of south fixes it.
Let the hero face the target. If the attack should hit something to one side, ask the AI to set Facing toward the nearest enemy before the swing.

A real session

The collab clip was built in four prompts in the CoPilot chat, with the Claude Code agent. The AI ran its own play tests and repaired what it found. Times are from one machine.

Two characters imported, with idle, walk and attack state machines: about 2.5 minutes.
A playable hero (WASD to move, Space to attack), a spring-arm camera, a game mode and a villager walking between three points: about 7 minutes.
A skeleton enemy that chases and attacks, hit points and a health counter on screen: about 7 minutes.
Wandering wolves, collectible herbs and a herb counter: about 7 minutes.

The look is a separate job

The AI builds the animation and the gameplay. The look of the clip was set up in the level, not by the AI:

Warm sun and lantern light.
Bloom, a vignette and a shallow depth of field for a tilt-shift feel.
An unlit emissive material on the characters.

Start with the unlit material and a fixed exposure. Tuning exposure by eye over many rounds cost more time than it gave back.

Limits

The AI does not know which animation each row of your sheet holds. You have to tell it.
Enemies walk straight at the hero, with no pathfinding around props.
At an exact 45 degree angle two axes tie and the animation picks east.
Health stops at 0. Nothing else happens until you ask for a death.
It could not read an animation state in the middle of a held key press, and it said so instead of guessing.

Permissions

Reading is free: inspecting an asset, a graph or a running animation never asks. Changes follow your Ask Before Edit or Auto Edit setting, the same as every other tool.

How it works

No link between the plugins. The extension reaches PaperZD by reflection only, so Ultimate Engine CoPilot builds and runs the same with or without PaperZD installed, and the extension keeps working across PaperZD versions of the same design. If an update renames something, the tool names the missing field instead of guessing.
Everywhere at once. The tools work in the CoPilot’s chat, in external MCP clients like Claude Code and Cursor, and in coding agents. See MCP Integration.
39 tools. Authoring, inspection and play-time tools for sources, sequences, notifies, skins, Animation Blueprints, graphs, state machines, characters and Sequencer.

See Extensions for how extensions work, and Play Testing for how the AI checks a running game.