The Castles of Dr. Creep in Zig

Limit	What it means
64 KB of memory	Code, castle, screen and monsters all fit in 65,536 bytes.
1 MHz processor	About a million tiny steps, called cycles, a second. We measure work in cycles.
50 frames a second	19,656 cycles per frame to read the joysticks, move everyone and redraw.
8 hardware sprites	Eight free-moving pictures over the background, total.
4 colours per 8×8 cell	The 320×200 screen is cut into 8×8-pixel squares called cells. Each cell gets three colours of its own, plus one background colour shared by the whole screen.
3 voices	The SOUND chip plays three notes at once, music and effects together.

Hex	Bits	Hex	Bits
`0`	`0000`	`8`	`1000`
`1`	`0001`	`9`	`1001`
`2`	`0010`	`A`	`1010`
`3`	`0011`	`B`	`1011`
`4`	`0100`	`C`	`1100`
`5`	`0101`	`D`	`1101`
`6`	`0110`	`E`	`1110`
`7`	`0111`	`F`	`1111`

Address	Bytes	What
`$0100–$01FF`	256	the processor's stack (reserved: hands off)
`$0200–$0203`	4	the player
`$0800–$77FF`	28 KB	the program image (reserved)
`$C000–$C7FF`	2 KB	sprite frames
`$CFF8–$CFFF`	8	sprite pointers
`$D000–$D02E`	47	the VIDEO chip
`$D800–$DBE7`	1,000	colour RAM
`$DC00–$DC02`	3	input ports
`$E000–$FF3F`	8,000	the bitmap

Code	Where its colour comes from
`00`	the background colour, one for the whole screen (`$D021`)
`01`	the cell's screen-plane byte, high half (its top four bits)
`10`	the same byte, low half (its bottom four bits)
`11`	the cell's colour-RAM byte

Address	Bytes	What
`$0100–$01FF`	256	the processor's stack (reserved)
`$0200–$0205`	6	the player (two new bytes)
`$0206–$0207`	2	the game: which screen we're on, and a clock
`$0300–$035F`	96	text: a lookup table, one letter's shape, a string buffer
`$0800–$66FF`	24 KB	the program image (reserved)
`$6700–$67FF`	256	the star map
`$6800–$77FF`	4 KB	the shape table
`$BB00–$BC8F`	400	the row table
`$C000–$C7FF`	2 KB	sprite frames
`$CC00–$CFE7`	1,000	the screen plane
`$CFF8–$CFFF`	8	sprite pointers
`$D000–$D02E`	47	the VIDEO chip
`$D800–$DBE7`	1,000	colour RAM
`$DC00–$DC02`	3	input ports
`$E000–$FF3F`	8,000	the bitmap

Offset	Bytes	What
`$00`	2	the castle's size in bytes, header included
`$02`	1	`$80`, which says "this is a castle"
`$03`	2	the room each player starts in (player 1, then player 2)
`$05`	2	the door each player starts at
`$07`	2	each player's lives
`$5F`	2	where the final room's objects are, or 0 if there's no final room

`at`	reads	does
`$7909`	`03 08`	a tag: doors, counted
`$790B`	`02`	the count: two
`$790C`	8 bytes	returns door 1 of 2
`$7914`	8 bytes	returns door 2 of 2
`$791C`		the count is used up: `continue` to the next tag
`$791C`	`06 08`	a tag: walkways, ended by a 0
`$791E`	3 bytes	returns a walkway (and twice more)
`$7927`	`00`	the end marker: skip it, `continue`
...	...	the pole, the ladder, the bell, the text
`$7952`	`00 00`	the end tag: `null`

Each step, in the Ladders room	Grid	Search (Q)
finding the way out of one cell	20 cycles	about 1,440
a walking step	204	1,626
a climbing step, picture change included	856	3,700

Mission Briefing

The Gatehouse sign has been telling you to ring the bell since Chapter 3, and the bell has been ignoring you. This chapter, it rings. Press fire at the bell and the door beside it slides open a row at a time. Push up and to the right and the explorer walks into the doorway, and out of a door in the next room. By the end you can walk the whole Training Castle, and every door you open stays open behind you. He can also die now: he flickers away, loses a life, and starts again at the castle's front door.

The Gatehouse: the explorer at the doorbell, and the door beside it half open, its lower half already wiped away to black

To make the doors work, you build the engine every later chapter runs on: a table of actors, the things that move, and a table of objects, the things they stand in front of.

New under the hood: an array of structs is one block of memory, fixed-capacity slot tables, and tables of functions.

A castle full of things

Picture a busy room in one of the later castles. Two explorers are working a switch together while a mummy shuffles after one of them. A ray gun's laser streaks across the room. Frankenstein's monster is waking up in his alcove, and lightning crackles under three machines, a sprite for each bolt. That's eight things that move, and every one is a sprite: the Comet has exactly eight sprites. Around them stand the things they use: doors, doorbells, switches, keys and locks. A busy room can have a couple of dozen of those.

Every frame the game has to visit the whole crowd: move the movers, find out who's touching what, and let anything with work to do get on with it. How all those things are laid out in memory decides how much that visit costs.

Under the Hoodmonsters.push(new Monster())

In JavaScript you'd write a class and keep a list:

class Monster {
  constructor(x, y) { this.x = x; this.y = y; }
  update() { /* chase the player */ }
}
const monsters = [];
monsters.push(new Monster(40, 100));

Every new takes a fresh piece of the heap, the pool of memory the JavaScript engine hands out as objects are made. Each piece goes wherever there's room and carries a hidden header. So the array doesn't hold monsters at all. It holds pointers to them, and the monsters are scattered across the heap. When a monster dies it becomes garbage, and the garbage collector frees it later, at a moment you don't get to choose. Python's lists work the same way.

The 1984 game can't afford any of that, and it doesn't need it. There will never be more than eight movers, so it keeps eight slots in one block of memory and marks the empty ones free. No pointers to follow, nothing to allocate, no garbage to collect.

JavaScript: an array of pointers

Each new lands wherever the heap had room. Visiting them follows a pointer each.

