Screens and Python link

Ren'Py supports defining screens in Python, as well as in the Ren'Py screen language. A Python screen is created by supplying a screen function to the renpy.define_screen() function. It can then be used like it was any other screen.

The screen function should have parameters corresponding to the scope variables it expects, and it should ignore extra keyword arguments. (That is, it should have **kwargs at the end of its parameter list.) It is then expected to call the UI functions to add displayables to the screen.The screen function is called whenever an interaction starts or restarts.

To ensure that this restarting is seamless to the user (and not causing things to reset), it's important that every call to a UI function supply the id argument. As a screen is re-created, Ren'Py will update each displayable with the contents of the old displayable with the same id. Ids are generated automatically by the screen language, but when doing things by hand, they must be manually specified.


UI Functions are deprecated and not recommended.

Here's an example Python screen:

init python:
    def say_screen(who, what, **kwargs):

        ui.text(who, id="who")
        ui.text(what, id="what")


    renpy.define_screen("say", say_screen)

Screen Functions link

The following functions support the definition, display, and hiding of screens.

renpy.call_screen(_screen_name, *args, **kwargs) link

The programmatic equivalent of the call screen statement.

This shows _screen_name as a screen, then causes an interaction to occur. The screen is hidden at the end of the interaction, and the result of the interaction is returned.

Positional arguments, and keyword arguments that do not begin with _ are passed to the screen.

If the keyword argument _with_none is false, "with None" is not run at the end of end of the interaction.

If the keyword argument _mode in kwargs, it will be mode of this interaction, otherwise it will be "screen" mode.

renpy.predicting() link

Returns true if Ren'Py is currently predicting the screen.

renpy.start_predict_screen(_screen_name, *args, **kwargs) link

Causes Ren'Py to start predicting the screen named _screen_name with the given arguments. This replaces any previous prediction of _screen_name. To stop predicting a screen, call renpy.stop_predict_screen().

renpy.stop_predict_screen(name) link

Causes Ren'Py to stop predicting the screen named name.

renpy.variant(name) link

Returns true if a name is a screen variant that can be chosen by Ren'Py. See Screen Variants for more details. This function can be used as the condition in a Python if statement to set up the appropriate styles for the selected screen variant.

name can also be a list of variants, in which case this function returns True if any of the variants is selected.

UI Functions link


The implementation of Ren'Py has changed, and UI functions that create displayables can now be far slower than their screen language equivalents.

The UI functions are Python equivalents of the screen language statements. For each screen language statement, there is a ui function with the same name. For example, ui.text corresponds to the text statement, and ui.add corresponds to the add statement.

There is a simple mapping between screen language parameters and arguments and Python arguments. Screen language parameters become positional arguments, while properties become keyword arguments. For example, the screen language statement:

text "Hello, World" size 40 xalign 0.5


ui.text("Hello, World", size=40, xalign=0.5)

(It really should have an id parameter added.)

There are three groups of UI functions, corresponding to the number of children they take.

The following UI functions do not take any children.

  • ui.add
  • ui.imagebutton
  • ui.input
  • ui.key
  • ui.label
  • ui.null
  • ui.text
  • ui.textbutton
  • ui.timer
  • ui.vbar
  • ui.hotspot
  • ui.hotbar
  • ui.spritemanager

The following UI functions take a single child. They must be given that child – use ui.null() if the child is missing.

  • ui.button
  • ui.frame
  • ui.transform
  • ui.window
  • ui.drag

The following UI functions take multiple children. They continue taking children until ui.close() is called.

  • ui.fixed
  • ui.grid
  • ui.hbox
  • ui.side
  • ui.vbox
  • ui.imagemap
  • ui.draggroup

There are a few UI functions that do not correspond to screen language statements, as they correspond to concepts that are not present in the screen language.

ui.adjustment(range=1, value=0, step=None, page=None, changed=None, adjustable=None, ranged=None, force_step=False) link

Adjustment objects represent a value that can be adjusted by a bar or viewport. They contain information about the value, the range of the value, and how to adjust the value in small steps and large pages.

The following parameters correspond to fields or properties on the adjustment object:

The range of the adjustment, a number.
The value of the adjustment, a number.

The step size of the adjustment, a number. If None, then defaults to 1/10th of a page, if set. Otherwise, defaults to the 1/20th of the range.

This is used when scrolling a viewport with the mouse wheel.


The page size of the adjustment. If None, this is set automatically by a viewport. If never set, defaults to 1/10th of the range.

It's can be used when clicking on a scrollbar.

The following parameters control the behavior of the adjustment.


If True, this adjustment can be changed by a bar. If False, it can't.

It defaults to being adjustable if a changed function is given or if the adjustment is associated with a viewport, and not adjustable otherwise.

This function is called with the new value when the value of the adjustment changes.
This function is called with the adjustment object when the range of the adjustment is set by a viewport.
If True and this adjustment changes by dragging associated viewport or a bar, value will be changed only if the drag reached next step. If "release" and this adjustment changes by dragging associated viewport or a bar, after the release, value will be rounded to the nearest step. If False, this adjustment will changes by dragging, ignoring the step value.
change(value) link

