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 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:
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 (label, action) tuples, corresponding to
menu choices. Label is text, and the screen is expected to
display that text in a way that causes action to be invoked when
it is selected.
screen choice:
vbox:
ypos .25
spacing 5
# Create one textbutton per label, action pair.
for label, action in items:
textbutton label:
action action
xmargin 50
xfill True
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.
NVL_Choice
The nvl_choice screen is used to display an NVL-mode menu. Its two
parameters are a combination of those of the nvl and choice
screens. It is given the following parameters:
- 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 (label, action) tuples, corresponding to
menu choices. Label is text, and the screen is expected to
display that text in a way that causes action to be invoked when
it is selected.
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:
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