Displayables link

A displayable is an object that can be shown to the user. Ren'Py displayables can be used in many ways.

  • Assignment to an image name using the image statement.
  • Added to a screen using the screen language add statement.
  • Assignment to certain config variables.
  • Assignment to certain style properties.

When a Ren'Py function or variable expects a displayable, there are five things that can be provided:

  • An object of type Displayable, created by calling one of the functions given below.
  • A string with a colon : in it. These are rare, but see the section on displayable prefixes below.
  • A string with a dot . in it. Such a string is interpreted as a filename by Image().
  • A color. A color may either be given as a hexadecimal color string in "#rgb", "#rgba", "#rrggbb", or "#rrggbbaa" form, a Color, or an (r, g, b, a) tuple, where each component is an integer between 0 and 255. Colors are passed to Solid().
  • An image name. Any other string is interpreted as a reference to an image defined with the image statement.
  • A list. If a list is provided, each item is expanded as described below, and checked to see if it matches a filename or image name. If so, expansion stops and the matched thing is then processed as described above.

Strings may have one or more square-bracket substitutions in them, such as "eileen [mood]" or "eileen_[outfit]_[mood].png". When such a string is given, a dynamic image is created. A dynamic image has text interpolation performed at the start of each interaction (such as say statements and menus). The resulting string is processed according to the rules above.

When a string has "[prefix_]" in it, that substitution is replaced with each of the style prefixes associated with the current displayable.

Images link

The most commonly used displayable is Image, which loads a file from disk and displays it. Since Image is so commonly used, when a string giving a filename is used in a context that expects a displayable, an Image is automatically created. The only time it's necessary to use Image directly is when you want to create an image with style properties.

Image(filename, *, optimize_bounds=True, **properties) link

Loads an image from a file. filename is a string giving the name of the file.

filename should be a JPEG or PNG file with an appropriate extension.

If optimize_bounds is True, only the portion of the image that inside the bounding box of non-transparent pixels is loaded into GPU memory. (The only reason to set this to False is when using an image as input to a shader.)

# These two lines are equivalent.
image logo = "logo.png"
image logo = Image("logo.png")

# Using Image allows us to specify a default position as part of
# an image.
image logo right = Image("logo.png", xalign=1.0)

There are three image file formats we recommend you use:

  • WEBP
  • PNG
  • JPG

Non-animated GIF and BMP files are also supported, but should not be used in modern games.

Loading an Image from a file on disk and decoding it so it can be drawn to the screen takes a long amount of time. While measured in the tenths or hundreds of seconds, the duration of the loading process is long enough that it can prevent an acceptable framerate, and become annoying to the user.

Since an Image is of a fixed size, and doesn't change in response to input, game state, or the size of the area available to it, an Image can be loaded before it is needed and placed into an area of memory known as the image cache. Once an Image is decoded and in the cache, it can be quickly drawn to the screen.

Ren'Py attempts to predict the images that will be used in the future, and loads them into the image cache before they are used. When space in the cache is needed for other images, Ren'Py will remove images that are no longer being used.

By default, Ren'Py will predictively cache up to 8 screens worth of image data. (If your screen is 800x600, then a screen's worth of data is one 800x600 image, two 400x600 images, and so on.) This can be changed with the config.image_cache_size configuration variable.

Although the precise amount is dependent on implementation details and there is significant overhead, as a rule of thumb, each pixel in the image cache consumes 4 bytes of main memory and 4 bytes of video memory.

Image-Like Displayables link

We call these displayables image-like because they take up a rectangular area of the screen, and do not react to input. These differ from normal images by varying their size to fill an area (Frame, Tile, and Solid), or by allowing the user to specify their size (Composite, Crop, Null). They are not image manipulators.

Image-like displayables take Position Style Properties.

DynamicImage(name) link

A DynamicImage is a displayable that has text interpolation performed on it to yield a string giving a new displayable. Such interpolation is performed at the start of each interaction.

Text Displayables link

See Text Displayables.

Dynamic Displayables link

Dynamic displayables display a child displayable based on the state of the game. They do not take any properties, as their layout is controlled by the properties of the child displayable they return.

