documentation indexreference manualfunction index

The Ren'Py Language

This section describes the Ren'Py language, and the functions found in that language. There is a simpler, less technical version if you find the detail on this page intimidating.

Contents


Script, Line, and Block Structure

Ren'Py scripts consist of one or more .rpy files. These script files may be read in any order, and all of them together make up a Ren'Py script. Please see Files and Directories for information about where Ren'Py searches for .rpy files.

Each of these files is divided into a series of logical lines. The first logical line of a file begins at the start of a file, and another logical line begins after each logical line ends, until the end of the file is reached. By default, a logical line is terminated by the first newline encountered. However, a line will not terminate if any of the following are true:

Ren'Py script files also can include comments. A comment begins with a hash mark that is not contained within a string, and continues to, but does not include, the next newline character. Some examples are:

# This line contains only a comment.
scene bg whitehouse  # This line contains a statement as well.

If, after eliminating comments, a logical line is empty, that logical line is ignored.

Logical lines are then combined into blocks. Two logical lines are in the same block if the lines have the same indentation preceding them, and no logical line with a lesser amount of indentation occurs between the two lines. Indentation may only consist of spaces, not tabs. In the following example:

line 1
    line a
    line b
line 2
    line c
    line d

In this example, here are three blocks. One block contains lines 1 and 2, another lines a and b, and the third contains lines c and d. This example can also serve to illustrate the concept of a block associated with a line. A block is associated with a line if the block starts on the next logical line following the line. For example, the block containing lines a and b is associated with line #

There are three kinds of blocks in an Ren'Py program. The most common is a block containing Ren'Py statements. Blocks may also contain menuitems or python code. The top-level block (the one that contains the first line of a file) is always a block of Ren'Py statements.

Syntax Constructs

Before we can describe Ren'Py statements, we must first describe a number of syntactic constructs those statements are built out of. In this subsection, we describe such constructs.

Keywords are words that must literally appear in the source code. They're used ito introduce statements, or to delimit parts of statements. You'll see keywords throughout the descriptions of statements. In grammar rules, keywords are in quotes. The keywords used by Ren'Py are:

at
behind
call
elif
else
expression
hide
if
image
init
jump
label
menu
onlayer
pass
python
return
scene
set
show
transform
while
with
zorder

A name consists of a letter or underscore (_) followed by zero or more letters, numbers, or underscores. For this purpose, unicode characters between U+00a0 and U+fffd are considered to be letters. A name may not be a keyword.

