renpy/doc/reference/Displayables - Ren'Py

documentation index ◦ reference manual ◦ function index

# Displayables

A displayable is a python object implementing an interface that allows it to be displayed to the screen. Displayables can be assigned to an image name using an `image` statement, and can then be shown to the user using the `show` and `hide` statements. They can be supplied as an argument to the ui.add function. They are also used as the argument to certain style properties. In this section, we will describe functions that create displayables.

When Ren'Py requires colors to be specified for a displayable, it allows them to be specified in a number of forms. In the following examples, lowercase letters stand for hexadecimal digits, while uppercase letters are short for numbers between 0 and 255. r, g, b, and a are short for red, green, blue, and alpha.

- A string of the form "#rgb". (yellow = "#ff0", blue = "#00f")
- A string of the form "#rgba". (yellow = "#ff0f", blue = "#00ff")
- A string of the form "#rrggbb". (yellow = "#ffff00", blue = "#0000ff")
- A string of the form "#rrggbbaa". (yellow = "#ffff00ff", blue = "#0000ffff")
- A 4-tuple of the form (R, G, B, A). (yellow = (255, 255, 0, 255), blue = (0, 0, 255, 255))

When Ren'Py expects a displayable to be specified, it allows them to be in the following forms:

- A displayable may be given directly, in which case it is used.
- A string beginning with "#" is used to create a solid object, with the color interpreted as above.
- Other strings are interpreted as the filenames of images, and are used to create image objects.

## Image Manipulators

An Image is a type of displayable that contains bitmap data that can be shown to the screen. All images are displayables, but not all displayables are images. Images differ from displayables in that they can be statically computed, and stored in the image cache. This loading occurs sometime before the image is to be used (but not at the time the Image is created). This generally makes Images faster than arbitrary displayables. An image manipulator is a function that returns an Image.

When an image manipulator requires another as input, the second image manipulator can be specified in a number of ways.

- It may be supplied as a string, which is interpreted as a filename and loaded with im.Image.
- It may be a directly specified image manipulator, in which case it is passed through unchanged.

Run-length Encoding. Ren'Py supports the use of run-length encoding to efficiently draw images with large amounts of transparency. All image manipulators support an rle argument. When True, run-length encoding is used. When false, it is not used. When None (the default), Ren'Py will randomly sample 10 points in the image image to try to find transparency, and use rle only if transparency is found. In exchange for increased load time, and additional memory proportional to the number of non-transparent pixels in the image, run-length encoding can draw images to the screen in time proportional to the number of non-transparent pixels in the image. When an image is mostly transparent, this can lead to a significant speedup in drawing time.

    init:
        image eileen happy = Image("eileen_happy.png", rle=True)

Caching. By default, image manipulators are cached in memory before they are loaded. Supplying the cache=False argument to an image manipulator will prevent this caching. This should only be used when an image manipulator is never used directly (such as by an image statement).

    init:
        image eileen happy = im.AlphaMask(Image("eileen_happy.base.jpg", cache=False),
                                          Image("eileen_happy.mask.jpg", cache=False))

Image Manipulator List. The image manipulators are:

Function: | im.Image | (filename, **properties):

This image manipulator loads an image from a file.

filename - The filename that the image will be loaded from.

Note that Image is an alias for im.Image.

Function: | Image | (...):

An alias for im.Image.

Function: | im.Alpha | (image, alpha, **properties):

Returns an alpha-mapped version of the image. Alpha is the maximum alpha that this image can have, a number between 0.0 (fully transparent) and 1.0 (opaque).

If an image already has an alpha channel, values in that alpha channel are reduced as appropriate.

Function: | im.AlphaMask | (base, mask, **properties):

base and mask should be image manipulators. This function takes the red channel from mask, and applies it to the alpha channel of base to create a new image.

Function: | im.Composite | (size, *args, **properties):

This image manipulator composites one or more images together.

This takes a variable number of arguments. The first argument is size, which is either the desired size of the image (in pixels), or None to indicate that the size should be the size of the first image.

It then takes an even number of further arguments. (For an odd number of total arguments.) The second and other even numbered arguments contain position tuples, while the third and further odd-numbered arguments give images (or image manipulators). A position argument gives the position of the image immediately following it, with the position expressed as a tuple giving an offset from the upper-left corner of the image. The images are composited in bottom-to-top order, with the last image being closest to the user.

Function: | im.Crop | (im, x, y, w, h, **properties):

This crops the image that is its child.

Function: | im.Flip | (im, horizontal=False, vertical=False, **properties):

This is an image manipulator that can flip the image horizontally or vertically.

im - The image to be flipped.

horizontal - True to flip the image horizontally.

vertical - True to flip the image vertically.

Function: | im.Map | (im, rmap=im.ramp(0, 255), gmap=im.ramp(0, 255), bmap=im.ramp(0, 255), amap=im.ramp(0, 255), force_alpha=False, **properties):

This adjusts the colors of the image that is its child. It takes as arguments 4 256 character strings. If a pixel channel has a value of 192, then the value of the 192nd character in the string is used for the mapped pixel component.

