FolioTier 1

bg

Set the background — clears the layer, then stages a new image.

Parameters

Parameter	Kind	Required	Default	Notes
image	identifier	yes	—	Identifier of the background image registered in the project's image table. Quoted form (`bg "bg kitchen morning"`) is accepted when the reference contains characters outside the identifier pattern.
as	string	no	—	Optional alias for the staged image. Surfaces in the node editor and migration report so authors can distinguish two `bg` calls that target the same asset (e.g. with different lighting).
tag	identifier	no	—	Optional tag used to identify the staged image for later `hide`. Defaults to the first whitespace-separated token of the image reference, matching Ren'Py's implicit tag rule.
on	identifier	no	background	Optional layer override. `bg` defaults to the `background` layer — naming a different layer (`on master`, `on overlay`) stages the image there instead.
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 new background takes effect. Same identifier set the standalone `transition` verb accepts (`fade`, `dissolve`, named project transitions).

Canonical example

Folio

bg bg-kitchen-morning
bg bg-park-afternoon with fade

Ren'Py

scene bg kitchen_morning
scene bg park_afternoon with fade

bg is the background swap. The runtime clears the target layer (by default the background layer), then stages the named image. This matches Ren'Py's scene semantics — every existing image on the layer goes away in the same step the new one comes in. (The verb is named bg to disambiguate from the story-unit "scene" surfaced in the studio's left rail; the importer rewrites Ren'Py's scene keyword to bg on the way in.)

Notes

The first positional argument is an image reference, not a literal path. Images are registered in the project's image table during import (Ren'Py image bg kitchen_morning = "bg kitchen morning.png" lands as a row keyed by the lookup string). The serializer round-trips the reference as a bare identifier when the value matches Folio's identifier pattern, and falls back to a quoted string otherwise — so the canonical example shows the unquoted form authors will see in practice.

bg defaults to the background layer. To clear a non-background layer (rare — usually show / hide is what you want there), pass on <layer>. The with <transition> tail applies a transition to the single staging operation; for a transition that runs at an explicit point in the scene without a stage change, use the standalone transition verb instead.

Parameters

Canonical example

Notes

See also