Displaying Images

The defining aspect of a visual novel, lending its name to the form, arethe visuals. Ren'Py contains four statements that control the display ofimages, and a model that determines the order in which the images aredisplayed. This makes it convenient to display images in a manner thatis 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'Pyhas thewith statement, which allows effects to be appliedwhen the scene is changed.

Most (if not all) of the statements listed in this page are checked byLint, which is not the case for their python equivalents.

Concepts

Image

An image is something that can be show to the screen using the showstatement. An image consists of a name and a displayable. When theimage is shown on a layer, the displayable associated with it isdisplayed on that layer.

Animage name consists of one or more names, separated byspaces. The first component of the image name is called theimagetag. The second and later components of the name are theimageattributes.

For example, take the image namemarybeachnighthappy. The imagetag ismary, while the image attributes arebeach,night,andhappy.

A displayable is something that can be shown on the screen. The mostcommon thing to show is a static image, which can be specified bygiving the filename of the image, as a string. In the example above,we might usemary_beach_night_happy.png as the filename.However, an image may refer toany displayable Ren'Py supports, not just static images. Thus, the same statementsthat are used to display images can also be used for animations, solidcolors, and the other types of displayables.

Layer

A layer is a list of displayables that are shown on the screen. Ren'Pysupports multiple layers, including user-defined layers. The order ofthe layers is fixed within a game (controlled by theconfig.layers variable), while the order of displayables withina layer is controlled by the order in which the scene and showstatements 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, andhide statements. It's generally used for backgrounds andcharacter sprites.

transient

The default layer used by ui functions. This layer is cleared atthe 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 withinan overlay function. This layer is cleared when an interaction isrestarted.

Additional layers can be defined by callingrenpy.add_layer(), andusing the various layer-relatedconfiguration variables.Using thecamera statement, one or more transforms can beapplied to a layer.

Defining Images

There are two ways to define images. You can either place an image filein 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 allowsimages that are not image files.

Images defined using the image statement take precedence over those definedby the image directory.

Images Directory

The image directory is named "images", and is placed under the game directory.When a file with a .jpg, .jpeg, .png, or .webp extension is placed underneath this directory,the extension is stripped, the rest of the filename is forced to lowercase,and the resulting filename is used as the image name if an image with thatname has not been previously defined.

This process takes place in all directories underneath the image directory. Forexample, all of these files will define the imageeileenhappy:

game/images/eileenhappy.pnggame/images/EileenHappy.jpggame/images/eileen/eileenhappy.png

When an image filename is given, and the image is not found, the images directoryis searched.

Oversampling

By default, the pixel size of an image defines the size it will take upwhen displayed. For example, if an image is 1920x1080 pixels, and thegame is configured, usinggui.init(), to run at 1920x1080, theimage will fill the entire screen.

When oversampling is enabled, the size that the image is displayed at issmaller than the image size would imply. For example, if an image is 3480x2160,and has an oversample of 2, then each axis will be halved, and the image wouldfill the same 1920x1080 window.

This is useful when the image might be zoomed in on, and the extra detail isrequired. Oversampling is also useful in conjunction withconfig.physical_widthandconfig.physical_height to allow a game to be remade with higherresolution graphics.

Oversampling is automatically enabled if the image ends with an '@' followedby a number, before the extension. For example,eileenhappy@2.png is2x oversampled, andeileenhappy@3.png will be 3x oversampled. Oversamplingcan also be enabled by giving theoversample keyword argument toImage().

A directory can also specify how much to oversample images inside it. For example,images/@2/eileenhappy.png will be oversampled 2x.

If no oversampling is applied to an image, Ren'Py will attempt to automatically findoversampled images to use. For example, if the game is scaled by more than 1x and less than or exactly 2x,Ren'Py loadingeileenhappy.png will look foreileenhappy@2.png, and use that if it exists. If the scalingis greater than 2x, Ren'Py will look foreileenhappy@4.png,eileenhappy@3.png, andeileenhappy@2.png,and use the first one that it finds, oreileenhappy.png if none of them exist.

Image Statement

Theimage statement is used to define an image. An image statementconsists of a single logical line beginning with the keywordimage,followed by an image name, an equals sign=, and adisplayable. For example:

imageeileenhappy="eileen_happy.png"imageblack="#000"imagebgtiled=Tile("tile.jpg")imageeileenhappyquestion=VBox("question.png","eileen_happy.png",)

When an image file is not directly in the game directory, you'll need togive the directories underneath it. For example, if the image is atgame/eileen/happy.png, then you can write:

imageeileenhappy="eileen/happy.png"

The image statement is run at init time, before the menus are shownor the start label runs. When not contained inside aninit block,image statements are run as if they were placed inside aninit block ofpriority 500.

