Sprite Animation — Direction-Based Frames

By the end of this lesson you can:

• Organise frame lists into a dictionary keyed by direction string ("right", "left", "up", "down").
• Update a direction variable based on which movement key is held and select the matching frame list.
• Combine direction-based frame selection with the tick-counter cycle from PZ-24 into a smooth four-way animated character.

Last lesson you used a list for frames. Today you use a dictionary of lists. Predict what this prints:

anim = {
    "right": ["run_r0", "run_r1", "run_r2"],
    "left":  ["run_l0", "run_l1", "run_l2"],
}
direction = "left"
tick = 7
FRAME_SPEED = 3

frames = anim[direction]
print(frames[(tick // FRAME_SPEED) % len(frames)])

run_l1

run_l2

Think of your character as an actor who has a different costume for each direction it faces. The wardrobe is a dictionary: give it the direction string, get back the right costume (frame list).

Setting up the animation dictionary

ANIM = {
    "right": ["hero_r0", "hero_r1", "hero_r2", "hero_r3"],
    "left":  ["hero_l0", "hero_l1", "hero_l2", "hero_l3"],
    "up":    ["hero_u0", "hero_u1", "hero_u2", "hero_u3"],
    "down":  ["hero_d0", "hero_d1", "hero_d2", "hero_d3"],
}
IDLE = {
    "right": ["hero_idle_r"],
    "left":  ["hero_idle_l"],
    "up":    ["hero_idle_u"],
    "down":  ["hero_idle_d"],
}

Single-item lists work fine for idle poses — the "cycle" just shows the same image forever.

Updating direction from input

direction = "right"   # starting direction
moving = False

def update():
    global direction, moving
    moving = False
    if keyboard.right:
        hero.x += 4
        direction = "right"
        moving = True
    if keyboard.left:
        hero.x -= 4
        direction = "left"
        moving = True
    if keyboard.up:
        hero.y -= 4
        direction = "up"
        moving = True
    if keyboard.down:
        hero.y += 4
        direction = "down"
        moving = True

Picking the frame

    frames = ANIM[direction] if moving else IDLE[direction]
    hero.image = frames[(tick // FRAME_SPEED) % len(frames)]

The story

Priya is building a top-down adventure. Her hero should face the direction of movement and freeze in that direction when no key is pressed. Save as four_way.py. The stand-in version draws a coloured circle with a direction indicator so you can test without images.

Stand-in version (no images required)

# four_way.py — direction-based animation (stand-in)

import pgzrun

WIDTH = 500
HEIGHT = 400
TITLE = "Four-Way Hero"

SPEED = 4
FRAME_SPEED = 6
cx, cy = 250, 200
direction = "down"
moving = False
tick = 0

ARROW = {"right": (1, 0), "left": (-1, 0), "up": (0, -1), "down": (0, 1)}
COLOURS = ["deepskyblue", "royalblue", "navy", "royalblue"]

def draw():
    screen.fill("beige")
    screen.draw.filled_circle((int(cx), int(cy)), 22, COLOURS[tick // FRAME_SPEED % 4])
    dx, dy = ARROW[direction]
    ax = int(cx + dx * 28)
    ay = int(cy + dy * 28)
    screen.draw.line((int(cx), int(cy)), (ax, ay), "white")
    screen.draw.filled_circle((ax, ay), 5, "white")
    screen.draw.text(f"dir: {direction}  moving: {moving}",
                     topleft=(8, 8), fontsize=22, color="black")

def update():
    global cx, cy, direction, moving, tick
    tick += 1
    moving = False
    if keyboard.right and cx < WIDTH - 25:
        cx += SPEED
        direction = "right"
        moving = True
    if keyboard.left and cx > 25:
        cx -= SPEED
        direction = "left"
        moving = True
    if keyboard.up and cy > 25:
        cy -= SPEED
        direction = "up"
        moving = True
    if keyboard.down and cy < HEIGHT - 25:
        cy += SPEED
        direction = "down"
        moving = True

pgzrun.go()

What you'll see

Direction-based animation stores frame lists in a dictionary keyed by direction string. In update(), check which key is pressed, update the direction variable, then pick ANIM[direction] as the active frame list. Combine with the tick-counter cycle from PZ-24 and your sprite looks exactly where it moves — no flipping maths, no extra conditions.