The defining aspect of a visual novel, lending its name to the form, are the visuals. Ren'Py contains four statements that control the display of images, and a model that determines the order in which the images are displayed. This makes it convenient to display images in a manner that is suitable for use in visual novels and other storytelling games.
The four statements that work with images are:
image- defines a new image.
show- shows an image on a layer.
scene- clears a layer, and optionally shows an image on that layer.
hide- removes an image from a layer.
As abrupt changes of image can be disconcerting to the user, Ren'Py
with statement, which allows effects to be applied
when the scene is changed.
An image is something that can be show to the screen using the show statement. An image consists of a name and a displayable. When the image is shown on a layer, the displayable associated with it is displayed on that layer.
An image name consists of one or more names, separated by spaces. The first component of the image name is called the image tag. The second and later components of the name are the image attributes.
For example, take the image name
mary beach night happy. The image
mary, while the image attributes are
A displayable is something that can be shown on the screen. The most
common thing to show is a static image, which can be specified by
giving the filename of the image, as a string. In the example above,
we might use
"mary_beach_night_happy.png" as the filename.
However, an image may refer to any displayable Ren'Py supports, not just static images. Thus, the same statements
that are used to display images can also be used for animations, solid
colors, and the other types of displayables.
A layer is a list of displayables that are shown on the screen. Ren'Py
supports multiple layers, including user-defined layers. The order of
the layers is fixed within a game (controlled by the
config.layers variable), while the order of displayables within
a layer is controlled by the order in which the scene and show
statements are called, and the properties given to those statements.
The following layers are defined as part of Ren'Py:
There are two ways to define images. You can either place an image file in the image directory, or an image can be defined using the image statement. The former is simple, as it involves placing properly named files in a directory, while the latter a allows more control over how the image is defined, and allows images that are not image files.
Images defined using the image statement take precedence over those defined by the image directory.
The image directory is named "images", and is placed under the game directory. When a file with the .jpg or .png extension is placed underneath this directory, the extension is stripped, the rest of the filename is forced to lower case, and the resulting filename is use as the image name if an image with that name has not been previously defined.
This process place in all directories underneath the image directory. For
example, all of these files will define the image
game/images/eileen happy.png game/images/Eileen Happy.jpg game/images/eileen/eileen happy.png
An image statement is used to define an image. An image statement
consists of a single logical line beginning with the keyword
followed by an image name, an equals sign (
=), and a
displayable. For example:
image eileen happy = "eileen_happy.png" image black = "#000" image bg tiled = LiveTile("tile.jpg") image eileen happy question = VBox( "question.png", "eileen_happy.png", )
The image statement must be run at init-time, before game code runs. When not contained inside an init block, image statements are run at init-time, as if they were placed inside an init block of priority 500.
See also the ATL variant of the image statement.
The show statement is used to display an image on a layer. A show
statement consists of a single logical line beginning with the
show, followed by an image name, followed by zero or
If the show statement is given the exact name of an existing image, that image is the one that is shown. Otherwise, Ren'Py will attempt to find a unique image that:
If a unique image cannot be found, an exception occurs.
If an image with the same image tag is already showing on the layer, the new image replaces it. Otherwise, the image is placed above all other images in the layer. (That is, closest to the user.) This order may be modified by the zorder and behind properties.
The show statement does not cause an interaction to occur. For the image to actually be displayed to the user, a statement that causes an interaction (like the say, menu, pause, and with statements) must be run.
The show statement takes the following properties:
The at property takes one or more comma-separated simple expressions. Each expression must evaluate to a transform. The transforms are applied to the image in left-to-right order.
If no at clause is given, Ren'Py will retain any existing
transform that has been applied to the image. If no transform
exists, the image will be displayed using the
Assuming we have the following images defined:
image mary night happy = "mary_night_happy.png" image mary night sad = "mary_night_sad.png" image moon = "moon.png"
Some example show statements are:
# Basic show show mary night sad # Since 'mary night happy' is showing, the following statement is # equivalent to: # show mary night happy show mary happy # Show an image on the right side of the screen. show mary night happy at right # Show the same image twice. show mary night sad as mary2 at left # Show an image behind another. show moon behind mary, mary2 # Show an image on a user-defined layer. show moon onlayer user_layer
A variant of the show statement replaces the image name with the
expression, followed by a simple expression. The
expression must evaluate to a displayable, and the displayable
is shown on the layer. To hide the displayable, a tag must be
given with the as statement.
show expression "moon.png" as moon
Show Layer. The show layer statement allows one to apply a transform or ATL transform to an entire layer (such as "master"), using syntax like:
show layer master at flip
show layer master: xalign 0.5 yalign 0.5 rotate 180
To stop applying transforms to the layer, use:
show layer master
Transforms used with show should not may any assumptions about their starting state. Currently, transforms used with show layer do not take their state from prior layer transforms, but we plan to change this in the future.
The scene statement removes all displayables from a layer, and then
shows an image on that layer. It consists of the keyword
followed by an image name, followed by zero or more properties. The
image is shown in the same way as in the show statement, and the scene
statement takes the same properties as the show statement.
The scene statement is often used to show an image on the background layer. For example:
scene bg beach
Scene Expression. Like the show statement, the scene statement can take expressions instead of image names.
Clearing a layer. When the image name is omitted entirely, the scene statement clears all displayables from a layer without showing another displayable.
The hide statement removes an image from a layer. It consists of the
hide, followed by an image name, followed by an optional
property. The hide statement takes the image tag from the image name,
and then hides any image on the layer with that tag.
Hide statements are rarely necessary. If a sprite represents a character, then a hide statement is only necessary when the character leaves the scene. When the character changes her emotion, it is preferable to use the show statement instead, as the show statement will automatically replace an image with the same tag.
The hide statement takes the following property:
e "I'm out of here." hide eileen
You should never write:
hide eileen show eileen happy
Instead, just write:
show eileen happy
The with statement is used to apply a transition effect when the scene
is changed, making showing and hiding images less abrupt. The with
statement consists of the keyword
with, followed by a simple
expression that evaluates either to a transition object or the special
The transition effect is applied between the contents of the screen at the end of the previous interaction (with transient screens and displayables hidden), and the current contents of the scene, after the show and hide statements have executed.
The with statement causes an interaction to occur. The duration of this interaction is controlled by the user, and the user can cause it to terminate early.
For a full list of transitions that can be used, see the chapter on transitions.
An example of the with statement is:
show bg washington with dissolve show eileen happy at left show lucy mad at right with dissolve
This causes two transitions to occur. The first with statement uses
dissolve transition to change the screen from what was
previously shown to the washington background. (The
transition is, by default, defined as a .5 second dissolve.)
The second transition occurs after the Eileen and Lucy images are shown. It causes a dissolve from the scene consisting solely of the background to the scene consisting of all three images - the result is that the two new images appear to dissolve in simultaneously.
In the above example, there are two dissolves. But what if we wanted the background to appear instantly, followed by a dissolve of the two characters? Simply omitting the first with statement would cause all three images to dissolve in - we need a way to say that the first should be show instantly.
The with statement changes behavior when given the special value
with None statement causes an abbreviated
interaction to occur, without changing what the user sees. When the
next transition occurs, it will start from the scene as it appears at
the end of this abbreviated interaction.
For example, in the code:
show bg washington with None show eileen happy at left show lucy mad at right with dissolve
Only a single transition occurs, from the washington background to the scene consisting of all three images.
The show, scene, and hide statements can take an optional with clause,
which allows a transition to be combined with showing or hiding an
image. This clause follows the statements at the end of the same
logical line. It begins with the keyword
with, followed by a
The with clause is equivalent to preceding the line with a
None statement, and following it by a with statement containing the
text of the with clause. For example:
show eileen happy at left with dissolve show lucy mad at right with dissolve
is equivalent to:
with None show eileen happy at left with dissolve with None show lucy mad at right with dissolve
The window statement is used to control if a window is shown when a character is not speaking. (For example, during transitions and pauses.) The window show statement causes the window to be shown, while the window hide statement hides the window.
If the optional transition is given, it's used to show and hide the window.
If not given, it defaults to
config.window_hide_transition. Giving None as the transition prevents
it from occurring.
The window itself is displayed by calling
config.empty_window. It defaults to
having the narrator say an empty string.:
show bg washington show eileen happy with dissolve window show dissolve "I can say stuff..." show eileen happy at right with move "... and move, while keeping the window shown." window hide dissolve
can_show(name, layer=None, tag=None) link
Determines if name can be used to show an image. This interprets name as a tag and attributes. This is combined with the attributes of the currently-showing image with tag on layer to try to determine a unique image to show. If a unique image can be show, returns the name of that image as a tuple. Otherwise, returns None.
check_image_attributes(tag, attributes) link
Checks to see if there is a unique image with the given tag and attributes. If there is, returns the tag and attributes in order. Otherwise, returns None.
copy_images(old, new) link
Copies images beginning with one prefix to images beginning with another. For example:
will create an image beginning with "eileen2" for every image beginning with "eileen". If "eileen happy" exists, "eileen2 happy" will be created.
Returns a list of image tags that have been defined.
get_image_bounds(tag, width=None, height=None, layer='master') link
If an image with tag exists on layer, returns the bounding box of that image. Returns None if the image is not found.
The bounding box is an (x, y, width, height) tuple. The components of the tuples are expressed in pixels, and may be floating point numbers.
get_ordered_image_attributes(tag, attributes=(), sort=None) link
Returns a list of image tags, ordered in a way that makes sense to present to the user.
This gets the placement of displayable d. There's very little warranty on this information, as it might change when the displayable is rendered, and might not exist until the displayable is first rendered.
This returns an object with the following fields, each corresponding to a style property:
Returns the set of image tags that are currently being shown on layer
has_image(name, exact=False) link
Return true if an image with name exists, and false if no such image exists.
Returns True if the named image has been seen at least once on the user's
system. An image has been seen if it's been displayed using the show statement,
scene statement, or
renpy.show() function. (Note that there are cases
where the user won't actually see the image, like a show immediately followed by
showing(name, layer='master') link
Returns true if an image with the same tag as name is showing on layer
This function takes one or more displayables as arguments. It causes
Ren'Py to predict those displayables during every interaction until
the displayables are removed by
This function takes one or more displayables as arguments. It causes Ren'Py to stop predicting those displayables during every interaction.