How to turn a script into Ren'py code

[alias_sqbr]

Since it's come up a few times for me, and I imagine others might find it useful too.

Ren'py is a Python based visual novel engine for creating interactive stories. It's designed for stories which rely mainly on character sprites and dialogue, which means most of the code looks a lot like the script of a play. It's aimed at non programmers and relatively easy to use, but there's a few things that seem to trip everyone up when they start.

So, you have a script for a scene you want to turn into renpy code. Where do you start?

Renpy has a very nice Quickstart Guide for downloading Renpy and creating a simple game, as well as a good inbuilt tutorial and some patchy but mostly useful online documentation.

I recommend following their advice for installing Renpy, then running the tutorial. Don't stress if some parts are a bit confusing. Now go through the Quickstart Guide and play around with the example game they give you.

Finally, try writing your script up yourself, then running it. If it works exactly as planned, hurrah! You don't need me :) If it doesn't, poke at the categories below to figure out where you went wrong, and if THAT still doesn't work leave a comment and I'll have a look.

(I've written code in italics. I haven't gone into images since I can't think of anything to say not covered better by the Quickstart guide. Note for Copper Rose people: all the characters and images you need are defined in declarations.rpy)

Starting

Open the Renpy launcher. If you're working within an existing project, choose that, otherwise start a new one. Click "Edit Script" to open jEdit (on the Mac, anyway), it's not perfect but helps a lot with indenting and keeping track of data types. You can create a new document using File->New, make sure to save it with the extension .rpy or it won't be compiled.

Give your scene a label, with the line label scene_name: at the start. Now go to script.rpy and put jump scene_name after the start label, like so:

label start:

    jump scene_name

Note the indenting. Now when you run the project, it will go straight to your scene.

Indenting

Indenting is the only way Renpy has to keep track of what code goes where in branching paths. An indent is required after any command followed by a colon, such as label, menu, or if. Specifically, the first line after the label at the start of your scene needs to be indented.

To indent a single line you can use Tab. To shift a block of text all at once, select the text you want to indent and choose Edit->Indent->Shift Indent Left/Shift Indent Right from the jEdit menu.

The number of spaces used to indent doesn't matter as long as it's consistent, but since jEdit automatically uses 4 spaces per indent you might as well stick to that.

jEdit will guess which lines need to be indented and by how much, and sometimes guesses wrong. This can be annoying.

Dialogue

Make sure all your dialogue is in the form of lines like character_name "Dialogue". You will probably have to search and replace a lot of smartquotes, and do searches like character_name: " to character_name ", depending on how your original script is formatted. The editor will highlight all the strings (dialogue) in the same colour (for me it's green), make sure you haven't missed any quotes anywhere.

Every character with a speaking line needs to be defined outside the script. The easiest way to do this is in a block at the start of your file. The format is define character_name = Character('Name', color="#c8ffc8").

Name is the name that shows up on screen, character_name is the name you use in code, and #c8ffc8 is the colour of the text their name is shown in.

So, you should have something like this:

define jane = Character('Jane Smith', color="#FF0000")
define bob = Character('Robert Smith', color="#0000FF")
label scene_name:
    jane "Hey Bob!"
    bob "Hey Jane!"

Congratulations, 90% of your code is done! If you have no branches, you should be able to test and run your code right now, though you won't see any images.

Branches

Branching choices have the following format:

menu:
    "First menu choice":
        character_name "Only those who choose first can see this"
    "Second menu choice":
        character_name "Only those who choose second can see this"
character_name "Everyone can see this."

NOTE THE INDENTING, after the menu command AND after each menu choice. If you don't indent correctly, Renpy will either crash or show your dialogue at the wrong time.

If a block of text is getting unwieldy or you want to link to it more than once, give it a label and use jump to jump to it. Here is an equivalent way to code the menu above:

menu:
    "First menu choice":
        jump first_part
    "Second menu choice":
        jump second_part

label first_part:
    character_name "Only those who choose first can see this"
    jump last_part

label second_part:
    character_name "Only those who choose second can see this"
    jump last_part

label last_part:
    character_name "Everyone can see this."

Regarding If and while statements and variables:
1)Changing variables has to be done in a Python block, usually by using a dollar sign
2) You SET a variable with a single equals sign, but you TEST it with a double equals sign.

See for example:

    $ countdown =10

    while countdown >= 0:
      if countdown ==0:
          "BLASTOFF!!"
      elif countdown == 10:
          "Starting countdown! 10..."
      else: 
          "[countdown]..."
      $ countdown -=1
    
    "And now the rocket is gone forever..."

Common errors

Forgetting to save the file you've just edited before running Renpy.

Doing a whole big scene at once instead of starting small to get the hang of the syntax.

Unclosed dialogue tags or smart quotes. If you want to use a quote symbol within dialogue use \".

Using the same label twice. Renpy will crash and say something like "Cannot assign style outside of init phase". This is the default "I am crashing and I don't know why" error, and usually means something has been defined twice.

Lone brackets: "unexpected end of file"

Forgetting to go into Python mode when dealing with variables. Remember the dollar sign!

Using == (testing equality) when you mean = (setting a variable) and vice versa.

Using - or + when you mean -= or +=. Note that the following statements are equivalent:

    $ x = x-1
    $ x -= 1
    $ x += -1

Not indenting correctly. Everything in the same if: while: menu: etc block needs to have the same indenting. The first line after a label: has to be indented.

Forgetting the colon after if elif else while menu label etc, including menu choices.

Also, a handy hint for jEdit: search and search and replace both have an "all buffers" option which makes it easier to track down bugs and fix wide scale mistakes.

Where next?

If you've gotten the hang of basic dialogue and want to do fancier things, here's some places to look for help:
Follow the 'Next Topic' trail on the sidebar of Renpy Docs pages
Read the relevant parts of the FAQ
Poke at the cookbook
Use the Renpy Docs page Search, search at LemmaSoft or just type "Renpy (what you want)" into google. In my experience results vary wildly.
Ask at Lemmasoft. Haven't tried this yet I am too shy :)

You can also ask me but my skills are pretty basic. Still I'll do my best!