The im.Map function can be used in a simple way, like im.Recolor, to scale down or remove color components from the source image, or it can be used in a more complex way to totally remap the color of the source image.

Function: | im.ramp | (start, end):

Returns a 256 character linear ramp, where the first character has the value start and the last character has the value end. Such a ramp can be used as a map argument of im.Map.

Function: | im.Scale | (im, width, height, bilinear=True, **properties):

This is an image manipulator that scales another image manipulator to the specified width and height.

bilinear - If True, bilinear interpolation is used. If False, nearest-neighbor filtering is used.

Function: | im.Recolor | (im, rmul=255, gmul=255, bmul=255, amul=255, force_alpha=False, **properties):

This adjusts the colors of the supplied image, im. It takes four arguments, rmul, gmul, bmul and amul, corresponding to the red, green, blue and alpha channels, with each being an integer between 0 and 255. Each channel has its value mapped so that 0 is 0, 255 is the argument supplied for that channel, and other values are linearly mapped in-between.

renpy/doc/reference/functions/im.TwoColor

Function: | im.Rotozoom | (im, angle, zoom, **properties):

This is an image manipulator that is a smooth rotation and zoom of another image manipulator.

im - The image to be rotozoomed.

angle - The number of degrees counterclockwise the image is to be rotated.

zoom - The zoom factor. Numbers that are greater than 1.0 lead to the image becoming larger.

Function: | im.Tile | (im, size=None, **properties):

This tiles the image, repeating it vertically and horizontally until it is as large as the specified size. If no size is given, then the size defaults to the size of the screen.

ImageReference is used to access images declared with the image statement.

Function: | ImageReference | (name):

This displayable accesses images declared using the image statement. name may be a string, or a tuple of strings giving the components of the image name.

This always a displayable, and may also be an image manipulator if name is declared to refer to an image manipulator.

## im.MatrixColor

The im.MatrixColor image manipulator takes a 20 or 25 element matrix, and uses it to linearly transform the colors of an image.

Function: | im.MatrixColor | (im, matrix):

This is an image operator that creates an image by using a matrix to linearly transform the colors in the image 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. If the elements of the matrix are named as follows:

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

and R, G, B, and A are the red, green, blue, and alpha components of the color, respectively, then the transformed color R', G', B', A' is computed as follows:

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

R', G', B', and A' are clamped to the range [0, 255].

It's often convenient to specify the matrix using an im.matrix object. These objects support a number of mathematical operations, such as matrix and scalar multiplication and scalar addition. Multiplying matrices together lets you perform multiple color manipulations at once, at the cost of a single MatrixColor operation.

Function: | im.matrix | (matrix):

Constructs an im.matrix object from the given matrix. im.matrix objects represent 5x5 matrices, and support a number of mathematical operations. The operations supported are matrix multiplication, scalar multiplication, element-wise addition, and element-wise subtraction. These operations are invoked using the standard mathematical operators (*, *, +, and -), respectively. If two im.matrix objects are multiplied, matrix multiplication is performed, otherwise scalar multiplication is used.

matrix is a 20 or 25 element list. If the list is 20 elements long, it is padded with [0, 0, 0, 0, 1 ] to make a 5x5 matrix, suitable for multiplication.

The following functions produce im.matrix objects:

Function: | im.matrix.identity | ():

Returns an identity im.matrix (one that does not change color or alpha).

Function: | im.matrix.saturation | (level, desat=(0.2126, 0.7152, 0.0722)):

Constructs an im.matrix that alters the saturation of an image. The alpha channel is untouched.

level - The amount of saturation in the resulting image. 1.0 is the unaltered image, while 0.0 is grayscale.

desat - This is a 3-element tuple that controls how much of the red, green, and blue channels will be placed into all three channels of a fully saturated image. The default is based on the constants used for the luminance channel of an NTSC television signal. Since the human eye is mostly sensitive to green, more of the green channel is kept then the other two channels.

Function: | im.matrix.desaturate | ():

Returns a matrix that desaturates the image (make it grayscale). This is equivalent to calling im.matrix.saturation(0).

Function: | im.matrix.tint | (r, g, b):

Constructs an im.matrix that tints an image, while leaving the alpha channel intact. r, g, and b, should be numbers between 0 and 1, and control what fraction of the given channel is placed into the final image. (For example, if r is .5, and a pixel has a red component of 100, the corresponding pixel will have a red component of 50.)

Function: | im.matrix.invert | ():

Constructs an im.matrix that inverts the red, green, and blue channels of the source image, while leaving the alpha channel alone.

Function: | im.matrix.brightness | (b):

Constructs an im.matrix that alters the brightness of an image, while leaving the alpha channel intact. b should be between -1 and 1, with -1 being the darkest possible image and 1 the brightest.

Function: | im.matrix.contrast | (c):

Constructs an im.matrix that alters the contrast of an image. c should be greater than 0.0, with values greater than 1.0 increasing contrast and less than 1.0 decreasing it.

Function: | im.matrix.opacity | (o):

