documentation index

## Adding Graphics to Your Story

### Initializing the Graphics

The first step in using a graphic image is to tell Ren'Py about it in an init block with an image statement. You create a Ren'Py image from either solid colors or files (really, any Displayable):

    init:
        image black = "#000000"
        image bg park = "park.jpg"
        image eileen happy = "eileen1.png"
        image eileen sad = "eileen2.png"
        image eileen surprised = "eileen3.png"

As you see, image names can be more than one word. We'll talk about why this is useful in the section on hiding images. Image names and character objects don't have anything to do with each other, so you can re-use character names as image names.

### Showing graphics before the game begins

If you want to show a picture before the player gets to the main screen, then use the label "splashscreen" like so:

    label splashscreen:
        show opening picture name
        $ renpy.pause(2.0)
        return

The line "$ renpy.pause(2.0)" will show the picture for two seconds. Change the number if you want to show it for a different time. If you leave the brackets empty, so:

    label splashscreen:
        show opening picture name
        $ renpy.pause()
        return

Then Ren'Py will show the picture until the player clicks the mouse or presses "Return".

### Scene Backgrounds

The scene statement clears the display of what's on it and optionally places a new background on the display:

    scene bg park

(Please recall that "bg park" is the name of the image; bg is not a keyword.)

### Character Graphics

Character graphics and other objects which are drawn in the foreground are displayed with the show statement:

    show eileen happy

A show statement without any modifiers shows the image centered in the screen. You can also display images on the sides:

    show eileen happy at right

    show eileen happy at left

#### Custom positions

Ren'Py already has some standard positions defined, but inevitably there will come a time when you want to position an image in a specific place.

You do that by using Position:

     show eileen happy at Position(xpos = 0.5, xanchor=0.5, ypos=0.5,
     yanchor=0.5)

xpos describes a point on the background to Ren'Py in terms of how far it is from the left-hand edge. If you use a whole number (e.g. 129) Ren'Py will assume you mean pixels. If, as above, you use a decimal number between 0 and 1, Ren'Py will calculate it as a proportion of the width. So 0.25 would be interpreted as "a quarter of the way across the background from the left."

xanchor describes a point on the image you want to position, again in terms of how far it is from the left hand side. Just as in xpos above, use a whole number to count pixels, or a decimal between 0 and 1 if you want to describe it as a proportion of the width.

Ren'Py now will show the image so that the xpos and xanchor points are in the same place.

Reduce the xpos value to move it left, increase the xpos value to move it right.

ypos and yanchor follow exactly the same rules, describing to Ren'Py how far the point is from the top of the image. (So to move an image down, you need to increase the ypos value.)

If you're going to use a custom Position more than once, then you can give it a name, like so:

    init:
        $ gardenpath = Position(xpos=0.5, xanchor=0.5, ypos=0.5, yanchor=0.5)

Then you can use it just like any pre-defined Position:

    show eileen happy at gardenpath

#### Overlapping images

When an image is added to a scene, Ren'Py adds it on its own, separate layer. By default each new layer is added on top of the ones which already exist.

Most of the time images added to a scene do not overlap, so it doesn't matter which layers they are on. However if you want to add the appearance of depth to a scene, then an easy way to do this is to partly overlap the images. The player will interpret a larger image on the topmost layer as closest to their viewpoint, and a smaller image drawn partly behind it as further back into the scene.

Imagine for a moment that we've made a background picture of a house with a garden, and we want to show two characters: one in the foreground and one a little way behind that, who will appear to be halfway up the garden.

In a real game you'd probably want to make custom positions for these images, but for simplicity, imagine that they're drawn so that they'll be correctly positioned when they're displayed in the default position.

Having the characters overlap correctly is no problem when beginning a new scene:

    scene bg houseGarden
    show distantChar
    show foregroundChar
    with dissolve

However if the scene is already showing, and we want distantChar to appear (perhaps having just come out of the house), then:

    *** Wrong! ***

    scene bg houseGarden
    show foregroundChar
    with dissolve

     "The sounds of argument in the house cease and distantChar
     comes running out into the garden."

    show distantChar with dissolve

    *** Wrong! ***

The code above will not give the effect we want: distatChar will be added to a layer above foregroundChar, and so the overlapping will be the wrong way round.

The way to get the effect we want is to use the behind keyword like this:

    ...
     "The sounds of argument in the house cease and distantChar
     comes running out into the garden."

    show distantChar behind foregroundChar with dissolve

Now the images are correctly overlapped.

You don't have to worry when you're using "show" to replace one image of a character with another. Ren'Py will automatically place the new image on the same layer where the old one was.

### Hiding Graphics

Hiding graphics which were displayed with the show statement can be accomplished in three ways:

#### Explicity

First, you can explicitly hide a graphic which was shown using the hide statement:

    hide eileen

If an image consists of more than one word, you only need to tell the hide statement about the first word (the "image tag"). This means that you don't have to keep track of the version of the character graphic that you've shown most recently.

#### Implicitly with show

The show statement will automatically replace the image with the same image tag which us currently being shown (though not quite in the same way as a hide statement). For example:

    show eileen happy
    e "I'm happy."
    show eileen sad
    e "Now I'm sad."

does the right thing — you don't get two copies of eileen on top of each other.

#### Implicitly with scene

The scene statement clears all images off of the screen, so if you're changing scenes you don't need to hide anything first.

### Special Effects

All of the statements which show and hide images can be modified by adding a with clause (see: with statement):

    scene bg park with fade

    show eileen happy with dissolve

There are many special effects available, but those are the two most commonly used. (It seems like only George Lucas can get away with stuff like side wipes, but if you want to try, you can check out the full list of Pre-Defined Transitions.)

### Getting What You Want to Happen, to Happen

Neither the scene statement nor the show statement, on their own, immediately display to the screen. Rather they queue images up, so if you combined them:

    scene bg park
    show eileen happy
    show ted happy at left

it will display all at once. The with statement and clause both change this. So if you wrote this:

    scene bg park with fade
    show eileen happy with dissolve
    show ted happy at left with dissolve

Ren'Py will first fade the background in, then dissolve eileen onto the screen, then dissolve ted onto the screen. To get a single fade into the new background with eileen and ted on it, use the statement form of "with" after you've told Ren'Py what you want on the screen:

    show bg park
    show eileen happy
    show ted happy
    with dissolve

(Please note: for historical reasons, this is not the same as:

    show bg park
    show eileen happy
    show ted happy with dissolve

Which will cause the background and eileen to display without a transition and then show ted with a dissolve transition. In general, if you're using more than one statement, only use the with statement on its own line.)

As a result of the show statement's queueing behavior, this won't work:

    show eileen happy
    show eileen sad
    show eileen morose
    show eileen elated

the reader will only see the last one. If you want to show several versions of a character without interacting with the reader, you need to use the with clause to get them displayed:

    show eileen happy with dissolve
    show eileen sad with dissolve
    show eileen morose with dissolve
    show eileen elated with dissolve

Previous: Your First Dialogue | Ren'Py Web Tutorial | Next: Giving the User a Choice With Menus

documentation index