RENPY TUTORIAL 01 - The Basics (Script Included)

Hello thar, Meinos Kaen here… And welcome to this tutorial video series for making games in Ren’py.

What is this series and why am I making it? Well, I am a game developer and recently, I decided to open one of our games -JPDE2: Adagio of Darkness- to community content, starting with making quests for the game.

As I was putting together the Game Design Document and reference materials, though, I noticed that most of the popular Video Tutorials for Ren’py are… Old. Crucially, they all start from before the 8.0 series, which brought us a lot of changes and new features for the engine as it is the first release which supports Python 3. This is a very big deal but, for the purposes of tutorial-making, it means that all these popular old tutorials are based on a version of Ren’py that is now deprecated.

So, since I was gonna need to make guides for Ren’py for the community anyway, I decided: what the heck. Let’s make a tutorial video series.

In this video, we’re going to learn the basics of Ren’py: we’re going to learn where to get it and how to create a new project; we’re going to learn how to get a Code Editor, which you will need to work on the game; we’re going to need how to add images and create speaking characters; and we’re going to learn some veeeeeeeeery basic image manipulation. Let’s go.

The first thing we’re gonna do is actually download Ren’py. Just go to your search engine or searchbar of choice, type in Ren’py -no need for the apostrophe, trust me- and the official website should be the top result. It’s a popular engine. Click on it and you will land on the Homepage. There’s some interesting information on here about the project, and it features a bunch of games made with it, there’s a database and a link to further documentation… For us, we just want to download the latest version. Click on the big green button.

On the download page, you’ll find downloads for a number of different installers. There’s one for Windows, one for Mac, one for Linux… Then there’s also some other versions and extra packages which are needed to build games for Android and Web… We’re not going to need them for the purposes of this or anytime soon. Also, I’m on Windows so let’s get that dot EXE.

Once it’s downloaded, boot it up and extract the program to a folder of your choosing. I’m going to extract it to my documents folder. Navigate to the folder you’ve just created and voila. Now, Ren’py was not actually installed so you’re not going to have an automatic shortcut on the desktop, nor are you going to find it searching from the Start Menu… So be sure to drag this renpy.exe file to your taskbar or create a link on the desktop, so you don’t need to go back to this folder every single time you want to boot up the software.

And speaking of which, boot it up and… Pronto. This is the basic look of Ren’py when you boot it up for the first time. Any download of Ren’py comes pre-packaged with a Tutorial Game, which is a game containing tips and tutorials for many aspects of the engine, and The Question: a proof of concept that showcases the basic capabilities of the engine. And I do say basic because, especially after the switch to Python 3, there’s so many things and kinds of game you can make with Ren’py… But, Ren’py on its own is not enough.

We also need a code editor. The one I use, and so does most of the internet, is called Visual Studio Code. Just like Ren’py, very easy: look up VSCODE and the first result should be the official site. Click on it and download the installer… There’s also the option of using the web version of the editor, VSCode.dev, which allows you to work on your code from any browser… Provided you have a Github account you can log into.

Github.com is a website which allows you to create online repositories of code and other kinds of files, which you and other collaborators can then work on collectively. Also, it allows you to back-up any files you’ve been working online directly from your code editor. I use it for all my projects, and it’s also where all the files for all the lessons in this tutorial series are going to be uploaded to.

After installing Visual Studio code, the next step is to tell Ren’py that that’s the Text Editor that we want it to use it by default… Go to preferences and you’ll see the setting for ‘Text Editor’ currently showing as ‘Not Set’. Click on it… And you’ll be brought to a page where you’re actually able to download Visual Studio code from inside Ren’py without needing to go find it on the Internet.

Now, if that is the case, why did I show the longer way around this too? For two reasons: one, you see that there’s an option to define any editor that you have associated with Ren’py files. Maybe you don’t like VSCode. Maybe you want to use a different text editor. Ren’py gives you that option. Two, I’ve been using Ren’py almost ten years now and, for all the stuff I’ve learned so far, there’s always something new and learning how to find information online is a crucial part of game development. I do it for Ren’py, I do it for Godot, I do it for Image Editing, and so on.

