Sprite Puppeteer

Overview

Sprite Puppeteer is a free browser tool for animating pixel-art game characters. It handles two kinds of character:

• Rigged: one picture, or a stack of layers, with a skeleton on it. You get built-in moves with several styles each, plus moves you keyframe yourself.
• Sprite-sheet: every frame is already drawn or rendered, in one or more camera sets (side, isometric, top-down) and up to 8 directions. Frames play exactly as drawn.

Either way you can play-test the character in an arena, then export it for Godot 4, Unity, GameMaker or Spine, or as a sprite sheet, PNG frames or a GIF. Every format carries a hurtbox, hitboxes and events for each frame.

The header has four modes: Animate, Rig, Edit and Play. The right-hand panel shows one group of cards at a time, picked with the tabs along its top (for example Moves, Polish, Export, Looks and Sprite in Animate). Each mode remembers its tab. Rig and Edit are hidden while a sprite-sheet character is loaded.

Sprite Puppeteer is one of four tools in Keyframe.it Studio, with the Keyframe.it editor, MeshForge and PixelForge.

Getting started

Open Sprite Puppeteer. The first time, it shows the sample orc, isometric and facing down. After that it reopens the last character you worked on.

With a sample

1. Click Projects in the header and pick Sample golem (rigged), Sample orc or Sample knight (sprite sheets rendered in Blender). The same buttons are in the Sprite card.
2. In Animate, click a move in the Animations list, or press the key shown on its button. P plays or pauses; , and . step one frame.
3. For the orc or knight, pick a Camera and a Direction in the Sprite card. The Pixel / HD switch on the stage changes the look.
4. Switch to Play, click the stage once and move with the arrow keys. The Controls tab lists every key.
5. Back in Animate, open Export, pick a Format and click the export button.

With your own sprite

1. Click Load PNG… in the Sprite card, or drop the file on the stage. Draw side views facing right; Mirror image flips one that faces left.
2. The tool places a skeleton from the sprite's shape and switches to Rig. Change Body type if it is not a humanoid.
3. Drag the coloured dots onto the joints. Tick Preview motion to watch a move while you adjust.
4. Optional: on the Parts tab, paint weapons as Prop, capes as Cloth and hair or tails as Jiggle.
5. In Animate, try the moves and pick styles. Test in Play, then export.

Loading sprites

A single image

Load PNG… takes PNG, GIF, WebP, JPEG, Aseprite (.aseprite, .ase) and PSD files. The Sprite card sets how the image is read:

• Detail (longest side): 160, 256, 420 (default) or 640 px. Larger images are scaled down to fit.
• Colours: Keep all, or reduce to 64, 32 or 16. Useful for painted or AI-made art.
• Pixel size: Auto detects upscaled pixel art and returns it to its native grid. You can also set 1 to 16.
• Background: Remove from edges (default), Remove everywhere, or Keep (use alpha).

These settings apply to sprites you load, not to the samples.

Layers, Aseprite and PSD

For a layered character, load the body first, then click Add layer… and pick extra PNG or WebP files of the same size. Each layer gets a role (Body, Rigid part, Prop, Cloth, Jiggle or Swap art), a bone and a draw order. Names pick a starting role: sword or shield becomes a Prop, cape or robe Cloth, hair or tail Jiggle, eyes-closed or mouth-open Swap art, and a bone name such as Forearm L a Rigid part.

Aseprite and PSD files load the same way: every visible layer becomes a sprite layer and keeps its name. Hidden layers and groups are skipped. From Aseprite the first frame is used, and tags named side, front, back, front 3/4 or back 3/4 each become a view. PSDs can be 8 or 16 bit, RGB or grayscale, from Photoshop, Krita, Procreate, Photopea or GIMP.

A folder of sprite sheets

Click Load sprite sheets… and pick the folder, or drop it on the stage. It needs PNG sheets with their JSON (TexturePacker or Aseprite, hash or array), or a manifest.json.

Without a manifest, the folder holding a sheet is its camera set and the folder above that is its look:

• orc/pixel/side/orc_side_walk.json + .png
• orc/pixel/topdown8/orc_topdown8_walk.json + .png
• orc/hd/topdown8/orc_topdown8_walk.json + .png

Folders named side, iso8, topdown8, topdown4 and similar get tidy labels. With no look folder, there is one look. A prefix shared by every sheet in a folder (orc_side_) is dropped from move names.

Name each frameTags entry <move>_<direction>, such as walk_SE or idle_down. Directions are compass letters (E, SE, S, SW, W, NW, N, NE; S faces down the screen) or words like right, downleft or up. A word such as left only counts as a direction when the move comes in several directions, so shuffle_left stays a move. A tag with no direction faces right. Untagged sheets are grouped by frame name without the numbers (walk_E_00, walk_E_01…).

