Parameters

Canonical example

sprite set vee frame happy
sprite move vee at(50%, 100%)
sprite motion vee heavy
sprite layer vee 2
sprite show vee with fade
sprite set vee frame surprised
sprite move vee at(80%, 100%) size(-> 60%) rotate(-> 8) with slide(0.5)
sprite hide vee with fade
sprite show vee

show vee happy at center with dissolve
show vee surprised zorder 2
hide vee with dissolve
show vee

A sprite is a project object - you define it once in the Sprite Manager (its name, its named frames, its default position), and from then on it is present in every scene, hidden by default. You don't add it to a scene; you show it when you want it on stage and hide it when you don't. The definition is the class; show / hide / set / move are the methods that act on it:

• sprite show <slug> reveals the sprite on stage - at its default frame and default position (both set in the Sprite Manager), optionally with a with fade transition. A first show materializes the sprite, and the line can carry the full staging in one go: sprite show vee frame happy z(10) at(50%, 100%) sets the pose, stacking, and position together. A sprite that hasn't been shown in the scene is simply invisible.
• sprite hide <slug> takes it off stage. It stays defined and keeps its frame and position, so a later show brings it right back.
• sprite set <slug> frame <name> switches to one of the definition's named frames. Same object, new look - position and visibility carry over. You can set a sprite before it's shown to pre-pick its look.
• sprite move <slug> at(…) repositions the sprite - position only; a move never resizes it (the sprite's size comes from its Sprite Manager default until a size(…) clause on a move changes it). By default the move is an instant snap; add with <curve>(<duration>) to animate the sprite gliding to the new spot (see Animated move below).

Notes

The name is the identity. sprite show vee references the sprite named vee in the Sprite Manager, and that same name threads through every later line. Because the name is the reference, renaming a sprite in the Sprite Manager is a project-wide rewrite - every show/hide/set/move that mentioned the old name is updated in the same edit, so a rename never orphans a line. In Studio you pick the name from a list; when hand-authoring, use a short id-ruled slug like vee (no spaces).

Frames are the sprite's looks. Each frame is a name plus an image, authored on the definition - so set chooses an existing frame rather than naming a loose image. A sprite shown without a set uses the definition's default frame. A frame with no image yet renders as a faint, translucent yellow placeholder box at the sprite's bounds, so you can block out a scene before the art exists and fill it in later from the Sprite Manager - the change propagates to every scene that uses the sprite.

Frames may be video-backed. Ren'Py image X = Movie(...) plus show X imports as a normal persistent sprite whose frame plays the video. A Movie sprite defaults to screen size (matching Ren'Py's Movie displayable), retains explicit positioning/transforms, follows the Movie loop policy, and remains mounted across dialogue until sprite hide, a clearing imported scene, or the Folio scene boundary. Use video for a foreground cutscene instead.

Always present, hidden by default. Every project sprite exists in every scene from the first frame; it just isn't painted until you show it. There's no "add" step and nothing to clean up - hide is the opposite of show, and a sprite you never show never appears. Sprites are scene-scoped: each scene starts with all of them hidden, so a show in one scene doesn't carry into the next. (There is no cross-scene "global" sprite; a narrator or viewpoint character is shown in each scene that needs it.)

with fade (and its sibling with pixelate) is the sprite's own transition - a per-sprite blend, not a whole-frame one. It belongs to the Sprite Action card, so all three verbs take it: on show it plays in, on hide it plays out, and on set it plays across, crossfading the old frame into the new one (sprite set vee frame happy with fade(0.5)). A flip-only set takes it too (sprite set vee frame keep flip(x) with fade). Direction is derived from where the sprite already is; you only pick the kind and the length. A set that changes nothing has nothing to blend, so the tail drops on save.

flip(x) mirrors the art left-to-right on a show or a set - the "face each other" idiom (Ren'Py xzoom -1). It is sticky: a later show or set without a flip clause keeps whatever flip the sprite has, flip(none) un-mirrors it, and a fresh show follows the sprite's default flip from the Sprite Manager. A flip never moves the sprite - its anchor point stays where it was. On its own, without a frame change, it spells sprite set vee frame keep flip(x) (keep is the bare no-change sentinel). hide and move take no flip; a vertical flip(y) is reserved for later. In Studio the Sprite Action inspector's Flip control (No change / Default / Original / Flipped) writes it.

Animated move. sprite move also takes a with <curve>(<duration>) tail that animates the reposition instead of snapping. The curves are:

• teleport - instant snap (the default when you omit the tail).
• linear - constant speed.
• slide - smooth ease-in-out; the natural "glide over there."
• accel - starts slow, speeds up (ease-in).
• decel - starts fast, eases to a stop (ease-out).
• overshoot - sails slightly past the target and settles back (back.out). This was renamed from warp; warp still works as a parse alias, so older with warp(...) scripts keep importing and playing unchanged.
• bounce - lands and bounces a couple of times to rest, like a dropped ball (bounce.out).
• elastic - springs past and wobbles into place (elastic.out). Also accepted under the alias spring.

duration is in seconds (default 0.5, range 0.05-3), e.g. sprite move vee at(80%, 100%) with slide(0.5). The move still updates the sprite's stored position - only how it gets there changes - so scrubbing the timeline lands it in the right spot. In Studio, pick the curve and duration from the move event's inspector (placement is still set by dragging on stage). Each scene's first reference re-stages the sprite, so a move animates from wherever the sprite currently sits.

Hold until the move finishes. By default an animated move is fire-and-continue: it starts the glide and the next line plays right away, so a sprite can drift across the stage while a character speaks. Add hold=true inside the motion call - sprite move vee at(80%, 100%) with slide(0.5, hold=true) - to make playback wait on that move until its tween finishes, then continue on its own (like a timed pause). That is what lets a run of back-to-back moves play one after another instead of collapsing to the final position in a single frame. In Studio, the move event's inspector has a Hold here until the move finishes checkbox, shown for animated curves only. hold is ignored on a teleport move - an instant snap has nothing to wait for.

For richer per-sprite animation (pop, tint, rotate) reach for the @sprite-opacity effect family, which targets a sprite by name. To reposition a sprite, use the sprite move verb - it changes the sprite's stored position.

A background change (bg) does not touch sprites - it only swaps the backdrop, so sprites stay put across a bg.

The old sprite add and sprite delete verbs were removed on 2026-06-10. add folded into sprite show - a first show materializes the sprite and carries frame / z / placement in the same line, which is also what a Ren'Py import now emits - and hide covers everything delete did (the object is never destroyed, only hidden). The grammar no longer parses either verb.

See also

• bg - swap the background (leaves sprites in place)
• @sprite-opacity - per-sprite opacity tween by name
• characters - declaring the cast a sprite represents