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.

Use bg to set a scene's backdrop to an image or a solid color while leaving sprites in place. Choose an image reference for a location or CG, or color(#rrggbb) for a full-frame color without a media asset.

An inline with dissolve, with fade or with slide changes the backdrop alone and continues to the next event by default. Dissolve and fade blend the old backdrop into the new one; slide pushes the old one off the frame as the new one enters from the opposite edge, plays only on forward motion, and moves left unless you pick another direction with slide(0.8, direction=up) or the arrow buttons in Forge. It also takes an optional curve for its motion, such as slide(0.8, curve=bounce) or the Motion dropdown. Enable Wait for it to finish in the Inspector, or add wait=true inside the transition call, to hold the story until the transition ends. Put background and sprite events inside one transition block when they should blend together.

Leaving wait out or setting wait=false keeps a background transition running while the story continues. This setting waits for the transition duration, not for video-backed background playback. Inside a transition block, the block controls waiting and a child bg has no transition clause or wait switch of its own; slide is only available as a bg's inline clause, never as a block.

fit applies to media references; a solid color already fills the stage and cannot take fit. Backgrounds clear at ordinary scene boundaries. Configure story-wide access to a background or CG in Forge Money; one unlock follows the media asset wherever it appears.

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 at the same moment cuts. Closed name set: `dissolve`, `fade`, and the background-only `slide`. `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). `slide(seconds)` pushes the old backdrop off the frame as the new one enters from the opposite edge, sprites untouched; bare `slide` = 0.6s leftward, `direction=<left\|up\|right\|down>` picks where the old art exits, and `curve=<name>` picks its motion (`linear`, `slide` default, `accel`, `decel`, `overshoot`, `bounce`, `elastic`). It plays only when the story moves forward - Back restores the earlier backdrop at once. Background transitions continue to the next event by default. Enable the Inspector's Wait for it to finish switch, spelled `wait=true` inside the call, to wait for the transition duration; omitted or `wait=false` continues immediately. This waits for the transition, not video-backed background playback. 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 or wait switch.

Canonical example

Folio

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

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 at an ordinary 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. Imported Ren'Py routes can use carry-stage to preserve the backdrop and sprites across a scene boundary.

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.

Background transitions continue immediately by default. Choose Fade, Dissolve or Slide in the Inspector, then enable Wait for it to finish to hold the story until the transition ends. In Folio, write bg bg-kitchen with dissolve(0.8, wait=true) or add wait=true inside a fade(...) or slide(...) call. Leaving it out or setting wait=false lets the next event run during the transition. With no transition, the background changes immediately.

slide pushes the old backdrop off the frame (left by default, or up, right or down) while the new one enters from the opposite edge, sprites untouched. It plays only when the story moves forward; Back restores the earlier backdrop at once.

The inline transition blends only the backdrop. To blend a background and sprites together, put their events inside a transition block. The block controls whether the story waits; its child bg has no transition clause or wait switch of its own.

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. Wait for it to finish waits for the background transition, not for the video to finish playing.

Visual access

Configure a background or CG's story-wide access in Forge Money. One unlock follows the resolved media asset across its appearances, even when different scene events refer to it. A video-backed background uses that video's access settings. A solid color(...) backdrop has no media asset to unlock. Access settings travel with the project authoring context rather than an extra clause on bg.

The timeline shows a small lock beside a monetized background's name. Its normal Inspector thumbnail shows the same reminder in the top-right corner. Choosing an unmonetized background removes both reminders. Prices and access editing belong in Money; the raw Asset Manager and background picker remain media-selection tools.

Parameters

Canonical example

Notes

Visual access

See also