Text is fundamental to visual novels, and generally quite important to storytelling-based games. This text may consist of dialogue labeled with the character that is saying it, and narration, which does not have a speaker. (For convenience, we will lump both dialogue and narration together as dialogue, except where the differences are important.) It's also important that the user be able to customize the look of dialogue to suit their game.
In Ren'Py, most dialogue is written using say statements. The look of dialogue may be customized on a per-character basis by using Character objects.
The say statement is used for dialogue and narration. Since it's
almost always the most frequently used statement in Ren'Py scripts,
the say statement has a syntax that minimizes the overhead in
writing it. Some example say statements are:
"This is narration."
"Eileen" "This is dialogue, with an explicit character name."
e "This is dialogue, using a character object instead."
"Bam!!" with vpunch
The first form of the say statement consists of a string by itself. This form is used for narration, with the narration being the contents of the string.
The second form consists of two strings. The first string is the name of the character who is speaking, and the second is the dialogue being spoken.
The third form consists of a simple expression followed by a string. The simple expression should evaluate to either a string giving a character name, or a Character object. In the latter case, the character object is used to control how the dialogue is shown.
The final form consists of a string and a with clause which has a transition. In this case, the string is shown and a screen is shaken at the same time.
Although the precise details of what a say statement does is controlled by the character object used, the usual effect of a say statement is to display dialogue on the screen until the user clicks to dismiss it, then to remove that dialogue on the screen.
Certain characters have special meaning to Ren'Py, and so can't be
used in dialogue strings. The { character begins a text tag, and
the [ character begins a substitution. To use them in dialogue,
double them. It may also be necessary to precede a quote with a
backslash to prevent it from closing the string. For example:
"I walked past a sign saying, \"Let's give it 100%!\""
By creating a Character object and using it in a say statement, you
can customize the look (and to some extent, the behavior) of
dialogue. Characters are created by using the define statement to
assign a Character to a variable. For example:
define e = Character("Eileen",
who_color="#c8ffc8")
Once this is done, the character can be used in a say statement:
e "Hello, world."
Character is a Python function that takes a large number of keyword arguments. These keyword arguments control the behavior of the character.
The define statement causes its expression to be evaluated, and assigned to the
supplied name. If not inside an init block, the define statement will
automatically be run with init priority 0.
Character(name=..., kind=adv, **args) linkCreates and returns a Character object, which controls the look and feel of dialogue and narration.
kind. This can
be used to define a template character, and then copy that
character with changes.Linked Image. An image tag may be associated with a Character. This allows a say statement involving this character to display an image with the tag, and also allows Ren'Py to automatically select a side image to show when this character speaks.
Voice Tag. If a voice tag is assign to a Character, the voice files that are associated with it, can be muted or played in the preference screen.
Prefixes and Suffixes. These allow a prefix and suffix to be applied to the name of the character, and to the text being shown. This can be used, for example, to add quotes before and after each line of dialogue.
Changing Name Display. These options help to control the display of the name.
Controlling Interactions. These options control if the dialogue is displayed, if an interaction occurs, and the mode that is entered upon display.
Click-to-continue. A click-to-continue indicator is displayed once all the text has finished displaying, to prompt the user to advance.
Null()
when you want a ctc_pause but no ctc_timedpause."nestled", the indicator is displayed as part of the text
being shown, immediately after the last character. "nestled-close" is
similar, except a break is not allowed between the text and the CTC
indicator. If "fixed",
the indicator is added to the screen, and its position is
controlled by the position style properties.Screens. The display of dialogue uses a screen. These arguments allow you to select that screen, and to provide arguments to it.
Keyword arguments beginning with show_ have the prefix
stripped off, and are passed to the screen as arguments. For
example, the value of show_myflag will become the value of
the myflag variable in the screen. (The myflag variable isn't
used by default, but can be used by a custom say screen.)
One show variable is, for historical reasons, handled by Ren'Py itself:
Styling Text and Windows.
Keyword arguments beginning with who_, what_, and
window_ have their prefix stripped, and are used to style the character name, the spoken text, and the window
containing both, respectively.
For example, if a character is given the keyword argument
who_color="#c8ffc8", the color of the character's name is
changed, in this case to green. window_background="frame.png"
sets the background of the window containing this character's
dialogue.
The style applied to the character name, spoken text, and window
can also be set this way, using the who_style, what_style, and
window_style arguments, respectively.
Setting config.character_id_prefixes makes it possible to style
other displayables as well. For example, when the default GUI is used,
styles prefixed with namebox_ are used to style the name of the
speaking character.
When a character is defined with an associated image tag, say statement involving that character may have image attributes placed between the character name and the second string.
In this form, if an image with the given tag is showing, Ren'Py will issue a show command involving the character tag and the attributes. If the image is not shown, Ren'Py will store the attributes for use by side images, but will not show an image.
For example:
define e = Character("Eileen", image="eileen")
label start:
show eileen mad
e "I'm a little upset at you."
e happy "But it's just a passing thing."
is equivalent to:
define e = Character("Eileen")
label start:
show eileen mad
e "I'm a little upset at you."
show eileen happy
e "But it's just a passing thing."
In the above example, the mad and happy replace one another.
But it is possible to revert to a happy-less eileen without specifying
the mad attribute. An attribute name prepended with the minus sign ( - )
has that effect, just as it does with the show statement.
For example:
define e = Character("Eileen")
label start:
show eileen
e mad "I'm a little upset at you."
e happy "That's funny."
e -happy "I'm not sure what to think now."
When an @ is included in the list of attributes, any element placed after it has an only temporary effect, and is reverted at the end of the line of dialogue.
For example, the following code is equivalent to the previous example:
define e = Character("Eileen", image="eileen")
label start:
show eileen mad
e "I'm a little upset at you."
e @ happy "That's funny."
e "I'm not sure what to think now."
A single line can combine permanent changes coming before the @, and temporary ones coming after.
e happy @ vhappy "Really! That changes everything."
The minus sign can also be used after the @ sign:
e @ right -mad "My anger is temporarily suspended..."
e "HOWEVER !"
To cause a transition to occur whenever the images are changed in this way, set
config.say_attribute_transition to a transition. For more control,
use config.say_attribute_transition_callback.
Here are a few example characters:
# A character that has its dialogue enclosed in parenthesis.
define e = Character("Eileen", what_prefix='(', what_suffix=')')
# A character that pulls its name from a variable.
define p = Character("player_name", dynamic=True)
A few character names are defined by default, and are used automatically in certain situations. Intentionally redefining these characters can change the behavior of Ren'Py, but accidentally using them can be a problem.
advnvlnarratorname_onlycenteredvcenteredextendA character that causes the last character to speak to say a line of dialogue consisting of the last line of dialogue spoken, "{fast}", and the dialogue given to extend. This can be used to have the screen change over the course of dialogue.
Extend is aware of NVL-mode and treats it correctly. Extend does not work properly if the language preference changes between the initial say and the extend.
For example:
# Show the first line of dialogue, wait for a click, change expression, and show
# the rest.
show eileen concerned
e "Sometimes, I feel sad."
show eileen happy
extend " But I usually quickly get over it!"
# Similar, but automatically changes the expression when the first line is finished
# showing. This only makes sense when the user doesn't have text speed set all the
# way up.
show eileen concerned
e "Sometimes, I feel sad.{nw}"
show eileen happy
extend " But I usually quickly get over it!"
Ren'Py includes several statements that allow for management of the dialogue window. As dialogue window is always shown during dialogue, these statements control the presence or absence of the window during non-dialogue interactions.
window showconfig.window_show_transition
is used.window hideconfig.window_hide_transition is
used.window autoconfig.window_auto_show – by default,
say statements. The window is hidden before statements listed in
config.window_auto_hide – by default, scene and call screen
statements, and menu statements without a caption.
(Only statements are considered, not statement equivalent
functions.)window auto hide, window auto showwindow show or window hide do. However, unlike those
statements, this keeps automatic management enabled.The window auto statement uses config.window_show_transition
and config.window_hide_transition to show and hide the window,
respectively. window auto is cancelled by window show and window hide.
For example:
window show # shows the window with the default transition, if any.
pause # the window is shown during this pause.
window hide # hides the window.
pause # the window is hidden during this pause.
window show dissolve # shows the window with dissolve.
pause # the window is shown during this pause.
window hide dissolve # hides the window with dissolve.
pause # the window is hidden during this pause.
window auto
"The window is automatically shown before this line of dialogue."
pause # the window is shown during this pause.
scene bg washington # the window is hidden before the scene change.
with dissolve
window auto show # Shows the window before it normally would be shown.
show eileen
with dissolve
"Without window auto show, the window would have been shown here."
Dialogue window management is subject to the "show empty window"
Preference(). If the preference is disabled, the statements above
have no effect.
Additional arguments can be passed to the say statement by including them in parenthesis after the say statement. For example, one can write:
e "Hello, world." (what_color="#8c8")
Arguments to the say statement are first processed by config.say_arguments_callback,
if it is not None. If any remain, they are then passed to the character,
which treats them as if they were present when the character was defined.
So, the example above displays the dialogue in green.
Special keywords _mode and _with_node will override the ones set in
the character only for this interaction.
Some visual novels have extended narration, or multiple blocks of dialogue from the same character. In these cases, typing the name of the character and the quotes multiple times is somewhat redundant.
To cover these cases, Ren'Py supports monologue mode. When dialogue is inside triple-quoted strings, Ren'Py will break the dialogue up into blocks at blank lines. Each block is then used to create its own say statement. Here's an example, with three blocks of narration followed by three lines of dialogue:
"""
This is the first line of narration. It's longer than the other two
lines, so it has to wrap.
This is the second line of narration.
This is the third line of narration.
"""
e """
This is the first line of dialogue. It's longer than the other two
lines, so it has to wrap.
This is the second line of dialogue.
This is the third line of dialogue.
"""
While additional clauses like arguments or attributes are allowed, they are passed to each line in the monologue, which may be less useful.
If you'd like to omit the spaces between the blocks, write
rpy monologue single at the top level of the file, before the first
monologue line.
Note
This may only make sense if you've read the Python Statements section.
When the first parameter to a say statement is present and an expression,
the say statement is equivalent to calling that expressing with the dialogue
and an interact argument of True. For example:
e "Hello, world."
is equivalent to:
$ e("Hello, world.", interact=True)
The say statement will search the character named store before the default
store. If you want to have a character with the same name as a variable in
the default store, it can be defined using:
define character.e = Character("Eileen")
This character can then be used alongside a variable in the default store:
label start:
# This is a terrible variable name.
$ e = 100
e "Our starting energy is [e] units."
A say with arguments sees the arguments passed to the function. For example:
e "Hello, world." (what_size=32)
is equivalent to:
$ e("Hello, world.", interact=True, what_size=32)
When e is a Character, this is further equivalent to:
$ Character(kind=e, what_size=32)("Hello, world.", interact=True)
But it's possible to use config.say_arguments_callback or
have e wrap a character to do things differently.
Window management is performed by setting the _window and
_window_auto variables, and by using the following two functions:
_window_hide(trans=False, auto=False) linkThe Python equivalent of the window hide statement.
window auto hide
statment._window_show(trans=False, auto=False) linkThe Python equivalent of the window show statement.
window auto show
statment.