documentation index ◦ reference manual ◦ function index
This page provides a simple overview of the Ren'Py language intended for non-programmers. There is also a more technical version of this page for more advanced users.
This simple version may not contain the same amount of detail, and may not be strictly accurate in a technical sense, but instead aims to give the reader an understanding of the common usage of the language features described, skipping exact detail for utility.
Contents |
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. When the game is started, Ren'Py will find the 'start' label and step through the lines one by one in order, doing whatever each line tells it to, until it runs out of script.
As Ren'Py runs through the script, it generally treats every line in the script file as a separate instruction; however, there are some exceptions:
$ a = Character(
'Abigail',
color="#454580"
)
"I was disoriented,
feeling like my thoughts
were split up, and
scattered somehow."
$ e = m * \
c * c
is equivalent to:
$ e = m * c * c
If you want to make notes within your script, then you can use comments. It's generally considered a good idea to write comments describing anything you think you'll need to remember - perhaps why a particular condition is checked, or what a variable is used for. To write a comment, simply type a hash (#). Ren'Py will ignore everything from that point until the end of the line, so you can write anything you like.
# This line is a comment and will be ignored.
# This line will be ignored too.
"This line is going to be picked up by Ren'Py and used as dialogue"
"This is dialogue" # but this bit on the end is a comment.
Note that because Ren'Py's ignoring the comments, it's not checking for parentheses or quotes or backslashes on the end of the line - so comments can never be extended over more than one line in your script file without putting another hash in.
Sometimes, a collection of lines need to be grouped together. This happens most frequently for labels, but also for conditional statements and loops and so on. Lines which are collected together are called 'blocks', and are written with an extra indentation in the script file:
line 1
line a
line b
line 2
line c
line d
In this example, here are three blocks. One block contains everything, the second block lines a and b, and the third contains lines c and d.
Note that lines a and b are said to be associated with line 1 - typically, line 1 will describe why lines a and b are in a block, e.g.:
if (x < 10):
# The lines in this block are only run if x is less than ten
"Sam" "Oh no!"
"Sam" "Ecks is less than ten!"
# But these lines - outside of the if's block - are run regardless of the value of x.
"We wandered down the road a bit more, looking for anything else as interesting as that ecks."
Note that lines which start a new block end with a colon (:). If a line ends with a colon, Ren'Py will expect to find a new block beneath it; if a line doesn't end in a colon, a new block shouldn't be started after that line.
The entire script will be divided up into label blocks and init blocks - these control the overall flow of the game; Ren'Py will always start at the 'start' label.
Init blocks are used to define things which are going to be used again and again throughout your script. Typically, this includes images and Characters. It's generally a bad idea to define anything which has a changing state in an init block; it's best to stick to things which remain the same throught the game, like background images, character sprites and so on.
When the game first starts, all of the init blocks in all of the game scripts are run; if any init blocks are later encountered in the middle of the script they're ignored and skipped entirely.
An init block is started by the word 'init', followed by a colon, e.g.:
init: # code for init block goes here # more init code
The most common things to find within an init block are definitions of Images and Characters:
Images must be defined in an init block.
When we define an image we give a name to an image file by which we can refer to it later in the script - so when we want to show a character sprite or start a new scene in a different background, we can use the images that we defined earlier.
An image is defined by the command 'image', followed by a name for that image, then an equals sign, then the filename for the image file we wish to use. Place the image file in the game directory alongside the script, and Ren'Py will be able to find it.
init: image eileen = "eileen.png"
Note that you can give images names with spaces in - if you do this, Ren'Py pays special attention to the first word of the name (see the show and hide commands for more details) so it's wise to group your images by that first part, e.g.:
init: image eileen happy = "eileen-happy.png" image eileen sad = "eileen-sad.png"
Also commonly defined in init blocks are Characters - a Character allows a quick and easy way to attach a name to dialogue, format text and so on, rather than having to type out the Character's full name and assign colours every time that Character speaks.
In its simplest form, one defines a character as follows:
init: $ l = Character("Lucy")
The dollar sign at the beginning of the line tells Ren'Py that this is a Python line. This is necessary for defining characters because there's no Ren'Py command to do it for us - Characters have too many options! The next part - 'l' in the example above - is the name by which we refer to that character in the rest of the script. The last part creates the Character itself; here we're just supplying the name which we want to be displayed when that character is used.
Creating a Character for each of the characters in your VN is not by any means essential, but at the very least it can help to save you typing the character name out each time they speak.
For further details on Characters and the many other options they have, see the article on Defining Characters.
The following items are a list of common commands Ren'Py understands, along with a usage explanation and example for each. While some effort has been made to order the list sensibly, it's unavoidable that sometimes references to later in the list will be necessary.
Speech displays text onto the screen, then waits for the user to click the mouse button or hit space or enter before proceeding to the next instruction. Speech falls into two categories - narration or dialogue.
Narration is simplest - it consists of the text to be narrated, enclosed between quotes, e.g.:
"It was a dark and stormy night"
Note that you can use either single or double quotes, but you must start and end the text with the same kind of quote. Of course, this means that you can include single-quotes in double-quoted text and vice-versa:
"'Twas the night before Christmas"
'I could tell it was going to be one of "those" days.'
Dialogue is used to have particular characters speak. Because the reader can't tell the difference between one character's voice and another's, when all their dialogue is just text, the name of the character speaking is displayed alongside the dialogue. Of course, this means that you have to specify the name of the character in the script, which is done by writing the character's name (in quotes) first, then the dialogue for that character immediately afterward, e.g.:
"Hamlet" "Alas, poor Yorick! I knew him, Horatio, a fellow of infinite jest, of most excellent fancy."
If you have defined a Character (in an init block), you can use that Character instead of the name when writing dialogue, e.g.:
init: $ e = Character("Eileen") label start: e "Hello!"
The show command is used for adding a sprite to a scene. The sprite must previously have been defined as an image in an init block, as the show command uses the image name.
In its most basic form, the show command consists of the word 'show', followed by the name of the image to show, e.g.:
init: image eileen = "eileen.png" label start: show eileen
This will show the image named 'eileen' - the one from the file 'eileen.png' - in the bottom-centre of the screen.
When you show an image, Ren'Py will look for an image which is already in the scene which shares the same first part of the name - if such an image exists, Ren'Py will remove it before showing the new image. This means that - for example - you don't have to hide old sprites of the same character when you're changing an expression.
init: image eileen happy = "eileen-happy.png" image eileen sad = "eileen-sad.png" label start: show eileen happy show eileen sad
When the second 'show' command is run, Ren'Py looks at the first part of the image name - in this case 'eileen' - and examines all the images already in the scene for an image with that tag. The previous 'eileen happy' also had 'eileen' for the first part of the image name, so this is removed from the scene before the second show takes place. This ensures that only one Eileen is on-screen at the same time.
Of course, it's not particularly useful to only be able to show things in the centre of the screen, so the show command can also be followed by an 'at' giving a position at which to place the new image in the scene:
show eileen at left
This will show the 'eileen' image at the left of the screen. The positions that Ren'Py understands out of the box are as follows:
Alternately, you can define your own positions with the Position function
The hide command is the opposite of the show command - it removes an image from a scene.
The syntax is similar - simply the word 'hide' followed by the name of the image to hide:
show eileen happy at left
# now there is one character in the scene
show lucy upset at right
# now there are two characters in the scene
hide eileen
# now there is only one character remaining
hide lucy
# and now there are none
As you can see from the above example, only the first part of the image name is necessary - in the same way that the 'show' command will replace an image in the scene just based on the first part of the image name, equally the hide command only needs this much to find it and hide it. Also note that it is not necessary to specify the position of the character to hide. In fact, even if you specify these things they will be ignored.
The scene command is used to start a new scene - this involves removing all images from the current scene and changing the background image to suit the new scene.
The scene command is followed by the image name for the new background image:
init: image bg funfair = "funfair.jpg" image bg ferris = "ferriswheel.jpg" image eileen = "eileen.png" label start: scene bg funfair show eileen at left # Now the background is 'funfair.jpg' and Eileen is shown at the left. ... scene bg ferris # Now Eileen has been removed and the background replaced by 'ferriswheel.jpg'.
The with statement acts as a modifier to a previous command, adding a transition effect. It can be appended to the end of a 'show', 'hide' or 'scene' statement to have that action performed with the given transition. For example:
show eileen with dissolve
Will dissolve Eileen in instead of her popping instantly into place.
Transitions that Ren'Py understands out of the box can be found in the list of predefined transitions.
Ren'Py will wait for a transition to finish before continuing, so if you instruct it to perform several in a row, it could take several seconds to complete:
scene bg funfair with fade
# Ren'Py waits for the funfair scene to fade in before...
show eileen at left with dissolve
# Ren'Py waits for Eileen to fully dissolve in before...
hide eileen with moveoutleft
# Ren'Py waits for Eileen to completely disappear off the side of the screen before...
"Who was that?"
Of course, sometimes this isn't desirable - you may wish for the scene to fade in, with a character sprite already displayed, in which case you need to stretch the with over more than one statement. If you place the with clause on a line on its own, then instead of being tied to one specific show, hide or scene, it will apply to every such command since the last dialogue or menu - or the last statement which did have its own with clause.
scene bg funfair
show eileen at left
show lucy at right
with fade
In the above example, whatever the previous scene was will fade to black, then a scene containing eileen and lucy in front of the 'bg funfair' background will fade in all as one single transition.
scene bg funfair with fade
show eileen at left
show lucy at right
with dissolve
In this example, however, the scene command had its own 'with' clause, so the 'with dissolve' at the end only applies to the two 'show' commands. So the previous scene will fade to black, then the new scene at the funfair will fade in, and as soon as that has finished Eileen and Lucy will both dissolve in at the same time.
The play statement is used for playing sound effects or music tracks.
To play music, follow the play command with the word 'music', then the filename of the music file you wish to play:
play music "entertainer.ogg"
To play a sound, follow the play command with the word 'sound', then the filename of the sound file you wish to play:
play sound "explosion.ogg"
When you play music, Ren'Py will loop the music, playing it over and over again; when you play a sound, Ren'Py will play it only once.
Sound output is divided into 'channels'. You can only be playing one piece of audio - sound or music - on a single channel at once. If you want to play two sounds simultaneously, you will need to specify that the second one is played on a different channel - this can be done by adding 'channel' and then the number of the channel you wish to use to the end of the command:
play sound "explosion.ogg" channel 0 play sound "yeehah.ogg" channel 1
By default, sounds are played on channel 0, and music is played on channel 7. Of course, this means that if you are only playing one sound at a time, you don't need to worry about channels - sounds can be played over music just fine.
By default, Ren'Py will stop any audio you already have playing on a channel if you play something new; if you want to specify a fadeout for an already-playing music or sound effect, then add 'fadeout' followed by a time in seconds to fade for to the end of the command.
play music "waltz.ogg" fadeout 1
Similarly, if you want to fade the new piece of music in, then use the 'fadein' keyword. One can combine any or all of these keywords in the same command:
play music "waltz.ogg" fadeout 1 fadein 2
The above example will fade whatever music is currently playing out over the course of one second, and fade in "waltz.ogg" over the course of two seconds.
Lastly, if you would prefer to give several pieces of music or sounds to be played one after another, you can give the play command a list of files instead of just a single filename. To use a list, use square brackets ([, ]) around a list of filenames separated by commas.
play music ["waltz.ogg", "tango.ogg", "rumba.ogg"]
The above example will play "waltz.ogg", then once it is finished play "tango.ogg", then "rumba.ogg", then start again at the beginning with "waltz.ogg".
Ren'Py will play files in the following formats:
Audio files should be saved at 44100Hz to avoid crackle.
Stop is the opposite of the play command; it stops whatever audio is currently playing. Similarly to play, you can choose from either 'stop sound' to stop a sound effect, or 'stop music' to stop playing music.
stop sound
Similarly to play, you can specify a fadeout for the audio you're stopping by adding the word 'fadeout' followed by a time in seconds.
stop music fadeout 1.5
The above example fades the currently-playing music out over the course of one and a half seconds.
You can also stop the audio that's playing on a particular channel. Again, this is done in a similar manner to the play command - simply append 'channel' and the channel number you wish to stop after the stop command, e.g.:
stop sound channel 2
Since you are only stopping audio which has already been played, the default channels are the same - channel 0 for sound effects and channel 7 for music.
The queue command queues up music files or sound effects to play after the currently-playing audio has finished. Ren'Py will queue the file you specify to play immediately after the currently-playing music has finished.
The simple usage of the command is similar to the play command - the queue command is followed by one of 'sound' or 'music' depending on whether you want to queue a music track or a sound effect, then the filename of the audio file you wish to queue:
queue music "waltz.ogg"
If you call the queue command a second time before the first piece of music finishes, your newly-queued file will replace the existing queued item and be played as soon as the currently-playing audio has finished.
play music "waltz.ogg" queue music "tango.ogg" "There's a waltz playing in the background..." queue music "rumba.ogg"
In the above example, first "waltz.ogg" is started playing, and then "tango.ogg" is queued. Then, the game displays some dialogue and waits for the user to click to continue.
In either scenario, once the rumba finishes it will continue to loop just the rumba.
If you wish to queue up more than one file at once, then you can supply a list of file names, separated by commas, inside square brackets ([, ]) instead of a single file name.
play music "rumba.ogg" queue music ["waltz.ogg", "tango.ogg"]
In this example, the rumba plays. Two files are added to the queue, so when the rumba finishes, it will play the waltz next; when the waltz finishes, it will play the tango. When the tango finishes, the entire queue will loop, so the waltz will play, then the tango, then the waltz again, then the tango again, and so on.
Similarly to the play command, you can specify a channel on which to queue the audio, by adding 'channel' followed by the channel number to the end of the command.
queue sound "explosion.ogg" channel 2
Note that you cannot queue music to a channel which is currently playing sound effects, or sound effects to a channel that is currently playing music. Each channel has its own queue, so you can queue - for example - music on the default channel and sound effects on the default channel and both of your queued items will be played independently.
Labels are used to divide a Ren'Py script up into sections, and also to allow a non-linear progression through those sections.
Generally, Ren'Py will run each line of the script in the order it finds them, so by way of example:
"This line is run first" "This line is run second" "This line is run third" # and so on...
However, in order to write a branching story, or perhaps a story in which some parts are repeated, we use labels. Labels contain blocks of Ren'Py script, and consist of the word 'label' followed by a name, followed by a colon(:) - which denotes that it contains a block.
label start: "This line is under the 'start' label." "As is this one." label next: "But this one is under the label 'next'." label last: "And this one is under 'last'."
Label names have to be unique across your entire script, because Ren'Py uses them to identify that particular place in the script - you can't have two labels with the same name, because Ren'Py wouldn't be able to tell those two label blocks apart. Label names cannot have spaces in, so it's common to use underscores to separate words in a label name:
label not valid: # The preceeding label won't work, because it has spaces in the name. label perfectly_valid: # The label 'perfectly_valid', on the other hand, is fine.
When Ren'Py reaches the end of a label block - for example the line "As is this one." in the above example - it simply continues on to the following label block, so in the example above the four lines are delivered in the order they're written, one after another, as if the label statements weren't there at all. Using the jump and call commands, however, we can move between labels in a non-linear fashion.
The jump command instructs Ren'Py to skip immediately to the label which is given, ignoring all of the script in between the present position and that label. Jumps can be forward or backward through the file, or even in a different script file in the same game directory.
The jump command consists of the word 'jump' followed by the name of the label to jump to:
jump some_label
Because the label could be anywhere, the jump command allows us to write scripts in a non-linear order, for example:
label start: "This line of dialogue will be spoken first." jump stage_two label stage_three: "This line will be spoken third." jump end "This line will never be run." label stage_two: "This line will be spoken second." jump stage_three label end: "And this line will be last."
Ren'Py cannot execute the line in the middle ("This line will never be run") because it's impossible to step line-after-line from a label to that dialogue line. The 'jump end' command will get in the way and re-direct Ren'Py to the 'end' label before it ever gets to that line of dialogue.
Call instructs Ren'Py to go off and run the code at another label, and then return and carry on from this point afterwards.
The call command consists of the word 'call', followed by the name of the label to call:
call subroutine
At the other end, the command 'return' tells Ren'Py to go back to the point of the call:
label subroutine: "Do some stuff." return
This means that if there is a part of your script which you want to re-use at multiple points, then you can use call to visit that part from anywhere else in your script and return to those different places without having to know each of their label names.
label start: "The teacher starts droning on about Hamlet..." call boring "I think I missed something. Now she's talking about Rozencrantz and... someone..." "Tom Stoppard? Was he in Hamlet?" call boring jump end label boring: "I can't keep my eyes open... so dull..." "Ah! Did I fall asleep?" return label end: "Huh. The lesson seems to be over. That was quick!"
This will produce the following dialogue:
Note that the bold lines above are those included in the 'boring' label which call skips to, after which it returns to the point in the script it was called from.
Sample code
menu: "yes": "yes" jump yes "no": "no" jump no label yes: "I agree." label no: "I don't agree."
The yes and no are your options; you can add as many as you like.
The : after each option lets you tell Ren'py what happens next like going to another page of sript or adding text