Sherlock: annotated disassembly

How Sherlock works

Sherlock (Melbourne House, 1984) is a text adventure written as one block of Z80 code and data that loads at 5D80 and starts at A040. The game is a clockwork: every person, including the player, is an actor that runs a small program, and a single loop gives each actor a turn as the minutes go by. Almost nothing is special-cased for the player.

Memory map

FromToWhat is there
5D80$5DBFThe dictionary index: where the words starting with each letter begin.
5DC0$67B6The dictionary: 592 words, five bits to a letter.
67B78258Every message the game prints, as bytecode.
8259$840AThe verb patterns: the verb number is the position in this table.
840B8B6EThe room table and the 106 room records.
8B6F$956FThe entity index and the entity records: every person, object and door.
9570$985FThe node heap, 752 bytes, for the engine's own linked lists.
9860$9964The actor table, the player's plan script and the case's relation words.
99659F37The case table, and the routines that run when a statement is proved or a character has taken a turn.
9F38$A03FThe default action record for each verb, the table of script-only verbs and the game variables.
A040$A59EStart-up and the main loop, the heap, the narration of commands.
A59F$AA70The message interpreter, the word printer and the word-wrapping character printer.
AA71$B190The shared action records and the parser.
B191$BA1FMatching a typed command against the verb patterns; orders and remarks to other people.
BA20$BF78Watson's and Lestrade's replies to what the player says: the case.
BF79C492The clock, saving and loading, the screen layout and the command window.
C493$CC0DCarrying out a command: action records, checks and the report of what happened.
CC0E$D6BEThe actor's turn and the plan-script interpreter, the random numbers, light, and room descriptions.
D6BF$DC14The player's turn: the line editor, the tokenizer and the number and money readers.
DC15F3C1Action records, sub-scripts and every character's plan script.
F3C2F60AThe picture interpreter.
F60BFFFFWhich rooms have a picture, and the picture data.

A turn

The main loop (A064) is one minute of game time per pass. It advances and prints the clock (BFD9, BF79), then walks the actor table at 9860 and gives a turn to every actor whose next-turn time has come. A turn begins by finding the actor (CC0E) and asking whether an order or remark is waiting for it (CC37, B91F). If so that is dealt with first (B936). Otherwise the actor's plan script runs one step at a time (CC78) until a step takes time. The minutes it took are added to the actor's next-turn time and the actor's own after-turn routine, if it has one, runs (9C77). Typing WAIT costs the player five minutes; TAKE LAMP costs one. When the game ends, 9E74 prints the ending and the game starts again.

The player is actor 0. The player's plan script (9921) reads a line from the keyboard with a time limit (D898) and WAITs if nothing is typed, splits the line into words (D715), parses one sentence (AAB2) and carries it out. A line of several sentences is worked through one a minute. Typed words are first turned into tokens (D9C5): dictionary words, numbers, clock times and old-style money such as 2/6 (DB67).

A command, typed or from a script, is a verb and up to two objects. B191 matches the words against the verb patterns; C4D1 finds the action record to use. A verb has a default record (9F38) and an object can have its own list of shared records (AA71). The record is run by C9BF: it names what each object must be (here, carried, a person, a door, a number: C628), tests flags on the objects, may call a pre-check routine, and then runs either a body of code or a sub-script. Afterwards CA60 reports what the player sees: the command as a sentence (A2E4), a new room (CA7F) or someone arriving (CAAF).

The world

Things, people and doors are entity records (8CBA), found through an index (8B6F). Each has a holder (a room, another thing, or a person), flags such as visible, a person, open, locked and seen, and a room. Rooms are records of their own (84E1) with their exits. Whether the player can see is decided by D078: outdoors between eight in the evening and six in the morning the player needs a light, and the oil lamp is lit from the start. D0DD builds the description of the room the player is in.

The engine also needs lists that grow and shrink while the game runs: orders and remarks waiting for actors, tokens from the typed line, countdowns, sub-script call frames. They are linked lists in a small heap (9570) managed by A11C and A1C7.

The characters

Every character's behaviour is a plan script in a small bytecode that CC78 interprets: DO a command, RUN an action record, ASK someone to do something, SAY or PRINT a message, SIGNAL and AWAIT another character, RETURN from a sub-script, PASS, GOTO. Each step can branch on success or failure. A step that succeeds after taking time ends the actor's turn; a failure moves on to the next step at once, so a step that fails to itself means "wait here until this works". Verbs from 128 up (9FAB) exist only for scripts: they test where people are, the hour and chance, and move things about.

Because characters use the same commands as the player, they can do what the player can: open doors, take cabs and trains, follow someone, and be given orders. SAY TO a person hands them what was said (B86A). Some steps are marked busy, and a character on one of them refuses what the player asks (CBA7). Each of nine characters also has an after-turn routine (9C85) for greetings, warnings and the like. See The cast and their scripts for every script.

Text

Dictionary words are stored five bits to a letter (A880 unpacks them), so a typed word is looked up through the per-letter index at 5D80. Messages are small programs (A59F runs them): ordinary bytes are letters, bytes from $60 up stand for common words, and control codes handle things like choosing one of several phrases at random (A6D3), articles (A7EB), capital letters and what a character says. The parameters of a message are pushed on the stack before the call. Output goes through a word-wrapping printer (A9B7) and a character routine that writes to the screen (AA14); the command window echoes what is typed (C1FC).

Pictures

Fourteen rooms have a picture, drawn when the player arrives from a compact list of drawing commands (F3C2): move the pen, draw a line (F56E), fill an area (F490), colour blocks of attributes. Rooms 54 and 55 share one picture. See The pictures.

Chance

The random number generator (D2AD) is seeded from the Z80 refresh register at the first keypress. It steps a pointer through memory and mixes the bytes it finds, never giving the same number twice running. Script chances (F198), countdowns and the greeting delays of the after-turn routines all use it.

The case

The solution is data. 9965 lists statements such as MRS BROWN KILLED HERSELF, each with the evidence needed to prove it: things the player must have seen or examined, or markers that only the game can set. Telling Lestrade a statement (BB67) proves it if the evidence is there and runs the statement's routine (99FC); otherwise it waits and is proved as soon as the evidence is complete (BC46). Telling Watson (BA67) only makes him remember it. Lestrade must be met, with Chief Constable Straker, by three on Monday afternoon (9DFF). The endings depend on what has been proved (9EA2, 9E85) and on who is with the player when Basil arrives (9E48). See The case for every statement and its evidence.

Saving

The game state is one block of 7,188 bytes from 840B to $A01F: the room and entity records, the heap, the actor table, the case table and the game variables. SAVE (B0C6) sets a flag, and at the end of that minute the main loop writes the block to tape (B0E4, C040) and checks it. LOAD, and a game that has ended, read the block back (B0D7) and start again from A040.