Customizing the 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 styles. To change just the text of menu items, consider using config.translations . To change just the position of buttons in a menu, use config.game_menu_positions and config.main_menu_positions .
Main Menu
The main menu can be customized by setting the config.main_menu variable. This variable should be a list of pairs. The first element of each pair is the name of the button on the main menu. The second item can be one of three things. It can be a string, in which case it is a label at which the game execution starts (after a jump out of the menu context). It can be 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.
If one wants to change the main menu each time it is invoked, but keep the look of it the same, then the thing to do is to provide a main_menu label. The code after this main_menu label should set config.main_menu, and then jump to _library_main_menu. This is useful, for example, if there are some items in the main menu that should be absent or disabled until some condition is met. (Say, the user reaching an ending for the first time.)
From Scratch. Finally, it may be desirable to write your own menu from scratch. This is done by creating the menu using ui functions called from code invoked through the main_menu label. To start the game, the code should jump out of the context, using ui.jumpsoutofcontext or renpy.jump_out_of_context . The code can jump to game menu screens, using the jump statement, renpy.jump , or ui.jumps . When interacting with the user, ui.interact should be called with suppress_overlay=True, suppress_underlay=True, and perhaps mouse="mainmenu".
The functions that are used to make a game menu screen, _game_nav() and _game_interact(), should also work with the main menu screen. When necessary, renpy.context().main_menu can be checked to see if we are in the main menu (it is True) or game menu (it is False). (see renpy.context )
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 _game_nav(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 actually draw the screen. Third, it should call _game_interact, instead of ui.interact , to interact with the user. This ensures that the game menu interaction is handled properly. 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-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 ui.jumps ('label'), where label is the name of the label under which your screen was defined above. Finally, the fourth parameter is a string containing a python expression. If the expression is not true, the button is insensitive.
To customize the game menu navigation buttons, one can replace the _game_nav() function.
Function: _game_nav( | screen) |
Called by Ren'Py to display navigation for a game menu screen.
screen- the screen we're at. Default parameters for this are "restart", "load", "save", "prefs", "quit", or None. When None, navigation buttons should't be shown.
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.
There is a convenience function for prompting the user for their response to a yes and no question.
Function: _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. The load screen, save screen, and preferences screen are define at the _load_screen, _save_screen and _prefs_screen labels, respectively.
From scratch. To write your own game menu entirely from scratch, set _game_menu_screen to point to the screen you would like to access when the user right-clicks. You can then jump between game menu screens using the jump statement, renpy.jump or ui.jumps . Jump to _return to return to the game or the main menu, as appropriate.