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.

### 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

### 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