FolioTier 1
hide
Remove a previously-staged image from its layer.
Parameters
| Parameter | Kind | Required | Default | Notes |
|---|---|---|---|---|
| image | identifier | yes | — | Identifier of the staged image to remove. Resolves against the layer's current stage by tag — `hide emma` clears whichever Emma sprite is currently shown. A `hide` for a tag that isn't on stage is a no-op and surfaces as a warning, matching Ren'Py. |
| as | string | no | — | Optional alias matching the `as` value used at `show` time. Only needed when two `show` calls staged the same tag with different aliases and you want to drop only one. |
| tag | identifier | no | — | Optional explicit tag. Defaults to the first whitespace-separated token of the image reference (same rule as `show`). Pass `tag <name>` when the reference doesn't carry the tag implicitly. |
| on | identifier | no | master | Optional layer override. Defaults to `master`. Hide on a different layer with `on <layer>` — most commonly `on background` to clear a background layered image without a full `bg` swap. |
| z | number | no | — | Optional z-order disambiguator. Rarely needed — included for symmetry with `show` and the rare case of multiple staged images sharing a tag at different z values. |
| with | identifier | no | — | Optional inline transition applied as the image leaves the stage. |
Canonical example
hide emma
hide emma with dissolvehide emma
hide emma with dissolvehide removes a staged image by tag. Pass the same reference you
showed (show emma-happy … hide emma-happy) or just the tag
(hide emma) — both resolve to the same on-stage entry because
tag derivation is symmetric across show and hide.
Notes
A hide whose tag isn't currently on stage is a warning, not an
error — Ren'Py treats the same case as a no-op, and games in the
corpus rely on that forgiveness. The importer carries the warning
through to the migration report so authors can review the dead
hide calls without the import failing.
hide defaults to the master layer; pass on <layer> to clear a
non-master layered image. For switching backgrounds, use
scene — it's a clear-and-stage in one step,
which reads cleaner than a hide followed by a scene on the same
asset.
See also
show— stage an imagescene— clear the background layer and stage a new imagetransition— standalone transition verb