The 1984 game: eight slots in a row

$BD00slot 0 · sprite 0 the explorer $BD10slot 1 · sprite 1 unused $BD20slot 2 · sprite 2 unused $BD30slot 3 · sprite 3 unused $BD40slot 4 · sprite 4 unused $BD50slot 5 · sprite 5 unused $BD60slot 6 · sprite 6 unused $BD70slot 7 · sprite 7 unused

16 bytes each, back to back, ending at $BD7F. Slot n is at $BD00 + 16n.

Three monsters in JavaScript, eight actors in 1984.

Sixteen bytes an actor

Anything that moves by itself is an actor, and slot n of the actor table goes with sprite n. The explorer moves into slot 0, taking his position, his picture and the direction of his last step with him. The player region shrinks to what the game has to remember about him between rooms: his slot, his status, his lives, his last joystick byte (still at $0203) and the door he came in by.

src/map.zig (replace the player region, its comment and its seven bytes)

zig

/// What the game knows about player 1 from room to room, five bytes in a
/// row. Where he is and what he's doing in a room is his actor's business
/// (actors.zig).
pub const player = Region{ .name = "player", .first = 0x0200, .last = 0x0204 };
pub const player_actor = player.first + 0; // the actor slot he has in this room
pub const player_status = player.first + 1; // a player.Status: playing, in a doorway, gone, dead
pub const player_lives = player.first + 2; // lives left, counting this one
pub const player_last_stick = player.first + 3; // joystick 1 as it read at his last turn
pub const player_door = player.first + 4; // the door he comes into the room by

src/map.zig (add below the row table)

zig

/// The actor table: a 16-byte slot for each of the VIDEO chip's eight
/// sprites (actors.zig).
pub const actors = Region{ .name = "actors", .first = 0xBD00, .last = 0xBD00 + 8 * 16 - 1 };

src/map.zig (in regions, add after row_table,)

zig

    actors,

Now the slot itself, in a new file:

src/actors.zig (new file)

zig

//! The actor table: everything in a room that moves by itself, as a
//! sprite. Eight slots in a row, one for each of the VIDEO chip's
//! sprites: slot n is sprite n. The explorer is the only kind of actor so
//! far; lightning, lasers and monsters move in later.

const std = @import("std");
const machine = @import("machine");
const Machine = machine.Machine;
const hw = machine.hw;
const map = @import("map.zig");
const shapes = @import("shapes.zig");
const sprites = @import("sprites.zig");
const player = @import("player.zig");

/// Where something is and how big: its top-left corner in castle
/// coordinates, and its size in fat pixels and rows. Actors and objects
/// both start with one.
pub const Box = extern struct { x: u8, y: u8, width: u8, height: u8 };

/// One slot: 16 bytes.
pub const Actor = extern struct {
    kind: Kind,
    state: State,
    box: Box, // where it is, and the size of its picture
    frame: u8, // the shape ID of its picture
    block: u8, // the sprite block showing it: n or n + 8
    color: u8, // its sprite's own colour
    countdown: u8, // engine steps until its next turn
    pace: u8, // engine steps from one turn to the next: 1 is every step
    flashes: u8, // flashes left while it's dying
    way: u8, // the direction of its last step
    stick: u8, // the direction its joystick read at its last turn
    fire: u8, // 1 if fire was pressed at its last turn
    walk: u8, // how far through a doorway it is
};

/// An actor's state: eight flags in one byte, the engine's to-do list.
pub const State = packed struct(u8) {
    unused: bool = false, // bit 0: the slot is empty
    hit_sprite: bool = false, // bit 1: its sprite touched another sprite
    hit_bitmap: bool = false, // bit 2: its sprite touched the room's foreground
    free: bool = false, // bit 3: empty the slot at the end of this step
    destroy: bool = false, // bit 4: its last turn: it tidies up, then it's freed
    dying: bool = false, // bit 5: flickering
    flash: bool = false, // bit 6: start dying
    created: bool = false, // bit 7: new this step
};

Box is a corner and a size. Objects have a box too, and when an actor's box overlaps an object's box, the actor is in front of it. Actor is sixteen bytes of u8s, so it's an extern struct with no padding (Chapter 3). Here's slot 0 with the explorer in it:

Slot 0, $BD00–$BD0F: the explorer in the Gatehouse doorway

00kindplayer

1$04stateflags ↓

2162x

3171y

48width

521height

box

616frameleft_0

70block

81colorwhite

91countdown

101pace

110flashes

12$80waystill

13$80sticknone

140fire

150walk

state = $04, bit by bit

bit 70created

60flash

50dying

40destroy

30free

its life story

21hit_bitmap

10hit_sprite

from the VIDEO chip

00unused

empty slot

Standing in the doorway, his sprite touches the door's pixels, so hit_bitmap is up. Slots 1–7 hold $01: only unused.

state is eight flags in a packed struct(u8), in 1984's bit order, and most of them mark a stage in an actor's life. destroy gives it one last turn to tidy up, and free empties its slot at the end of the step. The two hit flags are set from the VIDEO chip, and they're the best trick in the chapter. We'll use them when we build the doorbell.

A table of functions

Every kind of actor does something different on its turn. The explorer reads the joystick, a mummy (Chapter 8) chases the nearest explorer, and a laser (Chapter 7) flies until it hits something. The engine walks the table without knowing any of that, so it needs a way to get from a slot's kind byte to the right code.

src/actors.zig (add at the end of the file)

zig

/// Every kind of actor. Later chapters add more.
pub const Kind = enum(u8) { player, _ };

/// What each kind does: the function that takes its turn.
const Behaviour = struct {
    turn: *const fn (m: *Machine, n: u3) void,
};

/// One entry for every kind, found by number. The compiler won't build
/// the table with a kind missing.
const kinds = std.enums.directEnumArray(Kind, Behaviour, 0, .{
    .player = .{ .turn = player.turn },
});

