Statement Equivalents

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

Dialogue

The Ren'Py say statement is equivalent to calling the character object as a function. The following code displays the same line twice:

e "Hello, world."

$ e("Hello, world.")

Displaying narration can be done the same way, by using the narrator character. When calling a character, it's possible to supply the keyword argument interact. When interact is false, Ren'Py will display the character dialogue box, and will then return before performing an interaction.

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. 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 Ren'Py adds additional keyword arguments to character calls.

Displaying Images

The image, scene, show, and hide statements each have an equivalent python function.

renpy.hide(name, layer='master')

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.
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='master', what=None, zorder=0, tag=None, behind=[])

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.
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.
tag
A string, used to specify the 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.

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.