Project: Pack Train, an arcade game

Checkpoint 3: the rules

A Game holds everything else: the train, the crate, the score, and whether it's over. Its tick() is the heart of the program, and it still draws nothing:

import random

COLS, ROWS = 20, 15
DIRECTIONS = {"Up": (0, 1), "Down": (0, -1), "Left": (-1, 0), "Right": (1, 0)}

class Train:
    def __init__(self, start=(10, 7), length=3):
        x, y = start
        self.cells = [(x - i, y) for i in range(length)]
        self.direction = self.last_move = (1, 0)
    def head(self):
        return self.cells[0]
    def turn(self, name):
        dx, dy = DIRECTIONS[name]
        if (dx, dy) != (-self.last_move[0], -self.last_move[1]):
            self.direction = (dx, dy)
    def next_head(self):
        return (self.cells[0][0] + self.direction[0], self.cells[0][1] + self.direction[1])
    def move(self, grow=False):
        self.cells.insert(0, self.next_head())
        self.last_move = self.direction
        if not grow:
            self.cells.pop()

def on_grid(cell):
    x, y = cell
    return 0 <= x < COLS and 0 <= y < ROWS

class Game:
    def __init__(self, rng=None):
        self.rng = rng or random.Random()
        self.train = Train()
        self.score = 0
        self.over = False
        self.crate = self.place_crate()

    def free_cells(self):
        taken = set(self.train.cells)
        return [(x, y) for x in range(COLS) for y in range(ROWS) if (x, y) not in taken]

    def place_crate(self):
        free = self.free_cells()
        return self.rng.choice(free) if free else None

    def tick(self):
        if self.over:
            return
        nxt = self.train.next_head()
        grow = nxt == self.crate
        body = self.train.cells if grow else self.train.cells[:-1]
        if not on_grid(nxt) or nxt in body:
            self.over = True
            return
        self.train.move(grow)
        if grow:
            self.score += 1
            self.crate = self.place_crate()
            if self.crate is None:
                self.over = True  # the train fills the meadow: nothing left to collect

game = Game(random.Random(4))
game.crate = (12, 7)  # put a crate in the way, to watch one get collected
for _ in range(12):
    game.tick()
    print(game.train.head(), "score", game.score, "over" if game.over else "")

Three rules hide in tick. A crate is placed on a free cell, never under the train. A crash is checked before moving, so a stopped train is drawn where it hit. And the mule may step into the cell the tail is leaving, because the tail moves away on the same tick; that's why body drops the last cell, unless the train is growing and its tail stays put.

def free_cells(taken, cols, rows):
    return []


print(free_cells([(0, 0), (1, 1)], 2, 2))

Checkpoint 4: the clock and the keys

Now the screen joins in, through two kinds of event handler: functions you hand to the screen for it to call later.

• screen.ontimer(tick, 150) calls tick once, about 150 milliseconds from now. To keep going, tick asks for the next one itself, and stops asking when the game is over. That chain of ticks is the game loop.
• screen.onkeypress(handler, "Up") calls handler whenever Up is pressed, and screen.listen() starts listening for keys.
• screen.mainloop() waits for timers and keys until the window closes (here, until you press Stop).

Each key's handler only turns the train; it never draws or moves anything. Click the picture, then steer with the arrow keys or the buttons under it. (Browsers that can't pause Python show a recording of the train going straight instead.)

import json
import random
import turtle

CELL = 20
COLS, ROWS = 20, 15
DIRECTIONS = {"Up": (0, 1), "Down": (0, -1), "Left": (-1, 0), "Right": (1, 0)}

class Train:
    def __init__(self, start=(10, 7), length=3):
        x, y = start
        self.cells = [(x - i, y) for i in range(length)]
        self.direction = self.last_move = (1, 0)
    def turn(self, name):
        dx, dy = DIRECTIONS[name]
        if (dx, dy) != (-self.last_move[0], -self.last_move[1]):
            self.direction = (dx, dy)
    def next_head(self):
        return (self.cells[0][0] + self.direction[0], self.cells[0][1] + self.direction[1])
    def move(self, grow=False):
        self.cells.insert(0, self.next_head())
        self.last_move = self.direction
        if not grow:
            self.cells.pop()

