Transitions — Ren'Py Documentation (2024)

Transitions can be used as part of the with statement, as well as in other parts of Ren'Py, to applyeffects to changes in the scene. Ren'Py comes with a small number ofpre-defined transitions, which can be given directly to the withstatement. It also includes transition classes, which can be used tocreate new transitions.

Pre-Defined Transitions link

Pre-defined transitions can be given directly to the withstatement. For example:

show bg washingtonwith dissolve

fade link: Takes 0.5 seconds to fade to black, and then 0.5 seconds tofade to the new screen. An instance of the Fade() transitionclass.

dissolve link: Takes 0.5 seconds to dissolve from the old to the new screen. Aninstance of the Dissolve() transition class.

pixellate link: Pixellates the old scene for .5 seconds, and the new scene foranother .5 seconds. An instance of the Pixellate()transition class.

move link

Takes 0.5 seconds to the move images that have changed location totheir new locations. An instance of the MoveTransition()transition class.

Move transitions, and similar transitions like ease, can only be appliedto a single layer or all layers at once, using thewith statement. It will not work in other contextssuch as ATL, ComposeTransition(),or other ways of applying transitions.

moveinright link

Also: moveinleft, moveintop, moveinbottom

These move entering images onto the screen from the appropriateside, taking 0.5 seconds to do so.

moveoutright link

Also: moveoutleft, moveouttop, moveoutbottom

These move leaving images off the screen via the appropriate side,taking 0.5 seconds to do so.

ease link

Also: easeinright, easeinleft, easeintop, easeinbottom, easeoutright, easeoutleft, easeouttop, easeoutbottom

These are similar to the move- family of transitions, except thatthey use a cosine-based curve to slow down the start and end ofthe transition.

zoomin link: This zooms in entering images, taking 0.5 seconds to do so.

zoomout link: This zooms out leaving images, taking 0.5 seconds to do so.

zoominout link: This zooms in entering images and zooms out leaving images, taking 0.5 seconds to do so.

vpunch link: When invoked, this transition shakes the screen vertically for aquarter second. Imitating and customizing this transition andhpunch is best done using ATL Transitions.

hpunch link: When invoked, this transition shakes the screen horizontally for aquarter second.

blinds link: Transitions the screen in a vertical blinds effect lasting 1second. An instance of the ImageDissolve() transition class.

squares link: Transitions the screen in a squares effect lasting 1 second.

wipeleft link

Also: wiperight, wipeup, wipedown

Wipes the scene in the given direction. Instances of theCropMove() transition class.

slideleft link

Also: slideright, slideup, slidedown

Slides the new scene in the given direction. Instances of theCropMove() transition class.

slideawayleft link

Also: slideawayright, slideawayup, slideawaydown

Slides the old scene in the given direction. Instances of theCropMove() transition class.

pushright link

Also: pushleft, pushup, pushdown

These use the new scene to slide the old scene out the namedside. Instances of the PushMove() transition class.

irisin link

Also: irisout

Use a rectangular iris to display the new screen, or hide the oldscreen. Instances of the CropMove() transition class.

Transition Classes link

Transition classes are functions that can be called to create newtransitions. These functions are parameterized, allowing entirefamilies of transitions to be created.

Calling transition classes can be done as part of the withstatement. For example:

# A very long dissolve.with Dissolve(10.0)

If we find ourselves calling the same transition class repeatedly, wecan use the define statement to assign thetransition to a variable:

define annoytheuser = Dissolve(1.0)label start: show bg washington with annoytheuser

The time_warp argument taken by many transition classes can be givenbuiltin warpers found in the _warper module,see warpers.

AlphaDissolve(control, delay=0.0, *, reverse=False, mipmap=None) link

Returns a transition that uses a control displayable (almost always somesort of animated transform) to transition from one screen to another. Thetransform is evaluated. The new screen is used where the transform isopaque, and the old image is used when it is transparent.

control: The control transform.
delay: The time the transition takes, before ending.
reverse: If true, the alpha channel is reversed. Opaque areas are takenfrom the old image, while transparent areas are taken from thenew image.
mipmap: When the dissolve will be scaled to less than half its natural size,this can be set to True. This will cause mipmaps to be generated,which will make the dissolve consume more GPU resources, but willreduce artifacts. See mipmap for more information.

ComposeTransition(trans, before, after) link

Returns a transition that composes up to three transitions. If not None,the before and after transitions are applied to the old and newscenes, respectively. These updated old and new scenes are then suppliedto the trans transition.