Sometimes it’s easy to find, sometimes you can find someone on a game development community forum or Discord Server that can help you, and other times you need to parse results in a search engine… Point being: if you’re stuck on anything, boot up a search engine and look it up. And do not just stop at the AI Generated results, they’re wrong or superficial half the time.

Once you’ve downloaded and properly set up your Text Editor, it’s time to create your base game. Go back to the Starting Page of the Ren’py Engine and click on CREATE NEW PROJECT. You’re going to be asked to name your game… Then the base resolution you want to run the game at, we’re going to go with 1920x1080 in this Tutorial… And finally to choose a color scheme for the standard User Interface… Once it’s done, ta-daaa. Your base game is going to appear in the Starting Page list, with the name you’ve given it.

Let’s boot it up. You’ll see that a Base Ren’py game so created, while nothing spectacular to look at, comes pre-packaged with all the basic needs for a Visual Novel type of game. An about page for your credits, a help page for the built-in commands, preference menu with built-in settings for your audio, display and text… Plus a load/save screen. And of course, a little two sentences scenario to test the look and feel of your user interface.

With the bare bones in place, it’s time to start adding our personal meat to this project. Which means: we need to add images to the project files; we need to tell the project to find them; and then we need to tell the project to use it.

Going back to the starting page of Ren’py, you’ll see under preferences the Project Directory setting. This is a path on your machine where Ren’py will search for projects to display on the Starting Page list. And it’s also where all new project folders are created. So, theoretically, you could just navigate there and find the path of the project you want to work on, but there’s actually a much faster way to get where you need to go.

Again, on the Starting Page. Make sure that the project you’ve selected is the JPDE TUTORIAL ONE… On the right, you’ll see two columns: Open Directory and Edit File. These are built-in shortcuts which make Ren’py open certain folders of your Project in File Explorer, and open certain files of your Project in your chosen Text Editor respectively. If you click on Open Project…

Your Ren’py game will be opened in Visual Studio code, with everything in your directory displayed on the Navigation Bar on the left. And when you click on Open Directory Game… Your project folder will be opened in the File Explorer. Just like that, no need to navigate or make shortcuts on your File Explorer or Desktop, none of that nonsense. Everything one click away from Ren’py.

Last thing you need to do in Visual Studio code before you’re ready to work on the game, is to click on this icon with the four cubes stacked in a bigger cube. That is the Extensions tab. Extensions are optional packages which you can download from the official Visual Studio Marketplace, which you can use to add extra features to your Editor. Most of them are free, and the one you absolutely need is the Ren’py language extension. As you see, I already have it installed, but you just need to write Ren’py in the top searchbar and... Presto.

Why do you need this. Well, Visual Studio is called Visual for a reason. Depending on the language, as long as the Editor knows it, it’s going to highlight different elements of a sheet of code in different ways which makes working on any software much easier, both on your eyes and your brain. Let me show you by going to open the script.rpy file of our project.

See what I mean? Every single part of the code, depending on the type of element it’s referring to, has a different colour. The Green Decorative Text with the hashtag signs are greened out, names of variables are light blue, commands are dark blue, strings between quotes are orange and so on... Now imagine instead having a sheet of code where everything is just white text against a black screen... You would have a much harder time parsing what’s what. And not just that! Having the extension also tells Visual Studio Code how to highlight errors, and lets him display on-screen tips and shortcuts... You’ll see as we work on this but, bottom line: you need to install the Ren’py language extension.

Now for the fun part: adding characters and images! For this tutorial, we’re going to use the RWBY character images which you can find on our team’s itch page at jpde.itch.io.. Scroll down the list of projects and you’ll find the Building Bunny Blocks asset pack... Which I really need to update, now that I think about it, but anyway: the pack contains a group of high resolution sprites from the original JPDE, Sonata of Fire. If you want, we do accept contributions for it but it’s otherwise free. And if you like this tutorial, be sure to like, comment, subscribe... And if you want to support development, think about becoming a Patreon subscriber or on Ko-Fi. You get exclusive previews, voting rights, early access to game builds and my undying gratitude.

Either way, download the package, extract it... And you may notice something... Spooky, about the expressions. Oooooh noooo, they stole their bodies...! You will notice that each package contains an image for a base body and then a bunch of different images, each one displaying a different expression... This is because these packages are prepared for a very particular and very useful way of displaying character sprites which we will see in a future video.

