SMART EGG Engine

Technical analysis of the text adventure engine: compression, memory layout, parser, and Part 2 overlay architecture.

Engine Overview

The SMART EGG engine is a reusable, data-driven text adventure system for the Commodore 64. It was built by Said Hassan of Smart Egg Software and supports a complete adventure game infrastructure: a command parser, inventory system, room navigation, scoring, save/load, colored text output, and a sophisticated three-tier text compression scheme.

Evidence that this was a product, not a one-off:

• Clean separation between engine code and game data, in well-defined memory regions
• Part 2 works as a pure data overlay, reusing Part 1's engine at the exact same addresses
• Standard adventure infrastructure (parser, inventory, scoring, save/load) that is not game-specific
• Cross-platform release (C64 and ZX Spectrum) confirming an abstraction layer between engine and data

Memory Layout (C64, 64KB)

Text Compression Pipeline

Every compressed byte is processed by the handler at $880E. The pipeline works in three stages:

Raw text bytes
      |
      v
  EOR #$FF (XOR with $FF, invert all bits)
      |
      v
  Range check inverted value:
      |
      +-- $01-$5F: SINGLE CHARACTER
      |      Index into 96-entry character table at $8604
      |      Maps to PETSCII codes (A-Z, a-z, digits, symbols, colors)
      |
      +-- $60-$EF: DIGRAM (character pair)
      |      Subtract $60, lookup in 12x12 grid
      |      Grid uses 12 most frequent chars: SPACE,E,A,I,S,R,T,N,O,L,D,C
      |      Two characters emitted per byte (2:1 compression)
      |
      +-- $F0-$FF: DICTIONARY WORD
      |      One of 16 common words (WERE,WAS,WITH,AND,AS,THE,THAT,TO,
      |      FOR,OF,IN,HARPER,NORTH,SOUTH,EAST,WEST)
      |      Multi-character expansion per byte
      |
      +-- $FF (original $00): TERMINATOR
             End of text block

How It Works in 6502

$880E: LDA ($40),Y     ; load compressed byte from pointer at $40/$41
$8810: INC $41          ; increment source pointer
$8812: BNE +2
$8814: INC $42
$881F: EOR #$FF         ; XOR with $FF (invert all bits)
$8821: BEQ done         ; if zero (was $FF), text ends
$8823: CMP #$60         ; compare with $60
$8825: BCC single_char  ; below $60? single character
$8827: CMP #$F0         ; compare with $F0
$8829: BCS dictionary   ; $F0 or above? dictionary word
       ; else: digram ($60-$EF)

Compression Tables

Character Table (96 entries at $8604)

Maps compression indices ($01-$5F) to PETSCII codes. The table includes uppercase and lowercase letters, digits, punctuation, spaces, and PETSCII control codes for color changes (white, cyan, yellow, green, purple, pink). The ordering is optimized by frequency for the digram encoding.

Digram Characters (12 entries at $86CC)

The 12 most frequent characters, used to build the 12x12 digram grid (144 two-character pairs):

Dictionary Words (16 entries at $8684)

The presence of HARPER and the four compass directions alongside THE and AND proves that frequency analysis was run against this specific game's text, not a generic English corpus.

Parser Architecture

Input Buffer ($0200)
      |
      v
  Tokenizer
  - Strips leading spaces
  - Identifies verb (first word)
  - Identifies noun/object (remaining words)
      |
      v
  Verb Lookup
  - Searches verb table for match
  - Returns verb handler address
      |
      v
  Noun Resolution
  - Searches object table for match
  - Checks visibility (in room or inventory)
  - Returns object ID
      |
      v
  Action Dispatch
  - Calls verb handler with object
  - Handler checks preconditions
  - Modifies game state
  - Triggers text output
      |
      v
  Room Update
  - Checks for state changes
  - Runs room-specific event handlers
  - Updates score if applicable
  - Displays room description if moved

Vocabulary Structure

The vocabulary table at $7E04 uses a 5-byte record format where each byte is a compressed SMART EGG text byte. The 5th byte is a token/category ID. Words are truncated to 4 characters for matching, consistent with the common text adventure convention (e.g., "EXAM" matches both "EXAMINE" and "EXAMINATION").

The table contains roughly 200 vocabulary entries covering movement verbs, object interaction verbs, examination verbs, physical action verbs, system commands, and special keywords.

Part 2 Overlay Architecture

Part 1 loads completely:
  Engine code ($8604-$9BFC)  +  Game data ($0800-$7982)

Part 2 is a DATA OVERLAY:
  - Same engine code preserved in memory
  - New game data overlaid onto $0800-$7982
  - New text blocks in $2D00-$5000
  - New object table at $2D00-$2FA0
  - New pointer tables
  - Title screen: "LOAD YOUR DATA FROM PART I"

What the Overlay Preserves

Key finding: Part 1 and Part 2 use completely different compression tables. All 96 character table entries differ, all 12 digram characters differ, and 71 of 72 dictionary bytes differ. The SMART EGG compiler regenerates optimal tables for each part based on text content.

Key Code Addresses

Game Data Header ($0800)