Main and Game Menus - Ren'Py Visual Novel Engine

documentation index ◦ reference manual ◦ function index

# Main and Game Menus

This section describes how the content of the various menus can be customized. If you just want to change the look of the menus (to the extent made possible by the style system), use themes or styles. In particular, if you want to change the image background to the main menu and game menu, use the properties mm_root and gm_root in a theme.

To change just the text of menu items, consider using config.translations. To change the screens on the menus, you'll need to change the contents of the config.main_menu and config.game_menu variables. Otherwise, you'll want to use a layout that changes the look of the menus, or write your own layout.

## Main Menu

The main menu can be customized by setting the config.main_menu variable. This variable should be a list of tuples. The first component of each tuple is the name of the button on the main menu. The second component can be one of three things:

- a string, in which case it is a label at which the game execution starts (after a jump out of the menu context).
- a function, in which case the function is called when the button is clicked.
- Finally, it can be None, which causes the button to be insensitive.

The third component must be a string containing a python expression, which determines when the button is enabled. The optional fourth component is a string containing a python expression, that determines if the button is shown at all. (changed in 6.6.2)

To jump from the main menu to one of the screens in the game menu, one should use the _intra_jumps function to specify the appropriate transition.

Function: | _intra_jumps | (label, transition):

Jumps to label while remaining in the same context.

transition should be a string giving a field on the `config` object. When this function is run, that field is accessed, and is used to specify the transition that is used.

The default value of config.main_menu is:

        config.main_menu = [
            (u"Start Game", "start", "True"),
            (u"Continue Game", _intra_jumps("load_screen", "main_game_transition"), "True"),
            (u"Preferences", _intra_jumps("preferences_screen", "main_game_transition"), "True"),
            (u"Quit", ui.jumps("_quit"), "True")
            ]

## Game Menu

The first thing one may wish to do when modifying the game menu is to add a screen to it. This is done in two steps. The first is to create the screen, and the second is to add it to the config.game_menu list so that it can be reached from the game menu.

Each screen is represented in the code as a label that is jumped to to display the screen. There are five steps that this label should do in order to display the screen. First, it should call layout.navigation(screen), where screen is the name of the screen (the first component of the tuples in config.game_menu, described below). Second, it should call the ui functions to add components to the the screen. Third, it should call ui.interact to interact with the user. Fourth, it should examine the results of _game_interact, and react appropriately. Finally, it should jump back up to the screen label, showing the screen again after each interaction.

So that the user can see it, the screen should be added to config.game_menu. This is a list of four- or five-component tuples. The first is the name of the screen. It's used to determine if the button used to reach that screen should be indicated as selected. The second component is the text used for that button. The third component is a function that executes when the button is clicked. Normally, an appropriate function is `_intra_jumps`(label, transition), where label is the name of the label of your screen. The fourth component is a string containing a python expression. If the expression is not true, the button is insensitive. The optional fifth component is also a string containing a python expression. If the expression is not true, the button is not shown. (changed in 6.6.2)

The default value of config.game_menu is:

        config.game_menu = [
            ( None, u"Return", ui.jumps("_return"), 'True'),
            ( "preferences", u"Preferences", _intra_jumps("preferences_screen", "intra_transition"), 'True' ),
            ( "save", u"Save Game", _intra_jumps("save_screen", "intra_transition"), 'not main_menu' ),
            ( "load", u"Load Game", _intra_jumps("load_screen", "intra_transition"), 'True'),
            ( None, u"Main Menu", ui.callsinnewcontext("_main_menu_prompt"), 'not main_menu' ),
            ( None, u"Quit", ui.callsinnewcontext("_quit_prompt"), 'True' ),
            ]

Variable: | _game_menu_screen | = "_load_screen"

One can customize the screen the game menu jumps to by default by changing the value of _game_menu_screen. For example, one could set this to "load_screen" for the first few interactions, and then set it to "save_screen" for the rest of the game. This is especially useful for a game with no main menu.

If set to None, the user cannot enter the game menu. This is set to None at the start of the splashscreen, and reset to its old value when the splashscreen completes.

Use the layout.yesno_prompt function to ask yes/no questions of the user.

Function: | layout.yesno_prompt | (screen, message):

screen - The screen button that should be highlighted when this prompt is shown. If None, then no game menu navigation is shown.

message - The message that is shown to the user to prompt them to answer yes or no.

This function returns True if the user clicks Yes, or False if the user clicks No.

Pre-defined Screens. Layouts define the load screen, save screen, and preferences screen are define at the `load_screen`, `save_screen`, and `preferences_screen`, respectively.

Please see the page on Saving, Loading, and Rollback for a list of functions that can be used in the load and save screens, and the page on the Preferences for a list of preferences that can be customized.

Jump to `_return` to return to the game or the main menu, as appropriate. Jump to `_noisy_return` to play config.exit_sound before returning.

## Entering the Game Menu

To enter the game menu from game code, use renpy.call_in_new_context or ui.callsinnewcontext to call the `_game_menu` label with a parameter, the name of the screen you wish to enter. This parameter can be omitted to enter the default screen.

This can be omitted to use the default screen.

    init python:
        def overlay():
             # We can assume that "save_screen" is the default.
             ui.textbutton("Save", clicked=ui.callsinnewcontext("_game_menu"), xalign=0.0, yalign=0.0)
             ui.textbutton("Prefs", clicked=ui.callsinnewcontext("_game_menu", "preferences_screen"), xalign=1.0, yalign=0.0)

        config.overlay_functions.append(overlay)

documentation index ◦ reference manual ◦ function index