Okay, this is one of my favourite ideas in the whole game. *const fn (m: *Machine, n: u3) void is a function pointer. Chapter 2 showed you that a pointer is an address. Code lives at addresses too, in the program image, and a function pointer is the address where a function's code starts. player.turn, written without the brackets that would call it, is that address, so kinds[k].turn(m, n) reads an address out of the table and jumps to the code there:

  slot 0:  kind = 0 ──► kinds[0] = .{ .turn = ──┐ }
                                                 └──► player.turn's code, in the program image

You've written this before. In JavaScript it's const kinds = { player: { turn: playerTurn } } and kinds[a.kind].turn(m, n). It's the same idea, but JavaScript looks the entry up by name, in a hash table, while the game runs, so a missing entry shows up as undefined is not a function in the middle of play. Ours is looked up by number in an array, and a missing entry stops the build. std.enums.directEnumArray does the checking: it takes a struct with a field for every tag of Kind (like Chapter 3's EnumFieldStruct) and returns an array with each tag's entry at the tag's number.

The _ in Kind makes it non-exhaustive: any byte value is a legal Kind. m.view insists on that for any enum it reads straight out of memory (reference card, section 9), because a byte in RAM can hold anything. If a bug ever puts an unknown kind in a slot, indexing kinds stops the game with an out-of-bounds panic instead of jumping somewhere strange.

Slots, not lists

Now the table itself, and the two things every slot table needs: emptying it and finding a free slot.

src/actors.zig (add at the end of the file)

zig

pub const slots = 8;

comptime {
    if (@sizeOf(Actor) * slots != map.actors.last - map.actors.first + 1)
        @compileError("the actor table doesn't fill its region exactly");
}

/// The whole table, as the eight structs it is.
pub fn table(m: *Machine) *align(1) [slots]Actor {
    return m.view([slots]Actor, map.actors.first);
}

/// Slot `n`.
pub fn slot(m: *Machine, n: u3) *align(1) Actor {
    return &table(m)[n];
}

/// Empty every slot, before a room starts.
pub fn clear(m: *Machine) void {
    for (table(m)) |*a| {
        a.state = .{ .unused = true };
        m.work(10); // the store and the loop
    }
}

/// Take the first empty slot for a new actor of `kind`: every byte 0,
/// then `created`, and a turn every step. Null if all eight are taken.
pub fn add(m: *Machine, kind: Kind) ?u3 {
    for (table(m), 0..) |*a, i| {
        m.work(10); // the test and the loop
        if (!a.state.unused) continue;
        const n: u3 = @intCast(i);
        m.fill(map.actors.first + @as(u16, n) * @sizeOf(Actor), @sizeOf(Actor), 0);
        a.kind = kind;
        a.state = .{ .created = true };
        a.block = @as(u8, n) + 8; // so its first picture goes into block n
        a.countdown = 1;
        a.pace = 1;
        m.work(20);
        return n;
    }
    return null;
}

table is the big idea in one line. It's Chapter 3's typed view aimed at an array of structs, and in Zig an array of structs is exactly the diagram above: eight Actors, 128 bytes, nothing between them. table(m)[5] is the 16 bytes at $BD50, and slot(m, 5).box.x is the byte at $BD52. No pointers, no headers, only arithmetic. *align(1) says the struct may start at any address (Chapter 3). Making a view costs no cycles, so each loop charges m.work for its own work.

add is the slot finder: it returns the first unused slot, wiped, or null if all eight are taken, and the caller decides what that means. The explorer is always first into a room, so for him the table is never full.

The rest of the file is what the engine does with the table every frame:

src/actors.zig (add at the end of the file)

zig

/// Hand every actor to the VIDEO chip: where it is, its colour, its
/// picture, and which sprites are on at all. First thing in a frame.
pub fn show(m: *Machine) void {
    var on: u8 = 0;
    var multicolor: u8 = 0;
    for (table(m), 0..) |*a, i| {
        m.work(10); // the test and the loop
        if (a.state.unused) continue;
        const n: u3 = @intCast(i);
        const bit = @as(u8, 1) << n;
        on |= bit;
        multicolor |= bit;
        sprites.place(m, n, a.box.x, a.box.y);
        m.poke(hw.spriteColor(n), a.color);
        m.poke(hw.sprite_pointers + n, a.block);
        m.work(10); // the masks
    }
    m.poke(hw.sprite_enable, on);
    m.poke(hw.sprite_multicolor, multicolor);
}

/// One engine step for every actor, in slot order: each one whose
/// countdown runs out takes its turn.
pub fn step(m: *Machine) void {
    for (table(m), 0..) |*a, i| {
        m.work(10); // the test and the loop
        if (a.state.unused) continue;
        const n: u3 = @intCast(i);
        if (a.state.destroy) {
            kinds[@intFromEnum(a.kind)].turn(m, n); // its last turn
        } else {
            a.countdown -= 1;
            if (a.countdown != 0) continue;
            kinds[@intFromEnum(a.kind)].turn(m, n);
        }
        if (a.state.free) a.state = .{ .unused = true };
        a.countdown = a.pace;
        m.work(30); // the flags
    }
}

/// Show picture `id` for actor `n` from the next frame on. It's unpacked
/// into the block the sprite *isn't* showing (Chapter 2's double buffer),
/// and its size becomes the box the actor touches things with.
pub fn setFrame(m: *Machine, n: u3, id: shapes.Id) void {
    const a = slot(m, n);
    const hidden = a.block ^ 8; // n <-> n + 8
    const at = shapes.address(m, id);
    a.box.width = m.peek(at) * 4; // bytes to fat pixels
    a.box.height = m.peek(at + 1);
    const flags = sprites.unpack(m, id, hidden);
    a.color = flags & sprites.flag_color;
    a.block = hidden;
    a.frame = @intFromEnum(id);
    m.work(16); // the stores
}

show is Chapter 1's shadow copy, for every actor at once. setFrame is Chapter 2's double-buffered unpack, moved here so every actor can use it. It also writes the picture's size into the box, so the area an actor touches with is exactly the picture you see.