For now, you will find in the description a link to the pre-prepared images we will be using for this first lesson, which will only feature the bare-bone way of creating and displaying character images. Download it, extract it and grab the Penny folder from it. Open the file directory of your game, go to the images subfolder and drag the Penny folder to it... Now, if you go back to VSCode and open the project directory’s tree in the left sidebar, tadaaaa! The tree has been updated and the images have been added! And you can even preview them directly in the text editor! Beautiful! Hiii, Penny! We’re ready to use your images!

...except, actually, I don’t think I like it like this. Just having the Penny folder in the images folder, because, what about when I start adding other images? CG images, background images, item images, effects... Do I really want everything to be mixed up together in the same folder, with no organization whatsoever? It’s gonna get confusing really quick, especially in the Visual Studio file tree.

So let’s add a subfolder. We go back to the File Explorer, we create a new folder and we name it chs for Characters. Then we grab Penny’s sprite folder and we move it to this new subfolder we’ve created. And when we go back to Visual Studio code, you’ll see that once again the directory tree has updated automatically. No need to close and restart the software. This may seem nitpicky but, trust me: the more organized your directory is, the better is for you and for any future collaborators you might have. The file organization for JPDE1 Sonata of Fire was terrible, and it caused me no amount of headaches which I didn’t even realize I was making for myself until I got better as a game developer. File Directory hygiene is very important, everyone.

So, now that we’ve added Penny’s image files to the File Directory, are they ready to be used? Yes and no. Physically, they’re there, but the game doesn’t know that yet. We need to tell him that they’re there, and to do that we’re going to write our very first lines of actual code. Go to the top bar in Visual Studio and click on File... And then on New File. A bar will pop up asking you to name the file you want to create. I’m going to name it ch_scripts.rpy, which means we’re making a file that works with the Ren’py programming language. Enter, and then a new pop-up window will appear asking you where to place the newly created file.

Now, just like any other file, directory hygiene for your scripts is important. You could just have them all laying around in the top game root file of your game, but to make your life easy -and, again, in case you ever need to collaborate with anyone- I suggest to start making your own little tree of subfolders to neatly separate everything. In my case, I like to create another subfolder in the images folder and call it img_scripts. This is where I like to place different script files, each one for a different type of file. The one we’re creating, ch_scripts, is the script for character sprites.

Once created, Visual Studio code will open it automatically for the first time. As you can see, it’s empty -exception made for some automatic prompts by Visual Studio to get you started but you can ignore those-. It’s up to us to fill it in.

First, more organizational. We add a hashtag symbol on this line so that it’s purely decorative and we write Penny Ch Images. What I mean by Decorative lines? It means that this line of greened out text won’t actually be read as code by the Engine. For programming purposes, everything on this line is going to be ignored. It’s for human eyes only. So, again, a good organizational tool.

Next, we need to tell the engine about the existence of the images. Be sure to open the Penny folder in the Navigation Bar, as you’re gonna need it. First thing we need to write is simply ‘image’. This is a command that tells the engine that here we are defining an image object, which uses the built-in image class of Ren’py. Then, the name. As these are images for a character which will have different expressions, we’re gonna need to write the name of the character and the name of each expression separately. So first we write Penny, as we’re creating an image that belongs to the Penny character.

Now, let’s start with the Happy expression. We’re gonna write down happy (all lower case as that’s how I do things), then we add an equals sign and then we open quotes. Inbetween these quotes, we now need to write the path to the image as in: if I was a person, wanting to find this image in the file directory, what path would I need to take starting from the ‘game’ root folder of this project? For Penny’s happy expression, it goes images/chs/penny/happy.png. And there we go. Just like that, we’ve created our first image, which is an expression of the Penny character sprite. Remember to keep the name of the character and the name of the expression separated whenever you create images like this, for reasons you will see in a little bit.

For now, let’s try using the image! We’ve told the engine that it exists but now, how do tell Ren’py to actually use it? Let’s go back to the script file. As you can see, the default example script uses the command ‘show’ to showcase the sprite named Eileen with the expression called happy on the screen. Show is a general use command that you will use a lot to call to the screen a lot of visual objects. In this case, it’s used to showcase a sprite... But we want it to showcase our Penny sprite, not Eileen. So what do we do?

