Lesson 5: Velocity, Acceleration & Timesteps

🚗 Position, Velocity, Acceleration

Think about driving a car. Where you are on the road is your position. How fast you are going, and in which direction, is your velocity. Pressing the gas or the brake changes your velocity; how quickly it changes is your acceleration. The engine, the brakes and the wind are forces: they are what cause the acceleration.

You have already used the first row since the Intro course: pos += vel * dt. This lesson adds the second row, vel += accel * dt, and the forces behind it.

Play with the idea before writing any code. Each button below is a different set of forces acting on the same body; the update code never changes. The green arrow is velocity and the red arrow is acceleration.

Notice two things. With Constant velocity there is no red arrow at all: nothing is pushing, so nothing changes, and the ball keeps going. With Orbit, the red arrow always points at the center while the green arrow points sideways; a pull toward the center plus a sideways launch is all a circular orbit needs.

💪 Forces and F = ma

Newton's second law says force equals mass times acceleration, F = m × a. Games use it the other way around: you know the forces, so you work out the acceleration, a = F / m. The same push moves a light object more than a heavy one, which is exactly why a loaded truck feels sluggish.

Real games have many forces at once: thrust, gravity, wind, drag. The clean pattern is to collect them during a step, use them once, then clear them:

1. apply_force(f) adds each force to a running total.
2. update(dt) divides the total by the mass, changes the velocity, then moves the position.
3. The total goes back to zero, ready for next step's forces.

Here is the whole pattern as a complete program. Two bodies get the same push; one has four times the mass.

import pygame

pygame.init()
screen = pygame.display.set_mode((800, 400))
pygame.display.set_caption("Same Force, Different Mass")
clock = pygame.time.Clock()
font = pygame.font.Font(None, 28)


class Body:
    def __init__(self, x, y, mass, color):
        self.pos = pygame.Vector2(x, y)
        self.vel = pygame.Vector2(0, 0)       # px/s
        self.force = pygame.Vector2(0, 0)     # forces collected for this frame
        self.mass = mass
        self.color = color

    def apply_force(self, force):
        self.force += force                   # forces add up like vectors

    def update(self, dt):
        accel = self.force / self.mass        # a = F / m
        self.vel += accel * dt                # velocity changes by a * dt
        self.pos += self.vel * dt             # position changes by v * dt
        self.force = pygame.Vector2(0, 0)     # start the next frame with no forces


light = Body(60, 130, mass=1, color=(120, 200, 255))
heavy = Body(60, 270, mass=4, color=(255, 170, 90))
push = pygame.Vector2(200, 0)                 # the same push for both

running = True
while running:
    dt = clock.tick(60) / 1000
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False

    for body in (light, heavy):
        if body.pos.x < 740:                  # stop pushing near the right edge
            body.apply_force(push)
        else:
            body.vel.update(0, 0)
        body.update(dt)

    screen.fill((16, 20, 32))
    for body, label in ((light, "mass 1"), (heavy, "mass 4")):
        pygame.draw.circle(screen, body.color, body.pos, 10 + body.mass * 4)
        text = f"{label}: {body.vel.x:5.0f} px/s"
        screen.blit(font.render(text, True, body.color), (10, body.pos.y - 60))
    pygame.display.flip()

pygame.quit()

🔁 Explicit vs Semi-Implicit Euler

Stepping velocity and position forward by small amounts of time is called integration, and the two-line version is called Euler integration. There are two ways to order the lines, and they are not the same:

# Explicit (forward) Euler: position uses the OLD velocity
pos += vel * dt
vel += accel * dt

# Semi-implicit (symplectic) Euler: velocity first, position uses the NEW velocity
vel += accel * dt
pos += vel * dt

The difference looks tiny, but it decides whether a spring or an orbit stays stable. This short program simulates a spring for 10 seconds with both orders and compares the energy at the end with the energy at the start. A perfect simulation would print 1.00 for both.

# Explicit vs semi-implicit Euler on a spring (no window needed).
K = 40.0          # spring stiffness: acceleration = -K * x
DT = 1 / 60       # one step per frame at 60 FPS
STEPS = 600       # 10 seconds


def energy(x, v):
    return 0.5 * v * v + 0.5 * K * x * x


for method in ("explicit", "semi-implicit"):
    x, v = 100.0, 0.0
    start = energy(x, v)
    for _ in range(STEPS):
        a = -K * x
        if method == "explicit":
            x += v * DT           # position uses the OLD velocity...
            v += a * DT           # ...then velocity changes
        else:
            v += a * DT           # velocity changes first...
            x += v * DT           # ...then position uses the NEW velocity
    print(f"{method:14} energy after 10 s: {energy(x, v) / start:8.2f} x the start")