class Game:
    def __init__(self):
        self.train, self.score, self.over = Train(), 0, False
        self.crate = self.place_crate()
    def place_crate(self):
        free = [(x, y) for x in range(COLS) for y in range(ROWS) if (x, y) not in self.train.cells]
        return random.choice(free) if free else None
    def tick(self):
        if self.over:
            return
        nxt = self.train.next_head()
        grow = nxt == self.crate
        body = self.train.cells if grow else self.train.cells[:-1]
        if not (0 <= nxt[0] < COLS and 0 <= nxt[1] < ROWS) or nxt in body:
            self.over = True
            return
        self.train.move(grow)
        if grow:
            self.score += 1
            self.crate = self.place_crate()

screen = turtle.Screen()
screen.setup(COLS * CELL, ROWS * CELL + 40)
screen.bgcolor("#1d2b22")
screen.title("Pack Train")
screen.tracer(0)
pen = turtle.Turtle("square")
pen.hideturtle()
pen.penup()
pen.shapesize(0.9)

def to_xy(cell):
    return ((cell[0] - COLS / 2 + 0.5) * CELL, (cell[1] - ROWS / 2 + 0.5) * CELL)

def draw(game):
    pen.clear()
    for i, cell in enumerate(game.train.cells):
        pen.goto(to_xy(cell))
        pen.color("gold" if i == 0 else "peru")
        pen.stamp()
    if game.crate:
        pen.goto(to_xy(game.crate))
        pen.color("#9fd39a")
        pen.stamp()
    pen.color("white")
    pen.goto(-COLS * CELL / 2, ROWS * CELL / 2 + 4)
    pen.write(f"Crates: {game.score}", font=("Courier", 12, "bold"))
    if game.over:
        pen.goto(0, 0)
        pen.write("The train stopped. Space to go again", align="center", font=("Courier", 13, "bold"))
    screen.update()

game = Game()

def tick():
    game.tick()
    draw(game)
    if not game.over:
        screen.ontimer(tick, max(60, 150 - 5 * game.score))

def steer(name):
    return lambda: game.train.turn(name)

def restart():
    global game
    if game.over:
        game = Game()
        tick()

for name in DIRECTIONS:
    screen.onkeypress(steer(name), name)
screen.onkeypress(restart, "space")
screen.listen()
tick()
screen.mainloop()

draw starts with pen.clear(), which wipes everything that turtle stamped and wrote, and then draws the whole scene again from the game's state. Redrawing everything every frame sounds wasteful, but it means the picture can never drift away from the truth.

handlers = []
for name in ["Up", "Down"]:
    handlers.append(lambda: name)
print([h() for h in handlers])

Keeping the best score

A best score that vanishes when the program ends isn't much of a record, so save it in a file. JSON is a good fit: it's readable, and json.load gives back the same numbers you saved.

import json

def load_best(path="best.json"):
    try:
        with open(path) as f:
            return json.load(f)["best"]
    except (FileNotFoundError, KeyError, ValueError):
        return 0

def save_best(score, path="best.json"):
    with open(path, "w") as f:
        json.dump({"best": score}, f)

print("before:", load_best("trial-best.json"))
save_best(12, "trial-best.json")
print("after:", load_best("trial-best.json"))

The first game has no file yet, which isn't an error worth stopping for: load_best treats a missing or damaged file as a best of 0. In the game, tick checks once the train stops: if the score beats best, it updates best (which needs global best, since tick assigns to it) and saves it. In the academy, files live in your browser tab's own small file system, so the record lasts until you reload the page; on your computer it lasts for good.

import random

COLS, ROWS = 20, 15
DIRECTIONS = {"Up": (0, 1), "Down": (0, -1), "Left": (-1, 0), "Right": (1, 0)}

class Train:
    def __init__(self, start=(10, 7), length=3):
        x, y = start
        self.cells = [(x - i, y) for i in range(length)]
        self.direction = self.last_move = (1, 0)
    def turn(self, name):
        dx, dy = DIRECTIONS[name]
        if (dx, dy) != (-self.last_move[0], -self.last_move[1]):
            self.direction = (dx, dy)
    def next_head(self):
        return (self.cells[0][0] + self.direction[0], self.cells[0][1] + self.direction[1])
    def move(self, grow=False):
        self.cells.insert(0, self.next_head())
        self.last_move = self.direction
        if not grow:
            self.cells.pop()

