# SMIT0370 - FunAdv (Colossal Cave Adventure)

## Overview

This is a VAX/VMS FORTRAN implementation of the classic Colossal Cave Adventure game, maintained by **Charles T. Smith, Jr.** (1989). The code traces its lineage through MIT, Georgia Tech (CDC Cyber systems, ~1975), and was later modified by Neal White III before being ported to VAX/VMS.

## Files

| File | Description |
|------|-------------|
| `FUNADV.FOR` | Main FORTRAN source (~2500 lines) - game engine and database loader |
| `FUNADV.DAT` | Game database (binary, VAX format) - locations, objects, messages, travel table |
| `FUNADV.HEX` | Compiled VAX/VMS executable in hex-encoded format |
| `*.FOR` | Supporting FORTRAN modules (CARRY, DROP, MOVE, SPEAK, etc.) |

## How FUNADV.DAT is Read

### File Opening (FUNADV.FOR lines 380-382)

```fortran
open (Unit=1, err=201,
      file=filedir//'funadv.dat',
      carriagecontrol='none', status='old')
```

The data file is opened as FORTRAN unit 1. The `filedir` path is set by `IMAGE_DIR.FOR`.

### Database Section Structure

The DAT file contains **10 numbered sections**, each terminated by `-1`:

| Section | Purpose | Format | Storage Array |
|---------|---------|--------|---------------|
| 1 | Long location descriptions | `I8, 80A` (int + text) | `LTEXT(220)` |
| 2 | Short location descriptions | `I8, 80A` | `STEXT(220)` |
| 3 | Travel table (movement) | `10I8` (10 integers) | `TRAVEL(1500)`, `KEY(220)` |
| 4 | Vocabulary + object locations | `I8, A10, 2I8` | `KTAB(400)`, `ATAB(400)`, `PLAC(100)`, `FIXD(100)` |
| 5 | Object descriptions | `I8, 80A` | `PTEXT(100)` |
| 6 | Arbitrary messages | `I8, 80A` | `RTEXT(250)` |
| 7 | Action verb defaults | `10I8` | `ACTSPK(35)` |
| 8 | Liquid/condition bits | `10I8` | `COND(220)` |
| 9 | Class messages (scoring) | `I8, 80A` | `CTEXT(12)`, `CVAL(12)` |
| 10 | Hints | `10I8` | `HINTS(20,4)` |
| 0 | End marker | | |

### Reading Logic (lines 397-525)

```
1. Read section number: READ(1,1003) SECT    [FORMAT(I8)]
2. Dispatch via computed GOTO based on section type
3. For text sections (1,2,5,6,9):
   - Read: LOC, TEXT (80 chars), overflow check
   - Store text in LINES(2000) array as linked list
   - Set pointer in section-specific array (LTEXT, STEXT, etc.)
4. For numeric sections (3,7,8,10):
   - Read up to 10 integers per line
   - Process according to section semantics
5. Section 4 (vocabulary) is special:
   - Reads word number, 10-char word, and 2 integers
   - Object words (1000-1999) also store initial location
6. Loop until section 0 encountered
```

### Text Storage Architecture

All game text is stored in `LINES(2000)`, a structure array:

```fortran
STRUCTURE /TEXTYPE/
  Integer*4 count      ! Pointer to next line (negative if first line of message)
  Character*80 string  ! The actual text
END STRUCTURE
```

Section-specific arrays (`LTEXT`, `STEXT`, `PTEXT`, `RTEXT`, `CTEXT`) store indices into `LINES`, forming linked lists for multi-line messages.

### Travel Table Encoding (Section 3)

Each travel entry encodes: `NEWLOC * 1000 + MOTION_VERB`

Destination (`N = NEWLOC MOD 1000`):
- N <= 300: Go to location N
- 300 < N <= 500: Execute special code (N-300)
- N > 500: Print message (N-500), stay in place

Conditions (`M = NEWLOC / 1000`):
- M = 0: Unconditional
- 0 < M < 100: M% probability
- M = 100: Unconditional, but dwarves forbidden
- 100 < M <= 200: Must carry object (M-100)
- 200 < M <= 300: Must carry or be near object (M-200)
- 300 < M <= 400: PROP(M MOD 100) must NOT be 0
- etc.

### Vocabulary Encoding (Section 4)

Word number `N` where `M = N / 1000`:
- M = 0: Motion verb (movement)
- M = 1: Object (with location data following)
- M = 2: Action verb (CARRY, DROP, etc.)
- M = 3: Special verb (index into section 6 messages)

## Game Limits

```
2000 lines of message text
1500 travel options
 400 vocabulary words
 220 locations
 100 objects
  35 action verbs
 250 random messages
  12 player classifications
  20 hints
```

## The HEX File

`FUNADV.HEX` is NOT a hex dump of the data file. It's a **VAX/VMS object file** in hex-encoded record format:

```
<LENGTH><ADDRESS><DATA>
```

Contains:
- Compiled FORTRAN code
- Runtime library references (FORRTL, MTRTL, LIBRTL, PASRTL)
- Embedded string constants (object names, game messages)
- Symbol tables

## Historical Note

The code comments reveal the game's evolution:
- Originally developed at MIT under MULTICS
- Translated to FORTRAN, spread to mainframes and PCs
- Adapted for CDC Cyber at Georgia Tech (~1975) with 10-char words (sixbit)
- Evidence of earlier 5-char-per-word implementation
- Ported to VAX/VMS with CHARACTER type (replacing integer-packed strings)
- Text converted from uppercase to mixed case

## Contact (Historical)

```
Charles T. Smith, Jr.
Internet: cts@dragon.com
U.S. Mail: 2710 Regal Way, Tucker, GA 30084, USA
```