Reference Manual: (offline | online) Quickstart: (offline | online)

User-Defined Displayables

It's possible for a user to define displayables that extend Ren'Py's behavior. This section will explain the steps that are involved in defining your own displayables, and how to use them with Ren'Py.

A displayable is an object that inherits from renpy.Displayable, a class that has several methods that can be overridden to control the behavior of the displayable. Probably the most important of these is render, a method that must be overridden to return a renpy.Render object, which contains the result of drawing the displayable. The event method can be overridden to respont to events, and to terminate the interaction when necessary. Other methods allow a displayable to respond to a variety of events.

Displayables must be capable of being serialized. This means that they must not contain references to objects that are incapable of being serialized. Of particular note is that the renpy.Render object is incapable of being serialized.

Displayables have a number of methods and fields, not all of which are documented here. We strongly recommend you use a unique prefix for the names of fields and methods you add, to minimize the chance of conflicts.

renpy.Displayable

This is the base class for user-defined displayables. It has the following fields and methods.

Since you will be implementing many of these methods, rather than calling them, we include the normally hidden self parameter in the definition.

renpy.Render

Since one will not be subclassing renpy.Render, we omit the self parameter from method descriptions.

Utility Methods

Using User-Defined Displayables

Once a user-defined displayable class has been defined, objects of that class can be created. Such an object can be shown with a show statement, or added to the transient layer with ui.add .

Defining At-functions and Transitions

An At-function is a function that is suitable for use in an at-list, as part of a show statement. These are functions that take a displayable as an argument, and return a second displayable. (User-defined or not.)

Transitions take two keyword arguments, new_widget and old_widget, representing the new and old scenes, respectively. They return a displayable that performs the transition, which should have its delay fields set to the duration of the transition.

Notes

renpy.Displayable does not inherit from the store's object, and so it will not participate in rollback.

Although we will do our best to avoid breaking code unnecessarily, we reserve the right to change the displayable API as necessary to support the future development of Ren'Py. As a result, code using the displayable API may not be forward-compatible with future versions of Ren'Py.

Reference Manual: (offline | online) Quickstart: (offline | online)