Ren'Py Beginners Coding

by arty
Version 15.07.2018 - works with Ren'Py v7.0

Hello, welcome to a "little" guide I wrote up for a friend to teach him how to help me with
coding. He got too busy to actually do it, but I figured I might as well make it available to
others so the work wasn't in vain. :P

I know there's a quickstart guide in the official Ren'Py documentation, but I would explain
some things differently. So maybe this helps some people. This is just how I do things by the
way, and I don't claim it's the only or "correct" way to do them.

Table of Contents
(Click on the links to jump to the respective sections)
Setup 2
Characters 2
Images 2
Music 3
Variables 3

Basics 4
Narration and Dialogue 4
Showing and hiding characters 4
Showing 4
Optional: Mirroring 5
Changing Expressions 5
Hiding 5
Background transitions 5
Music 6
Sounds 6

More advanced stuff 8

Labels 8
Choices 9
Variables 10
Checking Variables 11
Strings 11
Numbers 12

Misc 13
Side Images 13
Setup
Before you get started and along the way, you should set up your characters, images (also
backgrounds), music, and variables. I always do this in the script.rpy file, before the actual
game start label.

I'll explain how to actually use the stuff you set up here in later sections.

Characters
You can add lots of fancy stuff to your speaking characters, but at the very least I would
recommend this setup:

define c = Character('Charactername', color='#c8ffc8', what_prefix='"', what_suffix='"')

I used ' quotes here because we put the " in the prefix/suffix of the character … aka adding
quotation marks to everything they say automatically.

"c" is the abbreviation you will refer to the character by when typing dialogue. The
"Charactername" is the name of the speaking character that will be displayed in the
namebox while they speak.

Images
For convenience, I recommend putting several subfolders into your game's images folder
and then defining the images in the script manually. That way you'll keep a better overview
and won't have to 1000% stick to a naming convention.

Define a basic expression image for a character like this:

image character expression = "filename.png"

"image" is the important keyword. "character" is where you put your character's name.
Example:

image claire neutral = "claireneutral.png"

"expression" is the name of the expression/outfit/etc you want the character to wear. You
can "stack" the expressions and just string as many of them together as you need. For
example:

image character day outfit expression = "filename.png"

Background images can be defined like this:

image bg location time = "filename.png"

Note the "bg". I recommend always including it for backgrounds

Music
Instead of typing the filename everytime you want to play a sound/song (and going back and
editing every single instance of it later….) do this where you define all your other materials:

define audio.title = "filename.ogg"

"title" is the name you want to refer to the file by in your code!

Variables
There's a lot of discussion going on about define and declare and whatnot when setting up
variables… What I do is I just "mention" the variable by putting something like this ​after​ the
start label:

$ variablename = 0

… or similar, depending on what kind of variable it is and what I want to use it for. Your
game will crash if you try to modify a variable that hasn't been "mentioned" like this before.
See Variables section for further explanation!
Basics
To get your basic VN started, you will only need the things I describe in the following
sections. Maybe not even all of them.

Narration and Dialogue

Narration is simply text inside quotation marks.

"Every new line is displayed in a new text box."

c "This is character dialogue...The letter at the beginning is the abbreviation for the
speaking character. Character abbreviations are defined in the beginning of your
script."

Put the letter before every line of dialogue that the character has.

"Speaker" "If you use a random character that isn't one of the recurring ones, you can
just put their name in quotation marks instead of the character abbreviation."

A quotation mark inside narration/dialogue will break the script, so only use ' inside
them...unless you 'escape' the quotation mark. To escape it, instead of " type \"

# You can put single-line comments with a hashtag, by the way.

These comments will not appear in the final game, they're just notes for you.

Showing and hiding characters

Showing
Add a character to a scene like this:

show character expression with dissolve

"character" is the defined name of the character image, "expression" the desired defined
expression, "with dissolve" is just added to make them fade in instead of popping up
suddenly
To add multiple characters at once, just put the "with dissolve" at the end of the commands
like this:

show character1 expression

show character2 expression
with dissolve

By default, the character shows up centered at the bottom of the screen

If you want to place them somewhere else, use this for example:
show character expression at right with dissolve

This also works with "at left" and "at center" (and several other pre-defined positions). If you
added a character on the right and want to add another one in the middle, and if your sprites
are wide, it's a good idea to modify the command to shift the images behind or in front of
each other. For example:

show character1 expression behind character2 with dissolve

You don't have to define character2's current expression again if you did already, but make
sure that you actually added them to the scene before you put someone behind them or it
won't work.

Optional: Mirroring
PROTIP: If you want to mirror a character image, simply add "flip" after the expression:

show character expression flip at left with dissolve

Then, you define a new "expression" for the character in the beginning of your script, with
either a completely new sprite or simply doing this:

image character expression flip = im.Flip("filename.png")

Use this with caution … some people don't like ​obviously​ mirrored sprites.

Changing Expressions
If you want to modify a character's expression, you just do the same as you would when you
add them, but you can leave out the position as the script will remember where they are!
Don't forget to add a transition, if desired.

