documentation progress
This commit is contained in:
326
.opencode/skills/kq4-room-documenter/SKILL.md
Normal file
326
.opencode/skills/kq4-room-documenter/SKILL.md
Normal file
@@ -0,0 +1,326 @@
|
||||
---
|
||||
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]`
|
||||
|
||||
**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
|
||||
```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: 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:
|
||||
```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
|
||||
- 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
|
||||
Reference in New Issue
Block a user