Translations by 이어진

Displaying Images

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 has the ``with`` statement, which allows effects to be applied when the scene is changed.

Concepts

Image

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 :dfn:`image name` consists of one or more names, separated by spaces. The first component of the image name is called the :dfn:`image tag`. The second and later components of the name are the :dfn:`image attributes`.

For example, take the image name ``mary beach night happy``. The image tag is ``mary``, while the image attributes are ``beach``, ``night``, and ``happy``.

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 :ref:`any displayable Ren'Py supports <displayables>`, 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.

Layer

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 :var:`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:

master

This is the default layer that is used by the scene, show, and hide statements. It's generally used for backgrounds and character sprites.

transient

The default layer used by ui functions. This layer is cleared at the end of each interaction.

screens

This layer is used by the screen system.

overlay

The default layer used when a ui function is called from within an overlay function. This layer is cleared when an interaction is restarted.

Additional layers can be defined by updating :var:`config.layers`, and the various other layer-related config variables. Using :func:`renpy.layer_at_list`, one or more transforms can be applied to a layer.

Image Statement

An image statement is used to define an image. An image statement consists of a single logical line beginning with the keyword ``image``, followed by an image name, an equals sign (``=``), and a displayable. For example::

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

See also the :ref:`ATL variant of the image statement. <atl-image-statement>`

Show 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 keyword ``show``, followed by an image name, followed by zero or more properties.

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:

Has the same tag as the one specified in the show statement.

Has all of the attributes given in the show statement.

If an image with the same tag is already showing, shares the largest number of attributes with that image.

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:

``as``

The as property takes a name. This name is used in place of the image tag when the image is shown. This allows the same image to be on the screen twice.

``at``

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 :var:`default` transform.

``behind``

Takes a comma-separated list of one or more names. Each name is taken as an image tag. The image is shown behind all images with the given tags that are currently being shown.

``onlayer``

Takes a name. Shows the image on the named layer.

``zorder``