Constructs an im.matrix that alters the opacity of an image, while leaving the red, green, and blue channels alone. An o of 0.0 is fully transparent, while 1.0 is fully opaque.

Function: | im.matrix.hue | (h):

Returns a matrix that rotates the hue by h degrees, while preserving luminosity.

Matrices constructed with these functions can be composed using matrix multiplication. For example, one can desaturate an image, and then tint it light blue.

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

It's far more efficient to multiply matrices rather than composing im.MatrixColor operations, since the matrix multiplication requires about 125 multiply operations, while the im.MatrixColor uses 16 per pixel times the number of pixels in the image.

There exist two image manipulators that wrap common uses of im.MatrixColor:

Function: | im.Grayscale | (im, desat=(0.2126, 0.7152, 0.0722)):

This image operator converts the given image to grayscale. desat is as for im.matrix.saturation.

Function: | im.Sepia | (im, tint=(1.0, .94, .76), desat=(0.2126, 0.7152, 0.0722)):

This image operator sepia-tones an image. desat is as for im.matrix.saturation. tint is decomposed and used as the parameters to im.matrix.tint.

## Backgrounds

There are two displayables that are eminently suitable for use as backgrounds:

Function: | Frame | (image, xborder, yborder, tile=False, bilinear=False):

Returns a displayable that is a frame, based on the supplied image filename. A frame is an image that is automatically rescaled to the size allocated to it. The image has borders that are only scaled in one axis. The region within xborder pixels of the left and right borders is only scaled in the y direction, while the region within yborder pixels of the top and bottom axis is scaled only in the x direction. The corners are not scaled at all, while the center of the image is scaled in both x and y directions.

image - The image (which may be a filename or image object) that will be scaled.

xborder - The number of pixels in the x direction to use as a border.

yborder - The number of pixels in the y direction to use as a border.

tile - If true, then tiling is performed rather then scaling.

bilinear - If true (and tile is false), bilinear scaling is performed instead of nearest-neighbor scaling.

For better performance, have the image share a dimension length in common with the size the frame will be rendered at. We detect this and avoid scaling if possible.

Function: | Solid | (color):

Returns a Displayable that is solid, and filled with a single color. A Solid expands to fill all the space allocated to it, making it suitable for use as a background.

color - The color that the display will be filled with, given either as an RGBA tuple, or an html-style string

## Text

Text can be used to show text to the user, as a displayable.

Function: | Text | (text, slow=False, slow_done=None, slow_speed=None, slow_start=0, slow_abortable=False, pause=None, tokenized=False, style='default', **properties):

A displayable that can format and display text on the screen.

text - The text that will be displayed on the screen.

slow - If True, the text will be typed at the screen at a rate determined by the slow_cps property, if set, or the "Text Speed" preference. If None (the default), then it will be typed at a speed determined by the slow_cps property. If False, then it will appear instantly.

style - A style that will be applied to the text.

properties - Additional properties that are applied to the text.

pause - If not None, then we display up to the pauseth pause (0-numbered.)

slow_done - A callback that occurs when slow text is done.

slow_speed - The speed of slow text. If none, it's taken from the preferences.

slow_offset - The offset into the text to start the slow text.

slow_abortable - If True, clicking aborts the slow text.

tokenized - True if the text is already tokenized.

Ren'Py also supports a parameterized text object, which shows text as if it was an image on the screen. But care should be taken, as it's almost always better to use a Character object to show text. By default there is one ParameterizedText image, named `text` declared, but the user can declare more than one to show multiple text blocks on the screen at once.

Function: | ParameterizedText | (style='default', **properties):

This can be used as an image. When used, this image is expected to have a single parameter, a string which is rendered as the image.

## Dynamic

DynamicDisplayable can be used in styles to change the displayable shown over the course of the game.

Function: | DynamicDisplayable | (function, *args, **kwargs):

This displayable evaluates a function, and uses the result of that function to determine what to show.

function should be function that should accept at least two arguments. The first argument is the time (in seconds) that the DynamicDisplayable has been shown for. The second argument is the number of seconds that a displayable with the same image tag has been shown for. Additional positional and keyword arguments passed to DynamicDisplayable are also given to the function. The function is expected to return a 2-tuple. The first element of this tuple should be a displayable. The second should be either the time (in seconds) that the return value is valid for, or None to indicate the return value is valid indefinitely.

The function is evaluated at least once for each interaction. It is also evaluated again when the specified time has elapsed.

Note that DynamicDisplayable does not accept properties. Instead, it uses the properties of the displayable returned by function

For compatibility with pre-5.6.3 versions of Ren'Py, DynamicDisplayable also accepts a string as the function argument. In this case, the string is evaluated once per interaction, with the result being used as the displayable for that interaction.

Function: | ConditionSwitch | (*args, **properties):

This is a wrapper around DynamicDisplayable that displays the first displayable matching a condition. It takes an even number of positional arguments, with odd arguments being strings containing python conditions, and odd arguments being displayables. On each interaction, it evaluates the conditions in order to find the first that is true, and then displays that displayable. It is an error for no condition to be true.

