Ren'Py 101: Starting Out Part I
by Rio

Ren'Py is a wonderful way to make a ren'ai game for those who have little to no programming skills. For those of you who are intimidated or are clueless as where to begin, I'll be covering everything you need to know to make and put together your own basic ren'ai game from start to finish. This is a six part series of tutorials that will cover all the basics. After you're done reading through these tutorials, you can make a multiple path-based game or a points-based game.

With a little ingenuity and creativity, these two basic types will be all you need to know. Above all else, keep up to date with the ren'ai games coming out - they are your best sources of inspiration.

Here is an overview of the topics I will covering in this tutorial:

1. What's What: Folders and Files

2. Running the Game and Editing the Script File

3. The Init Block

4. Changing the Menu Buttons, Save Slots, and the Preferences Menu

5. Setting Colors

1. What's What: Folders and Files

I assume that you have Ren'Py already downloaded and extracted into your computer. If you haven't already, go and download the latest version. Out of everything listed, the ones you will actually touch are:

game folder - being the main folder where everything goes (audio, backgrounds, character images), you'll be in here a lot.
run_game(.exe, .py, or .pyw) - you have to run this if you want to debug/play your game.
traceback.txt - this file will pop up when an error occurs, usually as you program and debug.

If you're curious what everything else does, here's a full list of what's what once you open the Ren'Py folder. Note: these are the files available in version 4.7.2. There may be changes in future versions.

common folder - contains files that changes menus styles, buttons, preferences, and fonts.
doc folder - reference manual for Ren'Py.
extras folder - special features such as readback, kana-mode, and more. Open and follow instructions to implement.
game folder - main folder where all images, script, music, and save files should be.
lib folder - do not touch unless you know what you're doing.
renpy folder - also don't touch unless you know what you're doing.

add_from.exe - adds from clauses to all bare call statements found in the program. For Windows users. - adds from clauses to all bare call statements found in the program. For Unix/Linux users.
archive_images.bat - automatically archives your images. Is used when running archiver.exe.
archiver.exe - Obfuscates your images (i.e. scrambles images so players won't see pics unless playing the game).

CHANGELOG.txt - the changes that have been made in the various Ren'Py updates .
console.exe - a windows executable that opens a windows console.
dump_text.exe - dumps all the text from a script. Useful for spell-checking a script. For Windows users. - dumps all the text from a script. Useful for spell-checking a script. For Unix/Linus users.
LICENSE.txt - licensing information concerning Ren'Py.
python23.dll - python interpreter for Windows.

renpy-mode.el - imenu support, so (X)Emacs users can use the speedbar to jump around in a script.
run_game.exe - for Windows users to run the game. - for Unix/Linux users to run the game.
run_game.pyw - for Mac users to run the game.

Back to Dev Corner | Back to Top

2. Running the Game and Editing the Script File

Now that you know what's what, play the demo game! For Windows users, double click on the run_game.exe file. For Unix/Linux users, use the command "python". For Mac users, run_game.pyw. If you encounter problems running the game, make sure you can run python and pygame. Mac users, download the supporting files listed under Step 1 in this page.

When you reach the part where Eileen suggests you open the script file, go into the game folder and open script.rpy. If a "Choose Program..." or "Open With..." window pops-up, I highly recommend you use SciTE text editor which features syntax highlighting, automatic indentation, and code folding. If you'd rather not, you can use Notepad or WordPad (particularly for Windows users).

On a side note, if you want to see the MPEG-1 feature on Ren'Py, you may download the Eisenhower.mpg file from here. Place it in the game folder and re-run the demo. You will now automatically be able to view this feature in action.

Now that you know how to run and open the script file, I suggest you take a look over the script file and read downwards. PyTom explains what certain sections of the coding is for with comments tags that start with the pound symbol (#). Try to see anything you may recognise and figure out on your own such as,

$ config.screen_width = 800
$ config.screen_height = 600
$ config.window_title = "The Ren'Py Demo Game"

which is what controls the screen size of your game and the title on the window, respectively. The one thing about coding (especially good coding) it that all names and comment tags usually have an indication of what sections does so that when the original programmer hands over their work to another - that new person may readily pick it up.

To edit the script file, just work like you would on a word editing software. For those using WordPad - you must not use any of the formatting tools (i.e. paragraph, bullets, etc)! Some things to consider when writing your script:

1. All lines must be in indents of four. The only time you do not indent is if it's a comment tag which can start anywhere you want it to or if you're starting a new label block. Ren'Py is rather picky about this especially in WordPad*, so I suggest you just get used to it. For clarification, a block is a group of lines that comes after a word (or several) and a colon such as "label beginning:" and "menu:" Example:

# This starts at the beginning of the game

label start:

    # Put save_name file here later. Don't forget!!!

    "Unnhhhhh- what happened?"
    "Looking around, I find myself alone in a run-down shed."


        "What should I do?"

        "Search the shed.":
            "I searched the shed and found nothing..."

        "Go outside.":
            "Slowly, I opened the door of the shed and peeked outside..."

*Some other editors such as SciTE are more lenient on some things such as allowing lines in label blocks to start at 0 indent but still adheres to the four-indent rule when it comes to other blocks like menu blocks. I highly suggest you get used to indenting for every block. For one, it's much easier to read your lines this way and for another, it's better to be consistent (i.e. you may forget to indent for other blocks).

2. Make sure you always have at least ONE blank line at the end of your script. This is necessary or else Ren'Py will throw out a traceback error at you.

3. Check your spelling, quotes, colons, and other signs. If the error is not caused by one of the above, then it is most likely spelling errors or the lack of or too many of the following signs. Errors will occur even from simplest typos such as typing "wtih" (wrong) instead of "with" (correct) or "labal" (wrong) instead of "label"(correct), etc.

Note: If you try to enter a quote within a quote, Ren'Py will spit out an error. The only ways Ren'Py will accept a double quote within a double quote is if you put two single quotes together or you do a character escape which is putting a \ in front of the ". For example,

"Bob" "What's with "it", anyways?" <--- Wrong (Ren'Py will think sentence stopped
                                   before the "i" of "it".)

"Bob" "What's with ' 'it' ', anyways?" <--- Correct (without the spaces in
                                       between single quotes)

"Bob" "What's with \"it\", anyways?" <--- Correct

Another way, is if you settle for just a single quote such as, "Bob" "What's with 'it', anyways?". You can also reverse the quotes and use single quotes on the outside and double quotes on the inside but if you have to use a single quote in the sentence, Ren'Py will count that as an error unless it's character escaped (i.e. \') or the word is spelled out. For example,

"Bob" 'What's with "it", anyways?' <--- Wrong (Ren'Py will think the sentence
                                       stopped right after "What".)

"Bob" 'What\'s with "it", anyways?' <--- Correct
"Bob" 'What is with "it", anyways?' <--- Correct

Another important fact: if you want to use a % in the text of your game, you have to double it to "%%". You cannot character escape it (i.e. \%) like with the quotes. An error will occur otherwise.

Some of the easier things that you don't have to worry too much about if an error occurs is if a music file is not present (Ren'Py will just not play it), and if an image such as a character or background is not in the folder or isn't declared (Ren'Py will just point it out on the screen). Of course, if you didn't correctly declare the images, Ren'Py will call you up on it.