# Move the images in and out while dissolving. (This is a fairly expensive transition.)define moveinoutdissolve = ComposeTransition(dissolve, before=moveoutleft, after=moveinright)

CropMove(time, mode='slideright', startcrop=(0.0, 0.0, 0.0, 1.0), startpos=(0.0, 0.0), endcrop=(0.0, 0.0, 1.0, 1.0), endpos=(0.0, 0.0), topnew=True) link

Returns a transition that works by cropping a scene and positioning it on thescreen. This can be used to implement a variety of effects, all of whichinvolve changing rectangular slices of scenes.

time

The time the transition takes.

mode

The name of the mode of the transition. There are three groupsof modes: wipes, slides, and other. This can also be "custom",to allow a custom mode to be defined.

In a wipe, the image stays fixed, and more of it is revealed asthe transition progresses. For example, in "wiperight", a wipe from left to right, first the left edge of the image isrevealed at the left edge of the screen, then the center of the image,and finally the right side of the image at the right of the screen.Other supported wipes are "wipeleft", "wipedown", and "wipeup".

In a slide, the image moves. So in a "slideright", the right edge of theimage starts at the left edge of the screen, and moves to the rightas the transition progresses. Other slides are "slideleft", "slidedown",and "slideup".

There are also slideaways, in which the old image moves on top ofthe new image. Slideaways include "slideawayright", "slideawayleft","slideawayup", and "slideawaydown".

We also support a rectangular iris in with "irisin" and arectangular iris out with "irisout".

The following parameters are only respected if the mode is "custom". Positionsare relative to the size of the screen, while the crops are relative to thesize of the image. So a crop of (0.25, 0.0, 0.5, 1.0) takes the middlehalf of an image.

startcrop: The starting rectangle that is cropped out of thetop image. A 4-element tuple containing x, y, width, and height.
startpos: The starting place that the top image is drawnto the screen at, a 2-element tuple containing x and y.
endcrop: The ending rectangle that is cropped out of thetop image. A 4-element tuple containing x, y, width, and height.
endpos: The ending place that the top image is drawnto the screen at, a 2-element tuple containing x and y.
topnew: If true, the scene that is cropped and moved (and is on top ofthe other scene) is the new scene. If false, it is the old scene.

define wiperight = CropMove(1.0, "wiperight")define wipeleft = CropMove(1.0, "wipeleft")define wipeup = CropMove(1.0, "wipeup")define wipedown = CropMove(1.0, "wipedown")define slideright = CropMove(1.0, "slideright")define slideleft = CropMove(1.0, "slideleft")define slideup = CropMove(1.0, "slideup")define slidedown = CropMove(1.0, "slidedown")define slideawayright = CropMove(1.0, "slideawayright")define slideawayleft = CropMove(1.0, "slideawayleft")define slideawayup = CropMove(1.0, "slideawayup")define slideawaydown = CropMove(1.0, "slideawaydown")define irisout = CropMove(1.0, "irisout")define irisin = CropMove(1.0, "irisin")

Dissolve(time, *, time_warp=None, mipmap=None) link

Returns a transition that dissolves from the old scene to the new scene.

time: The time the dissolve will take.
time_warp: A function that adjusts the timeline. If not None, thisshould be a function that takes a fractional time between 0.0 and 1.0,and returns a number in the same range.
mipmap: When the dissolve will be scaled to less than half its natural size,this can be set to True. This will cause mipmaps to be generated,which will make the dissolve consume more GPU resources, but willreduce artifacts. See mipmap for more information.

Fade(out_time, hold_time, in_time, *, color='#000') link

Returns a transition that takes out_time seconds to fade toa screen filled with color, holds at that screen for hold_timeseconds, and then takes in_time to fade to then new screen.

# Fade to black and back.define fade = Fade(0.5, 0.0, 0.5)# Hold at black for a bit.define fadehold = Fade(0.5, 1.0, 0.5)# Camera flash - quickly fades to white, then back to the scene.define flash = Fade(0.1, 0.0, 0.5, color="#fff")

ImageDissolve(image, time, ramplen=8, *, reverse=False, time_warp=None, mipmap=None) link

Returns a transition that dissolves the old scene into the new scene, usingan image to control the dissolve process. This means that white pixels willdissolve in first, and black pixels will dissolve in last.