Running it prints:

explicit       energy after 10 s:   757.41 x the start
semi-implicit  energy after 10 s:     0.96 x the start

Explicit Euler adds a little energy every step, so the spring swings wider and wider until it explodes. Semi-implicit Euler keeps the energy close to where it started, so the spring keeps swinging for as long as you like. It costs nothing extra, so every physics update in this course uses semi-implicit Euler: velocity first, then position.

Semi-implicit Euler is not exact. For a thrown ball it is slightly off from the textbook formula, and the error shrinks as the step gets smaller. That is fine for games, as long as the step is always the same size (you will see why in a moment).

🌬️ Drag and Speed Limits Done Right

Without anything slowing it down, a ship in space drifts forever. Games often add drag, a slow-down that gets stronger the faster you go, so ships coast to a stop. The line many tutorials use is a per-frame multiplier:

vel *= 0.98    # "lose 2% of the speed every frame"

"Every frame" is the problem. Here is what that line does to a speed of 100 px/s after one second at three frame rates, next to the fix you are about to write:

With the per-frame version, a player on a 144 Hz monitor gets a ship that stops five times faster than on a 60 Hz laptop. The fix is the same exponential decay you used for smoothing in the Interpolation & Easing lesson: turn "2% per frame" into a rate per second and let dt decide how much of it applies.

DRAG = 1.2                       # per second: bigger = stops sooner
vel *= math.exp(-DRAG * dt)      # same result at any frame rate

If you already have a per-frame number that feels right at 60 FPS, vel *= 0.98 ** (dt * 60) gives the same feel at every frame rate.

For a hard speed limit, pygame-ce's Vector2.clamp_magnitude() shortens a vector that is too long and leaves shorter ones alone, including the zero vector:

vel = vel.clamp_magnitude(MAX_SPEED)   # never faster than MAX_SPEED px/s

⏱️ Why Variable Timesteps Aren't Enough

Since the Intro course, every update has used the real frame time: dt = clock.tick(60) / 1000. That is a variable timestep, and it keeps speeds right at any frame rate. But the path an object takes still depends on the size of the steps. This program simulates the same jump (launch speed 600 px/s, gravity 980 px/s²) at three frame rates:

# The same jump at three frame rates, with a variable timestep.
GRAVITY = 980.0
JUMP_SPEED = 600.0

for fps in (30, 60, 144):
    dt = 1 / fps
    y, vy, peak = 0.0, -JUMP_SPEED, 0.0
    while True:
        vy += GRAVITY * dt
        y += vy * dt
        peak = max(peak, -y)
        if vy > 0 and y >= 0:
            break
    print(f"{fps:3} FPS: jump peak {peak:6.1f} px")

print(f"exact:   jump peak {JUMP_SPEED ** 2 / (2 * GRAVITY):6.1f} px")

 30 FPS: jump peak  173.8 px
 60 FPS: jump peak  178.7 px
144 FPS: jump peak  181.6 px
exact:   jump peak  183.7 px

Players on faster machines jump almost 8 pixels higher. In a platformer that decides whether a ledge can be reached. There are two more problems:

• Big hiccups. When the window is dragged or the computer stalls, one frame can take a quarter of a second. One huge step can carry a fast object straight through a thin wall, or make a stiff spring explode.
• No replays. The same inputs give slightly different results on every run, because the frame times are never exactly the same. Replays, ghosts and networked games need physics that repeats exactly.

🧮 The Fixed-Timestep Accumulator

A fixed timestep means the physics always advances by exactly the same small step, say STEP = 1/120 of a second, no matter how long the frame took. Think of the frame time as money coming in and each physics step as something that costs exactly STEP. You put the frame's time into a savings jar (the accumulator) and buy as many whole steps as you can afford. The change stays in the jar for next frame.

At 60 FPS with a 1/120 s step, each frame runs two physics steps. At 30 FPS it runs four. At 144 FPS it runs zero or one, and the leftovers add up until a step is due. Because every step is the same size, the jump reaches the same height everywhere, and the same inputs always give the same result.

Here is a complete program. Press F to switch the frame cap between 20, 60 and 144 FPS: the picture gets choppier or smoother, but the arc is the same every time.

import pygame

STEP = 1 / 120            # physics always advances exactly 1/120 s
MAX_FRAME = 0.25          # guard against the "spiral of death"
GRAVITY = 980.0

pygame.init()
screen = pygame.display.set_mode((800, 500))
pygame.display.set_caption("Fixed Timestep: F changes the frame rate")
clock = pygame.time.Clock()
font = pygame.font.Font(None, 28)

pos = pygame.Vector2(60, 450)
vel = pygame.Vector2(220, -620)
prev_pos = pos.copy()                 # where the ball was one step ago
trail = []
frame_caps = [20, 60, 144]
cap = 1                               # index into frame_caps
accumulator = 0.0