Changes the value of the adjustment to value, updating any bars and viewports that use the adjustment. link

Specifies a transform that is applied to the next displayable to be created. This is largely obsolete, as all UI functions now take an at argument.

ui.close() link

Closes a displayable created with by a UI function. When a displayable is closed, we add new displayables to its parent, or to the layer if no displayable is open.

ui.detached() link

Do not add the next displayable to any later or container. Use this if you want to assign the result of a ui function to a variable.

ui.interact(roll_forward=None, mouse='default') link

Causes an interaction with the user, and returns the result of that interaction. This causes Ren'Py to redraw the screen and begin processing input events. When a displayable returns a value in response to an event, that value is returned from ui.interact, and the interaction ends.

This function is rarely called directly. It is usually called by other parts of Ren'Py, including the say statement, menu statement, with statement, pause statement, call screen, renpy.input(), among many other functions. However, it can be called directly if necessary.

When an interaction ends, the transient layer and all screens shown with transient=True are cleared from the scene lists.

The following arguments are documented. As other, undocumented arguments exist for Ren'Py's internal use, please pass all arguments as keyword arguments.

The information that will be returned by this function when a roll forward occurs. (If None, the roll forward is ignored.) This should usually be passed the result of the renpy.roll_forward_info() function.
The style of mouse cursor to use during this function.
ui.layer(name) link

Adds displayables to the layer named name. The later must be closed with ui.close().

ui.screen_id(id_, d) link

Assigns the displayable d the screen widget id id_, as if it had been created by a screen statement with that id.

Actions link

Many of the displayables created in the screen language take actions as arguments. An action is one of three things:

  • A callable Python object (like a function or bound method) that takes no arguments.
  • An object of a class that inherits from the Action class.
  • A list of other Actions.

The advantage to inheriting from the Action class is that it allows you to override the methods that determine when a button should be sensitive, and when it is selected.

class Action link

To define a new action, inherit from this class. Override the methods in this class to change the behavior of the action.

__call__(self) link

This is the method that is called when the action is activated. In many cases, returning a non-None value from the action will cause the current interaction to end.