We go from show Eileen happy to show Penny happy. That’s it. We’ve now told Ren’py to use, at that line in the code sequence -which always go from the top to the bottom- to show the sprite belonging to the character Penny with the expression ‘happy’. Let’s test it! We go back to Ren’py, be sure we select the correct project and then we launch it...

And ta-daaaaaa! We have ourselves a Penny on the screen... Except she’s become a GIANT WOMAN! What is happening?! Why is Penny so big? Also, the text still displays the name ‘Eileen’ but one thing at the time.

Why the giant woman? Well, that would be because of the size of the sprite image I created when compared to the current resolution of the game. Remember when we created the project and it asked us what resolution we wanted to use and we said ‘1920x1080’? That’s Full HD, yes, but the sprites that I have for the RWBY characters are actually made with 4k screens in mind, which are double the size in pixels: 3840 x 2160, which is why they’re so big.

Now, you are asking yourself: Meinos, why did you do that? The real question is: what are the advantages of having such big sprites even when using a smaller resolution? Why not just make the sprites fit the screen? Well, again, that is because of my design philosophy and the way I write, direct and edit scenes in a game. There are a lot of cases where having such a big sprite is useful and, while the are methods to make images bigger or smaller using code, when you blow up the size of a small sprite the image will look grainy and ugly and blurred, on account of the stretching that happens. That is very ugly, I don’t like it, neither should you.

On the other hand, making a bigger image smaller does not cause any such artefact. So, when in doubt, go big, and make them smaller from there. Before showing you how to do that, let’s add a couple more expressions for Penny’s character sprites with a few other methods compared to the first one I showed you. Which consisted of typing down the command image, then the name of the character, the name of the expression and then the equals sign followed by the path of the image between quotes.

Now, you can image that can get very tedious very fast. So, is there a better way? Two, actually, that I use regularly alongside the first one. Each has different uses and depending on what you’re doing, you may use one or another.

For the second one, select the entire line where we defined the happy expression. Go to the next line and paste it in. You will notice that I named the image itself happy.png too, in the same lower case as the expression in the code, and this is the reason why. That way, all I need to do here is replace happy with the name of the next expression, in this case ‘cry’. That’s it.

An alternative way of doing this exact same thing is by using a keyboard shortcut. Once again, select the entire line where we defined the Happy expression for Penny and paste it on a new line. Then highlight the word happy and, by using control F, you will open up the find and replace screen -the default is just search but if you click on the little arrow on the left, it will expand to include the replace field.

Just write down the name of the new expression... Let’s say ‘blush in the replace field and enter. Enter. And for each ‘Enter’, one occurrence of the word happy has been replaced. Then, since we’ve reached the end of the sheet, it looped back around and went to the top again, where the first occurrence of the word happy is. This is a very useful tool, and I use it A LOT. Like, a lot a lot. The way I use it the most is: I tend to have all of my characters have the same set of expressions, with only exceptional variations. At the very least, all of my character sprites have a happy/sad/laugh/pain/surprise/shock set of expressions.

So, instead of having to do this for every expression for every character every single time, what I do is: I just copy the code of a previous character, change the name of the character from the old one to the new one, and then adjust for any extra or different expressions. Learn to familiarize yourself with the Find and Replace tool, it’s going to save you a lot of time on a lot of things.

The last method to add an image is the Drag and Drop method. Let’s say that this time we want to add the... Blank expression. But instead of typing it out or copying another line and then replacing what’s needed, we’re going to just write image Penny blank and the equal sign. Then, go to the navigation tree and drag the image you want to code to the code field while holding down the shift key. This is important, hold down the shift key, otherwise it’s just going to open a preview of the image... And ta-da! Easy copy of the image path!

And you can see here that you have two options for this. Relative Path and just Path. The difference is that Relative Path will copy the path of the item relative to the game you’re working on, while just Path will copy the path of the item relative to your machine. Relative Path is the one you want, of course... And after you copy dragged it like this, all that’s left to do is: remove the first part, which is game plus slash. We do this because game is the root folder of the game, and when you write down any path for a file in Ren’py, it automatically starts the search from there. So if we left ‘game’ here, it would start looking for a ‘game’ folder inside the root ‘game’ folder and would give us an error. We don’t want that.

