Quickstart — Ren'Py Documentation (2024)

Welcome to the Ren'Py quickstart manual. The purpose of this manual isto demonstrate how you can make a Ren'Py game from scratch in a feweasy steps. We'll do this by showing how to make a simple game,The Question.

The Ren'Py Launcher link

Before you begin making a game, you should first take some time tolearn how the Ren'Py launcher works. The launcher lets you create,manage, edit, and run Ren'Py projects.

Getting Started. To get started you'll want todownload Ren'Py.

Once you've downloaded Ren'Py, you'll want to extract and run it.

On Windows, double click on the executable file you download. It willextract Ren'Py into a folder named renpy-<version>. You can changeinto that folder and run renpy.exe. (It may be presentedas renpy if extensions are hidden.)
On Mac OS X, double-click on the downloaded drive image to mount it as adrive. When the drive opens, copy the folder named renpy-<version>somewhere else. (Where does not matter, but it has to be moved out ofthe read-only drive image. Do not move the renpy app out of the folder it's in– it won't work elsewhere.) Then change into it, and run the renpyapplication.
On Linux, unpack the tarball, change into the renpy-<version>directory, and then run renpy.sh.

After running this, the Ren'Py launcher should run.

The Ren'Py launcher has been translated to multiple languages. Tochange the language, choose "preferences" at the bottom right, and thenselect the language.

Choosing and Launching a Project. You should first see what thecompleted The Question game looks like. To do this, start the Ren'Pylauncher, and choose "The Question" from the first screen. Choose"Launch Project" to start The Question.

You can get back to the Ren'Py demo by doing the same thing, butchoosing "Tutorial" instead of "The Question".

Creating a new Project.Create a new project by choosing "Create New Project" from thelauncher.

If this is your first time creating a project, Ren'Py may ask you toselect the projects directory. This is a directory (also called a folder)where new projects are created, and is scanned for existing projects. Thedirectory chooser might pop up below Ren'Py, so be sure to look for itthere.

The launcher will then ask you for a project name. Since"The Question" is already taken, you should enter something different,like "My Question", and type enter.

After that, the launcher will ask you to select the project resolution.1280x720 is a good compromise between game size and image quality.For the purpose of this tutorial, we will select 1280x720 to match"The Question" game art, then click "Continue".

The launcher will then ask you to choose a color scheme – an accent andbackground color for the new GUI. It doesn't matter what you pick atthis point, so just pick something you find appealing, and then click"Continue".

At this point, Ren'Py will process for a bit, and spit out a simple gametemplate. The template used placeholder art and text, but is runnable, andsupports expected features like rollback, loading, and saving. Choose"Launch Project" to run it.

A Simple Game link

label start: "Sylvie" "Hi there! How was class?" "Me" "Good..." "I can't bring myself to admit that it all went in one ear and out the other." "Me" "Are you going home now? Wanna walk back with me?" "Sylvie" "Sure!"

This is a very simple Ren'Py game. It doesn't include any pictures ormusic, but it does show a conversation between two characters, and aline of narration.

To try this out, from the top screen of the launcher select "My Question"project, and then choose "script.rpy" from under Edit File. If this isyour first time, Ren'Py will ask you to select an editor (we recommendEditra for first time creators), and will download the editor you choose.Then it will open the script file in the editor.

Once the editor opens, erase everything in script.rpy. We're startingfrom scratch, so you don't need what's there. Copy the example above intoscript.rpy, and save it.

You're now ready to run this example. Go back to the launcher, andchoose "Launch Project". Ren'Py will start up. Notice how, without anyextra work, Ren'Py has given you menus that let you load and save thegame, and change various preferences. When ready, click "Launch Project",and play through this example game.

This example shows some of the commonly-used Ren'Py statements.

The first line is a label statement. The labelstatement is used to give a name to a place in the program. In this case,we create a label named start. The start label is special, as it'swhere Ren'Py scripts begin running when the user clicks "Start Game" onthe main menu.