This method must be overridden, as the default method will raise NotImplemented (and hence cause Ren'Py to report an error).

get_sensitive(self) link

This is called to determine if the button with this action should be sensitive. It should return true if the button is sensitive.

Note that __call__ can be called, even if this returns False.

The default implementation returns True.

get_selected(self) link

This should return true if the button should be rendered as a selected button, and false otherwise.

The default implemention returns False.

get_tooltip(self) link

This gets a default tooltip for this button, if a specific tooltip is not assigned. It should return the tooltip value, or None if a tooltip is not known.

This defaults to returning None.

periodic(self, st) link

This method is called once at the start of each interaction, and then is called periodically thereafter. If it returns a number, it will be called before that many seconds elapse, but it might be called sooner.

The main use of this is to call renpy.restart_interaction() if the value of get_selected or get_sensitive should change.

It takes one argument:

The number of seconds since the screen or displayable this action is associated with was first shown.
unhovered(self) link

When the action is used as the hovered parameter to a button (or similar object), this method is called when the object loses focus.

To run an action from Python, use

renpy.is_selected(action) link

Returns true if action indicates it is selected, or false otherwise.

renpy.is_sensitive(action) link

Returns true if action indicates it is sensitive, or False otherwise. link

Run an action or list of actions. A single action is called with no arguments, a list of actions is run in order using this function, and None is ignored.

Returns the result of the first action to return a value.

BarValues link

When creating a bar, vbar, or hotbar, a BarValue object can be supplied as the value property. Methods on the BarValue object are called to get the adjustment and styles.

class BarValue link

To define a new BarValue, inherit from this class and override some of the methods.

get_adjustment(self) link

This method is called to get an adjustment object for the bar. It should create the adjustment with ui.adjustment(), and then return the object created this way.

This method must be overridden, as the default method will raise NotImplemented (and hence cause Ren'Py to report an error).

get_style(self) link

This is used to determine the style of bars that use this value. It should return a tuple of two style names or style objects. The first is used for a bar, and the second for vbar.

This defaults to ("bar", "vbar").

get_tooltip(self) link

This gets a default tooltip for this button, if a specific tooltip is not assigned. It should return the tooltip value, or None if a tooltip is not known.

This defaults to returning None.

replaces(self, other) link

This is called when a BarValue replaces another BarValue, such as when a screen is updated. It can be used to update this BarValue from the other. It is called before get_adjustment.

Note that other is not necessarily the same type as self.

periodic(self, st) link

This method is called once at the start of each interaction. If it returns a number of seconds, it will be called before that many seconds elapse, but it might be called sooner. It is called after get_adjustment.

It can be used to update the value of the bar over time, like AnimatedValue() does. To do this, get_adjustment should store the adjustment, and periodic should call the adjustment's changed method.

InputValue link

When creating an input, an InputValue object can be supplied as the value property. Methods on the InputValue object are called to get and set the text, determine if the input is editable, and handle the enter key being pressed.

class InputValue link

To define a new InputValue, inherit from this class, override some or all of the methods, and set the value of the default field.

default link

If true, the input is eligible to be editable by default. (That is, it may be given the caret when the screen is shown.)

get_text(self) link

Returns the default text of the input. This must be implemented.

set_text(self, s) link

Called when the text of the input is changed, with the new text. This must be implemented.

enter(self) link

Called when the user presses enter. If this returns a non-None value, that value is returned from the interacton. This may also raise renpy.IgnoreEvent() to ignore the press. Otherwise, the enter-press is propagated to other displayables.

The following actions are available as methods on InputValue:

Enable() link

Returns an action that enables text editing on the input.

Disable() link

Returns an action that disables text editing on the input.

Toggle() link

Returns an action that toggles text editing on the input.

Creator-Defined Screen Language Statements link

Ren'Py supports defining custom screen language statements. Creator-defined screen language statements are wrappers for the screen language use statement. Positional arguments remain positional arguments, properties become keyword arguments, and if the statement takes a block, so does the use statement. For example, the custom screen language statement:

titledwindow "Test Window":
    icon "icon.png"

    text "This is a test."


use titledwindow("Test Window", icon="icon.png"):
    text "This is a test."

Creator-defined screen language statements must be registered in a python early block. What's more, the filename containing the creator-defined statement must be be loaded earlier than any file that uses it. Since Ren'Py loads files in Unicode sort order, it generally makes sense to prefix the name of any file registering a user-defined statement with 01, or some other small number.

Creator-defined screen language statements are registered with the renpy.register_sl_statement function:

class renpy.register_sl_displayable(name, displayable, style, nchildren=0, scope=False, replaces=False, default_keywords={}, default_properties=True) link

Registers a screen language statement that creates a displayable.

The name of the screen language statement, a string containing a Ren'Py keyword. This keyword is used to introduce the new statement.

This is a function that, when called, returns a displayable object. All position arguments, properties, and style properties are passed as arguments to this function. Other keyword arguments are also given to this function, a described below.

This must return a Displayable. If it returns multiple displayables, the _main attribute of the outermost displayable should be set to the "main" displayable - the one that children should be added to.

The base name of the style of this displayable. If the style property is not given, this will have the style prefix added to it. The computed style is passed to the displayable function as the style keyword argument.

The number of children of this displayable. One of:

The displayable takes no children.
The displayable takes 1 child. If more than one child is given, the children are placed in a Fixed.
The displayable takes more than one child.

The following arguments should be passed in using keyword arguments:

If true, and the displayable replaces a prior displayable, that displayable is passed as a parameter to the new displayable.
The default set of keyword arguments to supply to the displayable.
If true, the ui and position properties are added by default.

Returns an object that can have positional arguments and properties added to it by calling the following methods. Each of these methods returns the object it is called on, allowing methods to be chained together.

add_positional(name) link

Adds a positional argument with name

add_property(name) link

Adds a property with name. Properties are passed as keyword arguments.

add_style_property(name) link

Adds a family of properties, ending with name and prefixed with the various style property prefixes. For example, if called with ("size"), this will define size, idle_size, hover_size, etc.

add_prefix_style_property(prefix, name) link

Adds a family of properties with names consisting of prefix, a style property prefix, and name. For example, if called with a prefix of text_ and a name of size, this will create text_size, text_idle_size, text_hover_size, etc.

add_property_group(group, prefix='') link

Adds a group of properties, prefixed with prefix. Group may be one of the strings:

  • "bar"
  • "box"
  • "button"
  • "position"
  • "text"
  • "window"

These correspond to groups of Style Properties. Group can also be "ui", in which case it adds the common ui properties.

class renpy.register_sl_statement(name, positional=0, children='many', screen=None) link

Registers a custom screen language statement with Ren'Py.

This must be a word. It's the name of the custom screen language statement.
The number of positional parameters this statement takes.
The number of children this custom statement takes. This should be 0, 1, or "many", which means zero or more.
The screen to use. If not given, defaults to name.

Returns an object that can have positional arguments and properties added to it. This object has the same .add_ methods as the objects returned by renpy.register_sl_displayable.

As an example of a creator-defined screen language statement, here's an implementation of the titledwindow statement given above. First, the statement must be registered in a python early block in a file that is loaded early – a name like 01custom.rpy will often load soon enough. The registration call looks like:

python early:
    renpy.register_sl_statement("titledwindow", children=1).add_positional("title").add_property("icon").add_property("pos")

Then, we define a screen that implements the custom statement. This screen can be defined in any file. One such screen is:

screen titledwindow(title, icon=None, pos=(0, 0)):
        pos pos

            background "#00000080"

            has vbox

                if icon is not None:
                    add icon

                text title

            null height 15


When are used large property groups like a add_property_group, it makes sense to use the **properties syntax with a properties keyword in some place. For example:

screen titledwindow(title, icon=None, **properties):
        # When background not in properties it will use it as default value.
        background "#00000080"

        properties properties

        has vbox

            if icon is not None:
                add icon

            text title

        null height 15