This page is out of date

You've reached a page on the Ren'Py wiki. Due to massive spam, the wiki hasn't been updated in over 5 years, and much of the information here is very out of date. We've kept it because some of it is of historic interest, but all the information relevant to modern versions of Ren'Py has been moved elsewhere.

Some places to look are:

Please do not create new links to this page.

Layouts

Layouts control the feel of the out-of-game menus. There are five main kinds of layouts:

main_menu layouts control the feel of the main menu.
navigation layouts control the feel of the game menu navigation.
load_save layouts control the feel of the load and save screens.
yesno_prompt layouts control the feel of asking the user a yes or no question.
preferences layouts control the feel of the preference screens.
joystick_preferences layouts control the feel of the joystick preference screens.

There are also standalone layouts which do not fall into any of these categories. While a game needs exactly one of each of the five main kinds of layouts to function properly, it can have as many standalone layouts as it needs.

Each kind of layout provides certain functionality to the interface. The functionality provided by each kind of layout is described below. The selection of layouts is expected to occur before the selection of a theme. If no layout of a given kind is selected, then the classic variant is used. For example, if no yesno_prompt layout has been selected, then is used.

Note that there are combinations of layouts and themes that will not look reasonable together. This is not a bug... it's impossible to have every layout work with every other layout and every theme, and still have an unlimited range of layouts and themes. Caveat factor.

main_menu layouts

The main_menu layouts are responsible for defining the look of the main menu. This includes the background of the main menu, and the buttons that are used to go to the game menu or start a game.

The navigation layouts are responsible for defining the navigation through the game menu. This includes the background of the game menus and the buttons that are used to go between game menu screens.

load_save layouts

The load_save layouts are responsible for defining the load and save screens.

yesno_prompt layouts

The yesno_prompt layouts are responsible for defining yes/no prompt screens.

preferences layouts

The preferences layouts are used to define the preferences screen.

joystick_preferences layouts

The joystick_preferences layout are used to define the joystick preferences screen.

standalone layouts

These provide interesting functionality to Ren'Py games, and they stand alone, so it's possible to call as many of them as you want.

Defining New Layouts

This section contains some notes on how to define your own layouts. If you're not interested in defining your own labels, then you can safely ignore this section.

When it comes to defining layouts, there are two important principles you should follow:

must be called with the type of layout being defined, and it must be called before any theme function is called. For example, if a navigation layout is being defined, then layout.provides("navigation") should be called.
The layout needs to implement the contract of it's layout kind. These contracts are described below.

While the default layouts are enable through the use of functions on the layout object, this is by no means the only way to supply a layout. For a user-defined layout, it should be enough to place the call to in an init -2 python block, with the rest of the code residing in init blocks or labels as appropriate.

If your layout defines new configuration variables, you should set to False before creating them, and then back to True when you're done creating them. We suggest that configuration variables should be prefixed with the type of layout they're used by. Load/save variables should be prefixed by config.load_save_, navigation variables with config.navigation_ and so on. (For compatibility reasons, the default layouts do not conform to this standard.)

main_menu layouts

Main_menu layouts need to call:

    layout.provides('main_menu')

Main menu layouts are expected to define a main_menu_screen label. This label is expected to:

Show a fullscreen window of type mm_root. The code to do this is:

    python:
        ui.window(style='mm_root')
        ui.null()

Create a keymap that disables the game_menu binding. (This is optional, but it can prevent transitions from the main menu to itself.)

    python:
        ui.keymap(game_menu=ui.returns(None))

Displays the main menu on the screen. How this is done is generally up to the layout itself, but we strongly recommend you use to control the generation of the menu. Note that the documentation for config.main_menu says that bare strings cause a jump out of context to occur; use to implement this properly. Using config.main_menu ensures that your layout will work even with extensions (like image galleries) that add options to the main menu.

Navigation layouts need to call:

    layout.provides('navigation')

Navigation layouts are expected to redefine the layout.navigation function. The way to do this is to first define a function in an init python block, and then assign that function to layout.navigation.

It's suggested that your navigation function use to determine the game menu buttons to show to the user. (But note that the game menu is less often extended then the main menu, so this is correspondingly less important.)

load_save layouts

Load/save layouts need to call:

    layout.provides('load_save')

Load/save layouts are expected to provide two labels: load_screen and save_screen, which are used to load and save, respectively. These screens should call with "load" or "save" as an argument, and are otherwise unconstrained in how they provide loading and saving functionality.

Please see the section on load/save functions for the functions that would be used to actually implement these screens.

yesno_prompt layouts

Yes/no prompt layouts need to call:

    layout.provides('yesno_prompt')

Navigation layouts are expected to redefine the layout.yesno_prompt function. The way to do this is to first define a function in an init python block, and then assign that function to layout.yesno_prompt.

preferences layouts

Preferences layouts need to call:

    layout.provides('preferences')

The preferences layout should define a preferences_screen label, which contains code to set the preferences. This screen should call ("preferences"). It then needs to allow the user to alter the preferences, using the variables and functions defined in the preferences section. Finally, it should:

Allow the user to begin skipping, by jumping to the _begin_skipping label.
Allow the user to go to the joystick preferences, by jumping to the joystick_preferences_screen label.

joystick_preferences layouts

Joystick preferences layouts need to call:

    layout.provides('joystick_preferences')

The preferences layout should define a joystick_preferences_screen label, which contains code to set the joystick preferences. This screen should call ("joystick_preferences"). Unfortunately, the joystick preferences are undocumented at this time.

Example

An example of a new main_menu layout:

init -2 python:
    layout.provides('main_menu')

    style.mm_button = Style(style.button, help="main menu button")
    style.mm_button_text = Style(style.button_text, help="main menu button (text)")
    style.mm_button.size_group = "mm"

label main_menu_screen:
    python:
        layout.button(u"Start Game", "mm", clicked=ui.jumpsoutofcontext('start'), xpos=400, ypos=400)
        layout.button(u"Continue Game", "mm", clicked=_intra_jumps("load_screen", "main_game_transition"), xpos=450, ypos=430)
        layout.button(u"Preferences", "mm", clicked=_intra_jumps("preferences_screen", "main_game_transition"), xpos=500, ypos=460),
        layout.button(u"Quit", "mm", clicked=ui.jumps("_quit"), xpos=550, ypos=490)

        ui.interact()