step is one engine step, run every other frame, and it's the heartbeat of everything from here on. Each actor's countdown drops by one a step, and at 0 the actor takes its turn and the countdown restarts from pace. With a pace of 1 an actor moves every step; the explorer will use 3 for his slow walk through a doorway. An actor marked destroy gets its last turn straight away, and one marked free becomes unused, so slots are emptied by the engine, never in the middle of anyone's turn.

The explorer moves in

Time to move the explorer into his new home. His code now reads and writes his slot instead of the old player bytes, and uses actors instead of sprites:

src/player.zig (replace the comment at the top)

zig

//! Player 1: the explorer, an actor of kind `player`. He walks the
//! castle's floors, climbs its ladders, slides down its poles and goes
//! through its doors, steered by joystick 1.

src/player.zig (replace the sprites import)

zig

const actors = @import("actors.zig");

Delete the player_sprite constant and its comment: his actor slot number is his sprite slot now. start sets the two colours all multicolour sprites share and leaves the rest to actors.show:

src/player.zig (replace start)

zig

/// Once, at power-on.
pub fn start(m: *Machine) void {
    m.poke(hw.sprite_mc0, @intFromEnum(Color.pink)); // code 01: skin
    m.poke(hw.sprite_mc1, @intFromEnum(Color.orange)); // code 11: hat, belt, boots
    m.poke(map.player_last_stick, 0xFF); // nothing held
}

enter becomes add, which puts him in a slot and a doorway:

src/player.zig (replace enter)

zig

/// Into the room: an actor slot, and his place in its first doorway,
/// facing into the room. A room with no doors (the final room) puts him in
/// the middle of the floor.
pub fn add(m: *Machine) void {
    const n = actors.add(m, .player) orelse return; // he's the first in, so never
    m.poke(map.player_actor, n);
    const a = actors.slot(m, n);
    a.box.x = castle.left_edge + 80;
    a.box.y = room.floor_top - feet_y;
    a.way = still;
    if (room.firstDoor(m)) |at| {
        const d = m.view(castle.Door, at);
        a.box.x = d.x + door_x;
        a.box.y = d.y + door_y;
    }
    m.work(40); // the sums and the stores
    actors.setFrame(m, n, if (a.box.x < castle.left_edge + 80) .explorer_right_0 else .explorer_left_0);
}

show goes, since actors.show does it for everyone. In its place, his turn and the joystick reader it uses:

src/player.zig (replace show)

zig

/// His turn, actor `n`'s: on every engine step.
pub fn turn(m: *Machine, n: u3) void {
    const a = actors.slot(m, n);
    a.state.created = false;
    read(m, a);
    steer(m, n);
}

/// Read joystick 1, once a turn: its direction, and whether fire is down
/// now and wasn't at his last turn. The port byte is kept for next time here
/// and nowhere else in a room, so a fire button held down is never a
/// fresh press, however far he carries it.
fn read(m: *Machine, a: *align(1) actors.Actor) void {
    const stick = m.peek(hw.joy1);
    a.stick = stick_way[stick & 0x0F];
    a.fire = @intFromBool(pressed(stick, m.peek(map.player_last_stick)));
    m.poke(map.player_last_stick, stick);
    m.work(16); // the table read and the test
}

read fixes the problem Chapter 2 warned about in pressedFire. To spot a press, the code compares the stick with the value it saved last time. If he only read the stick while standing at a bell, that saved value could be from the far side of the room, and a button held all the way across would look like a fresh press the moment he arrived. So read runs on every turn, wherever he is. It's the only code that stores player_last_stick, and it records in his slot the direction and whether fire was pressed this turn. (A turn is every other frame, so a tap shorter than that could slip between two looks. No thumb is that quick.)

steer hardly changes, except that its game_tick test goes: the engine step sets everybody's pace now.

Type-In Listing`steer`, reading and writing his slot

src/player.zig (replace steer)

zig

/// One step: read the grid under his feet, pick a way to go, take the
/// step and pick his picture.
fn steer(m: *Machine, n: u3) void {
    const a = actors.slot(m, n);
    var x = a.box.x;
    var y = a.box.y;
    const fx = x + feet_x;
    const fy = y + feet_y;
    const ways = waysAt(m, fx, fy);

    // The stick's direction if that way is open. If it isn't, but it's
    // next to the way he was already going (a diagonal, say), keep going.
    const want = a.stick;
    const last = a.way;
    var way = still;
    if (want != still) {
        if (ways & bit(want) != 0) {
            way = want;
        } else if (last != still and ways & bit(last) != 0 and
            (want == (last +% 1) & 7 or want == (last -% 1) & 7))
        {
            way = last;
        }
    }
    a.way = way;

    if (way != still) {
        if (way & 3 == 2) y -= fy % 8; // off sideways: up onto the walkway's row
        if (way & 3 == 0) x = x - fx % 4 + 1; // up or down: feet in line with the rungs
        x +%= step_x[way];
        y +%= step_y[way];
        a.box.x = x;
        a.box.y = y;
    }
    m.work(60); // the sums, tests and table reads above

    // His picture. Walking: Chapter 2's walk, a frame every 2 fat pixels.
    // Up or down: a ladder has rungs that lead up from here or from just
    // below; a pole has none.
    const now = a.frame;
    var next = now;
    if (way == 2 or way == 6) {
        next = (if (way == 2) right_0 else left_0) + ((x >> 1) & 0b11);
    } else if (way == 0 or way == 4) {
        const rungs = (ways | waysAt(m, fx, fy +| 8)) & grid.up != 0;
        next = if (rungs) climb_0 + ((y >> 2) & 0b11) else @intFromEnum(shapes.Id.explorer_slide);
    } else if (now >= right_0 and now < left_0 + 4) {
        next = if (now >= left_0) left_0 else right_0; // stopped walking: stand
    } // stopped on a ladder or a pole: hold on
    if (next != now) actors.setFrame(m, n, @enumFromInt(next));
}

Delete setFrame from player.zig, and split the press test out of pressedFire, so it's a plain function of two bytes that anything can use:

src/player.zig (replace pressedFire)

zig

