A displayable is an object that can be shown to the user. Ren'Py displayables can be used in many ways.
image
statement.add
statement.When a Ren'Py function or variable expects a displayable, there are five things that can be provided:
:
in it. These are rare, but see the section on
displayable prefixes below..
in it. Such a string is interpreted as
a filename by Image()
.Color
, or an (r, g, b, a) tuple,
where each component is an integer between 0 and 255. Colors are
passed to Solid()
.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.
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) linkLoads 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:
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.
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.
AlphaMask
(child, mask, **properties) linkThis displayable takes its colors from child, and its alpha channel from the multiplication of the alpha channels of child and mask. The result is a displayable that has the same colors as child, is transparent where either child or mask is transparent, and is opaque where child and mask are both opaque.
The child and mask parameters may be arbitrary displayables. The size of the AlphaMask is the size of child.
Note that this takes different arguments from im.AlphaMask()
,
which uses the mask's red channel.
Borders
(left, top, right, bottom, pad_left=0, pad_top=0, pad_right=0, pad_bottom=0) linkThis object provides border size and tiling information to a Frame()
.
It can also provide padding information that can be supplied to the
padding
style property of a window or frame.
The padding information is supplied via a field:
padding
linkThis is a four-element tuple containing the padding on each of the four sides.
Composite
(size, *args, **properties) linkThis creates a new displayable of size, by compositing other displayables. size is a (width, height) tuple.
The remaining positional arguments are used to place images inside the Composite. The remaining positional arguments should come in groups of two, with the first member of each group an (x, y) tuple, and the second member of a group is a displayable that is composited at that position.
Displayables are composited from back to front.
image eileen composite = Composite(
(300, 600),
(0, 0), "body.png",
(0, 0), "clothes.png",
(50, 50), "expression.png")
Crop
(rect, child, **properties) linkThis creates a displayable by cropping child to rect, where rect is an (x, y, width, height) tuple.
image eileen cropped = Crop((0, 0, 300, 300), "eileen happy")
DynamicImage
(name) linkA 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.
Flatten
(child, drawable_resolution=True, **properties) linkThis flattens child, which may be made up of multiple textures, into a single texture.
Certain operations, like the alpha transform property, apply to every texture making up a displayable, which can yield incorrect results when the textures overlap on screen. Flatten creates a single texture from multiple textures, which can prevent this problem.
Flatten is a relatively expensive operation, and so should only be used when absolutely required.
Frame
(image, left=0, top=0, right=None, bottom=None, tile=False, **properties) linkA displayable that resizes an image to fill the available area, while preserving the width and height of its borders. It is often used as the background of a window or button.
Using a frame to resize an image to double its size.
Borders()
object, in which case that object is used in place
of the other parameters.# Resize the background of the text window if it's too small.
init python:
style.window.background = Frame("frame.png", 10, 10)
Null
(width=0, height=0, **properties) linkA displayable that creates an empty box on the screen. The size of the box is controlled by width and height. This can be used when a displayable requires a child, but no child is suitable, or as a spacer inside a box.
image logo spaced = HBox("logo.png", Null(width=100), "logo.png")
Solid
(color, **properties) linkA displayable that fills the area its assigned with color.
image white = Solid("#fff")
Tile
(child, style=u'tile', **properties) linkTiles child until it fills the area allocated to this displayable.
image bg tile = Tile("bg.png")
See Text Displayables.
Dynamic displayables display a child displayable based on the state of the game.
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 defined this way is off screen (Such as a character customization system). It is not designed for things that change frequently, such as character emotions.
ConditionSwitch
(*args, predict_all=None, **properties) linkThis 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:
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.
config.conditionswitch_predict_all
is
used.image jill = ConditionSwitch(
"jill_beers > 4", "jill_drunk.png",
"True", "jill_sober.png")
DynamicDisplayable
(function, *args, **kwargs) linkA displayable that can change its child based on a Python function, over the course of an interaction. It does not take any properties, as its layout is controlled by the properties of the child displayable it returns.
A function that is called with the arguments:
and should return a (d, redraw) tuple, where:
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) linkThis 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 default image should be specified.
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")
The At function produces a displayable from a displayable and one or more transforms.
At
(d, *args) linkGiven 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 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) linkA box that fills the screen. Its members are laid out from back to front, with their position properties controlling their position.
HBox
(*args, **properties) linkA box that lays out its members from left to right.
VBox
(*args, **properties) linkA 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) linkLays 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.
These displayables are used to create certain visual effects.
AlphaBlend
(control, old, new, alpha=False) linkThis 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.
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.
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.
For the list of image manipulators, see the image manipulator documentation.
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, text=None, **properties) linkThis displayable can be used to display a placeholder character or background.
The type of image to display. This should be one of:
Attempts to automatically determine the type of image to use. If the image name begins with "bg", "cg", or "event", uses 'bg'.
Otherwise, the 'girl' placeholder is used.
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.
Displaying Images : the basics of how to make all these displayables appear on the screen.