Writing a Text Adventure Parser in Atari BASIC
Text adventures were among the most popular kinds of type-in program, and they suit Atari BASIC well: they need no speed, just careful handling of strings and data. The heart of every adventure is the parser, the part that turns "TAKE THE LAMP" into something the program can act on. This guide builds a small, complete two-word parser with a three-room world, and explains the design decisions and memory tricks used by the adventure writers of the 1980s.
What you'll learn: splitting input into verb and noun, fixed-width vocabulary tables in a string, abbreviations, dispatching with ON ... GOTO, rooms, exits and objects stored compactly, and how to scale it up without running out of memory.
What you need: Atari BASIC. The program below was run in atari800, with the commands in the screenshot typed at its prompt.
1. Design first: how much language?
The book Creating Adventure Games On Your Computer (whose programs run on the Atari among other machines) starts with single-letter commands: N, S, E, W, U, D, F for fight, R for run, and so on. They are fast and simple, and its first full game cuts every input to its first letter. It notes that commercial games such as Zork accept whole sentences, and its last program moves on to two-word commands. That step, VERB NOUN, is the sweet spot for BASIC: rich enough to feel like conversation ("OPEN DOOR", "TAKE KEY"), and simple enough to parse quickly.
Robert A. Howell, who fitted the original Adventure into a 32K Atari 800 (see Ram Cram: Squeezing Big Programs into Atari BASIC), kept only the first five letters of every word. That was enough to keep NORTH, TAKE, DRAGO and INVEN distinct, and it saves memory and comparison time. Our parser uses the same rule.
2. The program
10 REM TWO-WORD PARSER FOR A TEXT ADVENTURE
20 DIM IN$(40),V$(20),N$(20),VB$(55),NN$(15),W$(5),D$(60),OL$(3),EX$(12),NL(3),DN$(20)
30 VB$="GO NORTHSOUTHEAST WEST TAKE GET DROP LOOK INVENQUIT "
40 NN$="LAMP KEY BOOK "
50 EX$="203001000001":REM EXITS N,S,E,W FOR ROOMS 1-3
60 OL$="123":REM WHERE EACH OBJECT IS (0 = CARRIED)
70 FOR J=1 TO 3:READ X:NL(J)=X:NEXT J:DATA 4,3,4
80 DN$="NORTHSOUTHEAST WEST "
100 R=1:GOSUB 600
110 ? :? "WHAT NOW";:INPUT IN$:IF IN$="" THEN 110
120 P=0:FOR I=1 TO LEN(IN$):IF IN$(I,I)=" " AND P=0 THEN P=I
130 NEXT I:N$=""
140 IF P=0 THEN V$=IN$:GOTO 160
150 V$=IN$(1,P-1):IF P<LEN(IN$) THEN N$=IN$(P+1)
160 W$=V$:GOSUB 500:V=K:W$=N$:GOSUB 550:NO=K
170 IF V=0 THEN ? "I DON'T KNOW HOW TO ";V$;".":GOTO 110
180 ON V GOTO 200,210,210,210,210,300,300,350,400,450,480
200 W$=N$:GOSUB 500:IF K<2 OR K>5 THEN ? "GO WHERE?":GOTO 110
205 V=K
210 D=V-1:X=VAL(EX$((R-1)*4+D,(R-1)*4+D)):IF X=0 THEN ? "YOU CAN'T GO THAT WAY.":GOTO 110
220 R=X:GOSUB 600:GOTO 110
300 IF NO=0 THEN ? "TAKE WHAT?":GOTO 110
310 IF VAL(OL$(NO,NO))<>R THEN ? "I SEE NO ";N$;" HERE.":GOTO 110
320 OL$(NO,NO)="0":? "TAKEN.":GOTO 110
350 IF NO=0 THEN ? "DROP WHAT?":GOTO 110
360 IF OL$(NO,NO)<>"0" THEN ? "YOU AREN'T CARRYING IT.":GOTO 110
370 OL$(NO,NO)=STR$(R):? "DROPPED.":GOTO 110
400 GOSUB 600:GOTO 110
450 ? "YOU ARE CARRYING:";:F=0:FOR J=1 TO 3:IF OL$(J,J)="0" THEN ? " ";NN$(J*5-4,J*5-5+NL(J));:F=1
455 NEXT J:IF F=0 THEN ? " NOTHING";
460 ? :GOTO 110
480 ? "BYE.":END
500 REM VERB W$ -> NUMBER K (0 = UNKNOWN)
505 IF LEN(W$)<5 THEN W$(LEN(W$)+1)=" "
510 K=0:FOR J=1 TO LEN(VB$) STEP 5:IF VB$(J,J+4)=W$ THEN K=(J+4)/5
520 NEXT J:RETURN
550 REM NOUN W$ -> NUMBER K (0 = UNKNOWN OR NONE)
555 IF LEN(W$)<5 THEN W$(LEN(W$)+1)=" "
560 K=0:FOR J=1 TO LEN(NN$) STEP 5:IF NN$(J,J+4)=W$ THEN K=(J+4)/5
570 NEXT J:RETURN
600 REM DESCRIBE ROOM R
610 RESTORE 1000+R*10:READ D$:? D$:? "EXITS:";
615 FOR J=1 TO 4:IF EX$((R-1)*4+J,(R-1)*4+J)<>"0" THEN ? " ";DN$(J*5-4,J*5);
618 NEXT J:?
620 FOR J=1 TO 3:IF VAL(OL$(J,J))=R THEN ? "THERE IS A ";NN$(J*5-4,J*5-5+NL(J));" HERE."
630 NEXT J:RETURN
1010 DATA YOU ARE IN A DUSTY HALL.
1020 DATA YOU ARE IN A LIBRARY.
1030 DATA YOU ARE IN A KITCHEN.
3. How the parser works
Splitting the line (120–150). The loop finds the first space. Everything before it is the verb V$, and everything after it the noun N$. With no space, the whole line is the verb. Atari BASIC has no INSTR, so a FOR loop does the search. Extra words after the second are kept in N$ and ignored by the lookup.
Five-letter slots (30–40, 500–570). The vocabulary lives in single strings with every word padded to five characters: "GO NORTHSOUTH...". To look a word up, it is copied into W$, which is DIMmed to exactly 5 characters. Assigning a longer word silently truncates it, so INVENTORY becomes INVEN. Shorter words are padded with spaces (lines 505 and 555). The loop then compares five-character slices. The position of the match gives the word number, and 0 means unknown. Because Atari BASIC has no string arrays, this fixed-slot layout is the standard substitute (see Atari BASIC String Handling and Tricks).
Synonyms are free. TAKE (word 6) and GET (word 7) both go to line 300 in the ON V GOTO list. Add CARRY or GRAB the same way, without touching the handlers.
Dispatch (180). ON V GOTO sends each verb number to its handler. Directions 2–5 share one handler (210), which works out the direction from the verb number. "GO NORTH" is handled by looking the noun up in the verb table (line 200) and pretending it was typed as the verb.
Answers that sound varied. The book recommends different refusal messages for different situations, so the program doesn't feel like it says "I CAN'T" to everything. Here, unknown verbs echo the word back ("I DON'T KNOW HOW TO DANCE."), and missing objects echo the noun.
4. The world in a few strings
- Exits (50).
EX$holds four digits per room, for north, south, east and west, each the number of the room in that direction or 0. Room 1's "2030" means north to room 2 and east to room 3. One character per exit is far cheaper than a numeric array, which costs six bytes per element. Line 615 prints the exits by scanning the room's four digits. - Objects (60).
OL$holds one character per object: the room it's in, or "0" when the player carries it. TAKE and DROP just change that character (lines 320 and 370). INVENTORY and the room description scan it. - Descriptions (610, 1010–1030). Each room's text is a DATA line at 1000 + 10 × room, reached directly with a computed
RESTORE. That is Howell's technique too: data stays in DATA statements and costs memory only once.
5. Scaling up
For a full-size game, Howell's advice from The Creative Atari still applies:
- Put all text in DATA and read it when needed, with a marker character at the end of long messages that span several DATA lines.
- Group the vocabulary by first letter on separate DATA lines and RESTORE straight to the right group. Searching one long list made his game take five to ten seconds per command, and grouping brought it down to one or two.
- Compress the map. His exit table used −n in DATA to stand for n zeros, cutting it from 7,560 bytes (as a numeric array) to 2,236.
- Abbreviate and reuse text. Removing "You are in " from 63 room descriptions and adding it back in the print routine saved about 600 bytes.
For two-word commands with adjectives or articles ("TAKE THE RUSTY KEY"), skip a small list of noise words (THE, A, AN) before taking the noun, and match adjectives as part of the noun phrase. The same slot-table lookup handles them.
6. Ideas to add
- Doors and conditions: an exit digit of a special value (say 9) can mean "locked", with a check for the key in
OL$. - Light: refuse to describe dark rooms unless the lamp's
OL$entry is "0". - Scoring: count treasures dropped in a particular room.
- Saving the game: write
RandOL$to a disk file with PRINT # (see Working with Disk Files in Atari BASIC), or use the self-modifying trick of storing them in DATA lines (see Self-Modifying Atari BASIC).
Troubleshooting
- ERROR 5 in the lookup: a padding assignment ran past the DIM. Only pad when
LEN(W$)<5. - Every word is unknown: the vocabulary string isn't padded to exact five-character slots. Count the spaces.
- ERROR 9 on INPUT: the input string isn't DIMmed, or is too short for long commands.
- Descriptions break mid-word on screen: keep each DATA line under 38 characters, or print a word at a time with your own wrapping.
Further reading
- Robert A. Howell, "Ram Cram Techniques for Atari: Original Adventure in 32K", The Creative Atari (1983).
- Creating Adventure Games On Your Computer: floor plans, vocabulary and the Werewolves and Wanderer and Citadel of Pershu programs.
- On this site: Ram Cram: Squeezing Big Programs into Atari BASIC, Atari BASIC String Handling and Tricks, Converting Microsoft BASIC and Applesoft Listings to Atari BASIC (for porting that book's programs).
Credits
- Picture: The example parser in use: two-word commands, abbreviations, exits worked out from the map, and a polite refusal for an unknown verb. — Program authors; screenshot by the site
- Creating Adventure Games On Your Computer — Chapter 4 (floor plan), Chapter 9 (interpreting commands), compatibility page — AtariArchives.org
- Robert A. Howell, "Ram Cram Techniques for Atari", The Creative Atari — Robert A. Howell; AtariArchives.org
