Lifecycle of a Ren'Py game

When launching a Ren'Py game, be it from the executable or from the launcher, it follows a series of steps up until the point where it is closed. This page exposes the various phases of this lifecycle, and various related statements.

Boot Time

There are a lot of things happening before the game window appears. This is the boot time. The only thing that's possibly visible at that point is the presplash.

Script Parsing Phase

To read the game's code, Ren'Py reads each of the game's .rpy (and _ren.py) files one by one, in the unicode order of their filepaths. That's the "parsing" phase, or "early" phase.

The first creator-written code being executed is what's written in python early blocks. These are executed after the file they're in has been read and parsed, but before the next file gets read. This is why statements which modify how parsing works, like Creator-Defined Statements, Creator-Defined Screen Language Statements or new custom Warpers, must be written in python early blocks.

The init python early syntax is sometimes encountered, but it's redundant and doesn't change anything in how the code gets executed compared to python early.

Init Phase

After parsing/early phase, the "init" phase starts. Several statements are executed at that time, including the Init Python Statement, the Define Statement, the Transform Statement, the Image Statement, the Screen Statement, and the style statement. The init phase is divided in successive epochs, or init priorities, from -999 to 999. Contrary to what the term may imply, epochs of lower priority are executed before epochs of higher priority.

By default, these statements are executed at init offset 0. However, they can be offset using the Init Offset Statement or by other means. The Image Statement is an exception to both of these rules, as it executes at an init priority of 500 by default, and the init offset statement adds or substracts from this 500, rather than replacing it.

Automatic image definition from the Images Directory occurs at init priority 0.

Note that while the default statements are not executed at init time, the priority of the statements influences the order in which they will be executed, relative to one another.

Init Offset Statement

The init offset statement sets a priority offset for all statements that run at init time. It should be placed at the top of the file, and it applies to all following statements in the current block and child blocks, up to the next init priority statement. The statement:

init offset = 42

sets the priority offset to 42. In:

init offset = 2
define foo = 2

init offset = 1
define foo = 1

init offset = 0

The first define statement is run at priority 2, which means it runs after the second define statement, and hence foo winds up with a value of 2.

Script Execution

This is what happens once the game window becomes visible. This is when normal Ren'Py statements execute, and when the rules described in Labels & Control Flow apply. This is also the time when the variables from default statements are set for the first time - as opposed to define statements which are set at init time.

Config variables should not be changed once normal game execution starts.

Splashscreen

If it exists, the splashscreen label is executed until it returns.

A splashscreen is only displayed once per time Ren'Py is run, and is skipped when script execution restarts.

Main Menu

If it exists, the before_main_menu label is executed. Then, once it returns, the main_menu screen is shown, unless a main_menu label exists, in which case it is executed instead. See Special Labels for more information.

The main menu itself is run in its own context. Ren'Py can leave this context by calling the Start action, which also jumps to a label or to the start label if none is specified. Returning from the main_menu label also enters the in-game phase at the start label, while loading a game enters the in-game phase at the spot where the game was saved.

In-Game Phase

This is the phase in which an actual playthrough of the game occurs, and this is the mode in which players generally spend most of their time. This phase continues until the game quits, or the game restarts and the player returns to the main menu.

During the in-game phase, the ShowMenu action can be used to display a screen in a new context.

The In-game phase continues until either the player quits or restarts the game to return to the main menu. The game may be restarted by returning when no call is on the stack, as explained explained in Labels & Control Flow. The game may also be restarted by the MainMenu action or the renpy.full_restart() function.

When the game restarts, all non-persistent data is reset to what it was at the end of the script execution phase, and then the script execution phase begins again, skipping the splashscreen.