documentation index ◦ reference manual ◦ function index
Contents |
By default, Ren'Py displays each scene by replacing the old scene with a new one. This is appropriate in general (such as for emotion changes), but it may be boring for large changes, such as a change in location or a character entering or leaving the scene. Ren'Py supports transitions that control how changes to the scene lists are exposed to the user.
Transitions occur between the last scene that was shown to the user, and the current scene that has been updated using the scene, show, or hide statements. A transition runs for a given amount of time, but may be dismissed early by the user. Once a transition is shown, the scene is considered shown for the purposes of future transitions.
Transitions are introduced with the `with` statement. The `with` statement takes an expression that is suitable for use with the `with` statement (that is, a callable that takes as input two scene lists), and runs that transition. Alternatively, if the expression is `None`, then the `with` statement has the effect of showing the scene to the user, and returning instantly. This is useful in conjunction with a future `with` statement, so that only some changes to the scene list will be transitioned in.
An example is in order. First, let us define a few objects that can be passed in as the argument to a with statement:
init: # Fades to black, then to the new scene. fade = Fade(0.5, 0, 0.5) # Dissolves between old and new scenes. dissolve = Dissolve(0.5)
A simple use of with would be to place it after a series of show and hide statements of the program. As an example:
scene bg whitehouse show eileen happy with fade
This series of statements will cause the old scene (displayed before these statements started) to fade to black, and be replaced with the new scene all at once. This is a useful behavior, for example, when we are replacing a scene with a new one, such as when the story changes locations.
scene bg whitehouse with None show eileen happy with dissolve
The `with None` statement is useful to break changes to the scene list into parts, as in the example above. When run, the background will be instantly shown, and then the character image will be dissolved in over the background.
Another use of the `with None` statement is to remove transient elements before a transition begins. By default, the scene list includes transient elements like dialogue, thoughts, and menus. `with None` always executes without these elements, and so gets rid of them.
The `show`, `hide`, and `scene` statements all take a with clause. One of these statement with a with clause associated with it is actually converted into three statements: A `with None` statement, the original statement sans the with clause, and the with clause as a with statement. For example:
scene bg whitehouse with fade show eileen happy at left with dissolve show lucy happy at right with dissolve
becomes
with None scene bg whitehouse with fade with None show eileen happy at left with dissolve with None show lucy happy at right with dissolve
This has the effect of fading out the old scene and fading in the new background, then dissolving in the characters one after the other.
show albert at far_left show bernardette at left show charles at center show derek at right show eleanor at far_right with dissolve
Additionally, you can also show multiple images at once by ordering them consecutively and putting the 'with' statement at the end, followed by your transition.
We also allow with clauses to be supplied for say and menu statements. When a with clause is supplied on one of these statements, the transition is used to introduce the say or menu element. For example,
e "How are you doing?" with dissolve
Will dissolve in a line of dialogue. The line of dialogue will be dismissed immediately, unless it is followed by a with statement or clause that causes it to transition to something else.
There are two variables that control transitions:
| Variable: | default_transition | = None |
If not none, specifies a default transition that is applied to all say and menu statements that are not provided a with clause. This is only considered if the transitions preference is set to "All".
| Variable: | _window_during_transitions | = False |
If set to true, this will show an empty line of narration during transitions, provided you are in the outermost context, and there is nothing transient on the screen.
This only works for the default config.with_callback.
This variable may be changed outside of an init block, but a "with None" statement should be run after doing so for change to take effect.
This is more-or-less obsoleted by the window statement.
| Definition: | fade |
An instance of the Fade transition that takes 0.5 seconds to fade to black, and then 0.5 seconds to fade to the new screen.
| Definition: | dissolve |
An instance of the Dissolve transition that takes 0.5 seconds to complete.
| Definition: | pixellate |
An instance of the Pixellate transition, which takes 1 second to complete, and creates pixels as big as 32x32 over the course of 5 steps in either direction.
| Definition: | move |
An instance of the MoveTransition transition, this takes 0.5 seconds to move images that changed position to their new locations.
| Definition: | moveinright, moveinleft, moveintop, moveinbottom |
These move entering images onto the screen from the appropriate side, taking 0.5 seconds to do so.
| Definition: | moveoutright, moveoutleft, moveouttop, moveoutbottom |
These move leaving images off the screen via the appropriate side, taking 0.5 seconds to do so.
| Definition: | ease, easeinright, easeinleft, easeintop, easeinbottom, easeoutright, easeoutleft, easeouttop, easeoutbottom |
These are similar to the move- family of transitions, except that they use a cosine-based curve to slow down the start and end of the transition.
| Definition: | zoomin |
This zooms in entering images, taking 0.5 seconds to do so.
| Definition: | zoomout |
This zooms out leaving images, taking 0.5 seconds to do so.
| Definition: | zoominout |
This zooms in entering images and zooms out leaving images, taking 0.5 seconds to do so.
| Definition: | vpunch |
When invoked, this transition shakes the screen vertically for a quarter second.
| Definition: | hpunch |
When invoked, this transition shakes the screen horizontally for a quarter second.
| Definition: | blinds |
Transitions the screen in a vertical blinds effect lasting 1 second.
| Definition: | squares |
Transitions the screen in a squares effect lasting 1 second.
| Definition: | wiperight |
An instance of CropMove that takes 1 second to wipe the screen right.
| Definition: | wipeleft |
An instance of CropMove that takes 1 second to wipe the screen left.
| Definition: | wipeup |
An instance of CropMove that takes 1 second to wipe the screen up.
| Definition: | wipedown |
An instance of CropMove that takes 1 second to wipe the screen down.
| Definition: | slideright |
An instance of CropMove that takes 1 second to slide the screen right.
| Definition: | slideleft |
An instance of CropMove that takes 1 second to slide the screen left.
| Definition: | slideup |
An instance of CropMove that takes 1 second to slide the screen up.
| Definition: | slidedown |
An instance of CropMove that takes 1 second to slide the screen down.
| Definition: | slideawayright |
An instance of CropMove that takes 1 second to slide the screen away and to the right.
| Definition: | slideawayleft |
An instance of CropMove that takes 1 second to slide the screen away and to the left.
| Definition: | slideawayup |
An instance of CropMove that takes 1 second to slide the screen away and to the up.
| Definition: | slideawaydown |
An instance of CropMove that takes 1 second to slide the screen away and to the down.
| Definition: | irisout |
An instance of CropMove that irises the screen out for 1 second.
| Definition: | irisin |
An instance of CropMove that irises the screen in for 1 second.
The following are functions that return things useful as transitions. The user should not supply the new_widget or old_widget parameters, as these are supplied by Ren'Py when a transition begins.
| Function: | CropMove | (time, mode='fromleft', startcrop=(0.0, 0.0, 0.0, #0), startpos=(0.0, 0.0), endcrop=(0.0, 0.0, #0, #0), endpos=(0.0, 0.0), topnew=True, old_widget=None, new_widget=None): |
The CropMove transition works by placing the old and the new image on two layers, called the top and the bottom. (Normally the new image is on the top, but that can be changed in some modes.) The bottom layer is always drawn in full. The top image is first cropped to a rectangle, and then that rectangle drawn onto the screen at a specified position. Start and end crop rectangles and positions can be selected by the supplied mode, or specified manually. The result is a surprisingly flexible transition.
This transition has many modes, simplifying its use. We can group these modes into three groups: wipes, slides, and other.
In a wipe, the image stays fixed, and more of it is revealed as the transition progresses. For example, in "wiperight", a wipe from left to right, first the left edge of the image is revealed 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 the image starts at the left edge of the screen, and moves to the right as the transition progresses. Other slides are "slideleft", "slidedown", and "slideup".
There are also slideaways, in which the old image moves on top of the new image. Slideaways include "slideawayright", "slideawayleft", "slideawayup", and "slideawaydown".
We also support a rectangular iris in with "irisin" and a rectangular iris out with "irisout". Finally, "custom" lets the user define new transitions, if these ones are not enough.
time - The time that this transition will last for, in seconds.
mode - One of the modes given above.
The following parameters are only respected if the mode is "custom".
startcrop - The starting rectangle that is cropped out of the top image. A 4-element tuple containing x, y, width, and height.
startpos - The starting place that the top image is drawn to the screen at, a 2-element tuple containing x and y.
startcrop - The starting rectangle that is cropped out of the top image. A 4-element tuple containing x, y, width, and height.
startpos - The starting place that the top image is drawn to the screen at, a 2-element tuple containing x and y.
topnew - If True, the top layer contains the new image. Otherwise, the top layer contains the old image.
| Function: | Dissolve | (time, old_widget=None, new_widget=None, alpha=False): |
This dissolves from the old scene to the new scene, by overlaying the new scene on top of the old scene and varying its alpha from 0 to 255. Dissolve only works correctly when both scenes are the same size.
time - The amount of time the dissolve will take.
alpha - If True, the resulting displayable will have an alpha channel, at the cost of some speed. If False, it will be treated as opaque, but be faster.
| Function: | Fade | (out_time, hold_time, in_time, old_widget=None, new_widget=None, color=None, widget=None): |
This returns an object that can be used as an argument to a with statement to fade the old scene into a solid color, waits for a given amount of time, and then fades from the solid color into the new scene.
out_time - The amount of time that will be spent fading from the old scene to the solid color. A float, given as seconds.
hold_time - The amount of time that will be spent displaying the solid color. A float, given as seconds.
in_time - The amount of time that will be spent fading from the solid color to the new scene. A float, given as seconds.
color - The solid color that will be fade to. A tuple containing three components, each between 0 or 255. This can also be `None`.
widget - This is a widget that will be faded to, if color is `None`. This allows a fade to be to an image rather than just a solid color.
If both color and widget are `None`, then the fade is to black.
| Function: | ImageDissolve | (image, time, reverse=False, old_widget=None, new_widget=None): |
This dissolves the old scene into the new scene, using an image to control the dissolve process. Basically, this means that white pixels come in first and black last.
The two children should be the same size, or the behavior of ImageDissolve is undefined.
image - The image that will be used to control this transition. The image should be the same size as the scene being dissolved.
time - The amount of time the dissolve will take.
reverse - This reverses the ramp and the direction of the window slide. When True, black pixels dissolve in first, and white pixels come in last.
alpha - If True, the resulting displayable will have an alpha channel, at the cost of some speed. If False, it will be treated as opaque, but be faster.
| Function: | MoveTransition | (delay, factory=None, enter_factory=None, leave_factory=None, old=False, layers=['master']): |
This transition attempts to find images that have changed position, and moves them from the old position to the new transition, taking delay seconds to complete the move.
If factory is given, it is expected to be a function that takes as arguments: an old position, a new position, the delay, and a displayable, and to return a displayable as an argument. If not given, the default behavior is to move the displayable from the starting to the ending positions. Positions are always given as (xpos, ypos, xanchor, yanchor) tuples.
If enter_factory or leave_factory are given, they are expected to be functions that take as arguments a position, a delay, and a displayable, and return a displayable. They are applied to displayables that are entering or leaving the scene, respectively. The default is to show in place displayables that are entering, and not to show those that are leaving.
If old is True, then factory moves the old displayable with the given tag. Otherwise, it moves the new displayable with that tag. (new in 6.6.1)
layers is a list of layers that the transition will be applied to. (new in 6.9.0)
Images are considered to be the same if they have the same tag, in the same way that the tag is used to determine which image to replace or to hide. They are also considered to be the same if they are the same displayable.
If you use this transition to slide an image off the side of the screen, remember to hide it when you are done. (Or just use it with a leave_factory.)
There are several constructors that create functions for use with enter_factory and leave_factory:
| Function: | MoveFactory | (**kwargs): |
Can be used with factory to supply arguments to Move.
| Function: | MoveIn | (pos, **kwargs): |
Can be used with enter_factory to move in entering elements.
pos - An (xpos, ypos, xanchor, yanchor) tuple, giving the position to move from. Any component can be None, to take the corresponding component of the final position.
Keyword arguments are passed to Move.
| Function: | MoveOut | (pos, **kwargs): |
Can be used with leave_factory to move in entering elements.
pos - An (xpos, ypos, xanchor, yanchor) tuple, giving the position to move to. Any component can be None, to take the corresponding component of the original position.
Keyword arguments are passed to Move.
| Function: | ZoomInOut | (start, end, **kwargs): |
Can be used with enter_factory or leave_factory. Used to zoom in or out entering or leaving displayables.
start - The zoom factor at the start of the transition.
end - The zoom factor at the end of the transition.
Keyword arguments are passed to FactorZoom.
| Function: | RevolveInOut | (start, end, **kwargs): |
Can be used with enter_factory or leave_factory. Used to revolve in or out entering or leaving displayables.
start - The clockwise revolution at the start of the transition.
end - The clockwise revolution at the end of the transition.
Additional keyword arguments are passed to Revolve.
| Function: | Pause | (delay): |
Returns a transition that shows the new screen for delay seconds.
This is useful for implementing a pause that behaves as a transition does, one that is skipped when transitions are.
| Function: | Pixellate | (time, steps, old_widget=None, new_widget=None): |
This pixellates out the old scene, and then pixellates in the new scene, taking the given amount of time and the given number of pixellate steps in each direction.
| Function: | ComposeTransition | (trans, before=None, after=None): |
This allows transitions to be composed before they are applied.
trans - The top-level transition.
before - If not None, a transition that is applied to the old and new screens, and used as the old screen for trans.
after - If not None, a transition that is applied to the old and new screens, and used as the new screen for trans.
This may not work with all transitions.
| Function: | MultipleTransition | (args): |
This creates a transition that consists of one or more transitions. args must be a list of odd length, containing at least 3 elements. Odd elements of this list are considered to be displayables, while even elements are transitions. When used, this causes the first element (a displayable) to transition to the third element (a displayable), using the second element as the transition. If the fourth and fifth elements are present, a transition will occur from the third element (a displayable) to the fifth element (a displayable) using the fourth element (a transition).
There are two special values that will be recognized as displayables. False will be replaced with a displayable containing the scene before the transition, while True will be replaced with a displayable containing the scene after the transition.
Some transitions can also be applied to specific layers, using the renpy.transition function. Only transitions that are not completely opaque can be used in this way.
This function defines a family of similar transitions.
| Function: | define.move_transitions | (prefix, delay, time_warp=None, in_time_warp=None, out_time_warp=None, layers=['master'], **kwargs): |
This defines a family of move transitions, similar to the move and ease transitions. For a given prefix, this defines the transitions:
time_warp, in_time_warp, out_time_warp - The time_warp argument supplied to Move for images remaining on the screen, newly shown images, and newly hidden images (respectively).
old - Causes the transitions to move the old displayables, rather than the new ones.
layers - The layers the transition will apply to.
Additional keyword arguments are passed (indirectly) to the moves. The most useful additional keyword argument is probably subpixel=True, which causes a subpixel move to be used.