FolioTier 1
show
Add an image to a stage layer without clearing the layer first.
Parameters
| Parameter | Kind | Required | Default | Notes |
|---|---|---|---|---|
| image | identifier | yes | — | Identifier of the image to stage. Looked up against the project's image table — the importer fails the build if the reference isn't defined. |
| as | string | no | — | Optional alias for the staged image. Useful when staging the same asset twice on different sides of the screen (`show emma-happy as left`, `show emma-happy as right`). |
| tag | identifier | no | — | Optional tag used to identify the staged image for later `hide` or replacement. Defaults to the first whitespace-separated token of the image reference — `show emma-happy` and a later `show emma-sad` share the tag `emma` by default, so the second `show` replaces the first. |
| on | identifier | no | master | Optional layer override. `show` defaults to the `master` layer — Ren'Py's standard sprite layer. Pass an alternative (`on overlay`, `on background`) to stage on a different layer. |
| z | number | no | — | Optional explicit z-order within the layer. Higher values stack above lower values. Omit for the layer's default ordering. |
| with | identifier | no | — | Optional inline transition applied as the image takes the stage. Equivalent to writing the standalone `transition` verb on the next line. |
Canonical example
show emma-happy
show emma-sad tag emma with dissolveshow emma happy
show emma sad with dissolveshow stages an image on a layer without clearing what was already
there. It's the workhorse for sprites — calling show emma-happy
followed by show emma-sad replaces the existing Emma sprite because
both lines share the implicit tag emma. Different tag, different
sprite: show emma-happy and show alex-happy both stay on stage
side by side.
Notes
The tag is what makes show idempotent against a given character.
Ren'Py derives the tag from the first whitespace-separated token of
the image reference — Folio matches that rule by default, so
show emma-happy and show emma-sad both auto-tag as emma (the
substring before the first hyphen in Folio, mirroring Ren'Py's
space-split). For two sprites whose references genuinely share that
first token but should stay on stage together, pass an explicit
tag <name> clause.
show defaults to the master layer — Ren'Py's standard sprite
layer. The with <transition> tail applies a transition only to this
staging operation; consecutive show lines with their own with
clauses transition independently.
See also
scene— clear the background layer and stage a new imagehide— remove a previously-staged image by tagtransition— standalone transition verb