Note that these dynamic displayables always display their current state. Because of this, a dynamic displayable will not participate in a transition. (Or more precisely, it will display the same thing in both the old and new states of the transition.)

By design, dynamic displayables are intended to be used for things that change rarely and when an image define this way is off screen (Such as a character customization system), and not for things that change frequently, such as character emotions.

ConditionSwitch(*args, predict_all=None, **properties) link

This is a displayable that changes what it is showing based on Python conditions. The positional arguments should be given in groups of two, where each group consists of:

  • A string containing a Python condition.
  • A displayable to use if the condition is true.

The first true condition has its displayable shown, at least one condition should always be true.

The conditions uses here should not have externally-visible side-effects.

predict_all
If True, all of the possible displayables will be predicted when the displayable is shown. If False, only the current condition is predicted. If None, config.conditionswitch_predict_all is used.
image jill = ConditionSwitch(
    "jill_beers > 4", "jill_drunk.png",
    "True", "jill_sober.png")
DynamicDisplayable(function, *args, **kwargs) link

A displayable that can change its child based on a Python function, over the course of an interaction.

function

A function that is called with the arguments:

  • The amount of time the displayable has been shown for.
  • The amount of time any displayable with the same tag has been shown for.
  • Any positional or keyword arguments supplied to DynamicDisplayable.

and should return a (d, redraw) tuple, where:

  • d is a displayable to show.
  • redraw is the amount of time to wait before calling the function again, or None to not call the function again before the start of the next interaction.

function is called at the start of every interaction.

As a special case, function may also be a python string that evaluates to a displayable. In that case, function is run once per interaction.

# Shows a countdown from 5 to 0, updating it every tenth of
# a second until the time expires.
init python:

    def show_countdown(st, at):
        if st > 5.0:
            return Text("0.0"), None
        else:
            d = Text("{:.1f}".format(5.0 - st))
            return d, 0.1

image countdown = DynamicDisplayable(show_countdown)
ShowingSwitch(*args, predict_all=None, **properties) link

This is a displayable that changes what it is showing based on the images are showing on the screen. The positional argument should be given in groups of two, where each group consists of:

  • A string giving an image name, or None to indicate the default.
  • A displayable to use if the condition is true.

A default image should be specified.

predict_all
If True, all of the possible displayables will be predicted when the displayable is shown. If False, only the current condition is predicted. If None, config.conditionswitch_predict_all is used.

One use of ShowingSwitch is to have images change depending on the current emotion of a character. For example:

image emotion_indicator = ShowingSwitch(
   "eileen concerned", "emotion_indicator concerned",
   "eileen vhappy", "emotion_indicator vhappy",
   None, "emotion_indicator happy")

Applying Transforms to Displayables link

The At function produces a displayable from a displayable and one or more transforms.

At(d, *args) link

Given a displayable d, applies each of the transforms in args to it. The transforms are applied in left-to-right order, so that the outermost transform is the rightmost argument.

transform birds_transform:
     xpos -200
     linear 10 xpos 800
     pause 20
     repeat

image birds = At("birds.png", birds_transform)

Layout Boxes and Grids link

Layout boxes are displayables that lay out their children on the screen. They can lay out the children in a horizontal or vertical manner, or lay them out using the standard positioning algorithm.

The box displayables take any number of positional and keyword arguments. Positional arguments should be displayables that are added to the box as children. Keyword arguments are style properties that are applied to the box.

Boxes take Position Style Properties and Box Style Properties.

Fixed(*args, **properties) link

A box that fills the screen. Its members are laid out from back to front, with their position properties controlling their position.

HBox(*args, **properties) link

A box that lays out its members from left to right.

VBox(*args, **properties) link

A layout that lays out its members from top to bottom.

# Display two logos, to the left and right of each other.
image logo hbox = HBox("logo.png", "logo.png")

# Display two logos, one on top of the other.
image logo vbox = VBox("logo.png", "logo.png")