If supplied, keyword arguments are used to position the chosen displayable.

Function: | ShowingSwitch | (*args, **kwargs):

This chooses a displayable to show based on which images are being shown on the screen. It expects an even number of positional arguments. Odd positional arguments are expected to be image names, while even positional arguments are expected to be displayables. An image matches if it is the prefix of a shown image. If the image name is None, it always matches. It is an error if no match occurs.

This takes the keyword argument layer, which specifies the layer that will be checked to see if the images appear on it, defaulting to "master". Other keyword arguments are used to position the chosen displayable.

Shown image names are tracked by the predictive image loading mechanism, and so ShowingSwitch will properly predictively load images.

## Animations

Ren'Py provides several kinds of animation displayables.

These animation functions take an anim_timebase parameter, that determines which timebase to use. The animation timebase, used when anim_timebase is True, starts at the instant of the first frame from which the tag of the image containing this animation has been shown on the screen. This can be used to switch between two animations, in a way that ensures they are synchronized to the same timebase. The displayable timebase, used when anim_timebase=False, starts at the first frame after the displayable is shown, and can be used to ensure the entire animation is seen, even if an image with the same tag was already on the screen.

The displayable timebase is set to zero for children of a Button, each time the button is focused or unfocused. This means that animations that are children of the button (including backgrounds of the button) that have anim_timebase=False will be restarted when the button changes focus.

The animation functions are:

Function: | Animation | (*args, **properties):

A Displayable that draws an animation, which is a series of images that are displayed with time delays between them.

Odd (first, third, fifth, etc.) arguments to Animation are interpreted as image filenames, while even arguments are the time to delay between each image. If the number of arguments is odd, the animation will stop with the last image (well, actually delay for a year before looping). Otherwise, the animation will restart after the final delay time.

anim_timebase - If True, the default, use the animation timebase. Otherwise, use the displayable timebase.

Function: | anim.TransitionAnimation | (*args, **kwargs):

A displayable that draws an animation with each frame separated by a transition.

This takes arguments such that the 1st, 4th, 7th, ... arguments are displayables, the 2nd, 5th, 8th, ... arguments are times, and the 3rd, 6th, 9th, ... are transitions.

This displays the first displayable for the given time, then transitions to the second displayable using the given transition, and shows it for the given time (the time of the transition is taken out of the time the frame is shown), and so on.

A transition may be None, to specify no transition should be used.

The last argument may be a transition (in which case that transition is used to transition back to the first frame), or a displayable (which is shown forever).