The other lines are say statements. There are twoforms of the say statement. The first is a string (beginning with a double-quote,containing characters, and ending with a double-quote) on a line byitself, which is used for narration, and the thoughts of the maincharacter. The second form consists of two strings. It's used fordialogue, with the first string being a character name and the secondbeing what that character is saying.

Note that all the say statements are indented by four spaces. This isbecause they are a block underneath the label statement. In Ren'Py,blocks must be indented relative to the prior statement, and all ofthe statements in a block must be indented by the same amount.

When strings contain double-quote characters, those characters need tobe preceded by a backslash. For example

 "Sylvie" "Did you ever hear Lincon's famous saying, \"The problem with Internet quotations is that many of them are not genuine.\""

While this simple game isn't much to look at, it's an example of howeasy it is to get something working in Ren'Py. We'll add the picturesin a little bit, but first, let's see how to define characters.

Characters link

Main article: Defining Character Objects

One problem with the first example is that it requires you torepeatedly type the name of a character each time they speak. In adialogue-heavy game, this might be a lot of typing. Also, bothcharacter names are displayed in the same way, in the accent colorselected when starting the game. To fix this, Ren'Py lets you definecharacters in advance. This lets you associate a short name with acharacter, and to change the color of the character's name.

define s = Character('Sylvie', color="#c8ffc8")define m = Character('Me', color="#c8c8ff")label start: s "Hi there! How was class?" m "Good..." "I can't bring myself to admit that it all went in one ear and out the other." s "Are you going home now? Wanna walk back with me?" m "Sure!"

The first and and second lines define characters. The first linedefines a character with the short name of "s", the long name"Sylvie", with a name that is shown in a greenish color. (The colorsare red-green-blue hex triples, as used in web pages.)

The second line creates a character with a short name "m", a long name"Me", with the name shown in a reddish color. Other characters can bedefined by copying one of the character lines, and changing the shortname, long name, and color.

We've also changed the say statements to use character objects insteadof a character name string. This tells Ren'Py to use the characterswe defined.

Images link

Main article: Displaying Images

Transitions link

Main article: Transitions

In the script above, pictures pop in and out instantaneously. Sincechanging location or having a character enter or leave a scene isimportant, Ren'Py supports transitions that allow effects to beapplied when what is being shown changes.

Transitions change what is displayed from what it was at the end ofthe last interaction (dialogue, menu, or transition – among otherstatements) to what it looks like after scene, show, and hide statementshave run.

label start: scene bg meadow with fade "After a short while, we reach the meadows just outside the neighborhood where we both live." "It's a scenic view I've grown used to. Autumn is especially beautiful here." "When we were children, we played in these meadows a lot, so they're full of memories." m "Hey... Umm..." show sylvie green smile with dissolve "She turns to me and smiles. She looks so welcoming that I feel my nervousness melt away." "I'll ask her...!" m "Ummm... Will you..." m "Will you be my artist for a visual novel?"

The with statement takes the name of a transition to use. The mostcommon one is dissolve which dissolves from one screen to thenext. Another useful transition is fade which fades thescreen to black, and then fades in the new screen.

When a transition is placed after multiple scene, show, or hidestatements, it applies to them all at once. If you were to write:

 scene bg meadow show sylvie green smile with dissolve

Both the "bg meadow" and "sylvie green smile" images would be dissolved inat the same time. To dissolve them in one at a time, you need to write twowith statements:

 scene bg meadow with dissolve show sylvie green smile with dissolve

This first dissolves in the meadow, and then dissolves in sylvie. Ifyou wanted to instantly show the meadow, and then show sylvie, youcould write:

 scene bg meadow with None show sylvie smile with dissolve

Here, None is used to indicate a special transition that updatesRen'Py's idea of what the prior screen was, without actually showinganything to the player.

Positions link

Main article: Transforms

By default, images are shown centered horizontally, and with theirbottom edge touching the bottom of the screen. This is usually okayfor backgrounds and single characters, but when showing more than onecharacter on the screen it probably makes sense to do it at anotherposition. It also might make sense to reposition a character for storypurposes.

 show sylvie green smile at right