See also theATL variant of the image statement.

Show Statement

Theshow statement is used to display an image on a layer. A showstatement consists of a single logical line beginning with thekeywordshow, followed by an image name, followed by zero ormore 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 tofind 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 largestnumber 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 allother images in the layer. (That is, closest to the user.) This ordermay be modified by thezorder andbehind properties.

The show statement does not cause an interaction to occur. For theimage to actually be displayed to the user, a statement that causes aninteraction (like the say, menu, pause, and with statements) must berun.

The show statement takes the following properties:

as

Theas property takes a name. This name is used in place of theimage tag when the image is shown. This allows the same imageto be on the screen twice.

at

Theat property takes one or more comma-separatedsimple expressions. Each expression must evaluate to atransform. The transforms are applied to the image inleft-to-right order.

If no at clause is given, Ren'Py will retain any existingtransform that has been applied to the image, if they werecreated with ATL or withTransform. If no transformis specified, the image will be displayed using thedefaulttransform.

See the section onreplacing transformsfor information about how replacing the transforms associated witha tag can change the transform properties.

behind

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

onlayer

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

zorder

Takes an integer. The integer specifies the relative ordering ofimages within a layer, with larger numbers being closer to theuser. This isn't generally used by Ren'Py games, but can be usefulwhen porting visual novels from other engines. This can also beuseful for displaying an image that will be above any zorder-lessimage displayed afterwards, without the burden of placing it onanother layer.

Assuming we have the following images defined:

imagemarynighthappy="mary_night_happy.png"imagemarynightsad="mary_night_sad.png"imagemoon="moon.png"

Some example show statements are:

# Basic show.showmarynightsad# Since 'mary night sad' is showing, the following statement is# equivalent to:# show mary night happyshowmaryhappy# Show an image on the right side of the screen.showmarynighthappyatright# Show the same image twice.showmarynightsadasmary2atleft# Show an image behind another.showmoonbehindmary,mary2# Show an image on a user-defined layer.showmoononlayeruser_layer

Attributes management

As shown above, attributes can be set, added and replaced.

They can also be removed using the minus sign:

# show susan being neutralshowsusan# show susan being happyshowsusanhappy# show susan being neutral againshowsusan-happy

Show expression

A variant of the show statement replaces the image name with thekeywordexpression, followed by a simple expression. Theexpression must evaluate to a displayable, and the displayableis shown on the layer. To hide the displayable, a tag must begiven with the as statement.

For example:

showexpression"moon.png"asmoon

Show Layer

Theshowlayer statement is discussed alongside thecamera statement,below.

Scene Statement

Thescene statement removes all displayables from a layer, and thenshows an image on that layer. It consists of the keywordscene,followed by an image name, followed by zero or more properties. Theimage is shown in the same way as in the show statement, and the scenestatement takes the same properties as the show statement.

The scene statement is often used to show an image on the backgroundlayer. For example:

scenebgbeach

Scene Expression.Like the show statement, the scene statement can take expressionsinstead of image names.

Clearing a layer.When the image name is omitted entirely, the scene statement clearsall displayables from a layer without showing anotherdisplayable.

Hide Statement

Thehide statement removes an image from a layer. It consists of thekeywordhide, followed by an image name, followed by an optionalproperty. 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 acharacter, then a hide statement is only necessary when the characterleaves the scene. When the character changes her emotion, it ispreferable to use the show statement instead, as the show statementwill automatically replace an image with the same tag.

The hide statement takes the following property:

onlayer

Takes a name. Hides the image from the named layer.

For example:

e"I'm out of here."hideeileen

You should never write:

hideeileenshoweileenhappy

Instead, just write:

showeileenhappy

With Statement

Thewith statement is used to apply a transition effect when the sceneis changed, making showing and hiding images less abrupt. The withstatement consists of the keywordwith, followed by a simpleexpression that evaluates either to a transition object or the specialvalueNone.

The transition effect is applied between the contents of the screen atthe end of the previous interaction (with transient screens anddisplayables hidden), and the current contents of the scene, after theshow and hide statements have executed.

The with statement causes an interaction to occur. The duration ofthis interaction is controlled by the user, and the user can cause itto terminate early.

For a full list of transitions that can be used, see the chapter ontransitions.

An example of the with statement is:

showbgwashingtonwithdissolveshoweileenhappyatleftshowlucymadatrightwithdissolve

This causes two transitions to occur. The first with statement usesthedissolve transition to change the screen from what waspreviously shown to the washington background. (Thedissolvetransition is, by default, defined as a .5 second dissolve.)