Hiding
To get rid of a character, just do this:

hide character with dissolve

You don't have to specify the expression or position. For hiding multiple characters at once,
just do the same as you'd do with showing them, putting the transition at the end of the
block.

Background transitions
Backgrounds are defined like character images in the beginning of the script.

The name of the background is always prefaced by "bg", and followed by any other modifiers
that you defined (day, evening, night, for example).
show bg cafeteria day with dissolve
show bg home evening with fade

The first line just transitions the previous background to the "cafeteria" one by crossfading.
The second background fades to black and fades back in showing the "home" background.
You're probably not going to use this in this context. The "fade" transition is more useful like
this:

scene bg cafeteria day with fade

The "scene" keyword means that all characters that are currently on the screen will be
hidden when the transition happens. You can use this to quickly clean up a scene, and if you
want to stay in the same location while still doing that, you can use the scene command like
this:

scene bg location time with dissolve

Of course you can also manually hide all characters, but that would involve more typing.
If you just want a black screen for a while, type:

scene black with dissolve

Music
If you defined an audio file in the beginning of the script, you can play it like this:

play music title fadeout 2.0 fadein 2.0

This will play the track "title" and fade out the previous track as well as fade in the new track
in the given amount of seconds (2 in this example). If there was no other music playing at
the moment, you can just leave out the "fadeout".

To stop the music, simply do this:

stop music fadeout 2.0

No need to specify the track title again. Tracks on the music channel will loop by default. To
have a music file play only once, add "​noloop​" to the play statement.

Sounds
Sounds work similarly to music, they just use a different channel and don't loop by default.

play sound title

Stop the sound while it is playing like this:

stop sound

For more advanced users, there's more and custom channels available. Additional options
and features such as queues and manual loops can be found in the documentation:
https://www.renpy.org/doc/html/audio.html
More advanced stuff

Labels
To make testing easier, you can add labels for convenience. If you split up your game into
multiple script files (and you should), you can jump from file to file with labels.
A label just looks like this:

label labelname:

"label" marks it as a label, and "labelname" is a name you can freely choose, but only assign
once in your whole game.
HOWEVER, there are sublabels. These are labels inside labels, and you can re-use the
names while inside a different label. Whenever you feel it's possible, please use a sublabel.
You can do that like this:

label .sublabelname:

Whereas the dot is important, and the "sublabelname" is the name of the label that you
assign.

Especially if the story branches, you should indent the stuff that follows after the label and
belongs to it. For example, in one label the player goes left, then you indent the stuff that
happens if they do that in that label. Then you add the label where they go right without an
indent, and then indent the stuff that happens inside that label.

You can also jump to labels:

jump labelname
or
jump .sublabelname

Note that there is no ":" when jumping!

The second line only works when jumping to the sublabels inside a "parent" label. If you
want to jump from one label into a certain sublabel-position inside another label, you have to
call it like this:

jump otherlabelname.sublabelname

So what do the labels actually do? Well, they mark "portions" of the script. For example, you
have a choice. "Go left" or "Go right". You make two labels, one called ".left" and one called
".right". Then you put the stuff you want to happen respectively "inside" the labels. Then, you
make a "common" label, for example ".cont".
Example:
label commonstuff:
"We are now inside the commonstuff parent label."
"There could be a choice menu here. Instead, we will just jump to the .left
sublabel."
jump .left
label .right:
"This portion will get completely ignored."
"If the player was in here, they would next get sent back to the common
route and ignore the .left label."
jump .cont
label .left:
"This is where the player will end up."
"We could now include a jump to the .cont sublabel, but this is not
necessary in this case since it's the next destination in the flow
anyway."
label .cont:
"The game continues here after the left or right deal."

You can put sublabels inside sublabels, by the way. Just try not to make it too insane.

Choices
To add a choice for the player, you have to add a "menu" like this:

menu:
"Choice 1 text":
# Stuff that happens
"Choice 2 text":
# Stuff that happens
"Choice 2 text":
# Stuff that happens

Note the indents.

You can use a menu like a label (aka jump to it) if you put this in the first line instead:

menu menuname:

… whereas "menuname" is the name you want to refer to in your jumps.

The thing that makes choices different from simple labels is that depending on which option
the player chooses, the script will only go into that choice's branch and skip the others by
default. It won't go through every choice. You can add normal script inside the choices'
branches.
By default, no text other than the choices will be shown during the choice. But you can add a
string before the first choice to display a text.

An example choice:

menu:
"Do you want to go to the cinema?"
"Yes":
"Good choice."
$ cinema = True
"No":
"Aw, shame."
$ cinema = False
"The script will continue normally and this narration will be displayed after the choice
is made and the respective branch was processed."

Don't worry about the $ stuff right now, that's variables and I will explain them shortly.
You can also just jump to a label from inside a choice option. A branch may not be empty,
though.

Variables
Here's where some people have difficulty. I'll try my best to explain.

