You've reached a page on the Ren'Py wiki. Due to massive spam, the wiki hasn't been updated in over 5 years, and much of the information here is very out of date. We've kept it because some of it is of historic interest, but all the information relevant to modern versions of Ren'Py has been moved elsewhere.
Some places to look are:
Please do not create new links to this page.
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 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.
When Ren'Py expects a displayable to be specified, it allows them to be in the following forms:
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.
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:
ImageReference is used to access images declared with the image statement.
The im.MatrixColor image manipulator takes a 20 or 25 element matrix, and uses it to linearly transform the colors of an image.
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.
The following functions produce im.matrix objects:
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:
There are two displayables that are eminently suitable for use as backgrounds:
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 object to show text. By default there is one image, named `text` declared, but the user can declare more than one to show multiple text blocks on the screen at once.
can be used in styles to change the displayable shown over the course of the game.
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:
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.)
The anim.Filmstrip function is not deprecated.
These displayables are used to layout multiple displayables at once.
These are generally used with the ui functions, but may sometimes be used as displayables.
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 function is a convenience constructor for the most common cases of linearly falling or rising particles, while the function gives complete control over the particle engine.
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 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 does not do what you want, it may make sense to define your own particle motion. This is done by calling the function.
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.
In general, one wants to use when an image is bigger than the screen, and when it is smaller. Both and are special cases of .
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.
To apply the results of these functions to a displayable, use the At function.
These positions can be used as the argument to the at clause of a scene or show statement.
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.
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.
A position in which the image is centered horizontally, with the bottom of the image flush against the bottom of the screen.
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.
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.
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).