Ren'ai Games

Ren'Py 101: Writing Your Script Part I

by Rio

The third part of a six-part series, we are now going to cover the actual writing of your script. If you haven't read through it already, please read over Part I and Part II of the tutorials - you'll understand things better as I don't like to repeat myself. Here are the topics I will covering in this tutorial:

1. Label Blocks

2. Save Name Titles

3. Menus

4. Jumps and Passes

1. Label Blocks

Blocks are much like the hierarch found in a branch of a family tree. The first blocks (line 1 and line 2) can be seen as siblings. They are in the same family and hence in the same block. Each indented grouping beneath the first block forms their own blocks much like children and grandchildren would form their own block based on generation.

In our example, line 1 and line 2 forms one block. They both have, as I call it, a "sub-block". Line a and line b is one with line 1 while line c and line d is a sub-block of line 2. Any sub-block becomes associated to the one before it. In other words, line a and line b, is associated with line 1.

line 1 <--- label, init, or python block
    line a <--- dialogue lines, python statements (ex/ $ renpy.music_start
            ('fade.mid') ),
    line b <--- scenes, shows, menus, and jumps and passes, to name a few
line 2 <--- label, init, or python block
    line c <--- menu block
        line i <--- dialogue, menu options, python statements
               (ex/ $ date = True),
        line ii <--- scenes, shows, jumps and passes, among other things
    line d <--- dialogue lines, python statements, etc.

Now that we have the concept of blocks down, the block you mainly have to concern yourself with is the "label" block, the "menu" block, and those lines associated with them (i.e. sub-blocks). Okay, technically, there's also the "init" block at the beginning of the script file but that's already there and you don't need to make more unless you're going for something more advanced. This includes python blocks.

Anyways, label blocks start at the zero level, meaning they have no spaces before them. The label is followed by a name and then a colon. Any successive line will now need to be indented by four spaces.

label hello: <--- Starts at 0 level and successive lines are indented at four spaces

    $ save_name = "Helloooo Hottie!"

    scene path_to_school
    show ojimaru normal
    "My name is Ojimaru. I consider myself to be a run-of-mill type of guy, "
    "okay looks, middling grades, average height,"
    "until one day-"
    "Female Voice" "Helllllooooo hottie!"
    "Dismissing the remark as going to one of the other guys walking to school
    next me,"
    "I kept going, when out of nowhere -"

One label block ends when another block follows it which is usually another label block. Aside from scene, show, and dialogue lines which I covered in the previous tutorial, let's move on to the others you can put under the label block.

Back to Dev Corner | Back to Top

2. Save Name Titles

The save_name python statement is one of the in-game features you may want to use. When not used, save files will just state a date and time when the save file was made. If used, you can specify a title indicative of where in the game the player is at. Highly helpful should the screenshot images to the left start looking similar to one another. Below is an example of a "save_name" in action on top and beneath it, where none was specified.

All you have to do to create a save file title is to insert the following line: $ save_name = "title of save file"
Make sure you specify this at the start of the label block as that is where save files usually start when loaded.

label hello:

    $ save_name = "Helloooo Hottie!" <--- This shows up as the Title of the
                                       Save File.

    scene path_to_school
    show ojimaru normal
    "My name is Ojimaru. I consider myself to be a run-of-mill type of guy, "

The lines within the double quotes is the area that you can change. You can place anything (numbers, signs, letters) in between just as long as you follow the earlier rules mentioned such as character escaping double quotes or using two percent signs if you'd like to use them in the title.

Back to Dev Corner | Back to Top

3. Menus

Menus are the driving forces behind the choices you see in Ren'Py games. They are their own block requiring sub-blocks for it to work properly. In essence, this is the structure of the menu block with those in yellow being optional.

menu name:

    set variable_name

    "character choices dialogue heading"

    "choice 1" if variable_condition_is_true:
        "character dialogue line, python statement, scene, show, call, jump or
        pass command"

    "choice 2" if variable_condition_is_true:
        "character dialogue line, python statement, scene, show, call, jump or
        pass command"

    "choice 3" if variable_condition_is_true:
        "character dialogue line, python statement, scene, show, call, jump or
        pass command"

Let's look at each element closely. Like label, menu has the ability of having a name. Unlike label, menu doesn't have to have a name set to it. You can leave all your menu blocks with just "menu:" and they will work fine.

Something you will most likely never use is the set variable_name line. This is an extra feature in Ren'Py that basically filters the choices shown to the player. Within the Ren'Py demo, this is used, where each choice is saved and the options list is whittled down until the player chooses or ends up with just the "I think I've heard enough" option. To make this work, you have to set a variable before the menu with the set line is executed. Below, is how it is done in the Ren'Py demo:

# This variable is used to save the choices that have been made in the main menu.
$ seen_set = [ ] <--- Variable is at False at this point

label choices:

    menu:

    # The set menu clause ensures that each menu choice can only be chosen once.
    set seen_set

     "What are some features of Ren'Py games?":
        call features from _call_features_1
        jump choices

     "How do I write my own games with it?":
        call writing from _call_writing_1
        jump choices

     quot;What's new with Ren'Py?":
        call whatsnew from _call_whatsnew_1
        jump choices

      # This choice has a condition associated with it. It is only displayed if
      # the condition is true
      # (in this case, if we have selected at least one other choice has been
      # chosen.)

    "Where can I find out more?" if seen_set:
        call find_out_more from _call_find_out_more_1
        jump choices

    "Why are we in Washington, DC?":
        call washington from _call_washington_1
        jump choices

    "I think I've heard enough." if seen_set:
        jump ending