/// Was fire pressed this frame? For the title screen, where there's no
/// actor yet. It keeps the stick for next time, so call it once a frame.
pub fn pressedFire(m: *Machine) bool {
    const stick = m.peek(hw.joy1);
    const yes = pressed(stick, m.peek(map.player_last_stick));
    m.poke(map.player_last_stick, stick);
    m.work(10);
    return yes;
}

/// Is fire pressed now that wasn't before? The Edge Detector Power-Up as
/// a plain function of two port bytes: no memory of its own.
pub fn pressed(stick: u8, before: u8) bool {
    return held(stick, joy.fire) and !held(before, joy.fire);
}

Now the frame. The room branch shows every actor, and every other frame runs an engine step, timed in a meter bucket of its own:

src/main.zig (add below the player import)

zig

const actors = @import("actors.zig");

src/main.zig (add below bucket_sprites)

zig

const bucket_actors = 3;

src/main.zig (in the .draw_room branch, replace player.enter(m);)

zig

            actors.clear(m);
            player.add(m);

src/main.zig (in the .room branch, replace everything from m.bucket(bucket_sprites); to player.steer(m);)

zig

            m.bucket(bucket_sprites);
            actors.show(m);

            // Then the castle itself, one engine step every other frame:
            // 25 a second. What it decides shows up next frame.
            if (m.peek(map.game_tick) & 1 == 0) {
                m.bucket(bucket_actors);
                actors.step(m);
            }

The tests still poke at the old player bytes. Find and replace these in main.zig's tests (any you miss won't compile):

Replace	With
`m.ram[map.player_x]`	`explorer(m).box.x`
`m.ram[map.player_y]`	`explorer(m).box.y`
`m.ram[map.player_frame]`	`explorer(m).frame`
`m.ram[map.player_block]`	`explorer(m).block`

and add the function they now call:

src/main.zig (add above inRoom)

zig

/// The explorer's actor slot.
fn explorer(m: *Machine) *align(1) actors.Actor {
    return actors.slot(m, @intCast(m.ram[map.player_actor]));
}

Type-In ListingThe slot table's tests, and the press rule's

src/actors.zig (add at the end of the file)

zig

// ---- tests ----------------------------------------------------------------

test "eight slots: add takes the first empty one, and a full table says no" {
    const m = try std.testing.allocator.create(Machine);
    defer std.testing.allocator.destroy(m);
    m.* = .{};
    clear(m);
    for (0..slots) |i| try std.testing.expectEqual(@as(?u3, @intCast(i)), add(m, .player));
    try std.testing.expectEqual(@as(?u3, null), add(m, .player));
    try std.testing.expect(slot(m, 3).state.created);
    try std.testing.expectEqual(3 + 8, slot(m, 3).block);

    // Free slot 3 the way the engine does, and the next actor gets it.
    slot(m, 3).state.free = true;
    step(m);
    try std.testing.expect(slot(m, 3).state.unused);
    try std.testing.expectEqual(@as(?u3, 3), add(m, .player));
    try std.testing.expectEqual(@as(?u3, null), add(m, .player));
}

test "the table is one block: slot n is 16 n bytes in, in the field order" {
    try std.testing.expectEqual(16, @sizeOf(Actor));
    try std.testing.expectEqual(2, @offsetOf(Actor, "box"));
    try std.testing.expectEqual(1, @bitSizeOf(State) / 8);
    const m = try std.testing.allocator.create(Machine);
    defer std.testing.allocator.destroy(m);
    m.* = .{};
    slot(m, 5).box.x = 99;
    try std.testing.expectEqual(99, m.ram[map.actors.first + 5 * 16 + 2]);
    slot(m, 5).state = .{ .unused = true, .flash = true };
    try std.testing.expectEqual(0b0100_0001, m.ram[map.actors.first + 5 * 16 + 1]);
}

src/player.zig (add at the end of the file)

zig

// ---- tests ----------------------------------------------------------------

const std = @import("std");

test "a press is fire held now and not before, whatever else is held" {
    const none: u8 = 0xFF;
    const fire: u8 = 0xFF & ~joy.fire;
    try std.testing.expect(pressed(fire, none));
    try std.testing.expect(!pressed(fire, fire)); // still held: not a press
    try std.testing.expect(!pressed(none, fire)); // let go
    try std.testing.expect(!pressed(none, none));
    try std.testing.expect(pressed(fire & ~joy.right, none & ~joy.right)); // walking and pressing
}

Build and run. Nothing looks different, and that's the point: the explorer walks, climbs and slides exactly as he did, but he's actor 0 now, and everything he does goes through the table. The meter has noticed. A frame costs about twice what it did, because show and step visit all eight slots, seven of them empty. That's the price of an engine with room for seven more actors, and it's a fixed price: an empty slot costs one test.

A promise from Chapter 3

Chapter 3's room.draw picks each record's code with a switch, and I promised you then that it would get a table of functions. Here it is:

src/room.zig (add above the machine import)

zig

const std = @import("std");

src/room.zig (replace draw)

zig

/// What preparing a room does with each kind of record: a function for
/// every kind, found by number. The compiler won't build the table with a
/// kind missing.
const Prepare = *const fn (m: *Machine, r: castle.Record) void;
const prepares = std.enums.directEnumArray(castle.Kind, Prepare, 0, .{
    .door = door,
    .walkway = walkway,
    .pole = pole,
    .ladder = ladder,
    .bell = bell,
    .lightning = later,
    .forcefield = later,
    .mummy = later,
    .key = later,
    .lock = later,
    .pattern = later,
    .ray_gun = later,
    .teleport = later,
    .trapdoor = later,
    .conveyor = later,
    .frankenstein = later,
    .text = line,
    .image = image,
});

/// Draw the whole room, and build its navigation grid on the way, every
/// record handed to its kind's function. Far too big for one frame: call
/// it with the display blanked.
pub fn draw(m: *Machine) void {
    screen.clear(m);
    grid.clear(m);
    var walk = prepare(m, m.peek(map.room_number));
    while (walk.next(m)) |r| {
        m.work(10); // the table read and the call
        prepares[@intFromEnum(r.kind)](m, r);
    }
}