The frame rate comes from the JSON, otherwise 12 fps. Rotated frames are not supported. A manifest.json can list everything instead: sets with their directions and animations, and per look an image, data, cell and pivot_px.

Rigging

Body types

Pick one under Body type in Rig mode. Each has its own skeleton and moves:

Joints

• With Move joints on, drag the dots onto the joints. Skin weights recompute when you let go.
• Auto-fit places joints from the body's proportions. Reset puts them back where they started. Mirror L → R copies the left side to the right.
• Weapon hand (screen side) sets the hand that holds the weapon. Show weights colours the sprite by bone. Joint blend softens the seams.

Painting parts

Switch to Paint parts and pick a mode on the Parts tab:

• Prop: rides one bone and never bends. Swords, shields, helmets.
• Cloth: hangs, trails and flutters. Capes, robes, scarves.
• Jiggle: keeps its shape but springs. Hair, tails, ears, chains.
• Bind: ties pixels to a chosen bone where auto-skinning got it wrong. Erase hands them back.

Set Attach to and Draw order, then paint with Brush or Fill similar colour.

Cut-out parts

One flat picture stretches at the joints. Export parts (Aseprite or PSD) cuts the character into one layer per bone, with a hidden guides layer circling each joint. Paint each part out to its circles, keep the layer names and canvas size, then click Load parts back…. Every part then moves as a solid piece. Tags like sword [prop Forearm R front] set other roles.

Face & FX

• Face: paint Eyes and Mouth so the character can blink, wince and shout. Automatic expressions adds them for you.
• Swap art: a layer that shows only while its channel is on (Eyes closed, Mouth open, Open hand L or R, Alternate). Channels can be keyed in Edit.
• Cloth & jiggle motion: Stiffness and Flutter.
• Glow pixels: pick a glow colour, or Auto. Glow pulses and flares on attacks.

Animating and editing moves

Moves and styles

Click a move in the Animations list, or press its key. Drag the timeline to scrub. The style bar under the timeline lists the move's styles; Walk, for example, has Standard, Heavy stomp, March, Sneak, Bouncy and Front-facing. Feel preset sets a matching style on every move: Standard, Heavy / brute, Heroic, Nimble, Bouncy / chibi, Stealth or Front-facing (RPG).

The Motion card has Speed, Exaggeration, Stepped frames, Motion smears, Dust & debris, Facing and Backdrop (Crypt, Checker, Plain, Green screen). The Polish tab adds Hit-stop, Overshoot, Weapon drag, Smooth rotation, Outline (Leave as drawn, Repair edges, Add outline) and stray-pixel clean-up.

Edit mode

• Your own moves: click New move or Copy as a new move. Pause on a frame and drag a joint to set a key. Set the name, hotkey, length and looping, an ease for each key, and events such as Hit with main hand, Ground slam, Cast an orb or Footstep.
• Built-in moves: a drag records a touch-up that blends into nearby frames. Blend sets how far.
• Pose at this frame: Copy, Paste, Mirror (front-facing art), Swap sides (side-view cycles) and Rest pose.
• Guides: onion skin (red before, blue after) and motion paths for hands, feet and head.

On the Pixels tab, Paint pixels fixes single pixels on one frame with Pencil, Eraser and Pick colour. Fixes go into every pixel export.

The Describe tab asks Claude to draft keyframes from a sentence. It only works when the tool runs on claude.ai. Elsewhere, build moves by hand or use an AI agent through the MCP connector.

Directions, camera sets and looks

Sprite-sheet characters

The Sprite card has a Camera chip per camera set, a Direction compass and a Look list. Directions marked ⇋ are mirrored from their opposite: a side view facing right also covers left. A missing diagonal uses its mirror or the nearest drawn direction. The frame rate comes from the sheets.

The Pixel / HD switch appears when there is more than one look. On the samples, Pixel is 128 px pixel art and HD the same renders at 256 px. HD loads the first time you pick it (about 25 MB for the orc). Exports use the current look.

The tool adds events (impacts, take-off, landing, falls), hurtboxes from the solid body and hitboxes from whatever reaches past the idle pose. Known move names get a group and a Play key: idle, walk, run, jump, crouch, dodge, attack, attack2, cast, block, hurt, stunned, knockdown, death, celebrate, taunt and more. Others get a free key.

• crouch_walk, sneak, walk_back and shuffle_left/shuffle_right have no key. Your movement plays them in the arena.
• A sheet named like axe_projectile is a thrown object. A throw whose notes give the release frame launches it from the hand. Exports keep it as its own animation and add a throw event.

The sample orc has 18 moves and a thrown axe in Side, Isometric, Top-down 8 and Top-down 4 sets. The sample knight has 14 isometric moves plus idle, walk, run and attack in side and top-down sets.

Rigged characters

Add Front, Back, Front ¾ and Back ¾ views next to Add view… in the Sprite card. Each view has its own joints and shares the moves, styles, outfits and recolours. Front and back views step in place for walks and runs.

