There are two kinds of special screen names in Ren'Py. The first are screens that will be automatically displayed when Ren'Py script language commands (or their programmatic equivalents) are run. The other type are menu screens. These have conventional names for conventional functionality, but screens can be omitted or changed as is deemed necessary.
On this page, we'll give example screens. It's important to realize that, while some screens must have minimal functionality, the screen system makes it possible to add additional functionality to screens. For example, while the standard say screen only displays text, the screen systen makes it easy to add features like skipping, auto-forward mode, or muting.
Some special screens take parameters. These parameters can be accessed as variables in the screen's scope.
Some of the screens also have special ids associated with them. A special id should be assigned to a displayable of a given type. It can cause properties to be assigned to that displayable, and can make that displayable accessible to calling code.
In-Game Screens
These screens are automatically displayed when certain Ren'Py statements execute.
Say
The say screen is called by the say statement, when displaying ADV-mode dialogue. It is
displayed with the following parameters:
who
The text of the name of the speaking character.
what
The dialogue being said by the speaking character.
It's expected to declare displayables with the following ids:
"who"
A text displayable, displaying the name of the speaking character. The character object can be given arguments that style this displayable.
"what"
A text displayable, displaying the dialogue being said by the speaking character. The character object can be given arguments that style this displayable. A displayable with this id must be defined, as Ren'Py uses it to calculate auto-forward-mode time, click-to-continue, and other things.
"window"
A window or frame. This conventionally contains the who and what text. The character object can be given arguments that style this displayable.
screen say:
windowid"window": hasvbox
if who:
text who id"who"
text what id"what"
Choice
The choice screen is used to display the in-game choices created with the menu statement. It is given the following parameter:
items
This is a list of (caption, action, chosen) tuples. For each choice, caption is the name of the choice, and action is the action to invoke for the choice, or None if this is a choice label. Chosen if a choice with this label has been chosen by the user before. (It doesn't have to be in the current game.)
screenchoice: window:
style"menu_window"
vbox:
style"menu"
for caption, action, chosen in items:
ifaction: button:
actionaction
style"menu_choice_button"
text caption style"menu_choice"
else:
text caption style"menu_caption"
Input
The input screen is used to display renpy.input(). It is given one parameter:
prompt
The prompt text supplied to renpy.input.
It is expected to declare a displayable with the following id:
"input"
An input displayable, which must exist. This is given all the parameters supplied to renpy.input, so it must exist.
screeninput: window: hasvbox text prompt inputid"input"
NVL
The nvl screen is used to display NVL-mode dialogue. It is given the following parameter:
dialogue
This is a list of ( who, what, who_id, what_id, window_id) tuples, each of which corresponds to a line of dialogue on the screen. Who and what are strings containing the speaking character and the line of dialogue, respectively. The ids should be assigned to the who and what text displayables, and a window containing each unit of dialogue.
items
This is a list of (caption, action, chosen) tuples. For each choice, caption is the name of the choice, and action is the action to invoke for the choice, or None if this is a choice label. Chosen if a choice with this label has been chosen by the user before. (It doesn't have to be in the current game.)
If items is empty, the menu should not be shown.
Ren'Py also supports an nvl_choice screen, which takes the same parameters as nvl, and is used in preference to nvl when an in-game choice is presented to the user, if it exists.
screennvl: window:
style"nvl_window"
hasvbox:
style"nvl_vbox"
# Display dialogue.
for who, what, who_id, what_id, window_id in dialogue:
window:
id window_id hashbox: spacing10 if who isnotNone: text who id who_id text what id what_id # Display a menu, if given.
if items:
vbox:
id"menu"
for caption, action, chosen in items:
ifaction: button:
style"nvl_menu_choice_button"
actionaction
text caption style"nvl_menu_choice"
else:
text caption style"nvl_dialogue"
Notify
The notify screen is used by renpy.notify() to display notifications to the user. It's generally used in conjunction with a transform to handle the entire task of notification. It's given a single parameter:
message
The message to display.
The default notify screen, and its associated transform, are:
screen notify:
zorder100
text message at _notify_transform
# This controls how long it takes between when the screen is # first shown, and when it begins hiding.
timer3.25action Hide('notify') transform _notify_transform:
# These control the position.
xalign.02yalign.015
# These control the actions on show and hide.
onshow: alpha0
linear .25alpha1.0 onhide:
linear .5alpha0.0
Menu Screens
These are the menu screens. The main_menu and yesno_prompt are invoked implictly. When the user invokes the game menu, the screen named in _game_menu_screen will be displayed. (This defaults to save.)
Remember, menu screens can be combined and modified fairly freely.
Main Menu
The main_menu screen is the first screen shown when the game begins.
screen main_menu:
# This ensures that any other menu screen is replaced.
tag menu
# The background of the main menu.
window:
style"mm_root"
# The main menu buttons.
frame:
style_group"mm"
xalign.98 yalign.98 hasvbox
textbutton _("Start Game") action Start()
textbutton _("Load Game") action ShowMenu("load")
textbutton _("Preferences") action ShowMenu("preferences") textbutton _("Help") action Help()
textbutton _("Quit") action Quit(confirm=False) initpython:
# Make all the main menu buttons be the same size.
style.mm_button.size_group="mm"
Navigation
The navigation screen isn't special to Ren'Py. But by convention, we place the game menu navigation in a screen named navigation, and then use that screen from the save, load and preferences screens.
screen navigation:
# The background of the game menu.
window:
style"gm_root"
# The various buttons.
frame:
style_group"gm_nav"
xalign.98 yalign.98
hasvbox
textbutton _("Return") action Return()
textbutton _("Preferences") action ShowMenu("preferences") textbutton _("Save Game") action ShowMenu("save")
textbutton _("Load Game") action ShowMenu("load") textbutton _("Main Menu") action MainMenu()
textbutton _("Help") action Help() textbutton _("Quit") action Quit() initpython:
style.gm_nav_button.size_group="gm_nav"
Save
The save screen is used to select a file in which to save the game.
screen save:
# This ensures that any other menu screen is replaced.
tag menu
use navigation frame:
hasvbox
# The buttons at the top allow the user to pick a # page of files.
hbox:
textbutton _("Previous") action FilePagePrevious() textbutton _("Auto") action FilePage("auto")
for i inrange(1, 9):
textbuttonstr(i) action FilePage(i) textbutton _("Next") action FilePageNext() # Display a grid of file slots.
grid25:
transposeTrue xfillTrue
# Display ten file slots, numbered 1 - 10.
for i inrange(1, 11):
# Each file slot is a button.
button:
action FileAction(i) xfillTrue
style"large_button"
hashbox
# Add the screenshot and the description to the # button.
add FileScreenshot(i) text ( " %2d. "% i
+ FileTime(i, empty=_("Empty Slot.")) +"\n"
+ FileSaveName(i)) style"large_button_text"
Load
The load screen is used to select a file from which to load the game.
screen load:
# This ensures that any other menu screen is replaced.
tag menu
use navigation frame:
hasvbox
# The buttons at the top allow the user to pick a # page of files.
hbox:
textbutton _("Previous") action FilePagePrevious() textbutton _("Auto") action FilePage("auto")
for i inrange(1, 9):
textbuttonstr(i) action FilePage(i) textbutton _("Next") action FilePageNext() # Display a grid of file slots.
grid25:
transposeTrue xfillTrue
# Display ten file slots, numbered 1 - 10.
for i inrange(1, 11):
# Each file slot is a button.
button:
action FileAction(i) xfillTrue
style"large_button"
hashbox
# Add the screenshot and the description to the # button.
add FileScreenshot(i) text ( " %2d. "% i
+ FileTime(i, empty=_("Empty Slot.")) +"\n"
+ FileSaveName(i)) style"large_button_text"
Preferences
The preferences screen is used to select options that control the display of the game.
screen preferences:
tag menu
# Include the navigation.
use navigation
# Put the navigation columns in a three-wide grid.
grid31:
style_group"prefs"
xfillTrue
# The left column.
vbox: frame:
style_group"pref"
hasvbox
label _("Display")
textbutton _("Window") action Preference("display", "window")
textbutton _("Fullscreen") action Preference("display", "fullscreen") frame:
style_group"pref"
hasvbox
label _("Transitions")
textbutton _("All") action Preference("transitions", "all") textbutton _("None") action Preference("transitions", "none") frame:
style_group"pref"
hasvbox
label _("Text Speed")
barvalue Preference("text speed") frame:
style_group"pref"
hasvbox
textbutton _("Joystick...") action ShowMenu("joystick_preferences") vbox:
frame:
style_group"pref"
hasvbox
label _("Skip")
textbutton _("Seen Messages") action Preference("skip", "seen") textbutton _("All Messages") action Preference("skip", "all") frame:
style_group"pref"
hasvbox
textbutton _("Begin Skipping") action Skip() frame:
style_group"pref"
hasvbox
label _("After Choices")
textbutton _("Stop Skipping") action Preference("after choices", "stop"
textbutton _("Keep Skipping") action Preference("after choices", "skip"
frame:
style_group"pref"
hasvbox
label _("Auto-Forward Time")
barvalue Preference("auto-forward time") vbox:
frame:
style_group"pref"
hasvbox
label _("Music Volume")
barvalue Preference("music volume") frame:
style_group"pref"
hasvbox
label _("Sound Volume")
barvalue Preference("sound volume")
textbutton"Test"action Play("sound", "sound_test.ogg") style"soundtest_button"
frame:
style_group"pref"
hasvbox
label _("Voice Volume")
barvalue Preference("voice volume")
textbutton"Test"action Play("voice", "voice_test.ogg") style"soundtest_button"
initpython:
style.pref_frame.xfill=True style.pref_frame.xmargin=5 style.pref_frame.top_margin=5 style.pref_vbox.xfill=True
style.pref_button.size_group="pref"
style.pref_button.xalign=1.0 style.pref_slider.xmaximum=192 style.pref_slider.xalign=1.0 style.soundtest_button.xalign=1.0
Yesno_Prompt
The yesno_prompt message is used to ask yes/no choices of the user. It takes the following parameters:
message
The message to display to the user. This is one of:
layout.ARE_YOU_SURE - "Are you sure?" This should be the default if the message is unknown.
layout.DELETE_SAVE - "Are you sure you want to delete this save?"
layout.OVERWRITE_SAVE - "Are you sure you want to overwrite your save?"
layout.LOADING - "Loading will lose unsaved progress.nAre you sure you want to do this?"
layout.QUIT - "Are you sure you want to quit?"
layout.MAIN_MENU - "Are you sure you want to return to the mainnmenu? This will lose unsaved progress."
The values of the variables are strings, which means they can be displayed using a text displayable.
yes_action
The action to run when the user picks "Yes".
no_action
The action to run when the user picks "No".
screen yesno_prompt:
modal True window:
style"gm_root"
frame:
style_group"yesno_prompt"
xfillTrue xmargin50 ypadding25 yalign.25 vbox:
xfillTrue spacing25
text _(message):
text_align0.5 xalign0.5 hbox:
spacing100 xalign.5
textbutton _("Yes") action yes_action textbutton _("No") action no_action