Statement Equivalents

To allow Ren'Py to be scripted in Python, each Ren'Py statement has a Python equivalent. This usually consists of a Python function, but may also consist of a pattern of Python calls that perform an action equivalent to the statement.

Note that using statement equivalents in lieu of the original statements usually removes any possible Lint checks and prediction optimizations, making your game less easily checkable and possibly less fluid. It can also disable features in certain cases.

Dialogue

Warning

Several features, such as skipping already-seen dialogues, are not available using the python version and only enabled when using the native say statement.

The Ren'Py Say Statement is equivalent to calling the character object (when any is present) as a function. Displaying narration (meaning when no character is supplied) can be done the same way, by using the narrator character.

e "Hello, world."
$ e("Hello, world.")

"And then the sun exploded."
$ narrator("And then the sun exploded.")

Proxy functions

This equivalence of characters and function objects works in the other direction as well. It is possible to declare a Python function, and then use that function in the place of a character object in a native say statement. For example, the following function uses a variable to choose between two characters.

define lucy_normal = Character("Lucy")
define lucy_evil = Character("Evil Lucy")

init python:

    def l(what, **kwargs):
        if lucy_is_evil:
            lucy_evil(what, **kwargs)
        else:
            lucy_normal(what, **kwargs)

label start:

    $ lucy_is_evil = False

    l "Usually, I feel quite normal."

    $ lucy_is_evil = True

    l "But sometimes, I get really mad!"

A function used in this way should either ignore unknown keyword arguments, or pass them to a character function. Doing this will allow the game to continue working if future versions of Ren'Py add additional keyword arguments to character calls.

Note that unlike other possible arguments, interact=True will always be passed to the function - unless manually passing (interact=False). A Say with Arguments sees the arguments (including the supplementary interact) passed to the function. For example:

e "Hello, world." (what_size=32)

resolves to the following call:

e("Hello, world.", what_size=32, interact=True)

Note that it's not required to pass interact=True when calling a Character object for it to work as intended. The following works just as well:

$ e("Hello, world.", what_size=32)

When e is a Character, this is further equivalent to:

$ Character(kind=e, what_size=32)("Hello, world.")

But it's possible to use config.say_arguments_callback or have e wrap a character to do things differently.

There is one additional way of replacing the say statement using Python:

renpy.say(who, what, *args, **kwargs)

The equivalent of the say statement.

who: Either the character that will say something, None for the narrator, or a string giving the character name. In the latter case, the say store function is called.
what: A string giving the line to say. Percent-substitutions are performed in this string.
interact: If true, Ren'Py waits for player input when displaying the dialogue. If false, Ren'Py shows the dialogue, but does not perform an interaction. (This is passed in as a keyword argument.)

This function is rarely necessary, as the following three lines are equivalent.

e "Hello, world."
$ renpy.say(e, "Hello, world.")
$ e("Hello, world.") # when e is not a string
$ say(e, "Hello, world.") # when e is a string

Dialogue Window Management

Window management is performed by setting the _window and _window_auto variables, and by using the following two functions:

_window_hide(trans=False, auto=False)

The Python equivalent of the window hide statement.

trans: If False, the default window hide transition is used. If None, no transition is used. Otherwise, the specified transition is used.
auto: If True, this becomes the equivalent of the window auto hide statement.

_window_show(trans=False, auto=False)

The Python equivalent of the window show statement.

trans: If False, the default window show transition is used. If None, no transition is used. Otherwise, the specified transition is used.
auto: If True, this becomes the equivalent of the window auto show statement.

Choice Menus

The menu statement has an equivalent Python function.

class renpy.Choice(value, /, *args, **kwargs)

This encapsulates a menu choice with with arguments. The first positional argument is is the value that will be returned, and the other arguments are the arguments that will be passed to the choice screen.

This is intended for use in the items list of renpy.display_menu() to supply arguments to that screen.

value: The value that will be given to the choice screen.

Positional arguments and keyword arguments are stored in this object and used by renpy.display_menu.

renpy.display_menu(items, *, interact=True, screen='choice', type='menu', _layer=None, args=None, kwargs=None)

This displays a menu to the user. items should be a list of 2-item tuples. In each tuple, the first item is a textual label, and the second item is the value to be returned if that item is selected. If the value is None, the first item is used as a menu caption.

This function takes many optional arguments, of which only a few are documented. Except for items, all arguments should be given as keyword arguments.

interact: If false, the menu is displayed, but no interaction is performed.
screen: The name of the screen used to display the menu.
type: May be "menu" or "nvl". If "nvl", the menu is displayed in NVL mode. Otherwise, it is displayed in ADV mode.
_layer: The layer to display the menu on. If not given, defaults to config.choice_layer for normal choice menus, and config.nvl_choice_layer for NVL choice menus.
_args: If not None, this should be a tuple containing the positional menu arguments supplied to this menu.
_kwargs: If not None, this should be a dict containing the keyword menu arguments supplied to this menu.

Note that most Ren'Py games do not use menu captions, but use narration instead. To display a menu using narration, write:

$ narrator("Which direction would you like to go?", interact=False)
$ result = renpy.display_menu([ ("East", "east"), ("West", "west") ])

If you need to supply per-item arguments, use renpy.Choice objects as the values. For example:

renpy.display_menu([
    ("East", renpy.Choice("east", icon="right_arrow"),
    ("West", renpy.Choice("west", icon="left_arrow"),
    ])

Displaying Images

The image, scene, show, and hide statements each have an equivalent Python function (see Displaying Images for the original statements).

renpy.get_at_list(name, layer=None)

Returns the list of transforms being applied to the image with tag name on layer. Returns an empty list if no transforms are being applied, or None if the image is not shown.

If layer is None, uses the default layer for the given tag.

renpy.hide(name, layer=None)

Hides an image from a layer. The Python equivalent of the hide statement.

name: The name of the image to hide. Only the image tag is used, and any image with the tag is hidden (the precise name does not matter).
layer: The layer on which this function operates. If None, uses the default layer associated with the tag.

renpy.image(name, d)

Defines an image. This function is the Python equivalent of the image statement.

name: The name of the image to display, a string.
d: The displayable to associate with that image name.

This function may only be run from inside an init block. It is an error to run this function once the game has started.

renpy.scene(layer='master')

Removes all displayables from layer. This is equivalent to the scene statement, when the scene statement is not given an image to show.

A full scene statement is equivalent to a call to renpy.scene followed by a call to renpy.show(). For example:

scene bg beach

is equivalent to:

$ renpy.scene()
$ renpy.show("bg beach")

renpy.show(name, at_list=[], layer=None, what=None, zorder=0, tag=None, behind=[], atl=None, **kwargs)

Shows an image on a layer. This is the programmatic equivalent of the show statement.

name: The name of the image to show, a string.
at_list: A list of transforms that are applied to the image. The equivalent of the at property.
layer: A string, giving the name of the layer on which the image will be shown. The equivalent of the onlayer property. If None, uses the default layer associated with the tag.
what: If not None, this is a displayable that will be shown in lieu of looking on the image. (This is the equivalent of the show expression statement.) When a what parameter is given, name can be used to associate a tag with the image.
zorder: An integer, the equivalent of the zorder property. If None, the zorder is preserved if it exists, and is otherwise set to 0.
tag: A string, used to specify the image tag of the shown image. The equivalent of the as property.
behind: A list of strings, giving image tags that this image is shown behind. The equivalent of the behind property.
atl: If not None, an ATL Transform that will be applied. This takes only the ATL itself, it does not apply prior state.

show a
$ renpy.show("a")

show expression w
# anonymous show expression : no equivalent

show expression w as a
$ renpy.show("a", what=w)
$ renpy.show("y", what=w, tag="a") # in this case, name is ignored

show a at T, T2
$ renpy.show("a", at_list=(T, T2))

show a onlayer b behind c zorder d as e
$ renpy.show("a", layer="b", behind=["c"], zorder="d", tag="e")

renpy.show_layer_at(at_list, layer='master', reset=True, camera=False)

The Python equivalent of the show layer layer at at_list statement. If camera is True, the equivalent of the camera statement.

reset: If true, the transform state is reset to the start when it is shown. If false, the transform state is persisted, allowing the new transform to update that state.

Transitions

The equivalent of the With Statement is the renpy.with_statement() function.

renpy.with_statement(trans, always=False)

Causes a transition to occur. This is the Python equivalent of the with statement.

trans: The transition.
always: If True, the transition will always occur, even if the user has disabled transitions.

This function returns true if the user chose to interrupt the transition, and false otherwise.

Jump

The equivalent of the Jump Statement is the renpy.jump() function.

renpy.jump(label): Causes the current statement to end, and control to jump to the given label.

Call

The equivalent of the Call Statement is the renpy.call() function.

renpy.call(label, *args, from_current=False, **kwargs)

Causes the current Ren'Py statement to terminate, and a jump to a label to occur. When the jump returns, control will be passed to the statement following the current statement.

The label must be either of the form "global_name" or "global_name.local_name". The form ".local_name" is not allowed.

from_current: If true, control will return to the current statement, rather than the statement following the current statement. (This will lead to the current statement being run twice. This must be passed as a keyword argument.)

renpy.return_statement(value=None): Causes Ren'Py to return from the current Ren'Py-level call.

Pause

The equivalent of the Pause Statement is the renpy.pause() function.

renpy.pause(delay=None, *, predict=False, modal=True, hard=False)

Causes Ren'Py to pause. Returns true if the user clicked to end the pause, or false if the pause timed out or was skipped.

delay: If given, the number of seconds Ren'Py should pause for.

The following should be given as keyword arguments:

predict

If True, when all prediction - including prediction scheduled with renpy.start_predict() and renpy.start_predict_screen() - has been finished, the pause will be ended.

This also causes Ren'Py to prioritize prediction over display smoothness for the duration of the pause. Because of that, it's recommended to not display animations during prediction.

The pause will still end by other means - when the user clicks or skips, or when the delay expires (if any).

modal

If True, a timed pause will not end (it will hold) when a modal screen is being displayed. If False, the pause will end while a modal screen is being displayed.

hard

When True, Ren'Py may prevent the user from clicking to interrupt the pause. If the player enables skipping, the hard pause will be skipped. There may be other circumstances where the hard pause ends early or prevents Ren'Py from operating properly, these will not be treated as bugs.

In general, using hard pauses is rude. When the user clicks to advance the game, it's an explicit request - the user wishes the game to advance. To override that request is to assume you understand what the player wants more than the player does.

tl;dr - Don't use renpy.pause with hard=True.

Calling renpy.pause guarantees that whatever is on the screen will be displayed for at least one frame, and hence has been shown to the player.

Layeredimage

The Layeredimage statement has Python equivalents. The group statement does not: the name of the group is supplied to Attribute, and the auto feature can be implemented using renpy.list_images().

class Attribute(group, attribute, image=None, default=False, *, prefix=None, variant=None, **kwargs)

This is used to represent a layer of an LayeredImage that is controlled by an attribute. A single attribute can control multiple layers, in which case all layers corresponding to that attribute will be displayed.

group: A string giving the group the attribute is part of. This may be None, in which case a group with the same name as the attribute is created.
attribute: A string giving the name of the attribute.
image: If not None, this should be a displayable that is displayed when this attribute is shown.
default: If True, and no other attribute for the group is selected, this attribute is.

The following keyword arguments are also known:

at: A transform or list of transforms that are applied to the image.
when: A string containing a when expression, described in the When section. The displayable is only shown when the expression is satisfied by the pool of attributes currently applied to the layeredimage.
variant: A string giving the variant of the attribute. This is used as part of finding the displayable when image is None.

Other keyword arguments are interpreted as transform properties. If any are present, a transform is created that wraps the image. (For example, pos=(100, 200) can be used to offset the image by 100 pixels horizontally and 200 vertically.)

If the image parameter is omitted or None, and the LayeredImage has been given the image_format parameter, the image_format is used to generate an image filename.

class Condition(condition, image, **kwargs)

When the condition is true, the layer is displayed. Otherwise, nothing is displayed.

This is used to implement a single if, elif or else layeredimage statement (for else, condition should be "True"). Several Conditions can then be passed to a ConditionGroup to emulate a full if/elif/else statement.

condition: This should be a string giving a Python condition that determines if the layer is displayed.
image: If not None, this should be a displayable that is displayed when the condition is true.
when: A string containing a when expression, described in the When section. The condition is only evaluated when the expression is satisfied by the pool of attributes currently applied to the layeredimage.
at: A transform or list of transforms that are applied to the image.

Other keyword arguments are interpreted as transform properties. If any is present, a transform is created that wraps the image. (For example, pos=(100, 200) can be used to offset the image by 100 pixels horizontally and 200 vertically.)

class ConditionGroup(conditions)

Takes a list of Condition to combine them into a single ConditionSwitch().

Implements the if/elif/else statement.

class LayeredImage(attributes, at=[], name=None, image_format=None, format_function=<function format_function at 0x76a4eaf94ae0>, attribute_function=None, offer_screen=None, **kwargs)

This is an image-like object that, when shown with the proper set of attributes, shows a displayable created by compositing together the displayables associated with those attribute.

attributes: This must be a list of Attribute, Condition, ConditionGroup or displayable objects. Each one reflects a displayable that may or may not be displayed as part of the image. The items in this list are in back-to-front order, with the first item further from the viewer and the last closest. Passing a displayable directly is the equivalent of the always layeredimage statement.
at: A transform or list of transforms that are applied to the displayable after it is parameterized.
name: The name of the layeredimage. This is used as part of the names of image components.
image_format: When a given image is a string, and this is supplied, the image name is interpolated into image_format to make an image file. For example, "sprites/eileen/{image}.png" will look for the image in a subdirectory of sprites. (This is not used by auto groups, which look for images and not image files.)
format_function: A function that is used instead of layeredimage.format_function to format the image information into a displayable.
attribute_function: If not None, a function that's called with a set of attributes supplied to the image, and returns the set of attributes used to select layers. This is called when determining the layers to display, after the attribute themselves have been chosen. It can be used to express complex dependencies between attributes or select attributes at random.
offer_screen: Sets whether or not the available area is taken into account as for how children are placed and how they are sized (when they have variable size). If False, the available area is considered, and if True it is not. If None, defaults to config.layeredimage_offer_screen.

Additional keyword arguments may contain transform properties. If any are present, a transform is created that wraps the result image. Remaining keyword arguments are passed to a Fixed that is created to hold the layer. Unless explicitly overridden, xfit and yfit are set to true on the Fixed, which means it will shrink to the smallest size that fits all of the layer images it is showing.

A LayeredImage is not a displayable, and can't be used in all the places a displayable can be used. This is because it requires an image name (generally including image attributes) to be provided. As such, it should either be displayed through a scene or show statement, or by an image name string used as a displayable.

add(a)

a: An Attribute, Condition, ConditionGroup or displayable object.

This method adds the provided layer to the list of layers of the layeredimage, as if it had been passed in the attributes argument to the constructor.