image: The control image. This can be any displayable. Itshould be the size of the scenes being dissolved, and if reverse=True,it should be fully opaque.
time: The time the dissolve will take.
ramplen: The length of the ramp to use. This must be an integer powerof 2. When this is the default value of 8, when a white pixelis fully dissolved, a pixel 8 shades of gray darker will havecompleted one step of dissolving in.
reverse: If True, black pixels will dissolve in before white pixels.
time_warp: A function that adjusts the timeline. If not None, thisshould be a function that takes a fractional time between 0.0 and 1.0,and returns a number in the same range.
mipmap: When the dissolve will be scaled to less than half its natural size,this can be set to True. This will cause mipmaps to be generated,which will make the dissolve consume more GPU resources, but willreduce artifacts. See mipmap for more information.

define circirisout = ImageDissolve("circiris.png", 1.0, time_warp=_warper.easeout)define circirisin = ImageDissolve("circiris.png", 1.0, reverse=True, time_warp=_warper.easein)define circiristbigramp = ImageDissolve("circiris.png", 1.0, ramplen=256)

MoveTransition(delay, *, enter=None, leave=None, old=False, layers=['master'], time_warp=_warper.linear, enter_time_warp=_warper.linear, leave_time_warp=_warper.linear) link

With these transitions, images changing position between the old and newscenes will be interpolated, which means their movement will be smoothinstead of instantaneous.

As only layers have tags, MoveTransitions can only be applied to a singlelayer or all layers at once, using the with statement.It will not work in other contexts such as ATL,ComposeTransition(), or other ways of applying transitions.

delay: The time it takes for the interpolation to finish.
old: If true, when a tag gets its image changed during the transition,the old image will be used in preference to the new one. Otherwise,the new images will be used.
layers: A list of layers that moves are applied to.

The two following parameters take transforms, which should not be animatedover time.

enter: If not None, images entering the scene will also be moved. The transformwill be applied to the image to get it in its starting position.
leave: If not None, images leaving the scene will also be moved. The transformwill be applied to the image to get it in its ending position.

The three following parameters take time warp functions,which take a number between 0.0 and 1.0, and should return a number in thesame range.

time_warp: A time warp function that's applied to the images changing positionbetween the old and new scenes.
enter_time_warp: A time warp function that's applied to images entering the scene.
leave_time_warp: A time warp function that's applied to images leaving the scene.

define longer_easein = MoveTransition(3.0, enter=offscreenright, enter_time_warp=_warper.easein)

In the following code, "a" will be leaving the scene (using leave andleave_time_warp), "b" will be changing position (using time_warp), and"c" will be entering (using enter and enter_time_warp). Because the sametag is applied before and after, "d" will not be counted as entering orleaving, but as changing position.

define some_move_trans = MoveTransition(...)label start: show a show b at left show ugly_eileen as d at right e "This is a dialogue !" hide a show b at right show c show pretty_eileen as d at left with some_move_trans

During the time when "d" is changing position, whether ugly or pretty eileenwill be shown depends on the value of old : if old is False, thedefault, ugly_eileen will instantly turn into pretty_eileen and then move,and if old is True, ugly_eileen will move and then instantly turn intopretty_eileen.

MultipleTransition(args) link

Returns a transition that allows multiple transitions to be displayed, oneafter the other.

args

A list containing an odd number of items. The first, third, andother odd-numbered items must be scenes, and the even itemsmust be transitions. A scene can be one of:

A displayable.
False, to use the old scene.
True, to use the new scene.

Almost always, the first argument will be False and the last True.

Note that this is a single parameter taking a list, this is not *args.

The transitions in args are applied in order. For each transition,the old scene is the screen preceding it, and the new scene is thescene following it. For example:

define logodissolve = MultipleTransition([ False, Dissolve(0.5), "logo.jpg", Pause(1.0), "logo.jpg", dissolve, True])

This example will dissolve to logo.jpg, wait 1 second, and thendissolve to the new scene.

Pause(delay) link: Returns a transition that only displays the new screen for delay seconds.It can be useful as part of a MultipleTransition.

Pixellate(time, steps) link

Returns a transition that pixellates out the old screen, and thenpixellates in the new screen.

time: The total time the transition will take, in seconds.
steps: The number of steps that will occur, in each direction. Each stepcreates pixels about twice the size of those in the previous step,so a 5-step pixellation will create 32x32 pixels.

PushMove(time, mode='pushright') link

Returns a transition that works by taking the new scene and using it to"push" the old scene off the screen.

time: The time the transition takes.
mode: There are four possible modes: "pushright", "pushleft", "pushup",and "pushdown", which push the old scene off the screen in thedirection indicated.

