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

name, description

name	description
kq4-room-documenter	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]

Filename: 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

## Look Description

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

4. Interactions Table

## 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

## 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

## 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: Save File

Save to: rooms/kq4-###-human-readable-name.md

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 [DONE](./rooms/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/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:

| `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
• Filename must be: kq4-##-human-readable-name.md (e.g., kq4-024-waterfall-and-pool.md)
• After completing the documentation, update README.md with the room description and link