FolioTier 1

bg

Set the background - clears the layer, then stages a new image. Scene-scoped: the backdrop belongs to its scene and clears at the boundary.

bg sets the backdrop for the current scene: it clears whatever image or color is currently on the stage and puts up the new one in its place. Reach for it whenever the location changes, whether that's a hard cut between rooms or a color card between chapters - anywhere the world behind your characters needs to be established or swapped.

Because the backdrop is scene-scoped, you don't need to clean it up yourself when the scene ends; it clears at the boundary along with everything else. Use the color form for transitional beats (black for a memory, white for a flash) without needing an artist to produce an actual asset.

fit only makes sense for image references - a solid color already fills the frame perfectly, so pairing fit with color(...) is a contradiction the compiler will flag rather than silently ignore.

The with clause only affects the backdrop layer. If a character sprite is meant to fade in alongside the new background, a with on bg won't touch it - the sprite will pop in on the same beat. For a shared crossfade across background and sprites, move the bg line inside a transition block instead of giving it its own with; a bg written inside a block isn't allowed to carry a clause of its own, so pick one approach or the other.

If you're bringing a project over from Ren'Py, don't be surprised to see scene black and hex-named images show up as color(...) automatically - the importer treats those as solid colors rather than pulling in an image asset.

Parameters

Parameter	Kind	Required	Default	Notes
image	identifier	yes	-	Identifier of the background image registered in the project's image table, OR a solid color spelled `color(#rrggbb)` - the stage fills edge to edge with that color and no image asset is involved (the inspector's IMAGE \| SOLID COLOR switch). Quoted form (`bg "bg kitchen morning"`) is accepted when the reference contains characters outside the identifier pattern. Ren'Py imports bake `scene black` and hex image defs (`image dusk = "#123456"`) into the color form.
fit	identifier	no	-	How the art fills the stage frame when its aspect ratio doesn't match: `fit(stretch)` squashes it to the frame (the default, omitted when serialized), `fit(cover)` scales it up until the frame is covered and crops the overflow, `fit(contain)` scales it down until the whole image is visible and letterboxes the remainder in black. Written as a call - `bg bg-park-afternoon fit(cover)` - and set from the Framing control in the bg inspector. Does not apply to a `color(...)` background (a solid always fills); combining them is an error.
with	identifier	no	-	Optional inline transition applied as the new background takes effect, and scoped to the backdrop alone - a sprite arriving in the same beat cuts. Same closed name set the `transition` block header accepts. `dissolve` takes an optional crossfade duration as a call - `with dissolve(0.8)` is 0.8s, and any decimal is legal (`dissolve(0.83)`); bare `dissolve` = the 0.5s registry default. `fade` is `fade(seconds, color=#rrggbb)`; bare `fade` = the defaults (1s, black). Legacy spellings like `dissolve-d8` no longer parse - they surface an unknown-transition diagnostic; write the call form. To blend the backdrop and the sprites around it together, drop the clause and put the `bg` inside a `transition` block instead; a `bg` inside a block cannot carry its own clause.

Canonical example

Folio

bg bg-kitchen-morning
bg bg-park-afternoon fit(cover) with fade
bg color(#000000) with dissolve(0.5)

Ren'Py

scene bg kitchen_morning
scene bg park_afternoon with fade
scene black with dissolve

bg is the background swap - purely a backdrop change. The runtime replaces the target layer's backdrop (by default the background layer) with the named image. (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.)

bg does not remove sprites. First-class sprite objects stay on stage across a bg - a background change is a backdrop swap, not a scene reset, so a sprite shown before the bg is still there after it. To clear a sprite deliberately, sprite hide it.

Backgrounds are scene-scoped. Unlike Ren'Py, where a scene backdrop persists until the next scene, a Folio bg belongs to its own scene: a scene's backdrop is whatever its own last bg event set, and it clears when the story crosses a scene boundary (advance, jump, call). Cross a boundary into a scene that states no bg of its own and the stage is empty - so re-state the bg in each scene that needs one. Returning from a call restores the calling scene's own backdrop (the last bg above the resume point), not the called scene's. Ren'Py imports map scene to a bg, so a later imported scene that doesn't re-state its background starts with a cleared stage; re-state the bg there.

Framing is per-bg. The stage is aspect-locked (16:9 by default), so art of a different shape has to give somewhere. fit(...) is that choice, and it lives on the event, not the project: one scene can stretch a hand-drawn panorama while the next letterboxes a 4:3 photograph. stretch is the default and the historical behavior, so a bg with no fit clause looks exactly as it always has. contain paints black bars around the art. Backgrounds still take no placement or size clauses - fit is the whole framing vocabulary; use a sprite for art you need to position.

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 clears the backdrop and stages a new image in one step. 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.

An imported Ren'Py scene X where X was defined by image X = Movie(...) uses this same backdrop contract with video media. It fills the stage, persists under subsequent dialogue, and follows the Movie's loop policy until another bg replaces it or the Folio scene ends. It does not become a cutscene overlay.

Studio

bg

Parameters

Canonical example

Notes

See also