Defining Characters - Ren'Py

documentation index ◦ reference manual ◦ function index

# Defining Characters

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_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:

- interact - True if this dialogue is being displayed interactively.
- type - The value of type supplied to Character.

Additional keyword arguments and unknown events should be ignored, for future expansion. The events that cause the callback to be called are:

- "begin" - called at the start of showing dialogue.
- "show" - called before each segment of dialogue is shown.
- "show_done" - called after each segment of dialog is shown (but before the interaction occurs).
- "slow_done" - called when slow text finishes showing.
- "end" - called at the end of showing dialogue.

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.

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:

- Keyword arguments beginning with "window_" are intepreted as properties of the window containing the dialogue, with the window_" prefix stripped off.
- Keyword arguments beginning with "what_" are interpreted as properties of the text being said, with the "what_" prefix stripped off.
- Keyword arguments begining with "show_" are supplied as keyword arguments to the show_function and predict_function, with the "show_" prefix stripped off.
- Keyword arguments beginning with "cb_" are supplied as keyword arguments to the callback function(s), with the "cb_" prefix stripped off.
- All other keyword arguments are interpreted as properties of the label. (color is the most common property passed as a keyword in this function.)

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.

## Calling Character Objects

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 one keyword parameter, interact, which determines if an interaction should take place. This use can programatically replace say statements. For example, the say statement:

    e "Hello, World!"

is equivalent to:

    $ e("Hello, World!", interact=True)

## Pre-Defined Characters

We give you a few pre-defined characters to work with.

- centered is a character that will cause what it says to be displayed centered,

in the middle of the screen, outside of any window.

- extend will cause 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.

    # 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!"

documentation index ◦ reference manual ◦ function index