sprite

Show a project sprite in a scene, then set its frame, move it, switch its idle motion, or hide it - every sprite is present (hidden) until shown.

Use sprite events to place a project sprite in a scene and change it over time. A sprite's name refers to one definition in the Sprite Manager, where its frames and starting stage settings live. Show reveals it, Hide removes it from view, and Set chooses a frame or facing. Move changes position, size, rotation, or anchor; Motion changes its resting animation; Layer changes which sprites paint in front. Each of those changes has a matching timeline event and inspector.

A sprite begins each scene hidden. A first Show follows its Sprite Manager defaults unless earlier sprite events in that scene changed its state. You can stage a frame before revealing it, then use later events to move it, change its expression, or place it in front of another sprite. Configure story-wide visual access in Forge Money: one unlock covers the sprite definition and all its current and future frames.

Placement belongs to Move. For a reveal at a specific spot, add a Sprite: Move event beside Sprite: Show. Move can resize and rotate as well as reposition, and can set an anchor without changing position. Omitted fields keep their current values.

Paint order belongs to its own Sprite: Layer event. Use sprite layer vee 2 for a numbered layer or sprite layer vee auto to restore automatic order. An inline z(...) clause on Show, Set, or Move is rejected. Imports and stored-data upgrades express that change with a separate Layer event.

Show, Hide, and Set can use a fade or pixelate transition; a Set transition blends between looks. Move uses a motion curve for travel, with optional independent timing for animated size or rotation. Motion and Layer settings persist until another event changes them.

A small lock beside a sprite event's name reminds you that its sprite has monetization settings, including on Move and Hide. Prices and visual access editing belong in Money. Older event locks are preserved as review input for Money's upgrade flow, not new Sprite Action settings.

Parameters

Parameter	Kind	Required	Default	Notes
slug	identifier	yes	-	The sprite's name and identity - used verbatim as the Folio token (`sprite show vee`). It points at a sprite defined in the project's Sprite Manager; every `show` / `hide` / `set` / `move` reuses the same name. Names are id-ruled (no spaces, start with a letter or underscore) and unique across the project. Renaming a sprite in the Sprite Manager rewrites every line that referenced it, so references never break.
frame	identifier	no	-	A named frame on the sprite's definition - each frame pairs a name (`happy`, `door-open`) with an image. On `set` it is required (`sprite set vee frame surprised`) and swaps to that frame's image without changing identity, position, or visibility; a sprite shown without a prior `set` uses the definition's default frame. Frames are authored in the Sprite Manager, so a `set` can never name an image the sprite doesn't have.
layer	number	no	-	The paint-order verb - `sprite layer vee 2` - re-layers the sprite from that point on: higher numbers paint in front of lower, and `sprite layer vee auto` returns it to automatic order (equal layers paint last-shown-in-front). It is its own event (like `motion`), takes no other clause, and is the only way to change a sprite's layer mid-scene - paint order, never movement. A sprite's starting layer is its Sprite-Manager default. A Ren'Py `show x zorder N` imports as a `sprite layer` line emitted just before the show, so the sprite is already on the right layer while any entrance plays. Layer changes always use this separate event. `z(N)` on another sprite verb is an error.
flip	identifier	no	-	Optional horizontal mirror on `show` / `set` - `flip(x)` mirrors the art left-to-right (a character facing the other way), `flip(none)` un-mirrors it, `flip(default)` re-follows the sprite's default flip from the Sprite Manager. It sits before `entrance(...)`. Omit it to keep whatever flip the sprite already has - so `sprite show vee frame sad` after a flipped show stays flipped, and a fresh show follows the sprite's default flip from the Sprite Manager. A flip never moves the sprite (its anchor point stays put); `hide` and `move` take no flip. `flip(y)` is reserved for a later vertical flip. The Sprite Action inspector's Flip control (No change / Default / Original / Flipped) writes it; on its own it spells `sprite set vee frame keep flip(x)`.
at	identifier	no	-	Optional position on `move` - `at(X, Y)` where X,Y are percent (`50%`) or pixel (`200px`) lengths marking where the anchor point lands. `move` repositions the sprite; a sprite shown without a `move` uses its default position from the Sprite Manager (then bottom-center). The stage edit box writes this when you drag the sprite; it emits percent so the placement survives a viewport resize.
size	identifier	no	-	Optional resize on `move` - `size(W)` or `size(W, H)` where W,H are percent (`40%`) or pixel (`200px`) lengths (H may be `auto` to keep the aspect ratio). A bare `size(40%)` snaps the width instantly before the move; an arrow animates it - `size(-> 40%)` eases from the sprite's current size, `size(10% -> 40%)` from an explicit start. An animated resize rides the position's `with` clock unless it carries its own inner timing (`size(-> 40% with decel 0.3)`). Omit to keep the current size (the Sprite-Manager default until a move changes it). The Move inspector's Resize card writes this; its Motion row sets the track's own curve + duration (Instant snaps).
rotate	identifier	no	-	Optional rotation on `move` - `rotate(D)` in degrees, pivoting around the sprite's `anchor` (so `bottom-center` leans a character around their feet, `center` spins a logo in place). A bare `rotate(15)` snaps; an arrow animates it - `rotate(-> 15)` turns from the current angle, `rotate(0 -> 720)` spins twice from 0. An animated turn rides the position's `with` clock unless it carries its own inner timing (`rotate(-> 720 with elastic 1.2)`). Go past 360 for full spins; negatives turn the other way (clamped to ten turns each way). Omit to keep the current angle. The Move inspector's Rotation card writes this; its Motion row sets the track's own curve + duration (Instant snaps).
anchor	identifier	no	-	Optional anchor point on `move` - which point of the sprite box the `at(X, Y)` position pins to. One of `top-left`, `top-center`, `top-right`, `center-left`, `center`, `center-right`, `bottom-left`, `bottom-center`, `bottom-right`. Omitting the clause keeps the current anchor; `anchor bottom-center` explicitly selects bottom-center. Only a `move` carries an anchor: a `show` never positions anything, so a sprite shown without a `move` anchors via its Sprite Manager default (then `bottom-center`). The Anchor dropdown in the Move inspector reads + sets it; the stage drag box no longer materializes the default.
motion	identifier	no	-	The idle-motion verb - `sprite motion vee heavy` - switches the resting breathing + head-sway a sprite performs while standing still. The profile token is one of `none` (stops it), `relaxed`, `quick`, `heavy`, or `exhausted`; depth, rate, and sway follow that profile's preset. It is its own event (like `move`), takes no other clause, and lasts until the next `sprite motion` on the same sprite. A sprite's starting idle motion is its Sprite-Manager default; `sprite motion` overrides it mid-scene.
with	string	no	-	Optional transition tail. On `show` / `hide` it is `with fade` - a per-sprite alpha fade (fades in on `show`, out on `hide`); `with fade(0.5)` sets the seconds, bare `with fade` uses the default. On `move` it is `with <curve>(<duration>)` - the POSITION track's motion: `teleport` (the default - instant snap), `linear`, `slide` (smooth ease-in-out), `accel`, `decel`, `overshoot` (sails past and settles), `bounce`, or `elastic`, with the duration in seconds (e.g. `with slide(0.5)`; bare `with slide` uses the default). Omitting the tail on `move` snaps the position instantly, exactly as before. An animated `size(-> ..)` or `rotate(-> ..)` track rides this clock when it has no timing of its own; a track with an inner timing (`size(-> 40% with decel 0.3)`) runs on its own curve + duration - so position, size, and rotation can each animate independently. When the position snaps but a track animates, only the inner timings appear (no shared tail; a size/rotate-only animated move still emits one, donated by the track); a held instant-position move keeps its hold as `with teleport(hold=true)`. On `set`, `with fade` or `with pixelate` transitions between frames, using the Sprite Action inspector's Transition control.

