Visual novel basic tutorial: programming in Ren’py.

2018.09.09, written by Kuna.

After finishing coding the demo for PBS, I thought that some other programmer rookies like me could have found useful a tutorial about basic programming with Ren’py! 

My aim is to summarize what I’ve learnt after coding a 35k-word script, focusing on those functions that allow a programmer to improve the narrative with expressiveness in order to stage a visual novel beautifully! 🌟

So if you’re already familiar with the basic of Ren’py (writing dialogues, showing backgrounds and sprites, etc.), I hope that here you’ll be able to find some useful tips to further polish your game! 

Enhance dialogues.

I think that writing the script for a visual novel is somewhere in between a novel and a game. To best express the narrative and the dialogues, you may need to use common tools as italic font as well as colored text.

I always find useful to write a list of the gimmicks I frequently use at the top of the script file. This way I can copy paste any of them in the dialogue/narrative any moment. (With the # I can basically use the script document as a notebook too!)

Be sure to have all the special characters you may need ready, like long-accented vowels, as well as the italic text code {i}{/i}. I personally use {w=0.2} to break dialogues after periods, {cps=10}{/cps} to slow down the text when a character is hesitant and {size=+04}{/size} when they’re screaming. I also use {outlinecolor=#FA4389}{/outlinecolor} to enhance in pink the words the player must pay attention too.

Useful effects.

Shake effect “vpunch”.

As for the text, there are a few, quick gimmicks to enhance the visuals as well. For example, having the screen shaking when a character is surprised can improve the immersion for the player. In Ren’py you can use the hpunch (=horizontal punch) and the vpunch (=vertical punch) functions to achieve this.

Just attach the with vpunch right after the dialogue line. Most of the time I also like to accompany the shaking with a deep sound, like a DOON, but, yeah, this depends on the atmosphere!

Flashing effect “Flash”.

Maybe you remember how games like Ace Attorney or Danganronpa have a flashing effect to accentuate revelation-like moments. Rendering that in Ren’py is very easy.

Once again, attach the with Flash at the end of your line and to achieve a similar result to Ace Attorney one, use a bell ring sfx just before the dialogue!

Mid-sentence flash/sound.

What if you want to be even more accurate and have the flashing effect happening mid-sentence? What if you want to have the sfx playing in that same moment too?

Let’s have a first line “Not that I…” and then, let’s replicate it in the next dialogue while setting the character-per-second (cps) count at zero. This way, only the “Not that I…” part will appear instantly as it had stayed there. Let’s attach the with Flash and we can play a sound right before the second line to enhance the flashing effect.

Instead, if we simply want to have a sound or a music track starting playing in the middle of a line of dialogue or in the middle of an animation, we can go about it differently.

Just by using brackets and setting the time of the silence with can have a pause before the track starts playing. 

Black fog.

One of the effects I’ve been frequently using while coding PBS is having the screen getting darker to make the reader focusing on the text only and enhance Kairi’s inner monologues.

Just as Kairi was wandering off for a moment, I’m having this black layer wrapping the background while staying transparent.

I defined bblack as a simple layer of black color:

Then I just show it with transparency alpha whenever the scene requires it.


We can also have the black layer appearing behind a character.

Since I named Fujisa’s sprite fu I will have the black layer being shown behind fu.

It’s useful to keep layers in mind for all kinds of scenes. This time it’s Fujisa’s turn to stay behind (the lines) for example. The other way would have looked odd, wouldn’t it?

Window hide/show.

Window show and window hide are useful commands that we can input to show and hide the textbox. It comes in handy when we want to perform transitions or show animations for example.

Ren’py make the textbox appear and disappear with a dissolve effect by default, but if we want to make that faster or slower we need to pay attention to the “grammar”:

We reached the end of the tutorial! 💥 Once again, this was meant to help tiding up the archive of effects Ren’py allows and to help programmer rookies finding their way into visual novel coding!

I believe that half of a visual novel’s programming is narrative, and the other half is expressiveness through visuals. That’s why I thought about having this kind of tutorial!

Thank you for reading! 🙌💜