kq4-decompile/.opencode/skills/kq4-room-documenter/SKILL.md

---
name: kq4-room-documenter
description: Generate comprehensive documentation for King's Quest IV rooms from decompiled SCI source code. Creates formatted markdown files following a standardized template with high-level summaries, look descriptions, interactions tables, scripts tables, and technical notes.
---

# KQ4 Room Documenter

Generate comprehensive documentation for King's Quest IV rooms from decompiled SCI source code.

## When to Use

Use this skill when:
- Documenting a new room from the KQ4 decompiled source
- Converting rm##.sc files to human-readable documentation
- Extracting interactions, scripts, and game logic from Sierra Script files
- Creating standardized room documentation for the remake project

## Default Configuration

**Model Provider**: Local  
**Model**: MiniMax-M2.5

## Documentation Format

Generate documentation following this exact structure:

### 1. Header
Format: `# Room ##: [Room Name]`

**Directory**: `rooms/kq4-##-human-readable-name/`
**Filename inside directory**: `kq4-##-human-readable-name.md`

### 2. High-Level Summary
A paragraph describing the room's purpose, key features, NPCs, and gameplay significance.

### 3. Look Description Section
```markdown
## Look Description

"[The room's primary description text when player looks around]"
```

### 4. Interactions Table
```markdown
## Interactions

| Status | Behavior Type | Command | Response |
|--------|--------------|---------|----------|
| Documented | [Look/Get/Action/Talk/Inventory] | `[command]` | "[Response text]" |
```

**Status Options:**
- `Documented` - Interaction fully documented with response text
- `Partial` - Interaction exists but response text not extracted
- `Unverified` - Interaction referenced but not confirmed in code

**Behavior Types:**
- `Look` - Visual examination commands (look, examine)
- `Get` - Item acquisition attempts (take, get, pick up)
- `Action` - Physical interactions (open, close, use, climb, kill, etc.)
- `Talk` - Dialogue commands (talk, ask, tell)
- `Inventory` - Item usage commands (use, give, deliver)

**Command Format:**
- Use backticks around commands
- Show alternative phrasings with `/` separator
- Include optional words in brackets: `[<around>]`
- Show synonyms where applicable
- Document unusual/unexpected command words (e.g., `dennis crown` instead of `use crown`)

**Response Format:**
- Include full text in quotes
- Reference message file: `(Print ## #)`

### 5. Scripts Table
```markdown
## Scripts

| Status | Behavior Type | Name | Trigger | Behavior |
|--------|--------------|------|---------|----------|
| Documented | [Interaction/Background] | [ScriptName] | [Trigger condition] | [Behavior description] |
```

**Behavior Types:**
- `Interaction` - Player-triggered scripts (entry, exits, dialogue, cutscenes)
- `Background` - Automatic/continuous scripts (animations, AI, environmental effects)

**Name:** The script class name from source (e.g., `SendOut`, `Tripped`, `Watch`)

**Trigger:** When the script activates (e.g., "Entering room when `dwarf_state = DWARF_STATE.HOSTILE`")

**Behavior:** What the script does, described clearly

### 6. Technical Notes Section
```markdown
## Technical Notes

- **Room Number**: ##
- **Picture**: ###
- **Region**: ### ([Region Name]) - if applicable
- **Exits**: [Direction→Room, ...]
- **Music**: [Sound number/name] - if applicable

### State Variables

| Variable | Values | Description |
|----------|--------|-------------|
| `[variable_name]` | `[values]` | [Description] |
```

**Variable Naming:**
- Convert `global###` to descriptive names
- Use enums where applicable: `dwarf_state = DWARF_STATE.FRIENDLY`
- Use boolean names: `diamonds_visible`, `room_visited`

### Additional Technical Details

- List synonyms defined in room: `[word] = [synonym]`
- List region synonyms if applicable
- Note special mechanics or behaviors
- Document entry points and conditions
- List all applied regions when multiple exist: `setRegions: ### ### ###`
- Document inventory item requirements: `(gEgo has: ##)` → map to item names
- Document view-based state detection (see Player State Patterns below)

## Workflow

### Step 1: Locate Source Files

1. Find the room script: `KQ4_v1.006.004_int0.000.502_SRC_(6)/src/rm##.sc`
2. Find the text file: `strings/text_###.txt`
3. Find the region script if applicable: `KQ4_v1.006.004_int0.000.502_SRC_(6)/src/rg###.sc`

### Step 2: Read Source Files

1. Read the room script to understand:
   - Room properties (picture, style, exits)
   - Init method (objects, NPCs, initial state)
   - HandleEvent method (interactions)
   - Scripts (instances of Script class)
   - State variables and conditions

2. Read the text file to extract:
   - Message text referenced by `Print` commands
   - Index numbers correspond to second parameter of Print

3. Read region script if room uses `setRegions:` to understand:
   - Shared interactions
   - Shared state
   - Additional commands

### Step 3: Extract Interactions

From `handleEvent` method:

1. Identify all `Said` patterns
2. Map them to corresponding `Print` commands
3. Look up message text in strings/text_###.txt
4. Categorize by behavior type (Look, Get, Action, Talk, Inventory)
5. Format commands with proper syntax showing alternatives

### Step 4: Extract Scripts

From Script instances:

1. Identify each Script class instance
2. Determine if Interaction or Background type
3. Document trigger conditions
4. Describe behavior in detail
5. Note any state changes

