Jump to content

How to code a VN with Ren'py (Comprehensive Guide)

Helvetica Standard

Recommended Posts

This is a long comprehesive guide 

It has now been moved to the mainsite.

to read it click the  chapter images for the individual parts:







note: part 4-5 not made yet. but hopefully will be added in future





Greetings FUWA.

The purpose of this thread is to help people who are interested in making their own Visual Novel projects realise this dream and hopefully pave the way for

more VN enthusiasts to join the OELVN development community. This is a five part guide explaining all the necesary steps for programming a standard

visual novel with the free engine Ren'py. In case you don't know, Ren'py is an app that allows you to develop and ultimately release your very own VNs.

This sounds too good to be true, right? And you must be wondering what's the catch. Well...there's just one: You need actual programming knowledge.

In the case of Ren'py you use the Python language. Don't worry though, as Ren'py is fairly easy to use and you can totally develop a full fledged visual novel

with relatively simple Python knowledge and this guide focuses on teaching you how to do exactly that while avoiding the difficult parts. Once you get the hang 

of it you will end up learning complex coding and this will open up a sea of infinite possibilities for your VN. That said, let's begin, Shall we?


What do we need?


1. A computer, be it MAC or PC. (Ren'py runs on every desktop platform)

2. Ren'py itself, which is a free to download app: Download Ren'py

3. Lots of patience and motivation.


Great! Then what are we waiting for?


Hold on just a little bit. XD 

Before we get started, there's something you need to know: Creating a Visual Novel is not a walk in the park. It's a very difficult endeavor that requires a lot of
work, time, responsibility and dedication. You also need plenty of other things such as a story framework, character designs, musical and artistic assets, just to

mention a very few. Depending on the scope of your project, creating a VN could be a "text adventure" with nothing more than dialogue or a very rich and

detailed visual story with tons of imagery, music and characters. That said, this requires a lot of time and plenty of expertise on several areas. Yes, that's right

you need help and resources.


Before we take the plunge on the programming part, I highly recommend you read Diamon's thread: So you want to create a visual novel

It contains extensive and very detailed information on how to start up a project of your own and it will most certainly help you as you

develop your VN project. Go ahead, take your time, I'll wait here. ;)


There we are. It was a fantastic read, was it not? Now that you have all that info down and you are prepared to tackle this task, then let's begin!










Yup. That's right. If you've read this far, you must know that this guide will help you tackle the programming/scripting part of the whole creative process surrounding a

visual novel. This guide is not an infallible source of wisdom for creating VNs and It won't make you a Python expert after you read it. XD That said, what this guide

WILL provide is a (hopefully) easy to understand way to code your VN without the need of extensive programming knowledge. I promise I'll be with you all the way

to the end. Let's do this! :D





Ok. First make sure you've downloaded Ren'py and installed it in your system (Then run Ren'py by double-clicking on the .exe file)

A window will appear shortly. This is the Launcher window or as I'll call it from now on "The Hub." This is your command center of sorts as you

will control most of the actions for developing your visual novel from here. That said, let's get familiar with it now, shall we?




1. Currently active projects: Your projects are listed here. You'll notice two entries already created, these are a tutorial VN which lists

several of ren'py's features, and well...just that. The other project is a sample VN that you can use as a reference for creating your own.

If you want to familiarize yourself with the script mechanic and the code language you can check the script files of this sample game.


2. Create a new project: Self explanatory for the most part. Click here to create your project. You'll be then prompted to name it and

add other details. You will also be given a set of three virgin script files and default configurations for your project.


3.Game directory: Once you're done creating your project, Ren'py will produce a "game folder" within its installation directory. You can quick

access this folder by clicking this link. The game folder is extremely important as it contains every asset you need for running your VN. Art,

music, sounds, config files and videoclips all go here.


4.Base directory: The folder where your project files are stored. Don't erase it by mistake!


5. Main script file: The place were your story unfolds, the main script file will allow you to code, parse and write the visual novel.

While the script contains the narrative and dialogue, its main function is to serve as a set of instructions for Ren'py to interpret.

Upon clicking here you'll be prompted to pick a scripting platform. It's recommended that you pick "Editra" as this guide

will be based on that one. (Although the differences between each platform are minor.)


6. Options script file: A script file with diverse configurations for your project. It has several default settings such as resolution,

font and text box design. You will most likely change and tweak these settings for custom ones later on.


7. Screens script file: this file controls the visual appearance of your visual novel. It has a default theme and style that you can customize

later to meet your needs and design choice. "screens" is a name used for the visual novel's GUI. It may sound simple but screens customization

requires python coding.


8. All scripts: Click on this to open all three script files at the same time.


9. Check script: Ren'py checks your main script file for errors. Useful for hard-to-find mistakes in very large script files.


10. Change theme: You can select a variety of default themes for your VN. They all share the default factory style.


11. Delete persistent data: Clicking this option erases game progress, saves, flags and image caches. Make sure to delete the persistent

data before packing a build in order to avoid transferring your saves and settings to the distro.


12.Build distributions: Ren'py will pack your assets and scripts into a distro. Do this only when you plan to release content.


13. Android: Ren'py will pack your assets and script into an android app. Not all Ren'py functions are yet available for this kind of distribution.

(Requires 3rd party software and other knowledge that the guide will not cover.)


14. Online resources: This sidebar allows you to consult the "ren'py documentation" which is a guide of basic functions, browse the website/list of

registered ren'py games, update the software and change the engine's preferences.


15. Launch project: Test launch your project. Ren'py will parse your script files and attempt to run your game. Any critical errors will

crash the engine and notify you the cause of the stop. 90% of the time, these errors are the programmer's fault and not Ren'py's. :P


Now that we know how the Hub works, let's go ahead and create our project, shall we?






Click on "Create new project" a window will appear shortly:




After naming your project you'll be greeted by the theme picker window:




After your project has been created it will immediately become the currently active project.

Before anything, let's click on the "Game" option to open our project's game folder:



You'll be visiting the Game folder quite often, be it for managing or defining assets. Now let us proceed to check the script files:

Click on the "script.rpy" option. You will be prompted to pick a scripting program. Pick "Editra." Then a window will appear shortly:







Basic script color code: 

green: used for definitions and dialogue/narration.

black: neutral input/ file names/transitions

goldenrod: used for statements/instructions.

blue: other instructions

wine red: comment lines/disabled lines


Note that you don't need to do anything to change the color of the text. The text changes color automatically depending on what you write (as Editra predicts

your inputs it changes color accordingly.) Here's an example of the color code:


label helvetica standard:

play sound "helv.mp3#remember to adjust sound file for resonant lows.                                                                                                       

h "Why hello everyone, this is an example of how text looks depending on the input given."                                                                                                                                                                                                              


This color code is very useful as it tells each bit of the script apart and allows you to identify errors in your coding/scripting. 

It won't be long before you memorize the coloring, increasing your workflow and pinpointing mistakes a lot easier.

So if a statement should be yellow and is green or a dialogue line should be green and it's black, you'll know you made a mistake.


Script actions (friendly edition)

Editra and Ren'py work with a plethora of script actions and most parts of it are python code. However we don't need all that

complicated mumbo-jumbo in order to create our visual novel. (At least not for the essential parts.) That said, let's go over

the actions that we'll be using in the future.


Dialogue and narration: The simplest script bits. You generally write these sections as you would write a dramatic play (sort of.)

for narration you open quotations, write your narrated line then close quotations:

" Triple brown big Betty walked to the door."


Quotations won't appear and are just a way of telling ren'py that you're writing a narration sentence. There are ways to make

your quotations visible for both narration and dialogue but we won't go over them to keep things simple.

Next is dialogue, this time you'll need a defined character. As you can see at the top of the screenshot there's a set of code

where you define your assets. This bit also includes characters. Let's define our character so we can "call it with the ren'py script."


define b = Character('Betty', color="#b7b7b7")


Where "define" is the instruction to define a character, "b" is a short hook used to summon your character when scripting, it can be any number or letter

or combination of both but for practical application use a single letter or number. "Betty" is the character's display name and the "#b7b7b7" is HTML code 

for the text's color. You can easily get a specific value for a color with the help of photoshop or any image editing software.

You can also use this: HTML color picker


image splash = "splash.png"
What you can see above is how to define an image. Images as well as characters require you to define them so Ren'py can summon them in-game. 
If you forget to define them, Ren'py will throw you an error: "xxxx not defined." or crash altogether.
As for the text above, "image"  is the instruction to define an image, "splash" is the hook you will use to make renpy summon the image. the hook can be
any combination of letters and numbers, but to make things easier make sure to name it as something allusive to the image or something easy to 
remember for recurrent images, such as sprites. And lastly the "splash.png" is the filename of the image you're defining. "splash.png" should be
inside your "Game" folder before attempting to define it. If Ren'py can't find the image in the folder, it will throw an error or crash.
Remember: You only need to define each image and character ONCE. You don't need to do this again everytime so don't worry.
Now that "splash" is defined you can summon it without the code (see below): 
show splash
With that out of the way, let's do a quick check of the script commands:
show: Show an instance of an image, displayable, imagemap or animation. You'll be using it often to summon sprites, bgi and CG's.
scene: clear all image layers and show a new instance of an image, displayable, imagemap or animation. Sounds similar to "show" but
this command empties image caches and creates a new layer. Note: Use this command at the beginning of each scene to purge the image
cache and to hide your images. If you never use "hide" or "scene", your images will never leave the screen till you do!
play: calls a track or a video-clip and plays it.
with: adds a secondary command. Example: show splash with dissolve.
pause: Pauses progression till user clicks mouse or timer runs out.
stop: Halts a process. Usually music
init: for advanced coding.
repeat: repeats a cycle till user clicks mouse.
return: Jumps back to title screen.
menu: Produces a choice menu for flags. User must pick an option to progress the script.
if: Conditional. If flag is true then the script will follow this path.
else: Conditional. If flag is true, else is ignored, otherwise it will be interpreted.
if not: Negative conditional. if flag is false it will be interpreted.
$: Flag conditional, can be true or false.
python: for advanced coding.
Script commands that require another instruction to work:
sound: works in tandem with play (for playing sounds.)
video: works in tandem with play (for playing videos.)
at: works in tandem with show (positioning) requires a third instruction.
behind: works in tandem with show. (positioning) requires another displayable.
left: works in tandem with show. (positioning) requires at.
right: works in tandem with show. (positioning) requires at.
center: works in tandem with show. (positioning) requires at.
These are basic animations for changing scenes/skipping time or animating certain events in your VN (such as punches, explosions, etc.)
Below is a list of Ren'py's default transitions. They all have a duration of half a second and generally speaking are the only ones you'll need for your VN.
There are ways to customize the transitions duration and even creating new ones, but for the sake of making your life easier, the guide won't cover that.
in order to use transitions you must add the "with" command along with an image instance to apply it to (see below):
show betty with dissolve
fade: screen will fade to black and then fade to a different screen. Don't use it on sprites as it will still fade the entire screen instead of just the sprite!
dissolve: basic dissolve, useful for changing the expressions of your sprites. Not recommended for screen wide images as the effect is too subtle.
pixellate: blurs the image with squares and does the same after new scene is rendered. Fairly versatile.
move: Positioning transition, this is just the radical and requires another command to work (shown below.)
moveinright: Positioning transition. It swipes the image into the scene from the right.
moveinleft: Positioning transition. It swipes the image into the scene from the left.
moveintop: Positioning transition.It swipes the image into the scene from the top.
moveinbottom: Positioning transition.It swipes the image into the scene from the bottom.
moveoutright: Positioning transition. It swipes the image out of the scene from the right.
moveoutleft: Positioning transition. It swipes the image out of the scene from the left.
moveouttop: Positioning transition. It swipes the image out of the scene from the top.
moveoutbottom: Positioning transition. It swipes the image out of the scene from the bottom.
zoomin: zooms images
zoomout: zooms out images
zoominout: zooms images in and out
vpunch: shakes the screen vertically, you can stack the effect several times to emulate rumbling, jumping, tremors etc.
hpunch: shakes the screen horizontally, useful for emulating shaking head effects.
blinds: An all time classic transition and the best for time skips. Screen will change vía vertical blinds effect.
squares: another classic. screen will fade with squares.
wipe: requires another command to work such as left. swipes the screen to the given direction.
irisin: a rectangle grows into the screen to cover the old scene with the new one.
irisout: a shrinking rectangle diminishes the old scene till it disappears and is replaced by the new one.
About indentation and sintax:
All of this sound pretty easy on paper but Ren'py's scripting is quite rigid and tolerates no mistakes. A missing comma, parenthesis,
a misplaced capital letter or a typo on a filename can break your code and drive you up the wall for several hours before you find out what went
wrong. It is strongly recommended that you check the script for errors after you make major changes to avoid this. Also pay attention to the
text's color to identify the mistakes yourself before they grow into a disaster. All of this however is no match for the biggest and
meanest of your enemies during coding/scripting, behold...
You must have noticed by now that dialogue and narration are set of lines one after the other like the script of a play or a book. the lines all
match the left margin and there's no edgy or arbitrary spaces you must add. However those are lines. Coding parts come in BLOCKS. And blocks
have their own margin! This is called indentation...
Editra is nice enough to automatically indent your coding by predicting the kind of programming instruction you're going to give. This normally saves you a lot
of trouble, but it only works for basic coding. Any kind of custom code and you're on your own. Below is an example of indentation at work:
The indentations are those huge blank spaces after the left margin that seem to serve no real purpose. They have a function but you don't need to know that.
what you need to do is to be careful when programming custom code. Sometimes Editra will be able to predict the indentation and sometimes it will refuse to cooperate.
Any sort of error in the margins and Ren'py will unceremoniously throw you a critical stop reading: "indentation mismatch" and a very vague hint as to how to track
the root of the mishap, not to mention that this effectively crashes Ren'py whenever you try to test run your project, forcing you to solve the issue ASAP, unless you
want to kiss your test runs good-bye and render your script and code useless. Fortunately, you won't have to deal with the monstrous indentation shown in the picture,
this however doesn't mean that you should ignore the warning. Fear indentation and respect it.
Now that we've seen what the main script is and how it works, let's go over to the options script file.
The options.rpy file. A script file with all of the configurations for your visual novel. It's the control center for most of the display options of your Visual novel.
From here you control your VN's resolution, the images used for title screen and subscreen, the amount of options in the preferences screen. The labels
of the save/load screen, the font your VN will use for text, the design of your text box, format options and much more. It sure sounds complicated
but  you don't need to code much, as you will be editing the contents rather than programming them. Let's go over some of the key areas of this script file, shall we?
Config.developer = This is like a switch that enables the use of the in game console, commonly known as "dev tools" Before you release a demo
or your completed VN to the public be sure to set it to "False" unless you want other users poking at your code, script and assets as they please. XD
config.screen_width/height = Here you edit your VN's resolution. As simple as it is it's still recommended that you set a maximum resolution of 720p.
Picking full HD resolution and above will give you tons of compatibility problems, as well as making your game size HUGE. Ren'py works with a default
resolution of 800x600. which is 4:3 aspect ratio. I f you decide to change the resolution to 16:9 format you'll have to edit other files (default sprite positions,
text box margin, text padding) manually. 
config.window_title = The title of you game's window. It can be anything as long as you have a solid changelog to keep track of your revisions.
For example: "Project Betty Mk II, REV. 1.0241" Don't forget to change it to your Final VN's name before you release it!
config.name/version = The display name of Ren'py's lovely crash window. All errors and critical stops will be logged with the name you give to this window
so you know what failed in which revision. You'll be seeing it quite often so make sure to give it a pleasant name. :P