# Display two logos. Since both default to the upper-left
# corner of the screen, we need to use Image to place
# those logos on the screen.
image logo fixed = Fixed(
    Image("logo.png", xalign=0.0, yalign=0.0),
    Image("logo.png", xalign=1.0, yalign=1.0))

The Grid layout displays its children in a grid on the screen. It takes Position Style Properties and the spacing style property.

Grid(cols, rows, *args, **properties) link

Lays out displayables in a grid. The first two positional arguments are the number of columns and rows in the grid. This must be followed by columns * rows positional arguments giving the displayables that fill the grid.

Effects link

These displayables are used to create certain visual effects.

AlphaBlend(control, old, new, alpha=False) link

This transition uses a control displayable (almost always some sort of animated transform) to transition from one displayable to another. The transform is evaluated. The new displayable is used where the transform is opaque, and the old displayable is used when it is transparent.

alpha
If true, the image is composited with what's behind it. If false, the default, the image is opaque and overwrites what's behind it.

Image Manipulators link

An image manipulator is a displayable that takes an image or image manipulator, and either loads it or performs an operation on it. Image manipulators can only take images or other image manipulators as input.

An image manipulator can be used any place a displayable can, but not vice-versa. An Image() is a kind of image manipulator, so an Image can be used whenever an image manipulator is required.

With the few exceptions listed below, the use of image manipulators is historic. A number of image manipulators that had been documented in the past should no longer be used, as they suffer from inherent problems. In any case except for im.Data, the Transform() displayable provides similar functionality in a more general manner, while fixing the problems, although it sometimes requires gl2 to be enabled.

im.AlphaMask(base, mask, **properties) link

An image manipulator that takes two image manipulators, base and mask, as arguments. It replaces the alpha channel of base with the red channel of mask.

This is used to provide an image's alpha channel in a second image, like having one jpeg for color data, and a second one for alpha. In some cases, two jpegs can be smaller than a single png file.

Note that this takes different arguments from AlphaMask(), which uses the mask's alpha channel.

im.Blur(im, xrad, yrad=None, **properties) link

An image manipulator that blurs the image manipulator im using an elliptical kernel described by xrad and optionally yrad.

If yrad is None, it will take the value of xrad resulting in a circular kernel being used.

image logo blurred = im.Blur("logo.png", 1.5)

The same effect can now be achieved with the blur transform property.

im.Crop(im, rect) link

An image manipulator that crops rect, a (x, y, width, height) tuple, out of im, an image manipulator.

image logo crop = im.Crop("logo.png", (0, 0, 100, 307))

The same effect can now be achieved by setting the crop transform property.

im.Data(data, filename, **properties) link

This image manipulator loads an image from binary data.

data
A string of bytes, giving the compressed image data in a standard file format.
filename
A "filename" associated with the image. This is used to provide a hint to Ren'Py about the format of data. (It's not actually loaded from disk.)
im.FactorScale(im, width, height=None, bilinear=True, **properties) link

An image manipulator that scales im (a second image manipulator) to width times its original width, and height times its original height. If height is omitted, it defaults to width.

If bilinear is true, then bilinear interpolation is used for the scaling. Otherwise, nearest neighbor interpolation is used.

image logo doubled = im.FactorScale("logo.png", 1.5)

The same effect can now be achieved with the zoom or the xzoom and yzoom transform properties.

im.Flip(im, horizontal=False, vertical=False, **properties) link

An image manipulator that flips im (an image manipulator) vertically or horizontally. vertical and horizontal control the directions in which the image is flipped.

image eileen flip = im.Flip("eileen_happy.png", vertical=True)

The same effect can now be achieved by setting xzoom (for horizontal flip) or yzoom (for vertical flip) to a negative value.

im.Grayscale(im, **properties) link

An image manipulator that creates a desaturated version of the image manipulator im.

The same effect can now be achieved by supplying SaturationMatrix(0) to the matrixcolor transform property.

im.Sepia(im, **properties) link

An image manipulator that creates a sepia-toned version of the image manipulator im.

The same effect can now be achieved by supplying SepiaMatrix() to the matrixcolor transform property.

im.Tile(im, size=None, **properties) link

An image manipulator that tiles the image manipulator im, until it is size.