A string begins with a quote character (one of ", ', or `), contains some sequence of characters, and ends with the same quote character. Inside a Ren'Py string, whitespace is collapsed into a single space, unless preceded by a backslash (as \ ). Backslash is used to escape quotes, special characters such as % (written as \%) and { (written as \{). It's also used to include newlines, using the \n sequence.

A simple_expression is a Python expression that starts with a name, a string, or any Python expression in parentheses. This may be followed by any number of the following:

  • A dot followed by a name.
  • A parenthesized python expression.

A python_expression is an arbitrary python expression that may not include a colon. These expressions are generally used to express the conditions in the if and while statements.

An image_name consists of one or more names, separated by spaces. The first name in an image_name is known as the image tag.

Name Munging

Before parsing a file, Ren'Py looks for names of the form __word, where word does not contain __. That is, starting with two or three underscores, and not containing another two consecutive underscores. It munges these names in a filename-specific manner, generally ensuring that they will not conflict with the same name in other files. For example, in the file script.rpy, __v is munged into _m1_script__v (the name is prefixed with the munged filename).

Names beginning with an odd number of underscores are reserved for Ren'Py, while those beginning with an even number of underscores can safely be used in scripts.

Grammar Rules

We will be giving grammar rules for some of the statements. In these rules, a word in quotes means that that word is literally expected in the script. Parenthesis are used to group things together, but they don't correspond to anything in the script. Star, question mark, and plus are used to indicate that the token or group they are to the right of can occur zero or more, zero or one, or one or more times, respectively.

If we give a name for the rule, it will be separated from the body of the rule with a crude ascii-art arrow (->).

Statements

Call Statement

The call statement is used to transfer control to the statement with the given name. It also pushes the name of the statement following this one onto the call stack, allowing the return statement to return control to the statement following this one.

call_statement -> "call" name ( "from" name )?
call_statement -> "call" "expression" simple_expression ( "from" name )?

call_statement -> "call" name "(" arguments ")" ( "from" name )?
call_statement -> "call" "expression" simple_expression "pass" "(" arguments ")" ( "from" name )?

If the expression keyword is present, the expression is evaluated, and the string so computed is used as the name of the statement to call. If the expression keyword is not present, the name of the statement to call must be explicitly given.

If the optional from clause is present, it has the effect of including a label statement with the given name as the statement immediately following the call statement. An explicit label is required here to ensure that saved games with return stacks can return to the proper place when loaded on a changed script. From clauses should be included for all calls in released games.

As from clauses may be distracting when a game is still under development, we provide with Ren'Py a program, called add_from, that adds from clauses to all bare calls in any game directory. It can be found in tools/add_from, although it needs to be run from the base directory. The easiest way to do this on windows is by running tools/game_add_from.bat. It should be run before a final release of your game is made. Be sure to make a backup of your game directories before running add_from. Also note that add_from produces .bak files for all files it can change, so delete them when you're satisfied that everything worked.

e "First, we will call a subroutine."

call subroutine from _call_site_1

# ...

label subroutine:

    e "Next, we will return from the subroutine."

    return

The call statement may take arguments, which are processed as described in PEP 3102. If the return statement returns a value, that value is stored in the _return variable, which is dynamically scoped to each context.

When using a call expression with an arguments list, the pass keyword must be inserted between the expression and the arguments list. Otherwise, the arguments list will be parsed as part of the expression, not as part of the call.

Define Statement

The define statement causes its expression to be evaluated, and assigned to the supplied name. If not inside an init block, the define statement will automatically be run with init priority 0.

define_statement -> "define" name "=" python_expression
define e = Character("Eileen")

Hide Statement

The hide statement is used to hide an image from the screen.

hide_statement -> "hide" image_name ( "onlayer" name )?

A hide statement operates on the layer supplied in the onlayer clause of the image_spec, defaulting to "master" if no such clause has been supplied. It finds an image beginning with the image tag of the image name, and removes it from that layer.

Please note that the hide statement is rarely used in practice. Show can be used by itself when a character is changing emotion, while scene is used to remove all images at the end of a scene. Hide is only necessary when a character leaves before the end of a scene.

If Statement

The if statement is used to conditionally execute a block of statements.

if_statement -> "if" python_expression ":"
elif_clause -> "elif" python_expression ":"
else_clause -> "else" ":"

The if statement is the only statement which consists of more than one logical line in the same block. The initial if statement may be followed by zero or more elif clauses, concluded with an optional else clause. The expression is evaluated for each clause in turn, and if it evaluates to a true value, then the block associated with that clause is executed. If no expression evaluates to true, then the block associated with the else clause is executed. (If an else clause exists, execution immediately continues with the next statement.) In any case, at the end of the block, control is transferred to the statement following the if statement.

if points >= 10:

   e "Congratulations! You're getting the best ending!"

elif points >= 5:

   e "It's the good ending for you."

else:

   e "Sorry, you're about to get the bad ending."

Image Statement

The image statement is used to declare images to Ren'Py. Image statements can either appear in init blocks, or are implicitly placed in an init block with priority 990. (changed in 6.9.0)

image_statement -> "image" image_name "=" python_expression

An image statement binds an image name to a displayable. The displayable is computed by the supplied python expression, with the result of the expression being passed to the im.Image function in loose mode. This means that if the assignment is a single string, it is interpreted as an image filename. Displayables are passed through unmolested. Once an image has been defined using an image statement, it can be used by the scene, show, and hide statements.

For a complete list of functions that define displayables, see the displayables page.

image eileen happy = "eileen/happy.png"
image eileen upset = "eileen/upset.png"

Init Statement

The init statement is used to execute blocks of Ren'Py statements before the script executes. Init blocks are used to define images and characters, to set up unchanging game data structures, and to customize Ren'Py. Code inside init blocks should not interact with the user or change any of the layers, and so should not contain say, menu, scene, show, or hide statements, as well as calls to any function that can do these things.

init_statement -> "init" (number)? ":"

An init statement is introduced with the keyword init, followed by an optional priority number, and a mandatory colon. If the priority is not given, it defaults to 0. Priority numbers should be in the range -999 to 999. Numbers outside of this range are reserved for Ren'Py code.

The priority number is used to determine when the code inside the init block executes. Init blocks are executed in priority order from low to high. Within a file, init blocks with the same priority are run in order from the top of the file to the bottom. The order of evaluation of priority blocks with the same priority between files is undefined.

The init blocks are all run once, during a special init phase. When control reaches the end of an init block during normal execution, execution of that block ends. If an init statement is encountered during normal execution, the init block is not run. Instead, control passes to the next statement.

Jump Statement

The jump statement is used to transfer control to the statement with the given name.

jump_statement -> "jump" name 
jump_statement -> "jump" "expression" simple_expression 

If the expression keyword is present, the expression is evaluated, and the string so computed is used as the name of the statement to jump to. If the expression keyword is not present, the name of the statement to jump to must be explicitly given.

Unlike call, jump does not push the target onto any stack. As a result, there's no way to return to where you've jumped from.

label loop_start:

e "Oh no! It looks like we're trapped in an infinite loop."

jump loop_start

Label Statement

Label statements allow a name to be assigned to a program point. They exist solely to be called or jumped to, whether by script code or the Ren'Py config.

label_statement -> "label" name ":"
label_statement -> "label" name "(" parameters ")" ":"

A label statement may have a block associated with it. In that case, control enters the block whenever the label statement is reached, and proceeds with the statement after the label statement whenever the end of the block is reached.

The label statement may take an optional list of parameters. These parameters are processed as described in PEP 3102, with two exceptions:

  • The values of default parameters are evaluated at call time.
  • The variables are dynamically, rather than lexically, scoped.

Inside a called label, variables can be declared dynamic using the renpy.dynamic function:


Function: renpy.dynamic (*vars):

This declares a variable as dynamically scoped to the current Ren'Py call. The first time renpy.dynamic is called in the current call, the values of the variables named in the supplied strings are stored. When we return from the current call, the variables are given the values they had at the time when renpy.dynamic was called. If the variables are undefined when renpy.dynamic is called, they are undefined after the current call returns. If renpy.dynamic is called twice for the same variable in a given call, it has no effect the second time.