So we remove it, we start the file path from ‘images’, and then we wrap it between quotes... And our images are ready! Let’s test it out again and this time I want to clean up the code a little, remove these hashtagged out instructions that came with the base Ren’py game, adjust things a little... Then, I’m going to create a new empty line inbetween the two lines of dialogue, and there we’re going to write show Pennyyyyy... Blush. There. And we save. Always save, otherwise even if you launch the game again your changes won’t be registered. Let’s see what we got.

Just like before, image is still too big, but that’s fine. Pay attention to Penny’s face... And there! The expression has changed without adding another new image on top of it. This is because, when we defined the images, we wrote them so that Ren’py recognizes them all as expressions belonging to the same displayable: Penny! Now, though, she’s still big... And the text still says Eileen. Let’s fix the text first.

What we’re going to do next is define a Character, which is another of the built-in classes of objects that comes pre-packaged with Ren’py. Once you define the Character object, every time you call it and follow it up with a string of dialogue between quotes, Ren’py will automatically understand that we want a dialogue box to appear, with that character’s name and the dialogue in the string. So, how do we define a character.

The default script.rpy has an example with Eileen’s character. There’s a lot more stuff you can decide when defining a speaker character on top of their name, but that’s for a future lesson. For now, all we need to make Penny speak is: define... Which is a command which creates a constant variable or object, aka: something that you don’t intend to change during a playthrough. Then, the call name of the speaker character, the word or letter you’re gonna use to call them. It’s Penny and it’s the only character in the game so we’re gonna use the letter P.

Then we add the = sign, followed by Character with a capital C, to make Ren’py understand that we’re creating an object belonging to that Class... Then parenthesis, and within those parenthesis a string of text between quotes. Penny. And there we go, it’s as simple as that. Define, call name for the speaker, equal sign, Character, parenthesis and inside the parenthesis the name of the character between quotes. Now it’s ready to use.

Let’s delete the dialogue strings for Eileen and replace them with some for Penny. The way you tell Ren’py to display dialogue, again, it’s by calling a speaker Character object with its call name and then following it up with a string of dialogue between quotes. So, for the Penny character we just created we gotta call it with the letter p. And we test it... Yes! Penny is now speaking to us, from the height of her giantness! Honestly, creating speakers and then using dialogue is so easy in Ren’py.

And if this is all you wanted to do with the program, this is all you need to know. You know how to create new characters, you know how to make them speak, you know how to display images and create expressions... That’s it. You can make a very basic game if all you need to do is speak in first person point of view to one character at the time. But if I know you budding, passionate creator, you want to do more. Also, there’s still the giant Penny to deal with. Which is why I’m now going to teach you about... Transforms.

Transforms are commands you can use to... Transform displayables in Ren’py. There are a bunch of built-in ones, and you can even create your own so that your images get procedurally modified without the need to call them again every single time. You can use them with sprites, backgrounds, screens, text... Everything. The ones I’m going to show you now are the three basic transforms anyone using Ren’py should know about, in my opinion. And I’m going to show you how to use them on the spot, ad hoc. The simplest and brute force way.

First of all, to apply transforms to an image you need to put a colon at the end of the line where you first display it. Then, you go to the next line below and tab to the right. This is code logic, and it’s very important. When you tab right below a line that ends with a colon, you tell the software that everything you write on this line is relative to the one above.

Secondly, the transforms get applied not to the single iteration of the displayable but to the image object. What does this mean? It means that we only need to call these transforms the first time we display the sprite, and it’s going to keep those modifications memorized even if we change the expression because, the way we created them, we told Ren’py that those are all expression of the same character image object. We’re gonna write them underneath show Penny happy but not underneath show Penny blush, because it’s unneeded. Ren’py will memorize the transforms we give the image object and not change them until one of two things happens.

The first is, of course, if we change transform by calling it again and giving it a new value. That will overwrite the value that was already memorized, only for whatever specific transform we’re modifying. If you first give an image transform A and transform B, and then later modify transform B, transform A will stay unchanged. The second thing is if we change scenes.

