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

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. (RLE was added in 5.6.2.)

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

Image Manipulator List. The image manipulators are:

Backgrounds

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

Text

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

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.

Dynamic

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

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 animation functions are:

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

Widget

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

Include: Nothing found for "^== "!

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

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)

This implements the snowblossom effect, which is a simple linear motion up or down the screen. This effect can be used for falling cherry blossoms, falling snow, and rising bubbles, 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. The numbers can be positive or negative, but you shouldn't mix the two in the same tuple. If positive numbers are given, the particles fall from the top of the screen to the bottom, as with snow or cherry blossoms. If negative numbers are given, the particles rise from the bottom of the screen to the top, as with bubbles.

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.

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: 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 positions are given as tuples containing xpos and ypos properties. The positions may be integer or floating point, but it's not permissable 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( self, 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.

Position Definitions

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