To do this repositioning, add an at clause to a show statement. The atclause takes a position, and shows the image at that position. Ren'Pyincludes several predefined positions: left for the left side ofthe screen, right for the right side, center for centeredhorizontally (the default), and truecenter for centeredhorizontally and vertically.

Creators can define their own positions, and event complicated moves,but that's outside of the scope of this quickstart.

Music and Sound link

Main article: Audio

Most Ren'Py games play music in the background. Music is played with theplay music statement. The play music statement takes a filename thatis interpreted as an audio file to play. Audio filenames are interpretedrelative to the game directory. Audio files should be in opus, ogg vorbis,or mp3 format.

For example:

 play music "audio/illurock.ogg"

When changing music, one can supply a fadeout and a fadein clause, whichare used to fade out the old music and fade in the new music.

 play music "audio/illurock.ogg" fadeout 1.0 fadein 1.0

The queue music statement plays an audio file after the current filefinishes playing.

 queue music "audio/next_track.opus"

Music can be stopped with the stop music statement, which can alsooptionally take a fadeout clause.

 stop music

Sound effects can be played with the play sound statement. Unlike music, soundeffects do not loop.

 play sound "audio/effect.ogg"

When a filename is in the game/audio directory, and the name without thefile extension can be used as a Python variable (that is, it begins witha letter, and contains only letters, numbers, and underscores), it is possibleto play that file without using quotes.

For example, if game/audio/illurock.ogg exists, we can write:

 play music illurock

See the audio namespace for more details.

Pause Statement link

The pause statement causes Ren'Py to pause until the mouse is clicked.

 pause

If a number is given, the pause will end when that number of secondshave elapsed.

 pause 3.0

Ending the Game link

You can end the game by running the return statement, without havingcalled anything. Before doing this, it's best to put something in thegame that indicates that the game is ending, and perhaps giving theuser an ending number or ending name.

 ".:. Good Ending." return

That's all you need to make a kinetic novel, a game without anychoices in it. Now, we'll look at what it takes to make a game thatpresents menus to the user.

Menus, Labels, and Jumps link

Main articles: In-Game Menus and

The menu statement lets presents a choice to the player:

 s "Sure, but what's a \"visual novel?\""menu: "It's a videogame.": jump game "It's an interactive book.": jump booklabel game: m "It's a kind of videogame you can play on your computer or a console." jump marrylabel book: m "It's like an interactive book that you can read on a computer or a console." jump marrylabel marry: "And so, we become a visual novel creating duo."

This example shows how a menu can be used with Ren'Py. The menu statementintroduces an in-game choice. It takes an indented block of lines, eachconsisting of a string followed by a colon. These are the menu choices that arepresented to the player. Each menu choice takes its own indented block of lines,which is run when that menu choices is chosen.

In this example, each of the two menu choices runs a single jump statement.The jump statement transfers control to the a label defined using the labelstatement. After a jump, script statements following the label are run.

In the example above, after Sylvie asks her question, the player is presentedwith a menu containing two choices. If the player picked "It's a videogame.",the first jump statement is run, and Ren'Py will jump to the game label.This will cause the POV character to say "It's a story with pictures and music.",after which Ren'Py will jump to the marry label.

If there is no jump statement at the end of the block associated with the label,Ren'Py will continue on to the next statement. The last jump statement here istechnically unnecessary, but is included since it makes the flow of the gameclearer.

Labels may be defined in any file that is in the game directory, and ends with.rpy. The filename doesn't matter to Ren'Py, only the labels contained insideit. You can think of all the .rpy files as being equivalent to a single big.rpy file, with jumps used to transfer control. This gives you flexibilityin how you organize the script of a larger game.

Supporting Flags using the Default, Python and If Statements link

Main articles: Python Statements and Conditional Statements

While some games can be made by only using the statements given above,other games require data to be stored and recalled later. For example,it might make sense for a game to remember a choice a player has made,return to a common section of the script, and act on the choice later. Thisis one of the reasons why Ren'Py has embedded Python support.