running = True
while running:
    frame_time = min(clock.tick(frame_caps[cap]) / 1000, MAX_FRAME)
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        elif event.type == pygame.KEYDOWN and event.key == pygame.K_f:
            cap = (cap + 1) % len(frame_caps)

    accumulator += frame_time
    while accumulator >= STEP:        # zero, one or several steps this frame
        prev_pos = pos.copy()
        vel.y += GRAVITY * STEP       # semi-implicit Euler
        pos += vel * STEP
        if pos.y > 450:               # landed: launch again from the start
            pos.update(60, 450)
            vel.update(220, -620)
            prev_pos = pos.copy()
            trail.clear()
        accumulator -= STEP

    alpha = accumulator / STEP        # how far we are into the next step (0..1)
    draw_pos = prev_pos.lerp(pos, alpha)
    trail.append(draw_pos.copy())

    screen.fill((16, 20, 32))
    pygame.draw.line(screen, (80, 90, 120), (0, 462), (800, 462), 2)
    for point in trail:
        pygame.draw.circle(screen, (70, 110, 170), point, 2)
    pygame.draw.circle(screen, (255, 200, 90), draw_pos, 12)
    text = f"frame cap {frame_caps[cap]} FPS   physics step {STEP * 1000:.1f} ms   (F to change)"
    screen.blit(font.render(text, True, (230, 230, 230)), (10, 10))
    pygame.display.flip()

pygame.quit()

Three details make it robust:

• MAX_FRAME prevents the spiral of death. If a frame took two seconds, the loop would try to run 240 steps before drawing, which makes that frame slow too, which means even more steps next time. Capping the frame time at 0.25 s means the game briefly runs in slow motion instead of freezing.
• Leftover time is kept, not thrown away. accumulator -= STEP keeps the remainder for the next frame, so no time is lost over the long run.
• Interpolation smooths the picture. The leftover time also tells you how far you are into the next step (alpha, from 0 to 1). Drawing at prev_pos.lerp(pos, alpha) hides the small stutter you would otherwise see when the frame rate and the step rate don't line up. It only affects drawing; the physics never sees it. Many games skip it at first, and you can add it later.

Read input from events once per frame, as you always have, and let every physics step that frame use it. The exercise does exactly that.

🏋️ Practice Exercise: Thruster Drift

"""Thruster Drift: Intermediate Lesson 5 practice exercise (solution).

A small ship is pushed around by thruster FORCES. Forces become
acceleration (a = F / m), semi-implicit Euler turns acceleration into
velocity and velocity into position, drag is frame-rate independent,
and all physics runs on a fixed timestep of 1/120 s.

Arrow keys: fire thrusters.   M: toggle heavy cargo (triples the mass).
Close the window to quit.
"""
import math

import pygame


WIDTH, HEIGHT = 800, 600
STEP = 1 / 120              # fixed physics step, in seconds
MAX_FRAME = 0.25            # never simulate more than this much time in one frame
THRUST = 600.0              # thruster force (force units; a = F / m)
DRAG = 0.8                  # drag rate per second: v *= exp(-DRAG * dt)
MAX_SPEED = 500.0           # pixels per second
LIGHT, HEAVY = 1.0, 3.0     # ship mass without and with cargo
KEY_DIRECTIONS = {
    pygame.K_LEFT: (-1, 0), pygame.K_RIGHT: (1, 0),
    pygame.K_UP: (0, -1), pygame.K_DOWN: (0, 1),
}


class Ship:
    def __init__(self, x, y, mass=LIGHT):
        self.pos = pygame.Vector2(x, y)
        self.vel = pygame.Vector2(0, 0)        # pixels per second
        self.force = pygame.Vector2(0, 0)      # sum of the forces for this step
        self.mass = mass
        self.last_accel = pygame.Vector2(0, 0) # kept only so we can draw it

    def apply_force(self, force):
        """Add a force for this step. Forces add up until step() uses them."""
        self.force += force

    def step(self, dt):
        """Advance the ship by dt seconds with semi-implicit Euler."""
        accel = self.force / self.mass                 # a = F / m
        self.vel += accel * dt                         # 1. velocity first...
        self.vel *= math.exp(-DRAG * dt)               # frame-rate independent drag
        self.vel = self.vel.clamp_magnitude(MAX_SPEED) # speed limit
        self.pos += self.vel * dt                      # 2. ...then position, with the NEW velocity
        self.pos.x %= WIDTH                            # wrap around the screen edges
        self.pos.y %= HEIGHT
        self.last_accel = accel
        self.force = pygame.Vector2(0, 0)              # forces must be re-applied every step