You can imagine a variable as a box of sort. It has a name, which can be seen as a label on
the box. It also has a value, which is the contents of the box. You can freely fill, empty, refill,
and modify the contents of the box. But you have to decide what sort of box you want it to be
when you first fill it. It may be a box only for tools, or a box only for books. But never tools
AND books.

That is mostly true for the variable types that hold text and numbers. There's another type,
which could be seen as a light switch. You have an ON state - True, and an OFF state -
False.

To tell the game what sort of variable it will have to deal with, you have to declare every
variable you are going to use in your script. Do this in the beginning of your script like I
explained in the Setup section. Then they are ready to be used.

There are three relevant types of variables:

$ boolean = True
$ string = "text"
$ number = 2

Every variable is marked by a $, followed by a space and the variable's name. A single = will
set the variable's value. The booleans are True or False. The strings can be any text, but
make sure to only use ' inside them instead of normal quotation marks (or escaped ones)
since the variable string itself is encased by ". A number may be an integer or decimal
number, and may also be negative.

You can use variables for many things, but the "classic" use is friendship points and
progression flags.

To manipulate a number variable, do this:

INCREASE by 10:
$ friendship += 10
DECREASE by 10:
$ friendship -= 10

SET new value to 10 (and delete old value)

$ friendship = 10
… this also works for booleans and strings:
$ cinema = True
$ mcname = "Thomas"

Checking Variables
If you understood everything so far, this should be easy.
You will want to check for variables to see what happened in the game so far.

This is how you make a conditional branch that checks for a boolean:

if variablename:
# Stuff happens if boolean value is True

You can also add an "else:" if you want to do stuff in case the boolean is false:

if variablename:
# Stuff happens if boolean value is True
else:
# Other stuff happens if boolean value is False
"The script continues here after the appropriate branch is processed."

Checking for numbers and strings is similar:

Strings
if variablename == "value":
# Stuff happens
Note the double == … if you only put one, it's not going to work because it will try to ASSIGN
a value instead of CHECKING for one.

Numbers
if variablename == 100:
# This happens if the value of variablename is exactly 100

That may not be desirable, so you can also check if numbers are greater/equal or
lower/equal than a certain value:

if variablename > 20:

# Stuff if greater than 20
if variablename >= 20:
# Stuff if greater or equal to 20
if variablename < 50:
# Stuff if lower than 50
if variablename <= 50:
# Stuff if lower or equal to 50

To exclude a value, do this:

if not variablename == "value":

# Stuff happens
Misc

Side Images
Sometimes you'll want your main character to also appear on screen, but not with the other
characters. Side Images are the way to do this! If you set these up, your speaking character
will appear on the bottom left of the screen when they talk.

My approach to this may be a bit cheat-y, but it works for me.

To give a character a side image, you have to declare them differently in the setup:

define mc = Character('Main Character', ​image = 'mainc'​, who_color = '#636074',

what_prefix = '"', what_suffix = '"', ​window_left_padding=110​)

The differences here are highlighted in red. Namely, you have to add the image tag, and the
window padding.

The image tag takes care of assigning the right side image to your speaking character. It has
to be declared in a special way in the setup, with the side keyword. For example:

image side mainc = "mc_side.png"

If you let your character speak like this:

mc "Hello! I'm now no longer faceless!"

… then a side image should appear next to the textbox. You can modify the expression if
you define multiple side images. For example, if you define a "mainc happy" side image, you
can show it like this:

mc happy "Hey! Now I'm in a good mood!"

You'll want your image to be a certain size. Depending on the shape of your side image, it
may be necessary to add or remove some padding from the textbox. Above in the
declaration, we gave the side image 110 pixels of space. If you modify this number, it will
leave more or less horizontal space for the side image.

Now, so far, so good. However! Your work is not done.

As you can see, your side image will blink in and out of existence very annoyingly when your
character is having a conversation with other characters. Now this is personal preference,
but I don't like that. To fix it, I use a little trick. This only works if you only show one
character's side images.
I declare my other characters normally, but then declare them a second time. Like this:

define l = Character("Lisa", who_color = "#ed86a2", what_prefix = '"', what_suffix = '"')

define ls = Character("Lisa", image = "mainc", who_color = "#ed86a2", what_prefix =
'"', what_suffix = '"', window_left_padding=110)

The second character is used when the main character and she have a conversation. I
assigned the main character's side images to her, so the game will think it is showing ​her
image, when in reality it's again showing the main character's, creating the illusion that he
stays on the screen during the dialogue.

So the dialogue script would look like this:

l "I have some lines."

l "Some more lines."
mc "Hey."
ls "Hey!"
mc "What's up?"
ls "Not much!"

In the first two lines, the speaking character (Lisa) is shown normally. In the consecutive
lines, I use the "ls" speaking character for her, so her text will be leaving space for the side
image and show the main character.

You can also use the same expressions that you declared for your main character, without
the need to declare them again.

Again, all of this is preference. Others may like another solution better.

And that's it for now!

If anything is unclear or if I forgot something very important, please tell me and I'll change it.

Happy coding!