Ren'Py Image Basics: show, scene, and Transitions

When you wrote scene bg room in the getting started guide, the screen was black. No image file existed yet.

This guide covers how to display images in Ren'Py 8.5.2 from the ground up — naming rules, scene/show/hide, transitions, expression switching, and position and layer control.

Understanding Image Naming Rules

Ren'Py automatically detects image files placed in game/images/ and makes them available in your script. Getting the naming wrong is the most common reason images don't show up.

Where to Put Files

Place images in game/images/. Subfolders are detected too.

mygame/
└── game/
    └── images/
        ├── bg forest.png
        ├── bg castle.jpg
        ├── characters/
        │   ├── eileen happy.png
        │   └── eileen sad.png
        └── ui/
            └── textbox.png

How Filenames Become Image Names

Ren'Py splits filenames by spaces or underscores and converts them to image names.

The first word becomes the tag and the rest become attributes. Tags group images together for show and hide. Attributes distinguish variants (expressions, outfits) within the same tag.

# If the file is bg forest.png
scene bg forest

# If the file is eileen_happy.png
show eileen happy

Why "My Image Isn't Showing"

When an image doesn't appear, check these three things first:

1. File isn't in game/images/ — Make sure it's not in a different folder
2. Image name doesn't match — Write scene bg forest, not scene bg_forest. Use spaces in your script
3. No interaction after show — show alone doesn't update the screen (explained in the next section)

scene, show, and hide

Three statements control images on screen. Each has a different role.

scene — Switch the Background

# Clear the screen and show a background
scene bg forest
with fade

scene clears all images on the layer before displaying the specified image. Use it for background changes.

Only the master layer is cleared, so UI elements from show screen remain.

show — Display a Character

# Show a character
show eileen happy

# Same tag replaces automatically
show eileen sad

show adds an image to the screen. If an image with the same tag is already showing, it replaces it. After show eileen happy, running show eileen sad removes eileen happy and shows eileen sad.

hide — Remove a Character

hide eileen

hide removes the image with the specified tag. You only need the tag name, no attributes.

Putting It Together

label start:
    # Show background
    scene bg forest
    with fade

    # Character enters
    show eileen happy
    with dissolve

    e "This forest is beautiful."

    # Change expression (same tag, auto-replaces)
    show eileen sad

    e "But it feels a bit lonely."

    # Character exits
    hide eileen
    with dissolve

    "She disappeared into the forest."

Switching Scenes with Transitions

The with statement adds animation effects to screen changes.

Basic Transitions

# Fade in (from black)
scene bg forest
with fade

# Dissolve (crossfade)
show eileen happy
with dissolve

# Commit preceding changes without showing them (updates the transition baseline)
scene bg castle
with None

Commonly used transitions:

For the full list, see Transitions.

Two Styles of with

There are two ways to write with.

# Style 1: Standalone with statement
# Transitions ALL preceding changes together
show eileen happy
show bg forest
with dissolve

# Style 2: Inline with show/scene
# Transitions only that one change
show eileen happy with dissolve

Style 1 is useful when you want to transition multiple changes (background + character) simultaneously.

Custom Transitions

Adjust Dissolve() or Fade() parameters to create your own transitions.

# 2-second dissolve
define slow_dissolve = Dissolve(2.0)

# Fade through white instead of black
define white_fade = Fade(0.5, 0.0, 0.5, color="#fff")

label start:
    scene bg forest
    with slow_dissolve

    scene bg castle
    with white_fade

Switching Character Expressions

Attribute-Based Variants

Prepare multiple images with the same tag but different attributes, and show handles expression switching.

images/
├── eileen happy.png
├── eileen sad.png
├── eileen angry.png
└── eileen surprised.png

show eileen happy
e "Nice weather today."

show eileen surprised
e "Wait, really?"

show eileen angry
e "That's terrible!"

show eileen sad
e "...I see."

When you run show eileen sad, the previous show eileen angry image is automatically removed and replaced with eileen sad. This is same-tag auto-replacement.

Manual Definition with image

You can define image names yourself instead of relying on auto-detection. Use this when files are outside game/images/ or when you need complex setups.

# Specify file paths directly
image eileen happy = "characters/eileen/happy.png"
image eileen sad = "characters/eileen/sad.png"

# Composite multiple parts together
image eileen happy dress = Composite(
    (300, 600),
    (0, 0), "characters/eileen/base_dress.png",
    (0, 0), "characters/eileen/face_happy.png",
)

Manually defined images work with show eileen happy just like auto-detected ones.

Controlling Position and Layers

Built-in Positions

Use the at keyword to set character positions.

show eileen happy at left
show sakura smile at right

e "I'm on the left."
s "I'm on the right."

Ren'Py's built-in positions:

Custom Positions

When built-in positions aren't enough, define your own with transform.

transform quarter_left:
    xalign 0.25
    yalign 1.0

transform quarter_right:
    xalign 0.75
    yalign 1.0

label start:
    show eileen happy at quarter_left
    show sakura smile at quarter_right

xalign sets horizontal position (0.0 = left edge, 1.0 = right edge). yalign sets vertical position (0.0 = top, 1.0 = bottom). Using yalign 1.0 is standard for character sprites so their feet align with the bottom of the screen.

Layer Order Control

When multiple characters overlap, you may need to control display order.

# zorder sets front/back (higher numbers are in front)
show eileen happy at left zorder 10
show sakura smile at right zorder 5

# behind places an image behind a specific tag
show sakura smile behind eileen

Wrapping Up

What we covered:

• Naming rules: Place files in game/images/. Spaces or underscores in filenames are converted to image names automatically
• scene/show/hide: scene switches backgrounds (with clear), show displays characters (same-tag replacement), hide removes them
• Transitions: with fade/with dissolve add animation effects to screen changes
• Expression variants: Prepare multiple images with the same tag and different attributes, then switch with show
• Position and layers: at left/center/right for positioning, zorder/behind for layer order

If you're new to Ren'Py, start with the getting started guide. For stat system implementation, see the stat management guide.

Dynamically compositing character expressions and outfit parts with LayeredImage, and controlling animations with ATL, are the next steps after mastering the basics in this guide.

Official resources:

• Displaying Images — official image display reference
• Transitions — full list of transitions
• Transforms — position and animation control
• r/RenPy — community