/// Machines and monsters come alive in later chapters.
fn later(m: *Machine, r: castle.Record) void {
    _ = m;
    _ = r;
}

Eleven kinds point at later, which does nothing until Chapter 6 starts replacing them. Leave a kind out and the build stops, before the game ever gets the chance to trip over it:

missing struct field: image

Every function in the table must have the type that Prepare declares, so all the drawers now take a castle.Record. The bell also stops using firstDoor and asks for its door by number, with a new function:

src/room.zig (replace firstDoor)

zig

/// Door `i` of room `n`, if the room has one. Doors come first in a
/// stream: their tag, a count, and 8 bytes for each door.
pub fn doorAt(m: *Machine, n: u8, i: u8) ?u16 {
    const at = objects(m, n);
    m.work(10); // the tests, and i * 8 is three shifts
    if (castle.kindOf(m, m.peek16(at)) != .door or i >= m.peek(at + 2)) return null;
    return at + 3 + @as(u16, i) * @sizeOf(castle.Door);
}

doorAt finds door i of any room, not only the one on screen, which the doors will need shortly. The rest is new signatures, with grid.add moving into the drawers that build the grid:

src/room.zig (replace the comment above walkway and its first two lines)

zig

/// A walkway: `length` pieces 4 fat pixels wide, a left end, middles and
/// a right end. Somewhere to walk.
fn walkway(m: *Machine, r: castle.Record) void {
    grid.add(m, r);
    const w = m.view(castle.Run, r.at);

src/room.zig (add above column)

zig

/// A sliding pole, and a ladder: somewhere to climb.
fn pole(m: *Machine, r: castle.Record) void {
    grid.add(m, r);
    column(m, .pole, r.at);
}

fn ladder(m: *Machine, r: castle.Record) void {
    grid.add(m, r);
    column(m, .ladder, r.at);
}

src/room.zig (in door, replace the first two lines)

zig

fn door(m: *Machine, r: castle.Record) void {
    const d = m.view(castle.Door, r.at);

src/room.zig (replace bell)

zig

/// A doorbell, in the colour of the room its door leads to.
fn bell(m: *Machine, r: castle.Record) void {
    const b = m.view(castle.Bell, r.at);
    const at = doorAt(m, m.peek(map.room_number), b.door) orelse return;
    const d = m.view(castle.Door, at);
    shapes.recolor(m, .bell, roomColors(m, d.to_room));
    place(m, .bell, b.x, b.y);
}

src/room.zig (in line, replace the first line)

zig

fn line(m: *Machine, r: castle.Record) void {
    const at = r.at;

src/room.zig (in image, replace the first line)

zig

fn image(m: *Machine, r: castle.Record) void {
    const at = r.at;

src/player.zig (in add, replace the firstDoor line)

zig

    if (room.doorAt(m, m.peek(map.room_number), 0)) |at| {

and a test that every kind has a function:

src/room.zig (add at the end of the file)

zig

// ---- tests ----------------------------------------------------------------

test "preparing a room has a function for every kind of record" {
    try std.testing.expectEqual(std.enums.values(castle.Kind).len, prepares.len);
}

Build and run: the castle draws as before, and preparing a room is now one table read and one call per record. That's the foundations poured. Now for something you can see.

Things in the room

The object table

An object is something an actor can stand in front of, or that has work of its own to do: a door, a doorbell, and later the switches, keys and locks. 1984 gives the object table 32 slots of 16 bytes, the 512 bytes from $BE00, right after the actors.

src/map.zig (add below the actors region)

zig

/// The room's object table: 32 slots of 16 bytes (objects.zig).
pub const objects = Region{ .name = "objects", .first = 0xBE00, .last = 0xBE00 + 32 * 16 - 1 };

src/map.zig (in regions, add after actors,)

zig

    objects,

The count of slots in use and how the room ends go in a new region at $020D ($020C stays free for a debug switch at the end of the chapter):

src/map.zig (add below the debug region)

zig

/// The room at work: how many objects it has, and how it ends.
pub const engine = Region{ .name = "engine", .first = 0x020D, .last = 0x020E };
pub const engine_objects = engine.first + 0; // object slots in use (objects.zig)
pub const engine_ending = engine.first + 1; // steps until the room is over, or 0 while it isn't ending

src/map.zig (in regions, add after debug,)

zig

    engine,

src/objects.zig (new file)

zig

//! The room's object table: the things in a room that an actor can stand
//! in front of, or that have work to do. Preparing the room fills it, up
//! to 32 of them, 16 bytes each. Doors and doorbells, for now.

const std = @import("std");
const machine = @import("machine");
const Machine = machine.Machine;
const map = @import("map.zig");
const actors = @import("actors.zig");
const doors = @import("doors.zig");

/// One slot: 16 bytes.
pub const Object = extern struct {
    kind: Kind,
    flags: Flags,
    box: actors.Box, // the part an actor has to stand in front of
    record: u16, // where its record is in the castle
    number: u8, // a door: its place among the room's doors. A bell: its door's
    open: u8, // a door: 1 once it's open, or opening
    step: u8, // a door: rows of its panel still to wipe
    spare: [5]u8, // for the machines and monsters to come
};

/// An object's flags. Three are used by the engine; the low five are
/// each kind's own.
pub const Flags = packed struct(u8) {
    own: u5 = 0,
    picked: bool = false, // bit 5: picked up, so it leaves the table (keys)
    execute: bool = false, // bit 6: it has work to do: give it a turn every step
    disable: bool = false, // bit 7: nobody can stand in front of it
};

/// Every kind of object. Later chapters add more.
pub const Kind = enum(u8) { door, bell, _ };

record is our first u16 field in a struct. We put it at an even offset, so Zig adds no padding before it and the machine accepts the view (Chapter 3's rule). The flags byte has 1984's three: disable (nobody can stand in front of it), execute (it has work to do) and picked (a taken key, Chapter 7). The other five bits belong to each kind. Then the handlers:

src/objects.zig (add at the end of the file)

zig

/// What each kind does: its work for a step while its `execute` flag is
/// set, and what happens when an actor stands in front of it. Null for
/// "nothing".
const Handlers = struct {
    execute: ?*const fn (m: *Machine, n: u8) void,
    in_front: ?*const fn (m: *Machine, n: u8, who: u3) void,
};

/// One entry for every kind, found by number.
const kinds = std.enums.directEnumArray(Kind, Handlers, 0, .{
    .door = .{ .execute = doors.open, .in_front = null },
    .bell = .{ .execute = null, .in_front = doors.ring },
});

This time the function pointers are optional, ?*const fn: a bell has nothing to do on its own, so its execute is null, and callers check first with Chapter 2's if (x) |v|.

Object 1, at $BE10: the Gatehouse bell

1$001401681219… byte 0, kind = 1: bell

↓ kinds[1]: the row at the kind's number

#	kind	.execute	.in_front
0	door	doors.open	doors.enter
1	bell	null	doors.ring

objects.step calls .execute for an object whose execute flag is up; objects.touching calls .in_front when boxes overlap. ↓ he's in front of the bell: call the address in .in_front

doors.ring(m, 1, 0)the code at that address runs

A switch would ask "door? bell?" in step, in touching, and in every place to come. The table is one read, however many kinds there are.

From a kind byte to the code that runs: index, read, call.

src/objects.zig (add at the end of the file)

zig

pub const slots = 32;

comptime {
    if (@sizeOf(Object) * slots != map.objects.last - map.objects.first + 1)
        @compileError("the object table doesn't fill its region exactly");
}

/// Slot `n`.
pub fn slot(m: *Machine, n: u8) *align(1) Object {
    return &m.view([slots]Object, map.objects.first)[n];
}

/// No objects, before a room is prepared.
pub fn clear(m: *Machine) void {
    m.poke(map.engine_objects, 0);
}

/// Take the next slot for an object of `kind`, standing in `box`, made
/// from the castle record at `record`. Null if the table is full; then
/// the object is drawn, but nothing can use it.
pub fn add(m: *Machine, kind: Kind, box: actors.Box, record: u16) ?u8 {
    const n = m.peek(map.engine_objects);
    if (n == slots) return null;
    m.poke(map.engine_objects, n + 1);
    m.fill(map.objects.first + @as(u16, n) * @sizeOf(Object), @sizeOf(Object), 0);
    const o = slot(m, n);
    o.kind = kind;
    o.box = box;
    o.record = record;
    m.work(30); // the stores
    return n;
}

In a room with more than 32 objects, the first 32 get to work and the rest are drawn and do nothing. That's what 1984 does.

src/objects.zig (add at the end of the file)

zig

/// One engine step for the objects: the ones that asked to run, run.
/// Everything else costs one test of one bit.
pub fn step(m: *Machine) void {
    const count = m.peek(map.engine_objects);
    var n: u8 = 0;
    while (n < count) : (n += 1) {
        const o = slot(m, n);
        m.work(12); // the test and the loop
        if (!o.flags.execute) continue;
        if (kinds[@intFromEnum(o.kind)].execute) |execute| execute(m, n) else o.flags.execute = false;
    }
}

/// Actor `who` has touched the room's foreground. Find the objects its box
/// overlaps, and tell each one it has an actor standing in front of it.
pub fn touching(m: *Machine, who: u3) void {
    const a = actors.slot(m, who);
    const count = m.peek(map.engine_objects);
    var n: u8 = 0;
    while (n < count) : (n += 1) {
        const o = slot(m, n);
        m.work(12); // the test and the loop
        if (o.flags.disable or !overlap(m, a.box, o.box)) continue;
        if (kinds[@intFromEnum(o.kind)].in_front) |in_front| in_front(m, n, who);
    }
}

/// Do two boxes overlap? An edge that touches counts. The sums are done in
/// a u16, so a box at the right of the screen can't wrap round.
pub fn overlap(m: *Machine, a: actors.Box, b: actors.Box) bool {
    m.work(40); // four compares, four sums
    return @as(u16, a.x) + a.width >= b.x and @as(u16, b.x) + b.width >= a.x and
        @as(u16, a.y) + a.height >= b.y and @as(u16, b.y) + b.height >= a.y;
}

step costs one bit test per object, and here's why that's clever. Most objects spend most of their lives doing nothing at all. A door is shut, or it's open, and either way it's standing still. Only a door that's been rung has work: wiping its panel a row at a time. So the bell sets the door's execute flag, and step runs only the objects whose flag is up. The flag is the to-do list. There's no queue of jobs to allocate, and a finished job clears its own bit.

touching finds out what an actor has bumped into. overlap says two boxes overlap unless one is entirely left of, right of, above or below the other, and an edge that touches counts. The sums are u16 because a box near the right edge plus its width can pass 255 (the overflow from Chapter 4).

Who's touching what

Who calls touching, and when? The brute-force answer is every actor against every object, every step. In a busy room that's 8 × 32 = 256 box tests a step, and nearly all of them say "no": an explorer strolling across empty floor isn't in front of anything.

Here's the trick I've been saving: the VIDEO chip can rule most of them out for us, at no cost. As the beam draws, it sets a sprite's bit in $D01F whenever one of its pixels lands on a foreground pixel of the bitmap (codes 10 and 11, reference card section 5), and in $D01E whenever it lands on another sprite. Every object is drawn with foreground pixels in it, so an actor that touched no foreground can't be standing in front of anything:

On screen: at the bell

First pass: the VIDEO chip, every pixel

code 01: doesn't countcodes 10, 11: foregroundhis spriteboth

16 of his pixels land on the bell's foreground, so $D01F = %0000_0001: bit 0, sprite 0, becomes his hit_bitmap. Out on bare floor his boots end a row above the floor's top, and $D01F stays 0.

Second pass: our code, boxes

overlap

Bell: 145 + 8 ≥ 140, 140 + 12 ≥ 145, and the same for y: they overlap, so ring runs. His feet are at 148, 8 fat pixels past the bell's edge, inside its reach of 12. Door: 145 + 8 = 153 is short of 160, so enter isn't called.

The bell three ways: on screen, to the VIDEO chip, and to our code.

Once a step the engine reads both registers, zeroes them so they start counting again, and copies each actor's bit into hit_bitmap and hit_sprite. Only an actor with hit_bitmap set looks through the objects. The hardware does the cheap, rough test on every pixel of every frame, and our code does the exact one only when it might say yes. The chip sets those bits whether anyone reads them or not; we finally do.

src/actors.zig (add below the sprites import)

zig

const objects = @import("objects.zig");

src/actors.zig (in clear, add at the end, and replace the comment above it)

zig

/// Empty every slot, and forget any collisions, before a room starts.
pub fn clear(m: *Machine) void {
    for (table(m)) |*a| {
        a.state = .{ .unused = true };
        m.work(10); // the store and the loop
    }
    m.poke(hw.sprite_sprite_hits, 0);
    m.poke(hw.sprite_bitmap_hits, 0);
}

src/actors.zig (replace step)

zig

/// One engine step for every actor, in slot order. The VIDEO chip's
/// collision reports come first, for free: an actor whose sprite touched
/// nothing in the room's foreground can't be standing in front of
/// anything, so only the ones that did look through the objects.
pub fn step(m: *Machine) void {
    const sprite_hits = m.peek(hw.sprite_sprite_hits);
    const bitmap_hits = m.peek(hw.sprite_bitmap_hits);
    m.poke(hw.sprite_sprite_hits, 0); // read them, then start again
    m.poke(hw.sprite_bitmap_hits, 0);
    for (table(m), 0..) |*a, i| {
        m.work(10); // the test and the loop
        if (a.state.unused) continue;
        const n: u3 = @intCast(i);
        const bit = @as(u8, 1) << n;
        a.state.hit_sprite = sprite_hits & bit != 0;
        a.state.hit_bitmap = bitmap_hits & bit != 0;
        if (a.state.destroy) {
            kinds[@intFromEnum(a.kind)].turn(m, n); // its last turn
        } else {
            a.countdown -= 1;
            if (a.countdown != 0) continue;
            if (a.state.hit_bitmap) objects.touching(m, n);
            kinds[@intFromEnum(a.kind)].turn(m, n);
        }
        if (a.state.free) a.state = .{ .unused = true };
        a.countdown = a.pace;
        m.work(30); // the flags
    }
}

clear clears the registers too, so a hit from the last room can't leak into the next. Nothing uses hit_sprite yet: the first thing that cares about two sprites touching is Chapter 6's lightning.

Ringing the bell

Doors and doorbells get a file of their own:

src/doors.zig (new file)

zig

//! Doors and doorbells at work: a bell rung, a door swinging open.

const machine = @import("machine");
const Machine = machine.Machine;
const map = @import("map.zig");
const castle = @import("castle.zig");
const room = @import("room.zig");
const actors = @import("actors.zig");
const objects = @import("objects.zig");
const player = @import("player.zig");

/// A bell answers feet up to 12 fat pixels from its left edge.
const bell_reach = 12;

/// A bell's `in_front`: the explorer, at the bell, presses fire. If its
/// door is shut, the door gets to work.
pub fn ring(m: *Machine, n: u8, who: u3) void {
    const a = actors.slot(m, who);
    const bell = objects.slot(m, n);
    m.work(20); // the tests
    if (a.kind != .player or a.fire == 0) return;
    if (a.box.x +% player.feet_x -% bell.box.x >= bell_reach) return; // his feet aren't under it
    const d = objects.slot(m, find(m, bell.number) orelse return);
    if (d.open == 0) d.flags.execute = true;
}

/// The object for the room's door `number`.
fn find(m: *Machine, number: u8) ?u8 {
    const count = m.peek(map.engine_objects);
    var n: u8 = 0;
    while (n < count) : (n += 1) {
        const o = objects.slot(m, n);
        m.work(12); // the tests and the loop
        if (o.kind == .door and o.number == number) return n;
    }
    return null;
}

/// A door's `execute`, from the step after its bell rang. The first time,
/// it opens in the castle, on both sides; then its panel is wiped a row a
/// step, from the bottom up, and last of all it's drawn open.
pub fn open(m: *Machine, n: u8) void {
    const o = objects.slot(m, n);
    m.work(20); // the tests
    if (o.open == 0) {
        o.open = 1;
        o.step = room.door_panel_height - 1;
        const d = m.view(castle.Door, o.record);
        d.side |= castle.door_open;
        if (room.doorAt(m, d.to_room, d.to_door)) |far| m.view(castle.Door, far).side |= castle.door_open;
        m.work(40); // the two doors' bits
    }
    room.wipe(m, o.box.x, o.box.y + o.step);
    if (o.step != 0) {
        o.step -= 1;
        return;
    }
    o.flags.execute = false; // done
    room.panel(m, o.record);
}

ring is the bell's in_front: it's the explorer (a laser can't ring a doorbell), fire was pressed on his last turn, and his feet are within 12 fat pixels to the right of the bell's left edge. That last test is 1984's own, and it's a lovely bit of thrift. It subtracts the bell's x from his feet's x with the wrapping -%. If his feet are left of the bell, the result wraps round to a huge number, so the one >= 12 test catches "too far right" and "left of the bell" at once. If the bell's door is shut, ring sets the door's execute flag, and that's all a bell does. It doesn't open anything. It asks.

open is the door's execute. The first time, it sets the open bit in the castle, on this door and on the one it leads to: a door is one opening in a wall, so it's open from both sides, and because the bit lives in the castle, it stays open when you come back. Then it wipes the panel a row a step, from the bottom up, like a portcullis going up:

the bell rings

execute: 1
open: 0
o.step: –
wiped: none

ring() sets the door's execute flag and stops there. Nothing is drawn yet.

step 1 of 24

execute: 1
open: 1
o.step: 23 → 22
wiped: row 23

Open bit set in the castle, on this door and the far one. Then the first row: the bottom.

step 2 of 24

execute: 1
open: 1
o.step: 22 → 21
wiped: row 22