Here, we'll show how to store a flag containing information about a choicethe player has made. To initialize the flag, use the default statement, beforelabel start.

# True if the player has decided to compare a VN to a book.default book = Falselabel start: s "Hi there! How was class?"

The book flag starts off initialized to the special value False(as with the rest of Ren'Py, capitalization matters), meaning thatit is not set. If the book path is chosen, we can set it to Trueusing a Python assignment statement.

label book: $ book = True m "It's like an interactive book that you can read on a computer or a console." jump marry

Lines beginning with a dollar-sign are interpreted as Python statements. Theassignment statement here assigns a value to a variable. Ren'Py has supportfor other ways of including Python, such as a multi-line Python statement,that are discussed in other sections of this manual. Ren'Py supports Python 2.7,though we strongly recommend you write Python that runs in Python 2 and Python 3.

To check the flag, use the if statement:

if book: "Our first game is based on one of Sylvie's ideas, but afterwards I get to come up with stories of my own, too."

If the condition is true, the block of script is run. If not, it is skipped.The if statement can also take an else clause, that introduced a block ofscript that is run if the condition is false.

if book: "Our first game is based on one of Sylvie's ideas, but afterwards I get to come up with stories of my own, too."else: "Sylvie helped with the script on our first video game."

Python variables need not be simple True/False values. Variables can beused to store the player's name, a points score, or for any otherpurpose. Since Ren'Py includes the ability to use the full Pythonprogramming language, many things are possible.

Releasing Your Game link

Once you've made a game, there are a number of things you should dobefore releasing it:

Check for a new version of Ren'Py.

New versions of Ren'Py are released on a regular basis to fix bugsand add new features. Before releasing, you'll want to click updatein the launcher to update Ren'Py to the latest version. You can also download newversions and view a list of changes at https://www.renpy.org/latest.html.

Rarely, changes to Ren'Py will require you to make a change to your game'sscript. Incompatible Changes hasa list of these changes.

Check the Script.

From the front page of the launcher, choose "Check Script(Lint)". This will check your games for potential errors. Since some ofthese errors will only affect users on other platforms, it's importantto understand and usually fix all errors, even if you don't see the problemon your computer.

Build Distributions.

From the front page of the launcher, choose "Build Distributions". Basedon the information contained in options.rpy, the launcher will build oneor more archive files containing your game.

Test.

Lint is not a substitute for thorough testing. It's yourresponsibility to check your game before it is released. Consider askingfriends to help beta-test your game, as often a tester can find problemsyou can't.

Release.

Once the game has been finished and tested, you should post the generatedarchive files on the web somewhere people can see them. (If you don'thave your own website, https://itch.io hosts a lotof visual novels.) Congratulations, you've released your first visual novel!

There are a few places where a game can be announced:

The Ren'Py Games List helps us keep track ofRen'Py games being made.
The Completed Games section of the Lemma Soft Forums is agood place to tell fellow creators about your game.

More advanced vays of customizing the building of the distribution of your gamecan be found in the Building Distributions section.

Script of The Question link

You can view the full script of ''The Question'' here.

Where do we go from here? link

This Quickstart barely scratches the surface of what Ren'Py is capable of.For brevity's sake, we've omitted many features Ren'Py supports andsimplified others – focusing on the minimum set of features used to make avisual novel.

To get a feel for what Ren'Py is capable of, please play through the Tutorial,and perhaps some of the games featured on the Ren'Py website.You may also want to read the rest of this manual, starting with the GUI CustomizationGuide.

Beyond that, we recommend checking out the Ren'Py section of the Lemma Soft Forums, whichhas a section for asking questions, and a cookbook section with libraries and examples meant for reuse. The Lemma Soft Forums are thecentral hub of the Ren'Py community, where we welcome new creators and the questions they bring.

Thank you for choosing the Ren'Py visual novel engine. We look forward to seeingwhat you create with it!