size
If not None, a (width, height) tuple. If None, this defaults to (config.screen_width, config.screen_height).

The same effect can now be achieved with Tile(im, size=size)

im.MatrixColor link

The im.MatrixColor image manipulator is an image manipulator that uses a matrix to control how the colors of an image are transformed. The matrix used can be an im.matrix object, which encodes a 5x5 matrix in an object that supports matrix multiplication, and is returned by a series of functions. im.matrix objects may be multiplied together to yield a second object that performs both operations. For example:

image city blue = im.MatrixColor(
    "city.jpg",
    im.matrix.desaturate() * im.matrix.tint(0.9, 0.9, 1.0))

first desaturates the image, and then tints it blue. When the intermediate image is not needed, multiplying matrices is far more efficient, in both time and image cache space, than using two im.MatrixColors.

The im.MatrixColor image manipulator has been replaced by Transforms and ATL transforms that specify the matrixcolor property. Each im.matrix generator has been given a new Matrix equivalent, as shown.

Warning

The new Matrix objects multiply in the opposite order as the im.Matrixcolor ones. With X being the Matrix corresponding to im.Matrixcolor.x, C*B*A will be the Matrix corresponding to im.a*im.b*im.c.

im.MatrixColor(im, matrix, **properties) link

An image operator that uses matrix to linearly transform the image manipulator im.

Matrix should be a list, tuple, or im.matrix() that is 20 or 25 elements long. If the object has 25 elements, then elements past the 20th are ignored.

When the four components of the source color are R, G, B, and A, which range from 0.0 to 1.0; the four components of the transformed color are R', G', B', and A', with the same range; and the elements of the matrix are named:

[ a, b, c, d, e,
  f, g, h, i, j,
  k, l, m, n, o,
  p, q, r, s, t ]

the transformed colors can be computed with the formula:

R' = (a * R) + (b * G) + (c * B) + (d * A) + e
G' = (f * R) + (g * G) + (h * B) + (i * A) + j
B' = (k * R) + (l * G) + (m * B) + (n * A) + o
A' = (p * R) + (q * G) + (r * B) + (s * A) + t

The components of the transformed color are clamped to the range [0.0, 1.0].

Placeholders link

The Placeholder displayable is used to display background or character images as appropriate. Placeholders are used automatically when an undefined image is used in developer mode. Placeholder displayables can also be used manually when the defaults are inappropriate.

# By default, the girl placeholder will be used.
image sue = Placeholder("boy")

label start:
     show sue angry
     "Sue" "How do you do? Now you gonna die!"
Placeholder(base=None, full=False, flip=None, **properties) link

This displayable can be used to display a placeholder character or background.

base

The type of image to display. This should be one of:

'bg'
To display a background placeholder. This currently fills the screen with a light-gray, and displays the image name at the top of the screen.
'boy'
Displays a male-identified placeholder with the image name on his chest.
'girl'
Displays a female-identified placeholder with the image name on her chest.
None

Attempts to automatically determine the type of image to use. If the image name begins with "bg", "cg", or "event", uses 'bg'.

Otherwise, contacts a web service to guess gender from the character's name, and uses that. (The 'girl' placeholder is used when the service can't guess.)

The webservice will only be contacted when config.developer is True.

full
If true, a full-body sprite is used. Otherwise, a 3/4 sprite is used.
flip
If true, the sprite is flipped horizontally.

Displayable Prefixes link

Displayable prefixes make it possible for a creator to define their own displayables, and refer to them anywhere a displayable can be used in Ren'Py. A prefixed displayable is a string with a colon in it. The prefix is to the left of the colon, and the argument is anything to the right of it. The config.displayable_prefix variable maps a prefix to a function. The function takes the argument, and either returns a displayable or None.

For example, this makes the big prefix return an image that is twice as big as the original.

init -10 python:
    def embiggen(s):
        return Transform(s, zoom=2)

    config.displayable_prefix["big"] = embiggen

The init -10 makes sure the prefix is defined before any images that use it. The prefix can then be used to define images:

image eileen big = "big:eileen happy"

or in any other place where a displayable is required.