@fade

Fade the frame out to a color and back in around a `transition fade:` block's changes, or bring one new background up from the color with `with fade`. Never an effect line, never a Style.

Reach for a fade when a change should feel like a break rather than one continuous moment: the next morning, a new location, the close of a chapter. A transition fade block fades the whole frame to its color, makes every change inside the block while the screen is covered, and then fades back in, so the reader never watches the old scene turn into the new one. For a single new backdrop, put with fade on the bg line instead: the new background comes up out of the color while any sprites on stage stay visible.

A fade always comes back, so it cannot hold the screen on a color by itself. To go dark and stay there, for narration in the dark or a pause before the next scene, change what is on stage inside one transition fade block: hide the sprites and set a solid color background such as bg color(#000000). The picture fades out and returns to a stage that is now only that color, dialogue plays over it, and a later bg line with fade brings the scene back.

Black is the default and reads as time passing or a scene closing. White suggests a memory, a blinding light or someone waking up, and a deep color taken from the next scene's palette softens the cut. Give the color as a hex value such as #ffffff, on the block header or on a background's with fade.

The duration runs from 0.1 to 5 seconds and defaults to 1, and the block header and a background with fade take the same range. A short fade reads as a blink; the upper end gives a slow, deliberate close before the next scene.

A transition fade block holds the story until it finishes. With wait=false in the header, the fade to the color still plays in full, but the next event starts while the picture fades back in, so a line of dialogue can appear as the scene returns. A background's with fade lets the story continue by default; add wait=true inside its call when the next line should wait for the reveal.

Use dissolve instead when the old picture should blend straight into the new one with no color in between: a fade hides the change behind the color, a dissolve shows it happening. There is no @fade line to write. The parser rejects one with an error that points to a transition fade block, a bg with fade, or a solid color background.

Demo

@fade

Hello.

A color overlay ramps over the stage and back to clear. A transition fade block plays both halves around its changes; a background's with fade plays only the reveal, on the backdrop.

Parameters

Parameter	Kind	Required	Default	Notes
duration	number	no	1	0.1-5 seconds. Default 1.
color	string	no	#000000	Hex color (#rgb or #rrggbb) or white/black. Default #000000.
wait	boolean	no	true	Block for the effect's duration when true; false fires and continues so effects can overlap.

Canonical example

Folio

transition fade(1, color=#000000):
  bg bg-kitchen-morning
say "Emma": "A whole night, gone."

Ren'Py

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

@fade is the runtime effect a fade transition lowers to. It has two spellings:

A transition fade(...): block fades the whole frame out to color, applies every change inside the block under the opaque wash, then fades back in. The header's duration splits in two, one half per leg. That is Ren'Py's with fade.
A background's with fade(...) plays only the reveal: the new backdrop comes up out of the color while sprites stay visible.

There is no @fade line, and Fade is not a Style: a held color overlay could not be edited or cleared from the Style card. An @fade line is a parse error that points at the two spellings above.

Notes

To go to a color and stay there, change what is on stage instead of holding an overlay: set a solid color background and hide the sprites, inside one fade so the change reads as a single beat.

transition fade(1.5, color=#000000):
  sprite hide emma
  bg color(#000000)
say "Emma": "Hours later."
bg bg-kitchen-morning with fade(1)

The black is the background now, so dialogue plays over it, and the next bg ... with fade brings the scene back.

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.

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. An older project that still stores a fade-and-hold step keeps playing it, shown in Forge as a preserved event the creator can delete.

Demo

Parameters

Canonical example

Notes

See also