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, 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.
Creates and returns a Character object, which controls the look and feel of dialogue and narration.
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.
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.
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_side_image will become the value of the side_image variable in the screen.
Some useful show_ variables implemented by the default screens are:
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.
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, the code:
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."
To cause a transition to occur whenever the images are changed in this way, set config.say_attribute_transition to a transition.
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.