Advanced Ren’Py: Part 1: Screen Language


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.

Beyond the showing of text and images, Ren’Py can also be extended through introducing new user interface elements, changing its defaults images, and combining Python with its own code to create even more interactive projects.


Screen Language

Ren’Py has its own internal way of displaying different user interface elements. It calls this the “screen language“. It is through this language that many things like the say and menu screens work.

Using the screen language, developers can create additional user interface elements and reactions through using screens.

Screenshot 2018-07-05 03.54.49

The code for a new screen need not be complex. It can be as simple as defining something as a screen and using one of a number of different displayable (things which can be displayed) within it.

Screenshot 2018-07-05 03.56.33

For example, defining hello_world to be a screen and using the text “Hello, world.” will display the text in the upper, left-hand corner. Once defined in the file “custom_screens.rpy” in the same project, it can be show through including the keywords show screen in the “script.rpy” file.

Screenshot 2018-07-05 03.59.44

In the above image, it is included on lines 16 – 18 and thus shown with other elements within an example, default project.

Screenshot 2018-07-05 04.01.49


To help with common arrangements using screens, Ren’Py has two frequently-used special keywords: hbox and vbox.



To help with arranging elements, the screen language in Ren’Py has hbox, a horizontally-defined box. When elements are put in this box, the elements run horizontally.

Screenshot 2018-07-05 04.05.56

Through using hbox, any new element is added and extends the box to the right.

Screenshot 2018-07-05 04.09.25



To help with arranging elements, the screen language in Ren’Py has vbox, a vertically-defined box. When elements are put in this box, the elements run vertically.

Screenshot 2018-07-05 04.11.15

Through using vbox, any new element is added and extends the box down.

Screenshot 2018-07-05 04.12.29


To help with holding multiple user interface elements, the screen language of Ren’Py has a container called a fixed. Unlike either hbox or vbox, it can use both to define more complex visual arrangements.


A fixed is a container for using multiple arrangement and other user-interface elements at the same time.

Screenshot 2018-07-05 04.18.58

Like hbox and vbox, it can contain multiple displayables.

Screenshot 2018-07-05 04.21.44


To help with creating a single window for containing a single child (grouping or element), the screen language in Ren’Py has a frame.



Much like a fixed, a frame can contain other displayable elements. However, while fixed can contain multiple, frame is designed to hold a single element or grouping. (If more are used, a fixed is created.)

frame also, like its name implies, has a default border, a framing.

Screenshot 2018-07-05 04.29.39

Like a fixed, it is also used with other elements.

Screenshot 2018-07-05 04.30.40


Beyond vbox and hbox, the screen language of Ren’Py also has the ability to create fixed layouts called a grid.



Instead of using increasing complex sets of hbox and vbox, a grid can be used to simply layouts into rows and columns.

Screenshot 2018-07-05 04.36.01

Defined with the number of rows and then columns, a grid can help with layout options.

Screenshot 2018-07-05 04.37.19


For those collections which go beyond the edge of the screen or contain more elements that can be shown at one time, the screen language of Ren’Py has a viewport.



viewport creates a container that can contain single element or grouping with the ability to add scrollbars.

Screenshot 2018-07-05 04.51.03

Through adding many elements or enough that they cannot be shown at one time, a viewport allows for scrolling through them.

Screenshot 2018-07-05 04.54.26

Note: In the above example, additional position style properties, xmaximum and ymaximum, are used to limit the size and force the appearance of greater scrollbar length. The properties draggable and scrollbars are also used, set to True and “vertical”.


For instances where a viewport is needed, but the layout should conform to a row-column layout, a combination of the two, vpgrid can be used.



Using both a grid and the ability to add scrollbars like in a viewport, a vpgrid uses both to arrange its element or groupings

Screenshot 2018-07-05 05.08.37

Unlike grid, its properties must be explicitly defined as rows and columns.

Screenshot 2018-07-05 05.12.34

Note:  In the above example, an additional style property, spacing, is used to defined the space between one element and the next in the group.

Finally, the screen language of Ren’Py has a more generic type of container called a window.



Other containers like frame are based on window.

Screenshot 2018-07-05 05.16.40

Like frame, it can hold other elements.

Screenshot 2018-07-05 05.19.56