def thrust_direction(held):
    """Combine the held arrow keys into one direction of length 0 or 1."""
    direction = pygame.Vector2(0, 0)
    for key in held:
        if key in KEY_DIRECTIONS:
            direction += KEY_DIRECTIONS[key]
    if direction.length_squared() > 0:
        direction = direction.normalize()
    return direction


def advance(ship, accumulator, frame_time, direction):
    """Run as many fixed STEPs as the frame's time allows.

    Returns (accumulator, steps_run). Leftover time stays in the
    accumulator for the next frame.
    """
    accumulator += min(frame_time, MAX_FRAME)
    steps = 0
    while accumulator >= STEP:
        ship.apply_force(direction * THRUST)
        ship.step(STEP)
        accumulator -= STEP
        steps += 1
    return accumulator, steps


def draw_arrow(screen, color, start, vector, scale):
    end = start + vector * scale
    if (end - start).length_squared() > 4:
        pygame.draw.line(screen, color, start, end, 3)
        pygame.draw.circle(screen, color, end, 4)


def main():
    pygame.init()
    screen = pygame.display.set_mode((WIDTH, HEIGHT))
    pygame.display.set_caption("Thruster Drift")
    clock = pygame.time.Clock()
    font = pygame.font.Font(None, 26)          # created once, before the loop

    ship = Ship(WIDTH / 2, HEIGHT / 2)
    held = set()                               # arrow keys currently held down
    accumulator = 0.0
    total_steps = 0
    steps_this_frame = 0

    running = True
    while running:
        frame_time = clock.tick(60) / 1000     # seconds since the last frame

        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                running = False
            elif event.type == pygame.KEYDOWN:
                if event.key in KEY_DIRECTIONS:
                    held.add(event.key)
                elif event.key == pygame.K_m:
                    ship.mass = HEAVY if ship.mass == LIGHT else LIGHT
            elif event.type == pygame.KEYUP:
                held.discard(event.key)

        accumulator, steps_this_frame = advance(ship, accumulator, frame_time, thrust_direction(held))
        total_steps += steps_this_frame

        screen.fill((14, 18, 30))
        pygame.draw.circle(screen, (120, 200, 255), ship.pos, 16)
        draw_arrow(screen, (80, 220, 120), ship.pos, ship.vel, 0.25)        # velocity: green
        draw_arrow(screen, (255, 110, 110), ship.pos, ship.last_accel, 0.1) # acceleration: red
        lines = [
            f"speed {ship.vel.length():5.0f} px/s   mass {ship.mass:.0f}   (M toggles cargo)",
            f"physics steps this frame: {steps_this_frame}   step = {STEP * 1000:.2f} ms",
        ]
        for i, text in enumerate(lines):
            screen.blit(font.render(text, True, (230, 230, 230)), (10, 10 + i * 24))
        pygame.display.flip()

    pygame.quit()
    print(f"Simulated {total_steps} physics steps of {STEP * 1000:.2f} ms.")
    print(f"Final speed: {ship.vel.length():.0f} px/s")


if __name__ == "__main__":
    main()

📓 Learning Journal

📝 Summary

Motion in a game is a chain: forces make acceleration (a = F / m), acceleration changes velocity, and velocity changes position. You collect forces during a step, use them once and clear them. You order the update velocity-first (semi-implicit Euler) because it keeps springs and orbits stable at no extra cost. You replaced per-frame drag with an exponential rate per second, and you measured how a variable timestep makes the same jump reach different heights. The fixed-timestep accumulator fixes that: physics always advances in identical steps, a frame-time cap prevents the spiral of death, and optional interpolation keeps the picture smooth.

🔭 Looking Ahead

Your ship floats in space. In the next lesson, Gravity & Jumping, you add the most important force in platformers and design a jump from two numbers: how high it goes and how long it takes to get there.

❓ Common Questions

🎯 Quick Quiz

🌟 Going Further

• Lunar lander: add a constant gravity force to Thruster Drift, a landing pad at the bottom, and a rule that you crash if you touch down faster than 80 px/s.
• Watch energy explode: change the spring program from Explicit vs Semi-Implicit Euler to print the energy every second for both integrators, and plot the numbers on paper. How many seconds until explicit Euler doubles?
• Replay test: record the arrow keys pressed at each physics step into a list, then play the list back into a fresh ship and check that it ends in exactly the same place.
• Read the docs: the pygame-ce pages for pygame.math (Vector2) and pygame.time (Clock). Find clamp_magnitude and lerp.
• Coming up in Game Dev III: Advanced: Build a Physics Engine (+ pymunk) covers Verlet and Runge-Kutta integrators, rotation and torque, and Racing Physics builds car handling from these same forces.