Next in line and one that is also optional but more likely for you to use is what I call the "character choices dialogue heading". True to it's name, this is what appears above the choices, usually in a character dialogue fashion of inner thought. All you need to do for this is have it appear below "menu:" but above the choices. It must be in double quotes and you cannot put in a character object before it or a manual character object (i.e. o "U-waahhhhh!" or "Ojimaru" "U-wahhhh!").

After this is the actual listing of the choices. Choices are listed much like internal dialogue (i.e. "Make a break for it.") but with the added addition of a colon after it. Example: "Make a break for it.": Right after the choice is what will happen when it is chosen. This may be a dialogue, a python statement, or a combination of both.

With a choice, you can add an if statement right after it. For example, "Make a break for it." if door_open:
When you make something like this, you have to have made a door_open variable before this condition. If door_open is set to True, this choice will appear along with the other choices in the menu. If it does not have a value of True, it will not be listed as one of the choices.

In the Ren'Py demo script above, for example, those with the if seen_set conditions are not initially listed. You will only get 4 choices. The if seen_set choices will be shown when at least one of the other choices have been clicked on first, increasing the choice list to 5.

Note: Don't forget the colon! It is one of the mostly likely common mistakes to happen while programming. If it is not present, Ren'Py will send you an error.

Technically, menu may have only one choice set to it but more likely, you will have at least two. That is why choice 2 and choice 3 below are in the optional color of yellow.

As mentioned in the above menu structure example, lines after the choice: may be a character dialogue, python statements, scene, show, and call, pass, or jump command. Note: I said a character dialogue. Ren'Py only allows one dialogue line after a choice whether it's just "Blah blah blah, when will it ever end?" or a "Blah, blah, blah, can you stop yapping already?" but not two or more. You can have as many of the others (python statement, scene, and show) as you want though. If you want to have more than one line show up, you can make like the Ren'Py demo and use the call command or you can do jumps. But all you really need to know is jump, so let us move onto that...

Back to Dev Corner | Back to Top

4. Jumps and Passes

Pass, in itself does nothing but tell Ren'Py to go to the next line. It is quite useful if you want to make a choice with no line or action beneath it.

Jump, on the other hand, tells Ren'Py to go from wherever it is now and continue running from the next label that jump names. For example, in the example below, the second choice executes jump girl. This tells Ren'Py to skip any lines in between the jump command and move to the named label title: girl. If you want to make an endless loop or until the right choice is called, I can change jump girl into jump weird (the label where the menu is), forcing the player to choose the "right" choice, namely "Get the hell off of me!!" before the story will continue.

label weird:

    $ save_name = "What the..!?"

    scene white
    "Female Voice" "Hi-yahhhhh!"
    "With a horrid screech of surprise,"
    "Ojimaru" "U-wahhhhhh!"
    "something collided onto me and I found myself face-first on the sidewalk
     seeing stars."
    scene black

        menu: <--- New block and indented four spaces with each successive line
             spaced by 4 too

            "Shaking my head and angry as hell, I say,"

            "Get the hell off of me!!": <--- Choice. When clicked, Ren'Py moves
             to the next line...

                pass <--- This tells Ren'Py to go to the next line in the script:
                 "Whoever it was..."

            "Would you please get OFF of me?":
                "With a giggle, and an affirmative, whoever it was got off of
                 me."

                jump girl <--- Tells Ren'Py to go to "label girl" and skips all
                 dialogue below

    "Whoever it was merely giggled, and bounced on top of me."
    scene sidewalk_bottom
    "Ojimaru" "Would you-"
    "Another bounce sent my face into the concrete -"
    "Ojimaru" "ge-of-"
    "Ojimaru" "Ooof!"
    "and the next left me seeing stars again."
    "After what seemed like an eternity of this, whoever it was jumped off of
     me with a gleeful sound."
    # With no jump command here, the story will automatically keep going down the
     script file...
    # and will now move on to label girl

label girl:

    $ save_name = "Ojimaru Meets \"Whoever\""

    scene path_to_school
    "I slowly rose to my feet..."
    "Looking dazedly around, I found myself alone on the sidewalk -"
    "when a voice called,"
    "Female Voice" "Awww, so cute~!"
    "Leaves rustled and from the shadows of the tree branch above me -"
    "I saw something - no someone - totally unexpected -"
    "Female Voice" "You Natoli's new pet, 'kay?"
    "With that exclamation, she leaped off the branch and jumped straight
     at me -"
    "Ojimaru" "H-h-hey! What're ya doin'?!?"

Jumps and passes do not have to be just used under the menu block, you can also use them in other blocks like the label block. But one important thing to remember about jumps: make sure you keep track of where each of them goes! Make a diagram if you have to. Also, always make sure your script flows!

<<Starting Out Part II | Back to Dev Corner | Writing Your Script Part II >>