### Step 5: Identify State Variables

From local variables and global references:

1. Convert `global###` to descriptive names
2. Identify boolean flags
3. Identify enum states
4. Document their purpose and values

### Step 6: Write Documentation

Follow the format exactly:
1. Header with room name
2. High-level summary
3. Look description
4. Interactions table
5. Scripts table
6. Technical notes with state variables

### Step 7: Generate Visual PNG

After saving the documentation, generate the room visual:
1. Run: `./sci_pic_render <room_number> "<path_to_game>" rooms/kq4-###-human-readable-name/`
2. This creates three PNG files:
   - `pic_###_visual.png` - Background visual
   - `pic_###_control.png` - Control (walkable areas)
   - `pic_###_priority.png` - Priority (z-ordering)
3. Move the markdown file into the room directory: `mv rooms/kq4-###-human-readable-name.md rooms/kq4-###-human-readable-name/`

### Step 8: Update README.md

After saving the room documentation:
1. Read the current README.md to find the Progress section
2. Find the row for this room number
3. Update the Status to include embedded PNG and link:
   - With PNG: `![pic_###_visual.png](./rooms/kq4-###-human-readable-name/pic_###_visual.png) [DONE](./rooms/kq4-###-human-readable-name/kq4-###-human-readable-name.md)`
   - Without PNG (if render fails): `[DONE](./rooms/kq4-###-human-readable-name/kq4-###-human-readable-name.md)`
4. Fill in the Room Description with a human-readable name (e.g., "Beach", "Fountain Pool", "Cave Entrance")

## Example Reference

See `rooms/kq4-055-seven-dwarfs-diamond-mine/kq4-055-seven-dwarfs-diamond-mine.md` for a complete example following this format.

## Command Reference

### SCI Script Patterns

**Room Definition:**
```
(instance Room## of Rm
    (properties
        picture ##
        style $0010
        east ##
        ...
    )
```

**Edge Behavior:**
- `(gEgo edgeHit: 0)` - Reset edge detection
- `(= horizon ##)` - Set walkable area boundary
- Entry positioning uses `switch gPrevRoomNum` with cases for each direction

**HandleEvent Pattern:**
```
(method (handleEvent pEvent)
    (cond 
        ((Said 'look>')
            (cond 
                ((Said '/object') (Print ## #))
                ...
            )
        )
    )
)
```

**Script Pattern:**
```
(instance ScriptName of Script
    (method (changeState newState)
        (switch (= state newState)
            (0 ...)
            (1 ...)
        )
    )
)
```

**State Checks:**
- `(if global### ...)` - Boolean flag check
- `(if (== global### #) ...)` - Equality check (use for enums)
- `(if (> (gEgo x?) ###) ...)` - Position check

### Text File Format

Text files use format: `[####] Message text`
- Index corresponds to second parameter of Print command
- Print 55 2 → Look for [0002] in strings/text_055.txt

### Player State Patterns

Player form/state is often determined by view number:
- `view: 2` - Normal form (on land)
- `view: 8` - Swimming form
- `view: 370, 371, 377` - Frog transformation forms
- `view: 44` - Falling/tripping
- Check current view: `(gEgo view?)` in conditions

Document state variables like:
```markdown
| `is_frog_form` | `true`, `false` | Player is in frog transformation (views 370-377) |
| `in_water` | `true`, `false` | Player is swimming (view 8) or in water |
```

### Inventory Item Reference

Items referenced by index in `gEgo has: ##` or `gInv has: ##`:
- `10` - Crown
- `17` - Fishing pole
- Map other numbers to item names when identified

### Control Areas

Walkable/control areas use hex bitmasks:
- `$0010` - Control area (e.g., waterfall zone)
- `$0001` - Terrain type (e.g., shallow water)
- `(gEgo onControl: 0)` - Check control under player
- `(gEgo onControl: 1)` - Check control at player's feet

### Score Tracking

Score changes use: `(gGame changeScore: ##)`
- Always paired with a flag to prevent re-awarding
- Example: `(if (== global200 0) (gGame changeScore: 5) (= global200 1))`
- Document as: `transformation_score_awarded` flag

### Viewer System

Background player scripts use the viewer system:
- Set viewer: `(gEgo viewer: ScriptName)`
- Remove viewer: `(gEgo viewer: 0)`
- Runs continuously (like a Background script on the player)
- Example: `frogViewer` monitors terrain and changes view accordingly
- Viewer doit method typically checks `(gEgo onControl: 1)` to determine terrain
- Switch views based on terrain: `(gEgo view: 371)` for shallow, `(gEgo view: 377)` for deep

### Multiple Regions

Rooms can apply multiple region scripts:
```
(self setRegions: 501 512 511 508)
```
Document all applied regions and check each for additional interactions.

## Output Requirements

- Use descriptive Status values: "Documented", "Partial", or "Unverified" (NOT "TODO")
- Use clear, descriptive variable names
- Include full message text in quotes
- Organize interactions logically by type
- Be thorough but concise in descriptions
- Create directory: `rooms/kq4-##-human-readable-name/`
- Save markdown as: `rooms/kq4-##-human-readable-name/kq4-##-human-readable-name.md`
- Generate PNGs using sci_pic_render into the room directory
- After completing the documentation, update README.md with the room description, embedded PNG thumbnail, and link