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 calling code.
These screens are automatically displayed when certain Ren'Py
say screen is called by the say statement, when displaying
ADV-mode dialogue. It is displayed with the following parameters:
- The text of the name of the speaking character.
- The dialogue being said by the speaking character.
It's expected to declare displayables with the following ids:
- A text displayable, displaying the name of the speaking
character. The character object can be given arguments that style
- 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.
- A window or frame. This conventionally contains the who and what
text. The character object can be given arguments that style
screen say(who, what):
window id "window":
text who id "who"
text what id "what"
choice screen is used to display the in-game choices created
with the menu statement. It is given the following parameter:
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:
A string giving the caption of the menu choice.
An action that should be invoked when the menu choice is
chosen. This many be None if this is a menu cation, and
config.narrator_menu is false.
This is true if this choice has been chosen at least once
in any playthrough of the game.
for i in items:
text i.caption style "menu_choice"
text i.caption style "menu_caption"
input screen is used to display
renpy.input(). It is given one
- The prompt text supplied to renpy.input.
It is expected to declare a displayable with the following id:
- An input displayable, which must exist. This is given all the
parameters supplied to renpy.input, so it must exist.
input id "input"
nvl screen is used to display NVL-mode dialogue. It is given
the following parameter:
A list of NVL Entry objects, each of which corresponds to a line
of dialogue to be displayed. Each entry has the following
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".
The name of the speaking character, or None of there is no
The text being spoken.
who_id, what_id, window_id
Preferred ids for the speaker, dialogue, and window associated with an
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.
- 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
nvl, and is used in preference to
an in-game choice is presented to the user, if it exists.
screen nvl(dialogue, items=None):
# Display dialogue.
for d in dialogue:
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.
for i in items:
text i.caption style "nvl_menu_choice"
text i.caption style "nvl_dialogue"
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
- The message to display.
The default notify screen, and its associated transform, are:
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')
# These control the position.
xalign .02 yalign .015
# These control the actions on show and hide.
linear .25 alpha 1.0
linear .5 alpha 0.0
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:
If present, the
ctc screen is displayed when dialogue has finished
showing, to prompt the player to click to display more text.
Here's a very simple ctc screen:
text _("Click to Continue"):