style.window.background = frame: This is the design of your game's text box. There's a default text box style but you can't go with that. No one can. it's too austere, too generic. That said the best way to style your text box is to manually design it vía an image editing software like Photoshop or Illustrator. I personally recommend these dimensions:

1180x140 (for 16:9 resolutions) and 800x200 (for 4:3 resolutions)

style.window.margin = The text box margin. the higher the value the more you'll eat at the horizontal edges of your text box. It's not recommended to edit this value

if you decide to use Ren'py default resolution (800x600)

style.window.padding = The margin for the text inside the textbox. Editing enables quick format justifying and centering of text is you're using 16:9 aspect ratio. Again, it's not recommended to fiddle with this is you decide to use the default resolution. 

style.window.yminimum = The minimum height of your text box, there's no real need to edit this value. :P




style.default.size = The default size of the text inside the textbox and other default style. You will most likely change this is you use a custom font and/or custom styles.

config.has.sound/music/voice = audio switch. As the image says, don't set it to false unless you plan to release a VN with no audio.

style button sounds:  You can set several audio files as button sounds when users click on interface menus and options. It's a nice detail and there's no

excuse not to do it, as it's very simple. Just don't use copyrighted sounds. xD

config.main_menu_music = You can link an audio file here to serve as the title screen's music. It will loop automatically so there's no need for added tinkering.