class Game:
    def __init__(self, rng):
        self.rng, self.train, self.score, self.over = rng, Train(), 0, False
        self.crate = self.place_crate()
    def place_crate(self):
        free = [(x, y) for x in range(COLS) for y in range(ROWS) if (x, y) not in self.train.cells]
        return self.rng.choice(free) if free else None
    def tick(self):
        nxt = self.train.next_head()
        grow = nxt == self.crate
        body = self.train.cells if grow else self.train.cells[:-1]
        if not (0 <= nxt[0] < COLS and 0 <= nxt[1] < ROWS) or nxt in body:
            self.over = True
            return
        self.train.move(grow)
        if grow:
            self.score += 1
            self.crate = self.place_crate()

g = Game(random.Random(1))
g.crate = (11, 7)
g.tick()
assert g.score == 1 and len(g.train.cells) == 4, "a crate just ahead is collected"
assert g.crate not in g.train.cells, "the next crate is on a free cell"

g = Game(random.Random(1))
g.crate = (0, 0)
g.train.cells = [(10, 8), (10, 7), (9, 7), (9, 8)]
g.train.direction = g.train.last_move = (0, 1)
g.train.turn("Left")
g.tick()
assert not g.over, "stepping into the cell the tail leaves is allowed"

g = Game(random.Random(1))
g.crate = (0, 0)
for _ in range(10):
    g.tick()
assert g.over and g.train.cells[0] == (19, 7), "the tenth tick right hits the fence"
print("all rule tests pass")

Go further

Pack Train is a complete game, and a good base. Some ideas, in rough order of difficulty:

• Levels: every five crates, add a rock to a random free cell that ends the game if you hit it.
• A pause key. tick keeps going but skips game.tick() while a paused flag is set.
• A paddle rally for two players: two paddles, W and S for one and the arrows for the other, and a ball with a velocity (dx, dy) that flips dy at the top and bottom walls and dx off a paddle. The ball moves in pixels, not cells, so collisions compare distances.
• A lane crossing: a hiker crosses lanes of carts moving at different speeds; reaching the far side starts a faster level. Each lane is an object with its own list of carts.

Each one reuses the shape you've built: rules in classes, one draw, small handlers, and a timer that keeps it all moving.

import turtle

W, H = 480, 360
screen = turtle.Screen()
screen.setup(W, H)
screen.bgcolor("#26221f")
screen.tracer(0)

cart = turtle.Turtle("square")
cart.shapesize(0.6, 4)
cart.color("#d9b26f")
cart.penup()
cart.goto(0, -H / 2 + 30)

stone = turtle.Turtle("circle")
stone.shapesize(0.6)
stone.color("#e8e4dc")
stone.penup()
dx, dy = 4, 5


def left():
    cart.setx(max(-W / 2 + 40, cart.xcor() - 30))


def right():
    cart.setx(min(W / 2 - 40, cart.xcor() + 30))


def tick():
    global dx, dy
    stone.goto(stone.xcor() + dx, stone.ycor() + dy)
    if abs(stone.xcor()) > W / 2 - 10:
        dx = -dx
    if stone.ycor() > H / 2 - 10 or stone.ycor() < -H / 2 + 10:
        dy = -dy  # your code: the bottom should cost a life, and the cart should bounce it
    screen.update()
    screen.ontimer(tick, 20)


screen.onkeypress(left, "Left")
screen.onkeypress(right, "Right")
screen.listen()
tick()
screen.mainloop()

import turtle

W, H = 480, 400
screen = turtle.Screen()
screen.setup(W, H)
screen.bgcolor("#18233a")
screen.tracer(0)

station = turtle.Turtle("triangle")
station.setheading(90)
station.color("#f2c94c")
station.penup()
station.goto(0, -H / 2 + 30)

burst = turtle.Turtle("circle")
burst.shapesize(0.4)
burst.color("#fff3b0")
burst.penup()
burst.hideturtle()
flying = False


def left():
    station.setx(max(-W / 2 + 20, station.xcor() - 20))


def right():
    station.setx(min(W / 2 - 20, station.xcor() + 20))


def fire():
    global flying
    if not flying:
        burst.goto(station.xcor(), station.ycor() + 15)
        burst.showturtle()
        flying = True


def tick():
    global flying
    if flying:
        burst.sety(burst.ycor() + 12)
        if burst.ycor() > H / 2:
            burst.hideturtle()
            flying = False
    # your code: the clouds, the hail, hits, lives and score
    screen.update()
    screen.ontimer(tick, 30)


screen.onkeypress(left, "Left")
screen.onkeypress(right, "Right")
screen.onkeypress(fire, "space")
screen.listen()
tick()
screen.mainloop()