Displayables

This image manipulator loads an image from a file.

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

An alias for im.Image.

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.

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.

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.

This crops the image that is its child.

Scales the supplied image manipulator im by the given width and height factors. If height is not given, it defaults to the width.

bilinear - If True, bilinear scaling is used.

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.

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.

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.

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.

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.

This takes as arguments two colors, white and black. The image is mapped such that pixels in white have the white color, pixels in black have the black color, and shades of gray are linearly interpolated inbetween. The alpha channel is mapped linearly between 0 and the alpha found in the white color, the black color's alpha is ignored.

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.

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.

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.

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].

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.

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

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 desaturated 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.

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

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.)

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

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.

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.

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.

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

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

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.

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.

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

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.

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.

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.

Note that ConditionSwitch is a wrapper around DynamicDisplayable, and may be simpler depending on your needs.

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.

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.

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.

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.

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.

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.

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.

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.

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

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_".

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.

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.

Position and Motion Functions

This section has been made somewhat obsolete by the introduction of ATL in Ren'Py 6.10.

Position Definitions

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

Transform

A Transform allows one to use a Python function to control many aspects of its child. While more complicated, Transform is powerful enough to implement all of the position and motion functions. A Transform may be used as a displayable (by supplying a child) or a position and motion function (omit the child).