If you don't edit this value, your main menu will be silent.




config.save_directory = The save directory of your developer build. Don't change it as there's a number of issues related to that. Thankfully it has a default location 

so you don't really have to worry about it.

config.default_fullscreen = If you set this value to false, the game will run in a window when clicking the exe/test launching the project. If set to true, it will launch in

fullscreen by default.

config.default_text_cps = the default characters per second value. Factory default is "0" which displays text instantly. You might want to change this later on.

config.default_afm_time = Default wait time for auto-read mode. Factory setting is very slow and unusable. You need to edit this before releasing content. XD


Now that we've checked the areas that we'll be editing in the options script file, let's have a look at the screens.rpy file.




The screens script file. The place where you will make your UI look pretty. Here you can customize nearly every visual aspect of the game's interface.

The main menu, sub menu, preferences menu, quick navigation, save/load menu and more can be fully customized to your heart's content...

...provided you have the corresponding coding knowledge for it XD Relax tho, as this guide will help you out in the creation of your own styles and UI.

One thing to remember when using custom styles are the IMAGEMAPS. Which are a little more than a set of images with hot spots attached to them

for navigation. There's code involved but nothing terribly complicated. And If you've read this far without your head exploding or going insane due to

my horrible explaining, then you'll be fine. :)




screen main_menu: The default style for your main menu. You'll heavily edit this section fairly soon as the factory style is painfully bland.

