Translations by Hanming Wu

Quickstart

Welcome to the Ren'Py quickstart manual. The purpose of this manual is to demonstrate how you can make a Ren'Py game from scratch, in a few easy steps. We'll do this by showing how to make a simple game, *The Question*, from scratch. This manual contains a number of examples, which are included as part of the demo game.

The Ren'Py Launcher

Before you begin making a game, you should first take some time to learn 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 to `download Ren'Py <http://www.renpy.org/wiki/renpy/Download_Ren'Py>`_.

Once you've downloaded Ren'Py, you'll want to extract it. This can generally be done by right-clicking on the package file, and picking "Extract" if that's an option, or "Open" if it's not. Follow the prompts, and you'll have a working copy of Ren'Py.

Please be sure you've extracted Ren'Py to its own directory or folder on disk. If you try to run it from inside a ZIP file, it won't work properly.

Once you've extracted Ren'Py, you'll need to run it.

On Windows, run the ``renpy`` or ``renpy.exe`` program.

On Mac OS X, run the ``renpy`` application.

On Linux, run the ``renpy.sh`` script.

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

**Choosing and Launching a Project.** You should first see what the completed *The Question* game looks like. To do this, start the Ren'Py launcher, 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, but choosing "Tutorial" instead of "The Question".

A Simple Game

This is perhaps one of the simplest Ren'Py games. It doesn't include any pictures or anything like that, but it does show a conversation between the two characters.

You're now ready to run this example. Go back to the launcher, and choose "Launch Project". Ren'Py will start up. Notice how, without any extra work, Ren'Py has given you menus that let you load and save the game, 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 label statement 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's where Ren'Py scripts begin running when the user clicks "Start Game" on the main menu.

The other lines are say statements. There are two forms 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 by itself, which is used for narration, and the thoughts of the main character. The second form consists of two strings. It's used for dialogue, with the first string being a character name and the second being what that character is saying.

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

When strings contain double-quote characters, those characters need to be preceded by a backslash. This is done in the last line of our example.

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

Init

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.

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.

Characters

One problem with the first example is that it requires you to repeatedly type the name of a character each time they speak. In a dialogue-heavy game, this might be a lot of typing. Also, both character names are displayed in the same way, in fairly boring white text. To fix this, Ren'Py lets you define characters in advance. This lets you associate a short name with a character, and to change the color of the character's name.

The first and and second lines define characters. The first line defines a character with the short name of "s", the long name "Sylvie", with a name that is shown in a greenish color. (The colors are 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 be defined by copying one of the character lines, and changing the short name, long name, and color.

We've also changed the say statements to use character objects instead of a character name string. This tells Ren'Py to use the characters we defined in the init block.

Images

A visual novel isn't much of a visual novel without pictures. Let's add some pictures to our game.

The first new thing we needed to do was to declare the images, using image statements on lines 2, 3, 5, and 6, inside the init block. These image statements give an image name, and the filename the image is found in.

For example, line 5 declares an image named "sylvie smile", found in the filename "sylvie_smile.png", with the tag "sylvie".

We have a scene statement on line 12. This statement clears out the screen, and shows the "bg meadow" image. The next line is a show statement, which shows the "sylvie smile" image on the screen.

The first part of an image name is the image tag. If an image is being shown, and another image with the same tag is on the screen, then the image that's on the screen is replaced with the one being shown. This happens on line 19, the second show statement. Before line 19 is run, the image "sylvie smile" is on the screen. When line 19 is run, that image is replaces with "sylvie surprised", since they share the "sylvie" tag.

For Ren'Py to find the image files, they need to be placed in the game directory of the current project. The game directory can be found at "`Project-Name`/game/", or by clicking the "Game Directory" button in the launcher. You'll probably want to copy the image files from the "the_question/game/" directory into the "my_question/game/" directory, so you can run this example.

Ren'Py does not make any distinction between character and background art, as they're both treated as images. In general, character art needs to be transparent, which means it should be a PNG file. Background art can be JPEG or PNG files. By convention, background images start with the "bg" tag.

**Hide Statement.** Ren'Py also supports a hide statement, which hides the given image.

It's actually pretty rare that you'll need to use hide. Show can be used when a character is changing emotions, while scene is used when everyone leaves. You only need to use hide when a character leaves and the scene stays the same.

Transitions

Simply having pictures pop in and out is boring, so Ren'Py implements transitions that can make changes to the screen more interesting. Transitions change the screen from what it looked like at the end of the last interaction (dialogue, menu, or transition), to what it looks like after any scene, show, and hide statements.

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

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

Both the "bg meadow" and "sylvie smiles" would be dissolved in at the same time. To dissolve them in one at a time, you need to write two with statements::