FolioTier 2

@fade

Fade the stage out to a color and hold it there - the out half only. A `transition fade:` block plays both halves around its body; `bg ... with fade` plays the reveal.

Use @fade when you want the stage to fade to a color and stay there, like a scene ending in darkness before you cut to the next beat. It is the out half of a fade only: the stage commits to the color and holds, and nothing brings it back until you write a follow up line. That is why the canonical pattern pairs it with bg ... with fade right after: the @fade covers the old scene, then the bg call reveals the new one.

Reach for @fade on its own when the hold matters dramatically - a beat of black before dialogue, a slow fade to white for a memory, a pause where you want the player sitting in the color for a moment. If you just want an ordinary crossfade between two backgrounds with no dramatic pause, skip @fade entirely and let a transition fade: block or a bare bg ... with fade handle both halves.

direction is always out when you write @fade directly; in is never authored by hand, it only exists as the second leg a transition fade: block plays automatically, or as what bg ... with fade lowers to for the reveal. Writing @fade and then forgetting a reveal line leaves the stage covered indefinitely, since nothing times out the hold on its own.

target=backdrop is the move when you want the background to vanish into the color but sprites to keep acting on top of it - useful for a character reacting while the setting itself dissolves. Leave target empty when the whole frame should go, sprites included.

set wait=false if you want the fade to start and let dialogue or another effect run during the hold rather than blocking on it. That is also how you stack effects, like a fade under a shake.

Demo

@fade

Hello.

A color overlay slides over the stage. As a line, `@fade(direction=out)` ramps the overlay from clear to solid color and holds it; the reveal back to clear is the `with fade` / `transition fade` form of the same effect.

Parameters

Parameter	Kind	Required	Default	Notes
duration	number	no	1	0.1-3 seconds. Default 1.
color	string	no	#000000	Hex color (#rgb or #rrggbb) or white/black. Default #000000.
direction	string	no	in	Must be `out` on an `@fade` line (fade to the color and hold). `in` is never written on a line: it is what `bg <image> with fade(...)` lowers to, and what the second leg of a `transition fade:` block plays after the first leg has taken the frame to the color.
target	string	no	""	What the color covers: empty (default) is the whole frame including sprites; `backdrop` covers only the background layer so sprites stay visible. Sprites are not a target - a sprite fades with its own `with fade` on show / hide.
wait	boolean	no	true	Block for the effect's duration when true; false fires and continues so effects can overlap.

Canonical example

Folio

bg bg-bedroom-night
@fade(direction=out)
bg bg-kitchen-morning with fade
say "Emma": "A whole night, gone."

Ren'Py

scene bg bedroom_night
with fade
scene bg kitchen_morning
with fade
e "A whole night, gone."

@fade paints a single color overlay across the stage and tweens its opacity in one direction. The two directions have two different homes:

Out and hold is the @fade(direction=out) line: the overlay ramps from clear to solid color and the stage stays there. In Forge it is the Style > Fade event (Global or Background scope). direction=out is required on the line; it is the only thing this line does.
The reveal (solid color back to clear) is a transition, not a line: bg <image> with fade(...) on the Background event lowers to this same effect with direction=in. A fade-in first tears down any lingering fade-out overlay, then removes its own overlay when the tween ends.
Both halves at once is a transition fade(...): block: the header's duration splits in two, the out leg runs, the body applies under the opaque wash, then the in leg runs. That is Ren'Py's with fade, and it needs no separate line.

An @fade line without direction=out is a parse error that points at the transition spelling. Reach for the line only when the screen should STAY on the color: "fade to black, beat, fade in on a new scene" is an out line followed by a with fade backdrop.

Notes

The overlay is what holds the screen on the color between the out and the reveal. It stays up until either a with fade or a transition fade: block supersedes it or a backdrop change starts the next scene fresh - so you can swap the bg while the screen is held at color and the reader never sees the cut.

target chooses what the color sits over:

target="" (default) covers the whole frame, sprites included - everything goes to the color.
target=backdrop covers only the background layer, leaving sprites rendered above the color. Use it to dissolve a backdrop out from under characters who stay on stage.

color is a hex literal (#rrggbb / #rgb), not a theme token. Black is the default; white reads as a sunlit blowout or a bright cut.

A common pattern brackets a background swap with an out line and a with fade reveal:

bg bg-bedroom-night
@fade(color=#000000, direction=out)
bg bg-kitchen-morning with fade
say "Emma": "Hours later."

The same beat written as one block, with the swap inside it:

transition fade(1, color=#000000):
  bg bg-kitchen-morning

The importer never writes an @fade line: a Ren'Py with fade arrives as the bg ... with fade(...) clause or as a transition fade: block around the changes it applied to. Fading out and STAYING there has no transition-verb spelling; @fade(direction=out) is the only way to write it.

Studio

@fade

Demo

Parameters

Canonical example

Notes

See also