tag menu: This little commad is incredibly important when creating your custom screens as it replaces default styles with your own. Forgetting to tag

your menus will result in broken links, crashes or unresponsive buttons.

style mm root: the default hook for the main menu screen. You can leave it as it is, if you're using custom styles.

Main menu style: Style buttons for the main menu. You will heavily edit this section pretty soon as well. Unless for some ungodly reason you prefer to use

the incredibly simplistic menu style that comes by default.




save/load screen: Yet another fully customizable menu. Yay! You can make the save/load screen be square or pear shaped, have 30+ color presets

and huge golden bold letters if you like. The sky is not the limit, your creativity is after all, boundless.

preferences screen: And another menu that we will customize to meet your design choices. in this one however we will keep the editing of sections to a minimum

for the sake of simplicity and traditionalism. The preference screen features, window mode, enabling or disabling of transitions and effects,

skip functions, text speed, auto read mode speed, sound volume and music volume.




And that's it for the first part of this guide, kind sirs and madams. I thank you deeply for reading this far and bearing with my ugly prose and sorry attempts at explaining.

You are now one step ahead into programming your visual novel and we'll work together for the remainder of this process. Don't forget your passion for VNs

and don't lose motivation, programming a VN is hard but your efforts will certainly pay off. Do join me next time, when I'll be covering:

Customizations in detail and a sample scene for coding/scripting practice. Many thanks for your time and until then. See ya :D

Kind regards. Helvetica Standard.





Link to comment
Share on other sites

This is incredible (and way more fun to use than the Ren'Py wiki and cookbook)! Would you mind if we featured it around the site/social media/etc.?


Thanks! I thought everyone would go insane at the sight of such dense information! XD

And sure, I don't mind. Featuring this will help it spread an more people can benefit from it that way.

I'll be making some adjustments and add stuff I might have missed too. (including my horrid "skype-esque" penmanship) :P

Link to comment
Share on other sites

Great post, Helvetica.

That's a hard name, so I'll call you Veti instead.


I hope it gets pinned. <3


V-Veti? xD LOL.

Thanks. I'm glad you like it! This is part 1 and 4 more are on the way. :D

I just hope I don't get buried in work before I can release part 2. 


p.s. You have great taste. Loving that avatar and signature!  :wub:

Link to comment
Share on other sites

  • 11 months later...

Wow! Thank you very much for these guides you've made, I've bookmarked them all to read when I know I can commit to learning.

Skimming this guide briefly, I can already clearly see that you've put an insane amount of hard work into this.

Thanks for the download link, I am actually interested in looking into this and see how the creation process works. Who knows, maybe thanks to your guide, I may even create my own VN some day.

Again, I thank you very much for your hard work! ^_^

Link to comment
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.


  • Recently Browsing   0 members

    • No registered users viewing this page.
  • Create New...