documentation index ◦ reference manual ◦ function index

# Character

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.)

## Example

    init:
        $ e = Character(u'Eileen', color=(200, 255, 200, 255),
                        show_function=side_show_say,
                        show_predict_function=side_show_predict_say,
                        show_side="cyan.png")
        $ equote = Character('Eileen',  color=(200, 255, 200, 255),
                             who_suffix = ':', what_prefix='"', what_suffix='"')
        $ ectc = Character('Eileen', color=(200, 255, 200, 255),
                           ctc = anim.Blink("arrow.png"))

    e "Ren'Py is a language and engine for writing and playing visual
           novel games."

    equote "By supplying what_prefix and what_suffix arguments
            to a Character object, we can automatically add
            things before each line of text."
    equote "This is a lot easier than having to put those
            quotes in by hand."
    equote "We can also use who_prefix and who_suffix to
            add text to the name of the speaker."

    ectc "Finally, we demonstrate a click to continue
          indicator. In this example, it's nestled in with the
          text."
    ectc "This also demonstrates the use of the anim.Blink
          function."

documentation index ◦ reference manual ◦ function index