You've reached a page on the Ren'Py wiki. Due to massive spam, the wiki hasn't been updated in over 5 years, and much of the information here is very out of date. We've kept it because some of it is of historic interest, but all the information relevant to modern versions of Ren'Py has been moved elsewhere.
Some places to look are:
Please do not create new links to this page.
This section describes the Ren'Py language, and the functions found in that language. I will begin replacing the language constructs with basic examples. As the refence file has all the nuances anyway, this version will be distilled down further.
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 dIn 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.
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 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.
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."
returnThe 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.
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 e = Character("Eileen")The hide statement is used to hide a displayable from the screen.
hide eileen
hide butterfly onlayer overlayIt tries to hide displayable from the "master" layer, if no layer has been specified with onlayer. The name doesn't have to match exactly. If you have image eileen happy on screen, then hide eileen will still hide it.
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.
The if statement is used to conditionally execute a block of statements. It 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."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.
image_statement -> "image" image_name "=" python_expressionAn 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 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"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:
$ john = Character("John Smith")
$ percy = Character("Sir Percival Blakely")
image black = "#000000"The number after an init statement is optional. If the priority is not given, it defaults to 0. Priority numbers should be in the range -999 to 999. The priority number is used to determine when the code inside the init block executes. Init blocks with the smaller number are executed before others. Within a file, init blocks with the same priority are run in order from the top of the file to the bottom.
The init blocks are all run once, during a special init phase. If an init statement is encountered during normal execution, the init block is not run. Instead, control passes to the next statement.
The jump statement is used to go from one part of the story to another. The jump command consists of the word 'jump' followed by the name of the label to jump to. The label may be in a different file.
jump some_labelIf you jump to the same label you're already in, you get stuck in a loop.
label loop_start:
e "Oh no! It looks like we're trapped in an infinite loop."
jump loop_startUsing the expression keyword, it's possible to make the story jump to a random label. The piece of python after the expression keyword must return a label name.
jump expression renpy.random.choice(["CowTown", "CakeTown", "over9000"])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 yellow:
'My submarine is yellow!'
label black (parametres):
'My label is black!'What are these parametres and why are they useful???
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:
Menus are used to present the user with a list of choices that can be made. In a visual novel, menus are the primary means by which the user can influence the story.
$ list = set()
menu password:
"What is the password?"
with vpunch
set list
"Jesus?":
"No"
jump password
"123":
"No"
jump password
"Jeff" if clever:
jump back_door
"You fail at hacking."When a menu is shown, it may appear with a transition. Also, each of the choices has its expression evaluated, and if not true, that choice is removed from the list. If no choices survive this process, the menu is skipped.
If the menu has a name, it is treated as a label for this menu statement, as if the menu statement was preceded by a label statement.
A string may be placed into a menu as a caption that cannot be selected. In general, captions are used to indicate what the menu is for, especially when it is not clear from the choices.
Before you show a menu, you can also specify a variable in which to store the list of choices the user has made. When the user chooses from the menu, that choice will be added to the list. When the game reaches another menu statement using the same variable name in a set clause (or reaches the same menu again), any choices matching items in the list will not be shown.
The pause statement causes Ren'Py to pause until the mouse is clicked. If the optional expression is given, it will be evaluated to a number, and the pause will automatically terminate once that number of seconds has elapsed.
pause_statement -> "pause" ( simple_expression )?The play statement is used to play sound and music. If a file is currently playing, it is interrupted and replaced with the new file.
play_statement -> "play" name simple_expression
( "fadeout" simple_expression )?
( "fadein" simple_expression )?
( "loop" | "noloop" )?
( "if_changed" )?The first simple_expression in the play statement is expected to evaluate to either a string containing a filename, or a list of filenames to be played. The name is expected to be the name of a channel. (Usually, this is either "sound", "music", or "movie".) The file or list of files is played using . The other clauses are all optional. Fadeout gives the fadeout time for currently playing music, in seconds, while fadein gives the time it takes to fade in the new music. Loop causes the music too loop, while noloop forces it not to loop. If_changed causes the music to only change if it is not the currently playing music.
play music "mozart.ogg"
play sound "woof.ogg"
"Let's try something more complicated."
play music [ "a.ogg", "b.ogg" ] fadeout 1.0 fadein 1.0The pass statement does not perform an action. It exists because blocks of Ren'Py statements require at least one statement in them, and it's not always sensible to perform an action in those blocks.
menu:
"Should I go to the movies?"
"Yes":
call go_see_movie
"No":
pass
"Now it's getting close to dinner time, and I'm starving."The python statement allows one to execute Python code in a Ren'Py script. This allows one to use Python code to declare things to Ren'Py, to invoke much of Ren'Py's functionality, and to store data in variables that can be accessed by user code. There are two forms of the python statement:
python_statement -> "$" python_code
python_statement -> "python" ( "hide" )? ":"The first form of a python consists of a dollar sign ($) followed by Python code extending to the end of the line. This form is used to execute a single Python statement.
A second form consists of the keyword python, optionally the keyword hide, and a colon. This is used to execute a block of Python code, supplied after the statement. Normally, Python code executes in a script-global namespace, but if the hide keyword is given, a new namespace is created for this block. (The script-global namespace can be accessed from the block, but not assigned to.)
$ score += 1
python:
ui.text("This is text on the screen.")
ui.saybehavior()
ui.interact()Init Python Statement. For convenience, we have created the init pythons statement. This statement combines an init statement and a python statement into a single statement, to reduce the indentation required for python-heavy files.
init python_statement -> "init" ( number )? "python" ( "hide" )? ":"The queue statement is used to queue up audio files. They will be played when the channel finishes playing the currently playing file.
queue_statement -> "queue" name simple_expression ( "loop" | "noloop" )?The name is expected to be the name of a channel, while the simple_expression is expected to evaluate to either a string containing a filename, or a list of filenames to be queued up. The files are queued using .
Loop causes the queued music to loop, while noloop causes it to play only once.
queue sound "woof.ogg"
queue music [ "a.ogg", "b.ogg" ]The say statement is used to present text to the user, in the form of dialogue or thoughts. It consists of the sayer, a string and an optional with clause after it used to specify a transition.
define E = Character('Eileen')
label start:
"I moved to my left, and she moved to her right."
"So we bumped into each other" with hpunch
"Girl" "Ouch!"
E "I'm so sorry, are you OK?"If you don't give a sayer, this is used to indicate POV character thoughts or narration. Otherwise you have to put there a character name or object (usually a or object).
The with clause is used to specify a transition; see With Statement and Clauses for details.
The scene statement is usually meant for changing the background of a scene. It clears a layer by removing all images from it and then may show a new image to the user.
scene image
scene onlayer master imageThe scene statement first clears out all images from "master" layer, unless another layer is specified. If additional arguments are present, then they are handled as if a statement was supplied.
By default, no background is added to the screen, so we recommend that every script begin with a scene statement that shows a full-screen background to the user.
The show statement is used to add an image to a layer. The image must have been defined using the statement.
show_statement -> "show" image_name
( "at" transform_list )?
( "as" name )?
( "behind" name_list )?
( "onlayer" name )?
( "with" simple_expression )?When adding an image, the show statement first checks to see if an image with the same tag (by default, first part of the image name) exists in the layer. If so, that image is replaced, without changing the order. This means that it's rarely necessary to hide images.
The show statement takes several optional clauses.
When an image is shown, Ren'Py checks to see if there was a previous image with that tag, and if that image used a transform. If this is true, Ren'Py does two things:
The generally has the effect of "remembering" the position of images shown on the screen. In some cases, this memory effect may override a position encoded into an image. In that case, the image must be hidden and shown again.
scene living_room
show eileen happy at left
show golden glow as halo at left behind eileen
e "I'm feeling happy right now."
show eileen upset at left
show darkness as halo at left behind eileen
e "But sometimes, I can get upset for no good reason."The show statement can also be used to display text, using the displayable. The text displayable is defined by default, and uses the centered_text style:
show text "Centered text"There is a second form of the show statement that takes an expression that returns a displayable. This can be used to show a displayable directly. The tag of the displayable is undefined, unless given with the as clause.
show_statement -> "show" "expression" simple_expression
( "as" name )?
( "onlayer" name )?
( "at" transform_list )?
( "behind" name_list )?
( "with" simple_expression )?show expression "myimage.png"The stop statement is used to stop playing sound and music.
stop name
stop music fadeout 1.0The name is expected to be the name of an audio channel. The sound or music is stopped using . The optional fadeout clause expects a time in seconds, and will cause it to take that long to fadeout the music.
The window statement is used to control if a window is shown when a character is not speaking. (For example, during transitions and pauses.)
window_statement -> window ( "show" | "hide" ) ( simple_expression )?The "window show" statement causes the window to be shown, while the "window hide" statement hides the window. If the optional simple_expression is given, it's a transition that's used to show and hide the window. If not given, it defaults to and . Giving None as the transition prevents it from occuring.
The window itself is displayed by calling . It defaults to having the narrator say an empty string.
show bg washington
show eileen happy
with dissolve
window show dissolve
"I can say stuff..."
show eileen happy at right
with move
"... and move, while keeping the window shown."
window hide dissolveThe with statement and with clauses are used to show transitions to the user. In addition to Scene, show, and hide statements, with clauses can also be applied to say and menu statements. In this case, the transition occurs when the dialogue or menu is first shown to the user.
You can apply a transition to multiple items at the same time, but be careful. The following:
show bg whitehouse with dissolve
show eileen happy with dissolvewill cause two transitions to occur. To ensure only a single transition occurs, one must write:
show bg whitehouse
show eileen happy
with dissolveFor pre-defined transition functions that can be used in any script, see Pre-defined Transitions. You can also construct your own using Transition Constructors.
The while statement is used to execute a block of Ren'Py statements while a condition remains true. The "not endgame" can be any python expression.
while not endgame:
"It's now morning. Time to get up and seize the day."
call morning
call afternoon
call evening
"Well, time to call it a night."
"Now it's time to wake up and face the endgame."When a while statement is executed, the python_expression is evaluated. If it evaluates to true, control is transferred to the first statement in the block associated with this while statement. If false, control is instead sent to the statement following the while statement. At the end of the while block, control returns to the beginning, to evaluate the expression again.