The second transition occurs after the Eileen and Lucy images areshown. It causes a dissolve from the scene consisting solely of thebackground to the scene consisting of all three images – the result isthat the two new images appear to dissolve in simultaneously.

With None

In the above example, there are two dissolves. But what if we wantedthe background to appear instantly, followed by a dissolve of the twocharacters? Simply omitting the first with statement would cause allthree images to dissolve in – we need a way to say that the firstshould be show instantly.

The with statement changes behavior when given the special valueNone. ThewithNone statement causes an abbreviatedinteraction to occur, without changing what the user sees. When thenext transition occurs, it will start from the scene as it appears atthe end of this abbreviated interaction.

For example, in:

showbgwashingtonwithNoneshoweileenhappyatleftshowlucymadatrightwithdissolve

Only a single transition occurs, from the washington background to thescene consisting of all three images.

With Clause of Scene, Show, and Hide Statements

The show, scene, and hide statements can take an optionalwith clause,which allows a transition to be combined with showing or hiding animage. This clause follows the statements at the end of the samelogical line. It begins with the keywordwith, followed by asimple expression.

The with clause is equivalent to preceding the line with awithNone statement, and following it by awith statement containing thetext of the with clause. For example:

showeileenhappyatleftwithdissolveshowlucymadatrightwithdissolve

is equivalent to:

withNoneshoweileenhappyatleftwithdissolvewithNoneshowlucymadatrightwithdissolve

Note that even though this applies to theShow ScreenandHide Screen statements too,Call Screen differently.

Camera and Show Layer Statements

Thecamera statement allows one to apply a transform or ATL transform to anentire layer (such as "master"), using syntax like:

cameraatflip

or:

camera:xalign0.5yalign0.5rotate180

To stop applying transforms to the layer, use:

camera

The camera statement takes an optional layer name, betweencamera andat or:.

cameramylayeratflip

Theshowlayer statement is an older version ofcamera, with somedifferences, that is still useful.

showlayermaster:blur10

The differences are:

  • The transforms applied withshowlayer are cleared at thenextscene statement, whilecamera transforms last untilexplicitly cleared.

  • showlayer requires a layer name, whilecamera defaults to themaster layer.

Hide and Show Window

Thewindow statement is used to control if a window is shown when a characteris not speaking (for example, during transitions and pauses). Thewindowshowstatement causes the window to be shown, while thewindowhide statement hidesthe window.

If the optional transition is given, it's used to show and hide the window.If not given, it defaults toconfig.window_show_transition andconfig.window_hide_transition. Giving None as the transition preventsit from occurring.

The window itself is displayed by callingconfig.empty_window. It defaults tohaving the narrator say an empty string.

showbgwashingtonshoweileenhappywithdissolvewindowshowdissolve"I can say stuff..."showeileenhappyatrightwithmove"... and move, while keeping the window shown."windowhidedissolve

Image Functions

renpy.add_layer(layer,above=None,below=None,menu_clear=True,sticky=None)

Adds a new layer to the screen. If the layer already exists, thisfunction does nothing.

One ofbehind orabove must be given.

layer

A string giving the name of the new layer to add.

above

If not None, a string giving the name of a layer the new layer willbe placed above.

below

If not None, a string giving the name of a layer the new layer willbe placed below.

menu_clear

If true, this layer will be cleared when entering the game menucontext, and restored when leaving it.

sticky

If true, any tags added to this layer will have it become theirdefault layer until they are hidden. If None, this layer will besticky only if other sticky layers already exist.

renpy.can_show(name,layer=None,tag=None)

Determines ifname can be used to show an image. This interpretsnameas a tag and attributes. This is combined with the attributes of thecurrently-showing image withtag onlayer to try to determine a unique imageto show. If a unique image can be show, returns the name of that image asa tuple. Otherwise, returns None.

tag

The image tag to get attributes from. If not given, defaults to the firstcomponent ofname.

layer

The layer to check. If None, uses the default layer fortag.

renpy.change_zorder(layer,tag,zorder)

Changes the zorder oftag onlayer tozorder.

renpy.check_image_attributes(tag,attributes)

Checks to see if there is a unique image with the given tag andattributes. If there is, returns the attributes in order.Otherwise, returns None.

renpy.clear_attributes(tag,layer=None)

Clears all image attributes for thetag image.If the tag had no attached image attributes, this does nothing.

layer

The layer to check. If None, uses the default layer fortag.

renpy.copy_images(old,new)

Copies images beginning with one prefix to images beginning withanother. For example:

renpy.copy_images("eileen","eileen2")

will create an image beginning with "eileen2" for every image beginningwith "eileen". If "eileen happy" exists, "eileen2 happy" will becreated.

old

A space-separated string giving the components of the old imagename.

new

A space-separated string giving the components of the new imagename.

