Rendering Model

There are three main entities in the Ren'Py rendering model: the current scene list, the old scene list, and the screen. The first two need a bit of explanation, but the screen is just the thing rendered on the user's monitor.

Interactions

Throughout this document, we'll refer to "interactions" with the user. An interaction is any contiguous time period, including of length zero, in which we either show something to the user, wait for and get the user's input, or both. Thus renpy.pause(0) causes a zero-length interaction in which we only show something to the user, while a say statement (a line of dialogue) starts an interaction that starts with drawing the dialogue to the screen and continues until the user clicks his mouse, which is potentially forever.

Scene Lists

Scene lists are data structures with all of the information necessary to draw a scene to the screen. In particular, they have layers, each of which has an ordered list of images to display. There can be any number of layers, but by default there are two layers: the master layer and the transient layer.

Master Layer

The master layer contains all of the images which typically span multiple interactions. The background image and character graphics will go on the master layer, for example.

Transient Layer

The transient layer contains images which span only a single interaction with the user. The most common thing on the transient layer is rendered dialogue and narration.

Ordering

For each layer, the images on it have a z-ordering. The user can explicitly specify the z-ordering of images, but more commonly they just get the implicit z-ordering of incrementing the z-order for every new image placed on the layer.

Drawing

Drawing to the screen is performed during an interaction with the user, and only then.

As the interaction begins, if there is no transition specified, Ren'Py simply draws the current scene list to the screen.

If a transition is specified, Ren'Py starts the transition at the beginning of the interaction and goes until the transition is finished. Animations, by contrast, start at the beginning of the interaction and continue until the end of the interaction.

Once an interaction is finished, the current scene list is copied to the old scene list.

Statements and Their Behaviors

Scene and Show

The scene statement (if used to specify an image) and show statement both (by default) place images on the master layer of the current scene list, but do not trigger an interaction. Thus you can think of them as queuing up images to display.

with

The with statement specifies a transition and causes an interaction. Technically, the user can click to prematurely terminate the transition, but otherwise the interaction caused by a with statement does not take user input.

with None

The with statement when given the argument of None is a special case. It does not cause an interaction, neither does it specify a transition. It merely copies the current scene list onto the old scene list and returns. (This can be used to transition from things that were never drawn into the screen.)

with clause

A statement that has a with clause:

statement args with transition

is equivalent to:

with None
statement args
with transition

And behaves exactly like that.

say

The say statement causes an interaction which last until the user terminates it (with the keyboard or mouse), except if auto-reading is enabled, in which case the interaction lasts for the auto-read duration. In particular, anything which was shown prior to a say statement will be displayed at the start of the say statement.

documentation index ◦ reference manual ◦ function index

Contents