define pushright = PushMove(1.0, "pushright")define pushleft = PushMove(1.0, "pushleft")define pushup = PushMove(1.0, "pushup")define pushdown = PushMove(1.0, "pushdown")

Swing(delay=1.0, vertical=False, reverse=False, background='#000', flatten=True) link

A transitions that rotates the old scene 90 degrees around an axis,so that it is edge on with the viewer, switches to the new scene,and then rotates that scene another 90 degrees to show the newscene to the viewer.

delay: How long the transition should take.
vertical: If true, the scene is rotate around the x-axis (pixels movevertically). If false, the scene is roated around the y axis,pixels moving horizontally.
reverse: When true, the rotation occurs in the reverse direction.
background: A displayable that is placed behind the scene as it rotates.
flatten: If true, the scenes are flattened into images the size ofthe screen before being rotated. Use this if images beingnot entirely on the screen causes undesired effects.

Transition Families link

Transition families are functions that define a large family ofrelated transitions.

define.move_transitions(prefix, delay, time_warp=None, in_time_warp=None, out_time_warp=None, old=False, layers=['master'], **kwargs) link

This defines a family of move transitions,similar to the move and ease transitions. For a givenprefix, this defines the transitions:

prefix - A transition that takes delay seconds to move images thatchanged positions to their new locations.
prefixinleft, prefixinright, prefixintop, prefixinbottom - Transitionsthat take delay seconds to move images that changed positions to theirnew locations, with newly shown images coming in from the appropriateside.
prefixoutleft, prefixoutright, prefixouttop, prefixoutbottom -Transitions that take delay seconds to move images that changedpositions to their new locations, with newly hidden images leaving viathe appropriate side.

The other parameters are as MoveTransition takes them:

time_warp, in_time_warp, out_time_warp

Time warp functions that are given a time from 0.0to 1.0 representing the fraction of the move that is complete, andreturn a value in the same range giving the fraction of a linearmove that is complete.

This can be used to define functions that ease the images around,rather than moving them at a constant speed.

The three arguments are used for images remaining on the screen,newly shown images, and newly hidden images, respectively.

old

If true, when a tag gets its image changed during the transition,the old image will be used in preference to the new one. Otherwise,the new images will be used.

layers

The layers the transition will apply to.

# This defines all of the pre-defined transitions beginning# with "move".init python: define.move_transitions("move", 0.5)

Dict Transitions link

In many places where Ren'Py takes a transition, it's possible to insteadspecify a dictionary that maps layer names to this transition. When thisis the case, Ren'Py applies each transition to the appropriate layer.

When a dict is used, the pause that usually occurs when a transition takesplace does not occur. Instead, the statement taking the dictionary returnsimmediately, and the transitions are scheduled to occur at the start of thenext interaction.

This can be used with the master layer to cause transitions to occur whiledialogue is being shown on the screen. For example, if we wrote:

define dis = { "master" : Dissolve(1.0) }

and:

show eileen happywith dise "Hello, world."

The dissolve will take place while the text is displayed on the screen.

Dict layer transitions can't be used every place a transition can be used,only places where applying transitions to a layer is possible. It can beused with the with statement and with cause of the scene, show, andhide statements. It can also be used with renpy.with_statement() andrenpy.transition(), the Show() and Hide() actions, andvarious config variables that take transitions. Dict layer transitions will notwork inside things that don't work with layers, such as ATL, ComposeTransition()and MultipleTransition().

This can interact poorly with statements that cause a transition to occurthemselves, like the transitions caused by window auto. That can often besolved with a second dict transition that applies to a different layer.For example, if you are seeing weird blinking when the dialogue window showsand hides, consider changing options.rpy to have:

define config.window_show_transition = { "screens" : Dissolve(.25) }define config.window_hide_transition = { "screens" : Dissolve(.25) }

This works because the dialogue window exists entirely on the screens layer.

Automatic Transitions after Scene, Show, and Hide link

Ren'Py can automatically show a transition after a series of scene, show,and hide statements. This transition can be enabled by setting the_scene_show_hide_transition variable to the transition to be used.

The transition will occur after one or more scene, show, or hide statements,provided the statement are not followed by a with statement, or a transitioncaused by Dialogue Window Management, like the various window statements.It's also disabled when in a menu context.

For example:

define _scene_show_hide_transition = Dissolve(0.25)label start: scene bg washington show eileen happy "The transition won't show here, because the dialogue window transitioned in." show lucy mad at right "The transition will happen here." hide lucy mad show eileen vhappy "And it will happen here, as well."