This function may only be run from inside an init block. It is anerror to run this function once the game has started. As theimagestatement runs with init priority 500, this should generally be calledwith init priority 501 or higher.

renpy.flush_cache_file(fn)

This flushes all image cache entries that refer to the filefn. Thismay be called when an image file changes on disk to force Ren'Py touse the new version.

renpy.get_attributes(tag,layer=None,if_hidden=None)

Return a tuple giving the image attributes for the imagetag. Ifthe image tag has not had any attributes associated since the lasttime it was hidden, returnsif_hidden.

layer

The layer to check. If None, uses the default layer fortag.

renpy.get_available_image_tags()

Returns a list of image tags that have been defined.

renpy.get_hidden_tags(layer='master')

Returns the set of image tags onlayer that are currently hidden, butstill have attribute information associated with them.

renpy.get_image_bounds(tag,width=None,height=None,layer=None)

If an image withtag exists onlayer, returns the bounding box ofthat image. Returns None if the image is not found.

The bounding box is an (x, y, width, height) tuple. The components ofthe tuples are expressed in pixels, and may be floating point numbers.

width,height

The width and height of the area that contains the image. If None,defaults the width and height of the screen, respectively.

layer

If None, uses the default layer fortag.

renpy.get_ordered_image_attributes(tag,attributes=(),sort=None)

Returns a list of image attributes, ordered in a way that makes sense topresent to the user.

attributes

If present, only attributes that are compatible with the givenattributes are considered. (Compatible means that the attributescan be in a single image at the same time.)

sort

If not None, the returned list of attributes is sorted. This is aone-argument function that should be used as a tiebreaker - seethis tutorialfor more information.

renpy.get_placement(d)

This gets the placement of displayable d. There's very little warranty on thisinformation, as it might change when the displayable is rendered, and might notexist until the displayable is first rendered.

This returns an object with the following fields, each corresponding to a styleproperty:

  • pos

  • xpos

  • ypos

  • anchor

  • xanchor

  • yanchor

  • offset

  • xoffset

  • yoffset

  • subpixel

renpy.get_registered_image(name)

If an image with the same name has beenregistered,returns it. Otherwise, returns None.

renpy.get_say_image_tag()

Returns the tag corresponding to the currently speaking character (theimage argument given to that character). Returns None if no characteris speaking or the current speaking character does not have a correspondingimage tag.

renpy.get_showing_tags(layer='master',sort=False)

Returns the set of image tags that are currently being shown onlayer. Ifsort is true, returns a list of the tags from back to front.

renpy.get_zorder_list(layer)

Returns a list of (tag, zorder) pairs forlayer.

renpy.has_image(name,exact=False)

Return true if an image withname exists, and false if no such imageexists.

name

Either a string giving an image name, or a tuple of strings givingthe name components.

exact

Returns true if and only if an image with the exact name exists -parameterized matches are not included.

renpy.list_images()

Returns a list of images that have been added to Ren'Py, as a list ofstrings with spaces between the name components.

renpy.mark_image_seen(name)

Marks the named image as if it has been already displayed on the current user'ssystem.

renpy.mark_image_unseen(name)

Marks the named image as if it has not been displayed on the current user'ssystem yet.

renpy.seen_image(name)

Returns True if the named image has been seen at least once on the user'ssystem. An image has been seen if it's been displayed using the show statement,scene statement, orrenpy.show() function. (Note that there are caseswhere the user won't actually see the image, like a show immediately followed bya hide.)

renpy.showing(name,layer=None)

Returns true if an image with the same tag asname is showing onlayer.

image

May be a string giving the image name or a tuple giving eachcomponent of the image name. It may also be a string givingonly the image tag.

layer

The layer to check. If None, uses the default layer fortag.

renpy.start_predict(*args)

This function takes one or more displayables as arguments. It causesRen'Py to predict those displayables during every interaction untilthe displayables are removed byrenpy.stop_predict().

If a displayable name is a string containing one or more *characters, the asterisks are used as a wildcard pattern. If thereis at least one . in the string, the pattern is matched againstfilenames, otherwise it is matched against image names.

For example:

$renpy.start_predict("eileen *")

starts predicting all images with the name eileen, while:

$renpy.start_predict("images/concert*.*")

matches all files starting with concert in the images directory.

Prediction will occur during normal gameplay. To wait for predictionto complete, use thepredict argument torenpy.pause().

renpy.stop_predict(*args)

This function takes one or more displayables as arguments. It causesRen'Py to stop predicting those displayables during every interaction.

Wildcard patterns can be used as described inrenpy.start_predict().

See also

Statement Equivalents : how to use most of the features described here in apython context.

Displayables : other objects to display, more diverse than basic images.