Back to Dev Corner | Back to Top

3. The Init Block

The init block is called before the game starts. It sets up everything in the game such as the size of the window, interface sounds effects, position of buttons, how buttons look, and where important files are such as character images and backgrounds used within the game. For setting character images, backgrounds, character animations, and so forth, it will be covered in the next tutorial: Starting Out Part II.

The first things you have to determine is the screen size of your game, the window title, the main menu (where the player first enters) and game menu (for save/load/ and preferences) images, plus the all important dialogue box or "frame" as it is called in the coding.

# Set up the size of the screen, and the window title.
$ config.screen_width = 800
$ config.screen_height = 600
$ config.window_title = "The Ren'Py Demo Game"

# Change some styles, to add images in the background of
# the menus and windows.
$ style.mm_root_window.background = Image("mainmenu.jpg")
$ style.gm_root_window.background = Image("gamemenu.jpg")
$ style.window.background = Frame("frame.png", 125, 25)

To change the screen size, enter the relevant width and height after config.screen_width and config.screen_height. The usual screen sizes are 640x480, 800x600, and 1024x768 with 800x600 being the most used in ren'ai games. Change the window title to the title of your game. For everything that is in quotes (usually letters), make sure it stays in quotes.

For the menus and frames, all you really need to do is replace the image with new ones so you don't have to change the coding. But if you want to rename it differently, it is up to you. As we're talking about images, the types you will most likely and should only be using are .jpg, .png., and .gif. Any others are too big to be put into a game.

If you'd rather not use an image for your frame, you can set a solid color such as Solid((0, 0, 0, 255)) instead of Frame("frame.png", 125, 25). For more about color, jump to 5: Setting Colors. If don't want any image or color whatsoever, you can set it to "None" like so: $ style.window.background = None

Note: Depending on the computer (or OS, more specifically), it may be case sensitive to file names so make sure everything declared is as it appears on the file name. For example, if you declare "mainmenu.jpg" - make sure that file is named "mainmenu.jpg" and not "MainMenu.JPG" or you run the possiblity of the game not working for others.

Back to Dev Corner | Back to Top

4. Changing Menu Buttons, Save Slots, and the Preferences Menu

Changing the menu buttons are completely optional but it allows you to add that extra bit of customization and uniqueness to your game rather than using the defualt colors of Ren'Py. The following are only a few of the styles you may change. They are the settings used for Garden Society: Kykuit. I suggest you donwload the game if you would like visuals along with the instructions.

# Change some styles, to add images in the background of
# the menus and windows.
$ style.mm_root_window.background = Image("mainmenu.jpg")
$ style.gm_root_window.background = Image("gamemenu.jpg")
$ style.window.background = Frame("frame.png", 125, 25)
$ style.mm_menu_window.ypos = 0.825 # main menu buttons, centered, and below...
$ style.mm_menu_window.xpos = 0.615 # the GSK title