The scene command is a very particular command, which tells Ren’py to take an image and display it on the background layer, which is by default behind everything else on the screen... But also, it resets every single displayable on the screen. When you call an image with screen, that image will become the new background for your scene, and every single image that was on the screen before you called the new background will disappear. You’ll need to call them again, and if you gave the images transforms, you’ll need to give those transforms to those images again. I’ll show you what that looks like next, but for now let’s transform Penny.

She’s way too big so, the transform we want to use is the ‘zoom’ transform. As it says, it zooms an image in or out. The way you define transforms is with a keyword -zoom, in this case- and then a float value. A float is an arithmetic number, a number that is followed by a dot and a subdecimal. When there’s no dot and subdecimal, it’s called an integer. Math terms!

The float value works like this. 1.0 is the original value, meaning in this case it’s the original size of the Penny sprite object. If we turned it up to 2.0, we would make the image twice as big! But in this case we want to make it smaller, so we’re going to make it 0.5 and turn it to half its original size... Aaand save.

And there we go! We can now see the sprite in all its full glory! Penny is cute no matter the size, isn’t she? But now we got another problem: the positioning! By adding one transform, Ren’py isn’t using the default positioning for the show command anymore. Which means that the values for both horizontal positioning and vertical positioning are 0.0, right now. Which translates to the top left corner of the screen... To fix that, we need add two more transforms!

The first is xalign, which moves the image you use it on along the X axis, which goes from left to right on a 2D screen. In this case, a 0.0 float value means the extreme left on the screen, while a 1.0 means the extreme right of the screen. You can actually go negative or above 1, and that will move the image off the screen, but that’s not we need in this case. The value we’re going to use is, once again, 0.5 which will move the image to the horizontal middle of the screen. Save and test...

And there we go. Penny has been horizontally centered but she’s still looking like she’s floating on air, there, doesn’t she? And that’s where Y Align comes in.

Yalign is the transform that aligns the image along the Y axis which, in a 2D screen, goes from up to down. So a 0.0 value means the extreme top of the screen, while 1.0 means the very bottom... And in this case, we want the bottom of our image to align with the bottom of the screen so we’re going to use a 1.0 value. Save and test... And there we go! Penny is right where we wanted her, now: her sprite fits the screen, she’s horizontally centered and her sprite’s feet are connecting with the bottom of it.

So we’ve learned the basic way of using transforms and, as I said, these are the three transforms that I think everyone should know, as they allow you to manipulate images in a simple way and not restrict yourself to only one displayable at one time. Zoom, Xalign, Yalign.

The very last thing I want to show you, today, is what using a scene command to change scenes and background does. To do that, we’re going to need to define the images for the background the same way we defined the images for Penny but without expressions, this time. We want them to be separate image objects. The process is the same, so I’m just gonna speed up through it. Drag a new folder with the new files to the directory, under images... Then we create a new images file, just for backgrounds... We define the new images vale_day and vale_night (these are images from the JPDE series, by the way, so that’s our version of Vale City from RWBY...).

And finally, we use the images like so. We’re going to start by changing the scene background to vale_day and then, after the first string of dialogue, we change it again to vale_night. Now, if you remember from earlier in the video, I said that anytime we change a scene with this command, everything else image wise gets reset. So what do you think it’s going to happen to Penny’s sprite? Let’s test it out.

There we go, beautiful Vale in daytime with perfect size Penny in the foreground. Because we gave her the right transforms... But when we switch to Vale at night, since it’s a new Scene... It’s like we’re calling the Penny image for the first time, because for this new scene we find ourselves in, it is! And because we didn’t modify any of the transforms, the image defaulted to the original size and the default positioning...

And that is it! These are the basics of Ren’py. You now know how to add images for characters, how to change images in the background and switch scenes, how to add speakers and write dialogue. And before all that, you know to properly set a project in Ren’py up.

Let me know in the comments if you found this tutorial useful, any questions or hot takes you might have, and like and subscribe so you won’t miss the moment the next video tutorial comes out. In the description, you will find a link to the Github, where you can download the project we’re going to be working on, and the notes for this lesson. I hope to see you on the next video and if you’re making your own personal projects, I’d love to see you around the JPDE community server! Ciao!