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."
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 final form is 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.
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, precede them with the backslash (\) character. 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.
Creates and returns a Character object, which controls the look and feel of dialogue and narration.
name
If a string, the name of the character for dialogue. When name is None, display of the name is omitted, as for narration.
kind
The Character to base this Character off of. When used, the default value of any argument not supplied to this Character is the value of that argument supplied to kind. This can be used to define a template character, and then copy that character with changes.
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.
what_prefix
A string that is prepended to the dialogue being spoken before it is shown.
what_suffix
A string that is appended to the dialogue being spoken before it is shown.
who_prefix
A string that is prepended to the name of the character before it is shown.
who_suffix
A string that is appended to the name of the character before it is shown.
Changing Name Display. These options help to control the display of the name.
dynamic
If true, then name should be a string containing a python expression. That string will be evaluated before each line of dialogue, and the result used as the name of the character.
image
If true, then name is expected to name an image file. That image is used as the name of the character.
Controlling Interactions. These options control if the dialogue is displayed, if an interaction occurs, and the mode that is entered upon display.
condition
If given, this should be a string containing a python expression. If the expression is false, the dialogue does not occur, as if the say statement did not happen.
interact
If true, the default, an interaction occurs whenever the dialogue is shown. If false, an interaction will not occur, and additional elements can be added to the screen.
mode
A string giving the mode to enter when this character speaks. See the section on modes for more details.
callback
A function that is called when events occur while the character is speaking. See the section on character callbacks fore more information.
Click-to-continue. A click-to-continue indicator is displayed once all the text has finished displaying, to prompt the user to advance.
ctc
A Displayable to use as the click-to-continue indicator, unless a more specific indicator is used.
ctc_pause
A Displayable to use a the click-to-continue indicator when the display of text is paused by the {p} or {w} text tags.
ctc_timedpause
A Displayable to use a the click-to-continue indicator when the display of text is paused by the {p=} or {w=} text tags. When None, this takes its default from ctc_pause, use Null() when you want a ctc_pause but no ctc_timedpause.
ctc_position
Controls the location of the click-to-continue indicator. If "nestled", the indicator is displayed as part of the text being shown, immediately after the last character. 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.
screen
The name of the screen that is used to display the dialogue.
Keyword arguments beginning with show_ have the prefix stripped off, and are passed to the screen as arguments. For example, the value of show_side_image will become the value of the side_image variable in the screen.
Some useful show_ variables implemented by the default screens are:
show_side_image
When given a Displayable, shows that displayable when the dialogue is shown. The position of that displayable is controlled by its position properties. This is often used to show an image of the speaking character to the side of the dialogue.
show_two_window
If true, restructures the layout so that the name of the character is placed in one window, and the dialogue text in a second window.
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.
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.
adv
The default kind of character used by Character. This sets up a character such that one line is displayed on the screen at a time.
nvl
A kind of Character that causes dialogue to be displayed in NVL-mode, with multiple lines of text on the screen at once.
narrator
The character that's used to display narration, by say statements without a character name.
name_only
A character that is used to display dialogue in which the character name is given as a string. This character is copied to a new character with the given name, and then that new character is used to display the dialogue.