Text is fundamental to visual novels, and generally quite important tostorytelling-based games. This text may consist of dialogue labeledwith the character that is saying it, and narration, which does nothave a speaker. (For convenience, we will lump both dialogue andnarration together as dialogue, except where the differences areimportant.) It's also important that the user be able to customize thelook of dialogue to suit their game.
In Ren'Py, most dialogue is written using say statements. The look ofdialogue may be customized on a per-character basis by using Characterobjects.
Say Statement link
The say statement is used for dialogue and narration. Since it'salmost always the most frequently used statement in Ren'Py scripts,the say statement has a syntax that minimizes the overhead inwriting 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 byitself. This form is used for narration, with the narration being thecontents of the string.
The second form consists of two strings. The first string is the nameof the character who is speaking, and the second is the dialogue beingspoken.
The third form consists of a simple expression followed by astring. The simple expression should evaluate to either a stringgiving 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 atransition. In this case, the string is shown and a screen is shakenat the same time.
Although the precise details of what a say statement does iscontrolled by the character object used, the usual effect of a saystatement is to display dialogue on the screen until the user clicksto dismiss it, then to remove that dialogue on the screen.
Certain characters have special meaning to Ren'Py, and so can't beused in dialogue strings. The { character begins a text tag, andthe [ character begins a substitution. To use them in dialogue,double them. It may also be necessary to precede a quote with abackslash to prevent it from closing the string. For example:
"I walked past a sign saying, \"Let's give it 100%!\""
It's also possible to use a proxy function instead of a characterobject. More details about this in this section.
Defining Character Objects link
By creating a Character object and using it in a say statement, youcan customize the look (and to some extent, the behavior) ofdialogue. Characters are created by using the define statement toassign 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 keywordarguments. These keyword arguments control the behavior of thecharacter.
- Character(name=..., kind=adv, **args) link
Creates and returns a Character object, which controls the lookand feel of dialogue and narration.
- name
If a string, the name of the character for dialogue. Whenname is None, display of the name is omitted, as fornarration. If no name is given, the name is taken fromkind, and otherwise defaults to None.
- kind
The Character to base this Character off of. When used, thedefault value of any argument not supplied to this Characteris the value of that argument supplied to
kind. This canbe used to define a template character, and then copy thatcharacter with changes.This can also be a namespace, in which case the 'character'variable in the namespace is used as the kind.
Linked Image.An image tag may be associated with a Character. This allows asay statement involving this character to display an image withthe tag, and also allows Ren'Py to automatically select a sideimage to show when this character speaks.
- image
A string giving the image tag that is linked with thischaracter.
Voice Tag.If a voice tag is assign to a Character, the voice files that areassociated with it, can be muted or played in the preferencescreen.
- voice_tag
A String that enables the voice file associated with theCharacter to be muted or played in the 'voice' channel.
Prefixes and Suffixes.These allow a prefix and suffix to be applied to the name of thecharacter, and to the text being shown. This can be used, forexample, to add quotes before and after each line of dialogue.
- what_prefix
A string that is prepended to the dialogue being spoken beforeit is shown.
- what_suffix
A string that is appended to the dialogue being spoken beforeit is shown.
- who_prefix
A string that is prepended to the name of the character beforeit is shown.
- who_suffix
A string that is appended to the name of the character beforeit is shown.
Changing Name Display.These options help to control the display of the name.
- dynamic
If true, then name should either be a string containing a Pythonexpression, a function, or a callable object. If it's a string,That string will be evaluated before each line of dialogue, andthe result used as the name of the character. Otherwise, thefunction or callable object will be called with no argumentsbefore each line of dialogue, and the return value of the call willbe used as the name of the character.
Controlling Interactions.These options control if the dialogue is displayed, if aninteraction occurs, and the mode that is entered upon display.
- condition
If given, this should be a string containing a Pythonexpression. If the expression is false, the dialoguedoes not occur, as if the say statement did not happen.
- interact
If true, the default, an interaction occurs whenever thedialogue is shown. If false, an interaction will not occur,and additional elements can be added to the screen.
- advance
If true, the default, the player can click to advance throughthe statement, and other means of advancing (such as skip andauto-forward mode) will also work. If false, the player will beunable to move past the say statement unless an alternate means(such as a jump hyperlink or screen) is provided.
- callback
A function that is called when events occur while thecharacter is speaking. See the section onCharacter Callbacks for more information.
Click-to-continue.A click-to-continue indicator is displayed once all the text hasfinished displaying, to prompt the user to advance.
- ctc
A displayable to use as the click-to-continue indicator, unlessa more specific indicator is used.
- ctc_pause
A displayable to use a the click-to-continue indicator when thedisplay of text is paused by the {p} or {w} text tags.
- ctc_timedpause
A displayable to use a the click-to-continue indicator when thedisplay of text is paused by the {p=} or {w=} text tags. WhenNone, 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 textbeing shown, immediately after the last character."nestled-close"issimilar, except a break is not allowed between the text and the CTCindicator. If"fixed", a new screen containing the CTC indicator is shown,and the position style properties of the CTC displayable are usedto position the CTC indicator.
Screens.The display of dialogue uses a screen. These argumentsallow you to select that screen, and to provide arguments to it.
- screen
The name of the screen that is used to display the dialogue.
- retain
If not true, an unused tag is generated for each line of dialogue,and the screens are shown non-transiently. Call renpy.clear_retain()to remove all retaint screens. This is almost always used withSpeech Bubbles.
Keyword arguments beginning with
show_have the prefixstripped off, and are passed to the screen as arguments. Forexample, the value ofshow_myflagwill become the value ofthemyflagvariable in the screen. (Themyflagvariable isn'tused by default, but can be used by a custom say screen.)One show variable is, for historical reasons, handled by Ren'Py itself:
- show_layer
If given, this should be a string giving the name of the layerto show the say screen on.
Styling Text and Windows.Keyword arguments beginning with
who_,what_, andwindow_have their prefix stripped, and are used to style the character name, the spoken text, and the windowcontaining both, respectively.For example, if a character is given the keyword argument
who_color="#c8ffc8", the color of the character's name ischanged, in this case to green.window_background="frame.png"sets the background of the window containing this character'sdialogue.The style applied to the character name, spoken text, and windowcan also be set this way, using the
who_style,what_style, andwindow_stylearguments, respectively.Setting config.character_id_prefixes makes it possible to styleother displayables as well. For example, when the default GUI is used,styles prefixed with
namebox_are used to style the name of thespeaking character.
Say with Image Attributes link
When a character is defined with an associated image tag, saystatement involving that character may have image attributesplaced between the character name and the second string.
In this form, if an image with the given tag is showing, Ren'Py willissue a show command involving the character tag and theattributes. If the image is not shown, Ren'Py will store theattributes for use by side images, but will not show an image.
For example:
define e = Character("Eileen", image="eileen")label start: show eileen concerned 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 concerned e "I'm a little upset at you." show eileen happy e "But it's just a passing thing."
In the above example, the concerned and happy replace one another.But it is possible to revert to a happy-less eileen without specifyingthe concerned 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 concerned "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 ithas 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 concerned 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 beforethe @, and temporary ones coming after.
e happy @ vhappy "Really! That changes everything."
The minus sign can also be used after the @ sign:
e @ right -concerned "My anger is temporarily suspended..."e "HOWEVER !"
To cause a transition to occur whenever the images are changed in this way, setconfig.say_attribute_transition to a transition. For more control,use config.say_attribute_transition_callback.
Example Characters link
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)
Special Characters link
A few character names are defined by default, and are usedautomatically in certain situations. Intentionally redefining thesecharacters can change the behavior of Ren'Py, but accidentally usingthem can be a problem.
advThe default kind of character used by Character. This sets up acharacter such that one line is displayed on the screen at atime.
nvlA kind of Character that causes dialogue to be displayed inNVL-Mode Tutorial, with multiple lines of text on the screenat once.
narratorThe character that's used to display narration, by say statementswithout a character name.
name_onlyA character that is used for dialogue in which thecharacter name is given as a string. This character is copied to anew character with the given name, and then that new character isused to display the dialogue.
centeredA character that causes what it says to be displayed centered,in the middle of the screen, outside of any window.
vcenteredA character that causes what it says to be displayed centeredin vertically oriented text, in the middle of the screen,outside of any window.
extendA character that causes the last character to speak to say a lineof dialogue consisting of the last line of dialogue spoken, "{fast}",and the dialogue given to extend. This can be used to have the screenchange over the course of dialogue.
Extend is aware of NVL-mode and treats it correctly. Extend does not workproperly if the language preference changes between the initial say andthe extend.
For example:
# Show the first line of dialogue, wait for a click, change expression, and show# the rest.show eileen concernede "Sometimes, I feel sad."show eileen happyextend " 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 concernede "Sometimes, I feel sad.{nw}"show eileen happyextend " But I usually quickly get over it!"
Dialogue Window Management link
Ren'Py includes several statements that allow for management of thedialogue window. As dialogue window is always shown during dialogue,these statements control the presence or absence of the window duringnon-dialogue interactions.
window showThe window show statement causes the window to be shown.It takes as an argument an optional transition, which is used to show thewindow. If the transition is omitted, config.window_show_transitionis used.
window hideThe window hide statement causes the window to be hidden. It takes as anargument an optional transition, which is used to hide the window. Ifthe transition is omitted, config.window_hide_transition isused.
window autoThis enables automatic management of the window. The window is shownbefore statements listed in config.window_auto_show – by default,say statements. The window is hidden before statements listed inconfig.window_auto_hide – by default,
sceneandcall screenstatements, andmenustatements without a caption.(Only statements are considered, not statement equivalentfunctions.)window auto hide,window auto showThese statements show or hide the window, with an optional transition,like
window showorwindow hidedo. However, unlike thosestatements, this keeps automatic management enabled.
The window auto statement uses config.window_show_transitionand 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 dissolvewindow auto show # Shows the window before it normally would be shown.show eileenwith 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 abovehave no effect.
Say with Arguments link
Additional arguments can be passed to the say statement by including themin 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.The keyword _with_none will override the with_none attribute of the character.
The interact parameter is a special case : when it was passed as Falsewhen defining the Character, passing interact=True will not overridethat, meaning no interaction will happen in that case.
Note that config.say_arguments_callback will be called every timea say statement executes, and not only when arguments are passed. It can beuseful to implement conditional overrides over characters' customizations.For example:
init python: def say_arguments_callback(char, *args, **kwargs): if colorblind_mode: kwargs["what_color"] = "#000" return args, kwargsdefine config.say_arguments_callback = say_arguments_callback
Monologue Mode link
Some visual novels have extended narration, or multiple blocks of dialoguefrom the same character. In these cases, typing the name of the characterand the quotes multiple times is somewhat redundant.
To cover these cases, Ren'Py supports monologue mode. When dialogue is insidetriple-quoted strings, Ren'Py will break the dialogue up into blocks at blanklines. Each block is then used to create its own say statement. Here's anexample, with three blocks of narration followed by three lines of dialogue:
"""This is the first line of narration. It's longer than the other twolines, 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 twolines, 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 arepassed to each line in the monologue, which may be less useful.
If you'd like to omit the spaces between the blocks, writerpy monologue single at the top level of the file, before the firstmonologue line.
If you'd like to disable this instead, and have all the lines you write betweentriple quotes be displayed as a single message, conserving line breaks, you cando it with rpy monologue none.
The character Store link
Main article: Other Named Stores
The say statement will search the character named store before the defaultstore. If you want to have a character with the same name as a variable inthe 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:
default e = 0label start: # This is still a terrible variable name. $ e = 100 e "Our current energy is [e] units."
This is especially useful in order to manage variable information about acharacter in a namespace without conflicting with the say statement:
define character.naomi = Character("Naomi Nagata", who_color="#8c8")default naomi = PersonClass(engineering=5, max_g_force=.7) # can be an object...define character.fred = Character("Fred Johnson", who_color="#72f")default fred.money = 1000 # ...or a dedicated named storedefault fred.rank = "Colonel"label traded: fred "Here you go." $ fred.money -= 50 $ naomi.money += 50 naomi "Thanks ! I knew you would value my class-[naomi.engineering] engineering skills."
Alternative Presentations link
NVL-Mode Tutorial : a mode that displays dialogue over the entire screen.
Speech Bubbles : a mode that displays dialogue in speech bubbles that can bepositioned interactively.
See Also link
Statement Equivalents : how to use most of the features described here ina python context, although with some drawbacks and limitations.
renpy.last_say() : provides information about the last say statement.
