Working with Ren’Py: Part 3: Scenes and Showing Images


Working with Ren’Py:

Advanced Ren’Py:

Customizing Ren’Py:

Ren’Py + Python:

Ren’Py is a engine for creating visual novels. It comes with a suite of tools for taking code and transforming it into programs that can be run on Windows, Mac, Linux, and even, with a little more work, mobile platforms like Android and iOS.



While text is a large part of most visual novels, many, if not all, also incorporate images at different points. Using images with Ren’Py generally requires two things: an image in the recommended file formats of WEBP, PNG, or JPG, and the use of a keyword such as scene or show.

Images, like menus and buttons, are shown on layers. Ren’Py has four default layers.

  • Master: where background and character images are shown
  • Transient: used by user interactions functions
  • Screens: used by the screen system
  • Overlay: used when a user interface function is called from within an overlay function

Usually, images are shown with the master layer. Unless part of a user interaction or created as part of a screen, images are shown and hidden from this layer.


In Ren’Py, the use of the scene keyword clears all current images and replaces them with a new image. Often, this is used through clearing any background or character images and showing a new image to set a new ‘scene’ through the use of a new background image.


Open the “script.rpy” file from “The Question”.


Lines 16 – 19 shows an example of using the scene keyword. In this case, it is used with “bg lecturehall” and tells Ren’Py to first clear out all current images and, second, to show the image “bg lecturehall”.


Opening the “images” folder for the “The Question” project shows it contains many images with different names. When the scene or show keyword is used in Ren’Py, it looks for images that match the name, tags, or attributes of what was used with the keyword.

Note: Ren’Py uses the words “tags” and “attributes” to mean additional words in the name of a file. To better help organize files, naming them “sylvie normal” for the default image of a character and then “sylvie smile” for when the character is smiling, for example, can create a shorthand for the different images associated with a single character. The “normal” and “smile” words would be considered its tags or attributes.

On line 17, the full line “scene bg lecturehall” tells Ren’Py to look for an image called “bg lecturehall” and then to show it. Since there is an image with the same name in the “images” folder, it is then shown.

Note: The with keyword can be used to create effects. It is not covered in this part, but can be used with the scene and other keywords to create transition effects.


Like lines 16 – 19, lines 29 – 32 show another example of the scene keyword. Here, like the earlier usage, the scene keyword is used to have Ren’Py to clear away any current background or character images, look for an image with the name “bg uni”, and then show it.


Beyond the scene keyword, it is often useful to show an image on top of another. Usually, this is used to show a character on a screen on top of some background.

In “The Question”, this appears early on with the background (“bg uni”) and the character (“sylvie green normal”) images stacked together.


Frequently, the show keyword, like in the above example, is used after the scene keyword. In this combination, the first is used to establish a new scene and the second to show a character either as the source or object of some dialogue or internal narration.


Lines 29 – 39 shows this same combination of scene and show. First, on lines 30 – 31, a new scene is established and the image “bg uni” is shown. Then, at lines 35 – 36, the show keyword is used to look for and show the image “sylvie green normal”.

When used in this order, first scene and then show, the images are stacked and the character image appears over the background one.


When used with the keyword show, an image can be be hidden, or removed from the current layer. This can help with showing when a character is speaking or if dialogue is directed at a new character or object.

It is recommended to use hide sparingly and, whenever possible, to simply use additional tags or attributes in images to achieve the same effect.

For example, instead of hiding and then showing the same character, —

hide eileen
show eileen happy

— the developers of Ren’Py recommend the following:

show eileen happy