Special Screen Names
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 system 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 the part of Ren'Py that displays the screen.
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(who, what):
window id "window":
has vbox
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 menu entry objects, representing each of the choices in the menu. Each of the objects has the following fields on it:
- caption
A string giving the caption of the menu choice.
- action
An action that should be invoked when the menu choice is chosen. This may be None if this is a menu caption, and
config.narrator_menuis False.
- chosen
This is True if this choice has been chosen at least once in any playthrough of the game.
- args
This is a tuple that contains any positional arguments passed to the menu choice.
- kwargs
This is a dictionary that contains any keyword arguments passed to the menu choice.
These items, and the actions within, become invalid when the menu statement ends.
In addition, any arguments passed to a menu statement are passed in during the call to the screen.
screen choice(items):
window:
style "menu_window"
vbox:
style "menu"
for i in items:
if i.action:
button:
action i.action
style "menu_choice_button"
text i.caption style "menu_choice"
else:
text i.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.
screen input(prompt):
window:
has vbox
text prompt
input id "input"
NVL
The nvl screen is used to display NVL-mode dialogue. It is given
the following parameter:
- dialogue
A list of NVL Entry objects, each of which corresponds to a line of dialogue to be displayed. Each entry has the following fields:
- current
True if this is the current line of dialogue. The current line of dialogue must have its what text displayed with an id of "what".
- who
The name of the speaking character, or None of there is no such name.
- what
The text being spoken.
- who_id, what_id, window_id
Preferred ids for the speaker, dialogue, and window associated with an entry.
- who_args, what_args, window_args
Properties associated with the speaker, dialogue, and window. These are automatically applied if the id is set as above, but are also made available separately.
- multiple
If multiple character dialogue, this is a two component tuple. The first component is the one-based number of the dialogue block, and the second is the total number of dialogue blocks in the multiple statement.
- items
This is the same list of items that would be supplied to the choice screen. If this is empty, the menu should not be shown.
When items is not present, the NVL screen is expected to always give a text widget an id of "what". Ren'Py uses it to calculate auto-forward-mode time, click-to-continue, and other things. (This is satisfied automatically if the default what_id is used.)
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.
screen nvl(dialogue, items=None):
window:
style "nvl_window"
has vbox:
style "nvl_vbox"
# Display dialogue.
for d in dialogue:
window:
id d.window_id
has hbox:
spacing 10
if d.who is not None:
text d.who id d.who_id
text d.what id d.what_id
# Display a menu, if given.
if items:
vbox:
id "menu"
for i in items:
if action:
button:
style "nvl_menu_choice_button"
action i.action
text i.caption style "nvl_menu_choice"
else:
text i.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(message):
zorder 100
text message at _notify_transform
# This controls how long it takes between when the screen is
# first shown, and when it begins hiding.
timer 3.25 action Hide('notify')
transform _notify_transform:
# These control the position.
xalign .02 yalign .015
# These control the actions on show and hide.
on show:
alpha 0
linear .25 alpha 1.0
on hide:
linear .5 alpha 0.0
Skip Indicator
If present, skip_indicator screen is displayed when skipping is in progress,
and hidden when skipping finishes. It takes no parameters.
Here's a very simple skip indicator screen:
screen skip_indicator():
zorder 100
text _("Skipping")
CTC (Click-To-Continue)
If present, the ctc screen is displayed when dialogue has finished
showing, to prompt the player to click to display more text. It may be
given a single parameter and multiple keyword arguments.
- arg
The ctc displayable selected by the
Character(). This is one of the ctc, ctc_pause, or ctc_timedpause arguments to Character, as appropriate. If no CTC is given to the Character, this argument is not passed at all.
In addition, there are several parameters that are only passed if the screen requires them.
- ctc_kind
The kind of CTC to display. One of "last" (for the last CTC on a line), "pause", or "timedpause".
- ctc_last
The ctc argument to
Character().- ctc_pause
The ctc_pause argument to
Character().- ctc_timedpause
The ctc_timedpause argument to
Character().
Here's a very simple ctc screen:
screen ctc(arg=None):
zorder 100
hbox:
xalign 0.98
yalign 0.98
add arg
text _("Click to Continue"):
size 12