Outfits and colours

On the Looks tab, hide layers with the dot buttons in the Sprite card and save the combination as an outfit. A recolour groups the sprite's colours; change a swatch and the group follows, keeping its shading. Export every outfit and colour makes a sheet for each combination.

Play-testing in the arena

In Play, click the stage once so it has keyboard focus. Touch buttons sit under the stage. Pick a Stage:

• Training room: one screen with the training dummy, which counts Hits, Damage and Best.
• Platforms: ledges sized to your jump, to test arcs and landings.
• Top-down: move in eight directions. Rigged characters use their front, back and ¾ views; sheet characters switch to a top-down or isometric set.

Tick Sparring partner for a tinted copy of your character that fights back. Hits use the same boxes as the exports.

The Controls tab shows the exact keys for the loaded character, including your own moves with a hotkey. A looping move that is not movement, such as Hover, plays twice and stops; any other key takes over at once.

Exporting

Open Animate › Export, set the options, pick a Format and click the main button (its label follows the format).

• Frame rate (8 to 30 fps) and Pixel scale (1× native to 4×).
• Frames: This animation or All animations.
• Directions: This view only, 4 or 8. Tags then read walk_down, walk_left, walk_upright and so on.
• Include dust, debris & sparks, and Show hit and hurt boxes on the stage to check them first.

Boxes and events are measured from the ground point under the feet. Big sheets split into pages of up to 4096 px. Engine zips include a README with the steps.

Sheet exports have a transparent background.

Projects and saving

Every character saves itself in this browser as you work: views, joints, parts, moves, styles, outfits and fixes. The Projects button in the header opens the library.

• Rename a character by editing its name. Open, Duplicate or Delete it; Delete asks you to click twice.
• New from image… starts a character from a sprite. Samples open as new characters and save once you change something.
• Save project file writes a .puppet.json; Open project file… reads one back in any browser.

Browser storage belongs to that browser alone, so use project files for backups and to move characters. If the browser blocks storage, the Projects dialog says so and project files still work. Undo and redo cover rig, paint and edit changes.

Working with the other Studio tools

On keyframe.it.com the Studio tools hand characters over through your browser's storage. A hand-over is read once and expires after 30 minutes.

• Keyframe.it editor: Menu → Send to Sprite Puppeteer renders the clips you pick as sprite sheets and opens them here as a character.
• MeshForge: in the sprite-sheet dialog, set Then open in to Sprite Puppeteer. Side-scroller, top-down and isometric views come across.
• PixelForge: Export → Open in Sprite Puppeteer sends an animation as a sheet character. For a still sprite the button reads Rig it in Sprite Puppeteer.
• Back to the editor: Open in Keyframe.it ↗ in the Export card sends a rigged character and all its moves as a Spine skeleton. It shows only on keyframe.it.com. If the new tab is blocked, use the link under the button.

AI agents

The scripting API window.spritePuppeteer lets an AI agent load art, pick views, play moves, render contact sheets, create keyframed moves, change settings and export, all without clicking. Methods are async and return JSON; spritePuppeteer.help() lists them.

The Keyframe.it MCP server exposes it as puppeteer_* tools. It needs Node 18+ and Google Chrome. In Claude Code run claude mcp add keyframe -- npx -y keyframe-mcp; other clients use command npx with args ["-y", "keyframe-mcp"].

1. puppeteer_open (optionally with a sample) or puppeteer_load_image with a file path.
2. puppeteer_state, then puppeteer_contact_sheet and puppeteer_set_view to judge moves.
3. Rigged characters: puppeteer_move_guide, then puppeteer_create_move.
4. puppeteer_export writes the files; puppeteer_open_result shows the page in Chrome.

Details are in llms.txt.

Keyboard shortcuts

You can also pan by dragging the stage in Animate, or an empty spot in Rig and Edit. Play mode keys are listed above.

Troubleshooting and tips

• Limbs stretch. Paint weapons as Prop, or use Cut-out parts.
• An area follows the wrong bone. Check joints with Show weights, then paint it with Bind.
• Background left behind, or holes. Change Background: Remove everywhere, or Keep (use alpha) for clean transparency.
• Upscaled art looks uneven. Set Pixel size by hand.
• Rig and Edit are gone. A sprite-sheet character is loaded. Load PNG… or Sample golem goes back.
• Spine is greyed out. Spine needs a rigged character.
• “No sprite sheets found.” The folder needs PNG sheets with JSON, or a manifest.json.
• Keys do nothing in Play. Click the stage first.
• Ledges out of reach. The character has no jump.
• 4 directions gives only left and right. Add Front and Back views.
• “Nothing was waiting to open.” Send it again from the other tool.
• Tip: use the Checker backdrop for a transparent GIF.

Frequently asked

More answers about the whole Studio in the FAQ.