documentation index ◦ reference manual ◦ function index
When showing dialogue to the user using the two-argument form of the say statement, the first argument to the say statement should almost always be a variable bound to a Character object. These objects implement (or call functions that implement) much of the logic required to show dialogue to the user.
Characters are declared by binding variables to the Character objects. Such declarations should take place inside init blocks, to ensure that the bindings are not saved with the game state, as this would prevent revised versions of a game from picking up changes to the init block. Perhaps the simplest definition is:
init: $ e = Character("Eileen")
This creates a new character object and binds it to the `e` variable. When the say statement:
e "Hello, World!"
runs, the line of text "Hello, World!" will be preceded by the label "Eileen", indicating who is talking. It's common to customize the color of this label. This can be done by supplying the `color` keyword argument to Character, as in:
init: $ e = Character("Eileen", color=(200, 255, 200, 255))
The color argument is actually setting the color property on the label. The color property takes an RGBA tuple consisting of four numbers, enclosed in parenthesis and separated by commas, with each number ranging from 0 to 255.
The Character function is defined as follows:
| Function: | Character | (name, kind=adv, **kwargs): |
Creates a new character object. This object is suitable for use as the first argument of a two-argument say statement. When it is used as such, it shows a window containing the character name and the second argument to the say statement. This behavior is customized by passing parameters to this function.
name is the name of the character that is speaking. It can be either a string containing the character name, or None to indicate that the label should not be shown. A name value consisting of a single space (" ") indicates that the label should be a blank line, which allows a narrator character to line up narration with character dialogue. name is the only requirement to Character.
kind, if supplied, gives the name of another Character object. The default values for all the settings of the newly-created character object are taken from that character object. If not given, defaults to adv. Another useful value is nvl, which by default causes nvl-mode interactions.
Keyword Arguments. In addition to name, Character takes keyword arguments that control its behavior.
dynamic - If true, then name is interpreted as a string containing a python expression that is evaluated to yield the name of the character.
image - If true, then name is interpreted as an image. This image is added to the dialogue window in place of the label.
condition - If present, this should be a string containing a python expression. This expression is evaluated whenever a line is said through this character object. If it evaluates to false, the line is not shown to the user.
interact - If true, the default, causes an interaction to occur when a line is shown to the user. If false, the interaction does not take place, and ui.interact (or some other means) must be called to cause an interaction to occur.
with_none - If True, causes a "with None" statement to be run after each interaction. If None (the default), checks config.implicit_with_none to determine if a "with None" should be run.
type - The type of interaction. See renpy.last_interact_type for how this is used.
Prefixes and Suffixes. The following keyword arguments can be used to add a prefix or suffix to everything said through a character object. These can be used when lines of dialogue need to be enclosed in quotes, as the preferred alternative to adding those quotes to every line of dialogue in the script.
who_prefix - Text that is prepended to the name of the character when forming the label of the dialogue.
who_suffix - Text that is appended to the name of the character when forming the label of the dialogue.
what_prefix - Text that is prepended to the line of dialogue before it is shown to the user.
what_suffix - Thext that is appended to the line of dialogue before it is shown to the user.
Click-to-continue. These keyword arguements are used to control the click-to-continue indicator:
ctc - If present, this argument takes a displayable that is used as the click-to-continue indicator. If not present or None, then no click-to-continue indicator is displayed.
ctc_pause - If given, a click-to-continue indicator that's shown when the display of text has been paused with the {p} or {w} text tags.
ctc_timedpause - If given and not None, a click-to-continue indicator that is displayed when a {p} or {w} tag has a time associated with it. One can use ctc_pause=Null() to disable ctc_pause only in the case of a timed pause.
ctc_position - If "nestled", the click-to-continue indicator is displayed nestled in with the end of the text. If "fixed", the click-to-continue indicator is displayed directly on the screen, with its various position properties determining where it is actually shown.
Functions. The following are keyword arguments that allow one to massively customize the behavior of a character object:
show_function - The function that is called to display each step of a dialogue to the user. (A dialogue may be broken down into steps by pause text tags.) It should have the same signature as renpy.show_display_say.
predict_function - The function that is called to predict the images from this dialogue. It should have the signature of renpy.predict_display_say.
callback - A callback or list of callbacks that are called at various points during the the process of displaying dialogue. The callback is called with a single positional argument, which indicates the event that occured, and the following keyword arguments:
Additional keyword arguments and unknown events should be ignored, for future expansion. The events that cause the callback to be called are:
Note that when interact=False, slow_done can occur after end. If callback is not given or None, it defaults to config.character_callback, if not None. The character callbacks in config.all_character_callbacks are called for all characters, before any more specific callbacks.
Default Show Function The following are keyword arguments that are processed by the default show_function.
show_two_window - Places the name of the character saying the dialogue into its own window.
show_side_image - Specifies a displayable that is show with this dialogue. The displayable should set its position properties in a way to place it where the user wants it. Similarly, the window properties should be set in a way that provides room for the side image.
show_two_window_vbox_properties - If supplied, a dictionary containing properties that are added to the vbox containing both windows, when show_two_window is true.
show_who_window_properties - If supplied, a dictionary containing properties that are added to the window containing the name of who is speaking, when show_two_window is true.
show_say_vbox_properties - If supplied, a dictionary containing properties that are added to the vbox inside the main window.
show_transform - If supplied, a transform that is applied to window(s) being shown.
Styles. The following keyword arguments control the styles used by parts of the dialogue:
who_style - Defaults to 'say_label', the style of the label.
what_style - Defaults to 'say_dialogue', the style of the text being said.
window_style - Defaults to 'say_window', the style of the window containing the dialogue.
Additional Keyword Arguments. Additional keyword arguments are interpreted as follows:
There is also a DynamicCharacter function:
| Function: | DynamicCharacter | (name, **kwargs): |
Equivalent to calling Character with the same arguments, and with the dynamic argument set to true.
| Method: | Character.copy | (...): |
The copy method on Characters takes the same arguments as the funcref Character constructor, with the exception that the name argument is optional. This method returns a new Character object, one that is created by combining the arguments of the original constructor and this method, with the arguments provided by this method taking precedence.
Character objects may be called directly, as if they were functions. They take one positional parameter, the line of dialogue to be show to the user. They also take keyword arguments:
This use can programatically replace say statements. For example, the say statement:
e "Hello, World!"
is equivalent to:
$ e("Hello, World!", interact=True)
We give you a few pre-defined characters to work with.
in the middle of the screen, outside of any window.
# 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!"