Not all transitions can be used with this. (Most notably, the various forms of MoveTransition can't.)

There is one keyword argument, apart from the usual style properties:

anim_timebase - If True, the default, use the animation timebase. Otherwise, use the displayable timebase.

Function: | anim.Blink | (image, on=0.5, off=0.5, rise=0.5, set=0.5, high=1.0, low=0.0, offset=0.0, anim_timebase=False, **properties):

This takes as an argument an image or widget, and blinks that image by varying its alpha. The sequence of phases is on - set - off - rise - on - ... All times are given in seconds, all alphas are fractions between 0 and 1.

image - The image or widget that will be blinked.

on - The amount of time the widget spends on, at high alpha.

off - The amount of time the widget spends off, at low alpha.

rise - The amount time the widget takes to ramp from low to high alpha.

set - The amount of time the widget takes to ram from high to low.

high - The high alpha.

low - The low alpha.

offset - A time offset, in seconds. Use this to have a blink that does not start at the start of the on phase.

anim_timebase - If True, use the animation timebase, if false, the displayable timebase.

Function: | anim.Filmstrip | (image, framesize, gridsize, delay, frames=None, loop=True, **properties):

This creates an animation from a single image. This image must consist of a grid of frames, with the number of columns and rows in the grid being taken from gridsize, and the size of each frame in the grid being taken from framesize. This takes frames and sticks them into an Animation, with the given delay between each frame. The frames are taken by going from left-to-right across the first row, left-to-right across the second row, and so on until all frames are consumed, or a specified number of frames are taken.

image - The image that the frames must be taken from.

framesize - A (width, height) tuple giving the size of each of the frames in the animation.

gridsize - A (columns, rows) tuple giving the number of columns and rows in the grid.

delay - The delay, in seconds, between frames.

frames - The number of frames in this animation. If None, then this defaults to colums * rows frames, that is, taking every frame in the grid.

loop - If True, loop at the end of the animation. If False, this performs the animation once, and then stops.

Other keyword arguments are as for anim.SMAnimation.

Function: | anim.SMAnimation | (initial, *args, **properties):

This creates a state-machine animation. Such an animation is created by randomly traversing the edges between states in a defined state machine. Each state corresponds to an image shown to the user, with the edges corresponding to the amount of time an image is shown, and the transition it is shown with.

Images are shown, perhaps with a transition, when we are transitioning into a state containing that image.

initial - The name (a string) of the initial state we start in.

showold - If the keyword parameter showold is True, then the old image is shown instead of the new image when in an edge.

anim_timebase - If True, we use the animation timebase. If False, we use the displayable timebase.

This accepts as additional arguments the anim.State and anim.Edge objects that are used to make up this state machine.

Function: | anim.State | (name, image, *atlist, **properties):

This creates a state that can be used in an anim.SMAnimation.

name - A string giving the name of this state.

image - The displayable that is shown to the user while we are in (entering) this state. For convenience, this can also be a string or tuple, which is interpreted with Image.

image should be None when this State is used with motion, to indicate that the image will be replaced with the child of the motion.

atlist - A list of functions to call on the image. (In general, if something can be used in an at clause, it can be used here as well.)

If any keyword arguments are given, they are used to construct a Position object, that modifies the position of the image.

Function: | anim.Edge | (old, delay, new, trans=None, prob=1):

This creates an edge that can be used with a anim.SMAnimation.

old - The name (a string) of the state that this transition is from.

delay - The number of seconds that this transition takes.

new - The name (a string) of the state that this transition is to.

trans - The transition that will be used to show the image found in the new state. If None, the image is show immediately.

prob - The number of times this edge is added. This can be used to make a transition more probable then others. For example, if one transition out of a state has prob=5, and the other has prob=1, then the one with prob=5 will execute 5/6 of the time, while the one with prob=1 will only occur 1/6 of the time. (Don't make this too large, as memory use is proportional to this value.)

We present two examples of this in action. The first shows how one can create a character that ocassionally, randomly, performs a 3-frame blink about once a minute.

    init:
        image blinking = anim.SMAnimation("a",
            anim.State("a", "eyes_open.png"),

            # This edge keeps us showing the eyes open for a second.
            anim.Edge("a", 1.0, "a", prob=60),

            # This edge causes the eyes to start closing...
            anim.Edge("a", 0.25, "b"),

            # ..because it brings us here.
            anim.State("b", "eyes_half.png"),

            # And so on...
            anim.Edge("b", 0.25, "c"),
            anim.State("c", "eyes_closed.png"),
            anim.Edge("c", 0.25, "d"),
            anim.State("d", "eyes_half.png"),

            # And back to a.
            anim.Edge("d", 0.5, "a")
            )

Remember, State can take a Position, and Edge can take a transition. This lets you move things around the screen, dissolve images into others, and do all sorts of complicated, unexpected, things. (But be careful... not all transitions do what you'd expect when used with SMAnimation.)

## Layout

These displayables are used to layout multiple displayables at once.

Function: | LiveComposite | (size, *args, **properties):

This is similar to im.Composite, but can be used with displayables instead of images. This allows it to be used to composite, for example, an animation on top of the image.

This is less efficient than im.Composite, as it needs to draw all of the displayables on the screen. On the other hand, it allows displayables to change while they are on the screen, which is necessary for animation.

This takes a variable number of arguments. The first argument is size, which must be a tuple giving the width and height of the composited widgets, for layout purposes.

It then takes an even number of further arguments. (For an odd number of total arguments.) The second and other even numbered arguments contain position tuples, while the third and further odd-numbered arguments give displayables. A position argument gives the position of the displayable immediately following it, with the position expressed as a tuple giving an offset from the upper-left corner of the LiveComposite. The displayables are drawn in bottom-to-top order, with the last being closest to the user.

Function: | Fixed | (*args, **properties):

A layout that expands to take the size allotted to it. Each displayable is allocated the entire size of the layout, with the first displayable further from the user than the second, and so on.

This function takes both positional and keyword arguments. Positional arguments should be displayables or images to be laid out. Keyword arguments are interpreted as style properties, except for the style keyword argument, which is the name of the parent style of this layout.

Function: | HBox | (*args, **properties):

A layout that lays out displayables from left to right.

This function takes both positional and keyword arguments. Positional arguments should be displayables or images to be laid out. Keyword arguments are interpreted as style properties, except for the style keyword argument, which is the name of the parent style of this layout.

Function: | VBox | (*args, **properties):

A layout that lays out displayables from top to bottom.

This function takes both positional and keyword arguments. Positional arguments should be displayables or images to be laid out. Keyword arguments are interpreted as style properties, except for the style keyword argument, which is the name of the parent style of this layout.

## Widget

These are generally used with the ui functions, but may sometimes be used as displayables.

Function: | Bar | (range, value, clicked=None, **properties):

This creates a Bar displayable, the displayable equivalent of a ui.bar. The parameters are the same as for ui.bar.

Function: | Button | (child, clicked=None, hovered=None, unhovered=None, role=, **properties):

This creates a button displayable that can be clicked by the user. When this button is clicked or otherwise selected, the function supplied as the clicked argument is called. If it returns a value, that value is returned from ui.interact.

child - The displayable that is contained within this button. This is required.

clicked - A function that is called when this button is clicked.

hovered - A function that is called when this button gains focus.

unhovered - A function that is called when this button loses focus.

role - The role this button undertakes. This can be the empty string, or "selected_".

Function: | Window | (child, **properties):

Creates a Window displayable with the given child and properties.

Function: | Viewport | (child, child_size=(None, None), offsets=(0.0, 0.0), style='viewport', **properties):

Creates a viewport displayable. A viewport restricts the size of its child, and allows the child to be displayed at an offset. This can be used for cropping and scrolling the images. Viewports have two methods, set_xoffset and set_yoffset, that allow the offsets to be changed, and hence the viewport to be scrolled.

child_size - The x and y size of the area the child is asked to render. If either is None, defaults to the size of this viewport.

offsets - The x and y offsets. If an integer, this is taken as a number of pixels. If a float, a fraction of the amount by which the child is larger then the viewport.

In general, viewports are only useful when the xmaximum and ymaximum properties are specified. You'll also want to set clipping=True on the style, although this is part of the default viewport style.

The set_xoffset and set_yoffset methods take a single argument, the new value of the offset.

Function: | Null | (width=0, height=0, **properties):

A displayable that does not display anything. By setting the width and height properties of this displayable, it can be used to take up space.

## Particle Motion

Ren'Py supports particle motion. Particle motion is the motion of many particles on the screen at once, with particles having a lifespan that is shorter than a single interaction. Particle motion can be used to have multiple things moving on the screen at once, such as snow, cherry blossoms, bubbles, fireflies, and more. There are two interfaces we've provided for the particle motion engine. The SnowBlossom function is a convenience constructor for the most common cases of linearly falling or rising particles, while the Particles function gives complete control over the particle engine.

SnowBlossom is a function that can be used for the common case of linearly rising or falling particles. Some cases in which it can be used are for falling snow, falling cherry blossoms, and rising bubbles.

Function: | SnowBlossom | (image, count=10, border=50, xspeed=(20, 50), yspeed=(100, 200), start=0, horizontal=False):

This implements the snowblossom effect, which is a simple linear motion up or down, left, or right. This effect can be used for falling cherry blossoms, falling snow, rising bubbles, and drifting dandelions, along with other things.

image - The image that is to be used for the particles. This can actually be any displayable, so it's okay to use an Animation as an argument to this parameter.

count - The number of particles to maintain at any given time. (Realize that not all of the particles may be on the screen at once.)

border - How many pixels off the screen to maintain a particle for. This is used to ensure that a particle is not displayed on the screen when it is created, and that it is completely off the screen when it is destroyed.

xspeed - The horizontal speed of the particles, in pixels per second. This may be a single integer, or it may be a tuple of two integers. In the latter case, the two numbers are used as a range from which to pick the horizontal speed for each particle. The numbers can be positive or negative, as long as the second is larger then the first.

yspeed - The vertical speed of the particles, in pixels per second. This may be a single integer, but it should almost certainly be a pair of integers which are used as a range from which to pick the vertical speed of each particle. (Using a single number will lead to every particle being used in a wave... not what is wanted.) The second number in the tuple should be larger then the first.

start - This is the number of seconds it will take to start all particles moving. Setting this to a non-zero number prevents an initial wave of particles from overwhelming the screen. Each particle will start in a random amount of time less than this number of seconds.

fast - If true, then all particles will be started at once, and they will be started at random places on the screen, rather then on the top or bottom.

horizontal - If true, the particles start on the left or right edge of the screen. If false, they start along the top or bottom edge.

The result of SnowBlossom is best used to define an image, which can then be shown to the user.

    init:
        image blossoms = SnowBlossom(Animation("sakura1.png", 0.15,
                                               "sakura2.png", 0.15))

It may make sense to show multiple snowblossoms at once. For example, in a scene with falling cherry blossoms, one can have small cherry blossoms falling slowly behind a character, while having larger cherry blossoms falling faster in front of her.

If SnowBlossom does not do what you want, it may make sense to define your own particle motion. This is done by calling the Particles function.

Function: | Particles | (factory, style='default', **properties):

Supports particle motion.

factory - A factory object.

The particles function expects to take as an argument a factory object. This object (which should be pickleable) must support two methods.

The create method of the factory object is called once per frame with two arguments. The first is either a list of existing particles, or None if this is the first time this Particles is shown (and hence there are no particles on the screen). The second argument is the time in seconds from some arbitrary point, increasing each time create is called. The method is expected to return a list of new particles created for this frame, or an empty list if no particles are to be created this frame.

The predict method of the factory object is called when image prediction is requested for the Particles. It is expected to return a list of displayables and/or image filenames that will be used.

Particles are represented by the objects returned from each factory function. Each particle object must have an update method. This method is called once per frame per particle, usually with the time from the same arbitrary point as was used to create the object. (The arbitrary point may change when hidden and shown, so particle code should be prepared to deal with this.) The update method may return None to indicate that the particle is dead. Nothing is shown for a dead particle, and update is never called on it. The update method can also return an (xpos, ypos, time, displayable) tuple. The xpos and ypos parameters are a position on the screen to show the particle at, interpreted in the same way as the xpos and ypos style properties. The time is the time of display. This should start with the time parameter, but it may make sense to offset it to make multiple particle animations out of phase. Finally, the displayable is a displayable or image filename that is shown as the particle.

## Position and Motion Functions

The result of these functions are suitable for use as the argument to the "at" clause of the scene and show statements. The result can also be called (using a second call) to return a displayable.

Function: | Position | (**properties):

Position, when given position properties as arguments, returns a callable that can be passed to the "at" clause of a show or scene statement to display the image at the given location. See the Position Properties section to get a full explanation of how they are used to lay things out.

Function: | Motion | (function, period, repeat=False, bounce=False, time_warp=None, add_sizes=False, anim_timebase=False, **properties):

Motion, when given the appropriate arguments, returns an object that when given as the `at` clause of an image causes an image to be moved on the screen.

function is a function that takes one or two arguments. The first argument is a fraction of the period, a number between 0 and 1. If add_sizes is true, function should take a second argument, a 4-tuple giving the width and height of the area in which the child will be shown, and the width and height of the child itself.

function should return a tuple containing two or four values. The first two values are interpreted as the xpos and the ypos of the motion. (Please note that if these values are floating point numbers, they are interpreted as a fraction of the screen. If they are integers, they are interpreted as the absolute position of the anchor of the motion.) If four values are returned, the third and fourth values are interpreted as an xanchor and yanchor.

Please note that the function may be pickled, which means that it cannot be an inner function or a lambda, but must be a function defined in an init block of your script. In general, it's better to use a Pan or a Move, rather than defining your own motion.

period is the time, in seconds, it takes to complete one cycle of a motion. If repeat is True, then the cycle repeats when it finishes, if False, the motion stops after one period. If bounce is True, the argument to the function goes from 0 to 1 to 0 in a single period, if False, it goes from 0 to 1.

time_warp, if given, is a function that takes a fractional time period (a number between 0.0 and 1.0) and returns a fractional time period. This allows non-linear motions. This function may also be pickled.

anim_timebase is true to use the animation timebase, false to use the displayable timebase.

add_sizes was added in 5.6.6.

Function: | Pan | (startpos, endpos, time, repeat=False, bounce=False, time_warp=None, **properties):

Pan, when given the appropriate arguments, gives an object that can be passed to the at clause of an image to cause the image to be panned on the screen. The parameters startpos and endpos are tuples, containing the x and y coordinates of the upper-left hand corner of the screen relative to the image. time is the time it will take this position to move from startpos to endpos. repeat, bounce, and time_warp are as for Motion.

As the current implementation of Ren'Py is quite limited, there are quite a few restrictions that we put on pan. The big one is that there always must be a screen's worth of pixels to the right and below the start and end positions. Failure to ensure this may lead to inconsistent rendering.

Please note that the pan will be immediately displayed, and that Ren'Py will not wait for it to complete before moving on to the next statement. This may lead to the pan being overlayed with text or dialogue. You may want to use a call to renpy.pause to delay for the time it will take to complete the pan.

Finally, also note that when a pan is completed, the image locks into the ending position.

Function: | Move | (startpos, endpos, time, repeat=False, bounce=False, time_warp=None, **properties):

Move is similar to Pan, insofar as it involves moving things. But where Pan moves the screen through an image, Move moves an image on the screen. Specifially, move changes the position style of an image with time.

Move takes as parameters a starting position, an ending position, the amount of time it takes to move from the starting position to the ending position, and extra position properties. The postions may either be pairs giving the xpos and ypos properties, or 4-tuples giving xpos, ypos, xanchor, and yanchor. These properties may be given as integers or floating point numbers, but for any property it's not permissible to mix the two. repeat, bounce, and time_warp are as for Motion.

In general, one wants to use Pan when an image is bigger than the screen, and Move when it is smaller. Both Pan and Move are special cases of Motion.

anim.SMAnimation can also be used to declare complicated motions. Use None instead of an image in States, and supply a move transition when moving between states. A SMAnimation so created can be passed in to the at clause of an image, allowing it to move things around the screen.

These movement clauses can also be used as Transitions, in which case they affect the position of a single layer or the entire screen, as appropriate.

Function: | Zoom | (size, start, end, time, after_child=None, time_warp=None, bilinear=True, opaque=True, **properties):

This causes a zoom to take place, using image scaling. When used as an `at` clause, this creates a displayable. The render of this displayable is always of the supplied size. The child displayable is rendered, and a rectangle is cropped out of it. This rectangle is interpolated between the start and end rectangles. The rectangle is then scaled to the supplied size. The zoom will take time seconds, after which it will show the end rectangle, unless an after_child is given.

The start and end rectangles must fit completely inside the size of the child, otherwise an error will occur.

size - The size that the rectangle is scaled to, a (width, height) tuple.

start - The start rectangle, an (xoffset, yoffset, width, height) tuple.

end - The end rectangle, an (xoffset, yoffset, width, height) tuple.

time - The amount of time it will take to interpolate from the start to the end rectange.

after_child - If present, a second child widget. This displayable will be rendered after the zoom completes. Use this to snap to a sharp displayable after the zoom is done.

time_warp - If not None, a function that takes a fractional period (between 0.0 and 0.1), and returns a fractional period. Use this to implement non-linear zooms. This function may be pickled, so it cannot be a lambda or other non-top-level function.

bilinear - If True, the default, this will use bilinear filtering. If false, this will use ugly yet fast nearest neighbor filtering.

opaque - If True and bilinear is True, this will use a very efficient method that does not support transparency. If False, this supports transparency, but is less efficient.

Function: | FactorZoom | (size, start, end, time, after_child=None, time_warp=None, bilinear=True, opaque=True, **properties):

This causes a zoom to take place, using image scaling. When used as an `at` clause, this creates a displayable. The render of this displayable is always of the supplied size. The child displayable is rendered, and then scaled by an appropriate factor, interpolated between the start and end factors. The rectangle is then scaled to the supplied size. The zoom will take time seconds, after which it will show the end, unless an after_child is given.

The algorithm used for scaling does not perform any interpolation or other smoothing.

size - The size that the rectangle is scaled to, a (width, height) tuple.

start - The start zoom factor, a floating point number.

end - The end zoom factor, a floating point number.

time - The amount of time it will take to interpolate from the start to the end factors.

after_child - If present, a second child widget. This displayable will be rendered after the zoom completes. Use this to snap to a sharp displayable after the zoom is done.

time_warp - If not None, a function that takes a fractional period (between 0.0 and 0.1), and returns a fractional period. Use this to implement non-linear zooms. This function may be pickled, so it cannot be a lambda or other non-top-level function.

bilinear - If True, the default, this will use bilinear filtering. If false, this will use ugly yet fast nearest neighbor filtering.

opaque - If True and bilinear is True, this will use a very efficient method that does not support transparency. If False, this supports transparency, but is less efficient.

Function: | RotoZoom | (rot_start, rot_end, rot_delay, zoom_start, zoom_end, zoom_delay, rot_repeat=False, zoom_repeat=False, rot_bounce=False, zoom_bounce=False, rot_anim_timebase=False, zoom_anim_timebase=False, rot_time_warp=None, zoom_time_warp=None, opaque=True, **properties):

This function returns an object, suitable for use in an at cause, that rotates and/or zooms its child.

rot_start - The number of degrees of clockwise rotation at the start time.

rot_end - The number of degrees of clockwise rotation at the end time.

rot_delay - The time it takes to complete rotation.

zoom_start - The zoom factor at the start time.

zoom_end - The zoom factor at the end time.

zoom_delay - The time it takes to complete a zoom.

rot_repeat - If true, the rotation cycle repeats once it is finished.

zoom_repeat - If true, the xzoom cycle repeats once it is finished.

rot_bounce - If true, rotate from start to end to start each cycle. If False, rotate from start to end once.

zoom_bounce - If true, zoom from start to end to start each cycle. If False, zoom from start to end once.

rot_anim_timebase - If true, rotation times are judged from when a displayable with the same tag was first shown. If false, times are judged from when this displayable was first shown.

zoom_anim_timebase - If true, zoom times are judged from when a displayable with the same tag was first shown. If false, times are judged from when this displayable was first shown.

opaque - This should be True if the child is fully opaque, and False otherwise.

RotoZoom uses a bilinear interpolation method that is accurate when the zoom factor is >= 0.5.

Rotation is around the center of the child displayable.

Note that this shrinks what it is rotozooming by 1 pixel horizontally and vertically. Images should be 1 pixel larger then they would otherwise be.

The produced displayable has height and with equal to the hypotenuse of the sides of the child. This may disturb the layout somewhat. To minimize this, position the center of the RotoZoom.

The time taken to RotoZoom is proportional to the area of the rotozoomed image that is shown on screen.

Function: | Revolve | (start, end, time, around=(0.5, 0.5), cor=(0.5, 0.5), **kwargs):

Used to revolve it's child around a point in its parent. around is the point in the parent that we are revolving around, while cor is the center of revolution for the child. start is the start revolution, and end is the end revolution, both in degrees clockwise.

Other keyword arguments are as for Motion.

To apply the results of these functions to a displayable, use the At function.

Function: | At | (displayable, *positions_and_motions):

The At function is used to apply the results of position and motion functions to displayables, yielding a displayable.

## Position Definitions

These positions can be used as the argument to the at clause of a scene or show statement.

Definition: | left |

A Position in which the left side of the image is aligned with the left side of the screen, with the bottom flush against the bottom of the screen.

Definition: | right |

A position in which the right side of the image is aligned with the right side of the screen, with the bottom of the image flush against the bottom of the screen.

Definition: | center |

A position in which the image is centered horizontally, with the bottom of the image flush against the bottom of the screen.

Definition: | offscreenleft |

A position in which the image is placed just off the left side of the screen. Please note that an image placed in this position, while not visible to the user, still consumes resources, and so images should be hidden when not visible. This position is intended to be used with the move transition.

Definition: | offscreenright |

A position in which the image is placed just off the right side of the screen. Please note that an image placed in this position, while not visible to the user, still consumes resources, and so images should be hidden when not visible. This position is intended to be used with the move transition.

documentation index ◦ reference manual ◦ function index