Canonical example

Folio

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

Ren'Py

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

A sprite is defined once in the Sprite Manager, with named frames and defaults for its frame, placement, anchor, layer, flip, and idle motion. Each scene starts with the sprite hidden. Folio events refer to the sprite by its name:

sprite show vee reveals it. A first show uses its Sprite Manager defaults. Show can select a frame, set horizontal flip, choose an entrance effect, and use a with fade or with pixelate transition.
sprite hide vee hides it. A later show can reveal it again.
sprite set vee frame happy selects a named frame without changing placement or visibility. Set can also change horizontal flip or transition between looks with with fade or with pixelate.
sprite move vee at(50%, 100%) changes placement. A Move can also change size, rotation, or anchor, independently of position. Its with clause animates the position; size and rotation can animate on that clock or use their own timing.
sprite layer vee 2 changes paint order. Higher layers paint in front; sprite layer vee auto returns to automatic order.
sprite motion vee heavy changes the sprite's resting motion profile.

Notes

Only a Move changes a sprite's position, size, rotation, or anchor. Put those values on a separate sprite move event. For example:

sprite show vee frame happy
sprite move vee at(50%, 100%) anchor bottom-center
sprite layer vee 2

Layer changes always use their own sprite layer event. An inline z(...) clause on Show, Set, or Move is an error. When an imported scene changes a sprite's layer, the importer creates a separate Layer event so it remains editable in the timeline.

Omitting a Move field keeps that field's current value. A bare Move with no position, size, rotation, or anchor change produces a warning. A bare Show uses the current frame and flip if the sprite has already been staged; otherwise it starts from the Sprite Manager defaults. Background changes leave sprites in place.

with fade and with pixelate on Show, Hide, or Set change the sprite's appearance. On Move, with slide(0.5) or another motion curve changes how the position travels. A Move without a curve snaps its position. The Move inspector can also wait for an animated move to finish before advancing.

Visual access

Configure a sprite's story-wide access in Forge Money. One unlock covers the sprite definition and all its current and future frames wherever it appears. Changing the sprite's name or a frame's art keeps that identity. Sprite events still control its appearance and placement; access settings travel with the project authoring context rather than a new scene verb.

The timeline shows a small lock beside every event that refers to a monetized sprite, including Move and Hide. The sprite picker and Sprite Manager header also show a lock. These are reminders of the sprite's access settings; prices and visual access editing belong in Money.

Older projects can carry a lock on an individual Show event. Review those placements in Money before upgrading them to story-wide access. Compatible upgrades keep their offer codes and existing buyers' access. Differing settings, conditions, or previously free appearances need review rather than an automatic upgrade. The Sprite Action inspector edits the sprite action; it does not create or change those older event locks.

Parameters

Canonical example

Notes

Visual access

See also