# King's Quest IV: The Perils of Rosella - Interaction Documentation

A comprehensive documentation of all game interactions extracted from the decompiled SCI (Sierra's Creative Interpreter) source code. This project documents the logic, conditions, state changes, and dependencies for recreating King's Quest IV as a modern point-and-click adventure.

## Repository Structure

```
/
├── rooms/                          # Room-specific interaction documentation
│   ├── kq4-001.md                  # Beach (starting room)
│   ├── kq4-002.md                  # Beach continuation
│   ├── kq4-007.md                  # Fisherman's shack exterior
│   ├── kq4-042.md                  # Fisherman's cottage interior
│   └── ...                         # One file per room
├── KQ4_v1.006.004_int0.000.502_SRC_(6)/
│   └── src/                        # Decompiled SCI scripts
│       ├── Main.sc                 # Game engine & global handlers
│       ├── Game.sc                 # Core game classes
│       ├── Feature.sc              # Object interaction framework
│       ├── InvI.sc                 # Inventory system
│       ├── rm1.sc - rm99.sc        # Room scripts
│       └── *.sc                    # Various utility scripts
└── README.md                       # This file
```

## Source Code Overview

### File Types

- **`.sc` files**: Sierra Script source code (main logic)
- **`.sco` files**: Compiled script object files (not human-readable)
- **`game.sh`**: Header file with game constants and defines

### Key Source Files

| File | Purpose |
|------|---------|
| `Main.sc` | Global game state, inventory, death handlers, sound management |
| `Game.sc` | Core Game class, save/load system, event handling |
| `Feature.sc` | Base classes for interactive objects (Feature, View, Actor) |
| `InvI.sc` | Inventory item definitions and display logic |
| `Class_255_0.sc` | Low-level system procedures and kernel functions |
| `rm##.sc` | Individual room scripts (rooms 1-99) |
| `*Reg.sc` | Region scripts (shared logic for multiple rooms) |

### Room Script Anatomy

Each room script (`rm##.sc`) typically contains:

```
Room## of Rm                    # Room class definition
├── Properties
│   └── picture                 # Background image number
├── Methods
│   ├── init()                  # Room initialization
│   │   ├── north/south/east/west  # Exit directions
│   │   ├── horizon             # Walkable area boundary
│   │   ├── setRegions:         # Apply shared region logic
│   │   ├── Props/Actors/Views  # Interactive objects
│   │   └── gEgo positioning    # Player start position
│   ├── doit()                  # Per-frame logic (rarely used)
│   ├── handleEvent()           # Text parser input handling
│   └── dispose()               # Cleanup when leaving room
└── Instances
    ├── Scripts                 # Multi-step sequences
    ├── Props                   # Animated objects
    ├── Views                   # Static scenery
    └── Sounds                  # Audio effects
```

## Game Systems

### Parser Commands

The original game uses a text parser with verb-noun structure:

- **`Said 'look/grass'`** - Player typed "look at grass"
- **`Said 'use/key'`** - Player typed "use key"
- **`Said 'take/diamond'`** - Player typed "take diamond"
- **`Said '[<around][/room]'`** - "look around" or "look room"

### State Management

Global variables track game state:

| Variable | Purpose |
|----------|---------|
| `gEgo` | Player character object |
| `gRoom` | Current room instance |
| `gPrevRoomNum` | Previous room number |
| `gInv` | Inventory collection |
| `global100` | Unknown flag (weather/time?) |
| `global101` | Room has been visited |
| `global116` | Story progression state |
| `global105` | Multi-path room state |

### Inventory System

Items referenced by index in `gInv at: ##`:

| Index | Item |
|-------|------|
| 1 | Diamonds |
| 17 | Fishing pole |
| ... | (others documented per-room) |

### Message System

Text displayed via `Print scriptNum messageNum`:
- `Print 1 0` = Message 0 from script 1
- Messages stored separately in RESOURCE files
- To be extracted and added to room documentation

### Looking Up Text in the Strings Directory

Message text is extracted and stored in the `strings/` directory:

| File Pattern | Contents |
|--------------|----------|
| `strings/script_XXX_strings.txt` | Script-specific strings (room names, object names) |
| `strings/text_XXX.txt` | In-game dialog and message text |

**To look up a message:**

1. Identify the script number from the `Print` command (e.g., `Print 2 1` = script 2, message 1)
2. Open `strings/text_XXX.txt` where XXX matches the script number
3. Find the entry with the matching message number (e.g., `[0001]`)

**Example:**
```
Print 2 1  →  Look in strings/text_002.txt, line [0001]
Result: "You see a river in the distance to the north."
```

**Note:** Message numbers in the code start from 0 and are displayed in brackets (e.g., `[0001]` = message 1).

## Room Documentation Format

Each room file follows this structure:

```markdown
# Room ##: [Room Name]

## Overview
- **Room Number**: ##
- **Picture**: ###
- **Region**: [Beach/Forest/Castle/etc.]
- **Exits**: North→#, South→#, East→#, West→#

## Objects

### [Object Name]
- **Type**: Prop/View/Actor
- **Position**: (x, y)
- **View**: ### (sprite/animation resource)
- **States**: [list of possible states]

#### Interactions

**Look**:
- Condition: [when visible]
- Text: "Message from game"
- Logic: [simplified state check]

**Use [Item]**:
- Condition: [inventory check]
- Effect: [what happens]
- State Change: [global or local variable changes]

## NPCs

### [Character Name]
- **Type**: Actor
- **Behavior**: [wandering, stationary, scripted]

#### Dialogue
- **Greeting**: [initial interaction]
- **Topics**: [what player can ask about]
- **Conditions**: [when available]

## Scripts

### [Script Name]
- **Trigger**: [what starts it]
- **Steps**: [sequence of actions]
- **State Changes**: [what it modifies]

## Walkthrough Integration

- **Critical Path**: [essential interactions]
- **Optional**: [side content]
- **Deaths**: [ways to die in this room]
```

## Conversion Notes for Point-and-Click

When adapting to a KQ5-style interface (walk, look, hand, talk, inventory):

1. **Walk**: Automated - player clicks destination, character walks there
2. **Look**: Maps to `Said 'look/object'` commands
3. **Hand**: Maps to `Said 'use/object'`, `Said 'take/object'`, `Said 'open/object'`
4. **Talk**: Maps to `Said 'talk/person'` or `Said 'ask/person/about'`
5. **Inventory**: Click item, then click target (replaces `Said 'use/item/on/target'`)

### Simplifications Made

- **Auto-walking**: No manual positioning needed
- **Context-sensitive**: Combine look/take/use based on object type
- **Smart defaults**: Auto-select appropriate verb for known object types
- **Inventory drag**: Drag item to target instead of typing commands

## Message Extraction Status

| Status | Description |
|--------|-------------|
| ⏳ Pending | Text resources not yet extracted from RESOURCE.### files |
| 📝 Documented | Text added to room files |

Text messages referenced as `Print scriptNum messageNum` will be extracted from the game's RESOURCE files and added to each room's documentation.

## Contributing

When adding room documentation:

1. Read the corresponding `rm##.sc` file
2. Document all `handleEvent` interactions
3. Note all Props, Views, and Actors
4. Track state dependencies (global variables)
5. Include original text when available
6. Describe simplified logic for point-and-click adaptation

## Progress

| Room Number | Room Description | Status |
|-------------|------------------|--------|
| 001 | Beach | [DONE](./rooms/kq4-001-beach.md) |
| 002 | Meadow (with Satyr/Pan) | [DONE](./rooms/kq4-002-meadow.md) |
| 003 | Fountain Pool | [DONE](./rooms/kq4-003-fountain-pool.md) |
| 004 | Ogre's Cottage Exterior | [DONE](./rooms/kq4-004-ogres-cottage.md) |
| 005 | Forest Grove | [DONE](./rooms/kq4-005-forest-grove.md) |
| 006 | Cave Entrance | [DONE](./rooms/kq4-006-cave-entrance.md) |
| 007 | Fisherman's Shack Exterior | [DONE](./rooms/kq4-007-fishermans-shack.md) |
| 008 | Back of Fisherman's Shack | [DONE](./rooms/kq4-008-back-of-fishermans-shack.md) |
| 009 | Shady Wooded Area | [DONE](./rooms/kq4-009-shady-wooded-area.md) |
| 010 | Forest Path | [DONE](./rooms/kq4-010-forest-path.md) |
| 011 | Enchanted Grove | [DONE](./rooms/kq4-011-enchanted-grove.md) |
| 012 | Haunted Forest | [DONE](./rooms/kq4-012-haunted-forest.md) |
| 013 | Beach | [DONE](./rooms/kq4-013-beach.md) |
| 014 | Green Meadow | [DONE](./rooms/kq4-014-green-meadow.md) |
| 015 | The Frog Pond | [DONE](./rooms/kq4-015-frog-pond.md) |
| 016 | Graveyard | [DONE](./rooms/kq4-016-graveyard.md) |
| 017 | Spooky House Exterior | [DONE](./rooms/kq4-017-spooky-house-exterior.md) |
| 018 | Cemetery | [DONE](./rooms/kq4-018-cemetery.md) |
| 019 | Coastal Cliffs | [DONE](./rooms/kq4-019-coastal-cliffs.md) |
| 020 | Meadow | [DONE](./rooms/kq4-020-meadow.md) |
| 021 | Bridge Over Stream | [DONE](./rooms/kq4-021-bridge-over-stream.md) |
| 022 | Gnome's Cottage | [DONE](./rooms/kq4-022-gnomes-cottage.md) |
| 023 | Forest Path with Cottage | [DONE](./rooms/kq4-023-forest-path-with-cottage.md) |
| 024 | Waterfall and Pool | [DONE](./rooms/kq4-024-waterfall-and-pool.md) |
| 025 | Beach at River Delta | [DONE](./rooms/kq4-025-beach-at-river-delta.md) |
| 026 | River Meadow | [DONE](./rooms/kq4-026-river-meadow.md) |
| 027 | Forest Path | [DONE](./rooms/kq4-027-forest-path.md) |
| 028 | Mine Entrance | [DONE](./rooms/kq4-028-mine-entrance.md) |
| 029 | Dense Forest | [DONE](./rooms/kq4-029-dense-forest.md) |
| 030 | Mountain Pass | [DONE](./rooms/kq4-030-mountain-pass.md) |
| 031 | Open Ocean | [DONE](./rooms/kq4-031-open-ocean.md) |
| 032 | Ocean Near Island | [DONE](./rooms/kq4-032-ocean-near-island.md) |
| 033 | Enchanted Island Beach | [DONE](./rooms/kq4-033-enchanted-island-beach.md) |
| 034 | Island Beach | [DONE](./rooms/kq4-034-island-beach.md) |
| 035 | Island Beach | [DONE](./rooms/kq4-035-island-beach.md) |
| 036 | Island Garden Pond | [DONE](./rooms/kq4-036-island-garden-pond.md) |
| 037 | Fairy Island | [DONE](./rooms/kq4-037-fairy-island.md) |
| 038 | Island Garden | [DONE](./rooms/kq4-038-island-garden.md) |
| 039 | Island Beach | [DONE](./rooms/kq4-039-island-beach.md) |
| 040 | Island Beach (East) | [DONE](./rooms/kq4-040-island-beach-east.md) |
| 041 | Island Shore | [DONE](./rooms/kq4-041-island-shore.md) |
| 042 | Fisherman's Cottage Interior | [DONE](./rooms/kq4-042-fishermans-shack-inside.md) |
| 043 | Desert Island | [DONE](./rooms/kq4-043-desert-island.md) |
| 044 | Inside Whale | [DONE](./rooms/kq4-044-inside-whale.md) |
| 045 | Genesta's Bed Chamber | [DONE](./rooms/kq4-045-genestas-bed-chamber.md) |
| 046 | Tower Stairway | [DONE](./rooms/kq4-046-tower-stairway.md) |
| 047 | Genesta's Palace Entry Hall | [DONE](./rooms/kq4-047-genestas-palace-entry-hall.md) |
| 048 | Ogre's Bedroom | [DONE](./rooms/kq4-048-ogres-bedroom.md) |
| 049 | Ogre's Cottage | [DONE](./rooms/kq4-049-ogres-cottage.md) |
| 050 | Ogress's Kitchen | [DONE](./rooms/kq4-050-ogress-kitchen.md) |
| 051 | Ogre's Closet | [DONE](./rooms/kq4-051-ogres-closet.md) |
| 052 | | N/A (doesn't exist) |
| 053 | Seven Dwarfs' Bedroom | [DONE](./rooms/kq4-053-seven-dwarfs-bedroom.md) |
| 054 | Seven Dwarfs' Cottage | [DONE](./rooms/kq4-054-seven-dwarfs-cottage.md) |
| 055 | Seven Dwarfs Diamond Mine | [DONE](./rooms/kq4-055-seven-dwarfs-diamond-mine.md) |
| 056 | Seven Dwarfs' Diamond Mine (West) | [DONE](./rooms/kq4-056-seven-dwarfs-diamond-mine-west.md) |
| 057 | Witches' Cave | [DONE](./rooms/kq4-057-witches-cave.md) |
| 058 | Tower Organ Room | [DONE](./rooms/kq4-058-tower-organ-room.md) |
| 059 | Baby Nursery | [DONE](./rooms/kq4-059-baby-nursery.md) |
| 060 | Bedroom | [DONE](./rooms/kq4-060-bedroom.md) |
| 061 | Tower Stairs | [DONE](./rooms/kq4-061-tower-stairs.md) |
| 062 | Bedroom | [DONE](./rooms/kq4-062-bedroom.md) |
| 063 | Attic | [DONE](./rooms/kq4-063-attic.md) |
| 064 | Old Dining Room | [DONE](./rooms/kq4-064-old-dining-room.md) |
| 065 | Old Kitchen | [DONE](./rooms/kq4-065-old-kitchen.md) |
| 066 | Secret Tower | [DONE](./rooms/kq4-066-secret-tower.md) |
| 067 | The Parlor | [DONE](./rooms/kq4-067-the-parlor.md) |
| 068 | The Foyer | [DONE](./rooms/kq4-068-the-foyer.md) |
| 069 | The Crypt | [DONE](./rooms/kq4-069-the-crypt.md) |
| 070 | Waterfall Cave | [DONE](./rooms/kq4-070-waterfall-cave.md) |
| 071 | Cave Entrance | [DONE](./rooms/kq4-071-cave-entrance.md) |
| 072 | Dark Cave Passage | [DONE](./rooms/kq4-072-dark-cave-passage.md) |
| 073 | Cave Exit | [DONE](./rooms/kq4-073-cave-exit.md) |
| 074 | Troll Cave | [DONE](./rooms/kq4-074-troll-cave.md) |
| 075 | Troll Cave Passage | [DONE](./rooms/kq4-075-troll-cave-passage.md) |
| 076 | Dark Chasm | [DONE](./rooms/kq4-076-dark-chasm.md) |
| 077 | Swamp | [DONE](./rooms/kq4-077-swamp.md) |
| 078 | Swamp Island | [DONE](./rooms/kq4-078-swamp-island.md) |
| 079 | Mountain Path to Dark Castle | [DONE](./rooms/kq4-079-mountain-path-to-dark-castle.md) |
| 080 | Lolotte's Castle Entrance | [DONE](./rooms/kq4-080-lolottes-castle-entrance.md) |
| 081 | Edgar's Tower Bedroom | [DONE](./rooms/kq4-081-edgars-tower-bedroom.md) |
| 082 | Lolotte's Tower Bedroom | [DONE](./rooms/kq4-082-lolottes-tower-bedroom.md) |
| 083 | Castle Dungeon Cell | [DONE](./rooms/kq4-083-castle-dungeon-cell.md) |
| 084 | Cottage Front | [DONE](./rooms/kq4-084-cottage-front.md) |
| 085 | Dark Tower Stairs | [DONE](./rooms/kq4-085-dark-tower-stairs.md) |
| 086 | Dim Hallway (West End) | [DONE](./rooms/kq4-086-dim-hallway-west-end.md) |
| 087 | East End of Hallway | [DONE](./rooms/kq4-087-east-end-of-hallway.md) |
| 088 | Stone Tower Stairs | [DONE](./rooms/kq4-088-stone-tower-stairs.md) |
| 089 | Castle Kitchen | [DONE](./rooms/kq4-089-castle-kitchen.md) |
| 090 | West Tower Bottom | [DONE](./rooms/kq4-090-west-tower-bottom.md) |
| 091 | Castle Dining Room | [DONE](./rooms/kq4-091-castle-dining-room.md) |
| 092 | Lolotte's Throne Room | [DONE](./rooms/kq4-092-lolottes-throne-room.md) |
| 093 | Bottom of East Tower | [DONE](./rooms/kq4-093-bottom-of-east-tower.md) |
| 094 | Unicorn Stable | [DONE](./rooms/kq4-094-unicorn-stable.md) |
| 095 | Fisherman's Pier | [DONE](./rooms/kq4-095-fishermans-pier.md) |
| 096 | | N/A (doesn't exist) |
| 097 | | N/A (doesn't exist) |
| 098 | Transitional Room | [DONE](./rooms/kq4-098-transitional-room.md) |
| 099 | Transitional Room | [DONE](./rooms/kq4-099-transitional-room.md) |

## Credits

- **Original Game**: Sierra On-Line (1988)
- **Decompilation**: Unknown decompiler tools
- **Source Code**: King's Quest IV v1.006.004
- **Documentation**: Created for remake project

## License

This documentation is for educational and preservation purposes. King's Quest IV is a trademark of Sierra On-Line/Activision.