documentation index ◦ reference manual ◦ function index

Overlays

Overlays are used to display information above the scene currently displayed. The overlay is regenerated each time an interaction with the user begins, making it suitable for displaying to the user things like statistics or dates. The overlay is generally displayed whenever transient things (like dialogue, thoughts and menus) are.

Overlays are set up by adding to the config.overlay_functions list a Python function which, when called, uses the ui functions to add widgets to the screen. By default, such widgets are added to the 'overlay' layer, but a call to ui.layer can change the layer to any of the layers listed in config.overlay_layers. These functions are called for each interaction, which allows the overlay to change to reflect the status of game variables. If a variable affecting the overlay changes during an interaction, renpy.restart_interaction should be called to regenerate the overlay.

As an example, take the following code fragement. When added to a program, this displays a date image in the upper-right corner of the screen (as is done in Kanon). The image shown is based on the variable date. If date is None, then no date is shown. Otherwise, a png file beginning with the value of date is shown.

init:
    $ date = "mar25"

    python hide:
        def date_overlay():
            if date:
                ui.image(date + ".png",
                         xpos=1.0, xanchor="right",
                         ypos=0.0, yanchor="top")

        config.overlay_functions.append(date_overlay)

Like all config variables, config.overlay_functions should only be changed in an init block. If you need to toggle an overlay on and off, then the overlay function should be conditioned on some normal variable. This is done in the example above when date is None.