$ style.file_picker_entry.idle_background = Solid((0, 0, 0, 255)) #black
$ style.file_picker_entry.hover_background = Solid((255, 255, 255, 255)) #white
$ style.file_picker_text.idle_color = (255, 255, 255, 255) #white
$ style.file_picker_text.hover_color = (0, 0, 0, 255) #black
$ style.button_text.color = (255, 255, 255, 255) #white
$ style.button_text.hover_color = (051, 051, 204, 255) # navy blue

$ style.prefs_label.color = (0, 0, 0, 255) # black
$ style.yesno_label.color = (0, 0, 0, 255) # black

mm_menu_window(.ypos, .xpos):
These two edit the position of the buttons in the main menu of the game. Instead of the buttons at the lower, right-hand corner, it is now directly under the title. This setting was made specifically for Garden Society. You should experiment with the numbers to find something that suits your main menu. More specifically, .ypos refers to the position of the menu buttons on the y-axis (i.e. vertical) while the .xpos refers to the x-axis or horizontal line.

More in depth, fellow developer Chronoluminaire explains that the xpos and ypos are "a proportion of the distance across the screen, with 0.0 = top or left and 1.0 = bottom or right. ...(There is also a) difference between 1.0 (float = proportion = far right-hand side) and 1 (integer = absolute = 1 pixel from the left-hand side)... A number of artists may prefer to work entirely in absolute coordinates, ... (and that's) how that's done."

file_picker_entry(.idle_background, .hover_background):
This is for backgrounds of the save files. When the user is there to save or load a save file, these two are in effect in conjuction with the file_picker_text settings.

For example, when in the save or load mode, the backgrounds of the save files will be in black (with text in white) because it is idle. When the player goes and hovers over the save files, though, the hover mode is activated, and the background turns into white (with the text also changing into black).

file_picker_text(.idle_color, .hover_color):
This controls the colors of the text inside the save file boxes. When no mouse is over the save file, the text is white on a black background (as dictated by file_picker_entry.idle_background). When there is a mouse over the save slot, the text turns to black and the background changes into black.

button_text(.color, .hover_color):
.color refers to the color of the menu buttons when the mouse is not over it. .hover_color refers to when the mouse is over the button. In the case of above, the color of the menu is normally white until it is hovered over and turns into a navy blue color.

prefs_label.color and yesno_label.color:
Prefs_label controls the color of the sections in the Preferences Menu. For example, the labels (Display, Music, Sound Effects, Tab and CTRL Skip, Transitions) will be in black as dictated in the above coding. Yesno_label, on the other hand, determines the color of the Quit question "Are you sure you want to end the game?".

For a full list of all the styles you can edit, I suggest you open up the style.rpy file in the common folder. Do NOT directly change the settings of the files in the common folder! Should Ren'Py upgrade and the coding should change, you will find yourself doing a lot of backtracking to "fix" your game. Instead, enter the new style under the Init block of your script file.

Here's some other interesting game design topics at Lemmasoft Forum:

On the Topic of Menus... - repositioning the save slots and the menu list. Scroll down to the post by mikey.

Font/Text Questions - releasing a Ren'Py game in another language, using multiple fonts, creating deafult odd window, and taking out the drop shadow on the menu choices.

Back to Dev Corner | Back to Top

5. Setting Colors

Now that you have some familiarity with reading through the styles by yourself, let's take a closer look into setting the color. Setting the color of something will always require four sets of three-digit numbers. The first three numbers indicate the RGB (Red, Green, and Blue) values while the fourth number refers to Opacity or Transparency. The fourth number is always a 255, meaning, it's at maximum and is Solid. The lower this number, the more opaque the color becomes.

$ style.file_picker_entry.idle_background = Solid((0, 0, 0, 255)) #black
$ style.file_picker_entry.hover_background = Solid((255, 255, 255, 255)) #white
$ style.button_text.color = (255, 255, 255, 255) #white
$ style.button_text.hover_color = (051, 051, 204, 255) # navy blue

The first three numbers are what you have to worry about and change. Just by looking at the first three numbers, you can guess what color is dominant. For example, these are the "true" colors of red, green, and blue, respectively.

(255, 0, 0, 255) Red
(0, 255, 0, 255) Green
(0, 0, 255, 255) Blue

The closer the number is to 255, the more of that particular color is shown with 255 being all of that color and 0 being none of that color. When mixing colors, the closer each color is to 255 each, the more light the color becomes. For the color white, for example, all the numbers (or RGB) must be set to 255 each (example: 255, 255, 255, 255). For darker colors, the more each number is to 0, the darker it becomes. For true black, each color must be set to zero such as (0, 0, 0, 255).

For an easy to use color palette, feel free to use the Hue Color Chart below. It can also be found in the Development Corner page.

Hue Color Chart Hue Color Chart (245KB)
Use as a reference for changing text colors, dialogue boxes, screen colors, and more. Each color box includes hexadecimal code and individual RGB numbers. Example: Periwinkle is Hexadecimal #CCCCFF, and RGB (204, 204, 255) respectively.

Back to Dev Corner | Go to Starting Out Part II >>


Content© 2005 &, unless otherwise specified. All rights reserved.