documentation progress

rooms/001-beach.md

@@ -0,0 +1,239 @@
+# Room 001: Beach (Starting Area)
+
+## Overview
+- **Room Number**: 1
+- **Script**: `rm1.sc`
+- **Picture**: 1 (with overlay 101 if `global100` is set)
+- **Region**: Beach
+- **Regions Applied**: 503 (BeachReg), 501, 504, 506
+
+### Exits
+- **North**: Room 25
+- **South**: Room 7 (Fisherman's shack exterior)
+- **East**: Room 2
+- **West**: Room 31
+- **Horizon**: 100 (player cannot walk above this Y coordinate)
+
+### State Dependencies
+- `global105`: Controls dolphin riding state and player positioning
+  - `0`: Normal beach access from various rooms
+  - `1-4`: Different horizontal positions when entering from north/south
+  - `14`: Dolphin ride arrival (special entrance)
+- `global100`: If set, overlays picture 101 (alternate weather/time?)
+- `global205`: Cleared when dolphin ride completes
+
+## Visual Elements
+
+### Animated Waves (Background Effects)
+Three animated wave Props cycle continuously using `waveActions` script.
+
+#### wave1
+- **Type**: Prop
+- **Position**: (203, 75)
+- **View**: 665
+- **Loop**: 0
+- **Animation**: Cycles through frames, then hides, cycles next wave
+- **Priority**: 0 (background layer)
+- **Behavior**: Creates continuous wave animation effect
+
+#### wave2
+- **Type**: Prop
+- **Position**: (191, 115)
+- **View**: 665
+- **Loop**: 1
+- **Animation**: Cycles through frames
+- **Priority**: 0
+
+#### wave3
+- **Type**: Prop
+- **Position**: (191, 188)
+- **View**: 665
+- **Loop**: 2
+- **Animation**: Cycles through frames
+- **Priority**: 0
+
+### Sea Spray / Mist
+- **Type**: Prop (`newProp`)
+- **Position**: (69, 61)
+- **View**: 650
+- **Loop**: 1
+- **Cel**: 1
+- **Animation**: Forward cycle (continuous)
+- **Purpose**: Ambient atmospheric effect
+
+## Player Positioning Logic
+
+The room uses complex positioning based on `global105` state and `gPrevRoomNum`:
+
+### Default State (global105 = 0)
+- **From South (Room 7)**: 
+  - If x > 128: Position at (300, 187)
+  - Else: Position at (225, 187)
+- **From North (Room 25)**: Position at x=225, y=horizon+yStep+1
+- **New Game (Room 0)**: Position at (220, 135)
+- **From East (Room 2)**:
+  - If y ≤ horizon: x=318, y=horizon+yStep+1
+  - Else: x=318, keep current y
+
+### Dolphin State (global105 = 14)
+- Special arrival from dolphin ride
+- Sets `global205 = 0`
+- Changes player view to 312 (dolphin riding animation)
+- Initiates `rideDolphin` script
+
+## Interactions
+
+### Look Commands (Parser)
+
+#### Look at grass
+- **Command**: `look grass` / `look at grass`
+- **Text**: `Print 1 0` (message resource pending extraction)
+- **Logic**: Direct text display, no conditions
+
+#### Look at brook
+- **Command**: `look brook` / `look at brook`
+- **Text**: `Print 1 1` (message resource pending extraction)
+- **Logic**: Direct text display, no conditions
+
+#### Look around room
+- **Command**: `look` / `look around` / `look room`
+- **Text**: `Print 1 2` (message resource pending extraction)
+- **Logic**: General room description
+
+### Region-Based Interactions (via BeachReg - Script 503)
+
+The following interactions are inherited from the BeachReg region:
+
+#### Look at ocean/water
+- **Command**: `look ocean` / `look water`
+- **Conditions**: 
+  - If `gEgo view != 2` (not swimming): Shows one message
+  - If `gEgo view == 2` (swimming): Shows different message
+- **Text**: `Print 503 2` or context-specific messages
+
+#### Look at fish
+- **Command**: `look fish`
+- **Conditions**: 
+  - If player has item 24 (fish in inventory): Shows fish item
+  - Else: Shows default message
+- **Text**: `Print 503 3` or item display
+
+#### Drink water
+- **Command**: `drink` / `get drink`
+- **Conditions**:
+  - Must be in swim view (view 2)
+  - Must be near water (control color check)
+- **Effect**: Plays drinking animation (view 21)
+- **Script**: `drinking` - 4-state animation sequence
+
+#### Bathe/Dive/Wade in ocean
+- **Command**: `bathe ocean` / `dive ocean` / `wade ocean`
+- **Conditions**:
+  - Only available when `global105 == 4` (dolphin accessible)
+- **Response**: Context-aware messaging
+
+## Scripts
+
+### rideDolphin
+**Purpose**: Handles player arrival via dolphin ride
+
+**Trigger**: `global105 == 14` on room entry
+
+**Sequence**:
+1. State 1: Disable input (`proc0_8`), move player to (66, 136)
+2. State 2: 
+   - Create dolphin Actor
+   - Set `global105 = 4`
+   - Restore player viewer
+   - Position dolphin at player position minus 5 pixels Y
+   - Set dolphin view 311, loop 2
+   - Wait 4 seconds
+3. State 3:
+   - Accelerate dolphin (xStep 4, yStep 3)
+   - Change to loop 5
+   - Move dolphin off-screen to (-10, 100)
+   - Re-enable input (`proc0_9`)
+   - Clear `global205`
+4. State 4:
+   - Dispose dolphin Actor
+   - Clear player script
+
+**State Changes**:
+- Sets `global105 = 4`
+- Clears `global205 = 0`
+
+### waveActions
+**Purpose**: Manages continuous wave animation cycle
+
+**Sequence**:
+1. State 0: Initialize - Create static wave Views from wave Prop positions, add to picture
+2. State 1: Show next wave Prop, animate to end
+3. State 2: Hide wave, advance to next wave in list, loop back to State 1
+
+**Behavior**: Infinite loop cycling through wave1 → wave2 → wave3 → wave1...
+
+## Point-and-Click Adaptation Notes
+
+### Automated Behaviors
+- **Walking**: Player clicks anywhere on walkable area, character auto-walks
+- **Horizon**: Enforced automatically; player cannot walk above y=100
+- **Exits**: Walking off screen edges transitions to connected rooms
+
+### Cursor Mappings
+
+| Original Command | Point-and-Click Equivalent |
+|------------------|---------------------------|
+| `look grass` | Eye cursor on grass patch |
+| `look brook` | Eye cursor on water/brook area |
+| `look around` | Eye cursor on background/scenery |
+| `drink water` | Hand cursor on water (when near) |
+| `bathe ocean` | Hand cursor on ocean (when dolphin available) |
+
+### Context-Sensitive Actions
+- **Dolphin interaction**: Only show "ride" cursor when `global105 == 4`
+- **Swim view**: Automatically switch to swimming animation (view 2) when entering water
+
+### Visual Feedback
+- Waves animate continuously (no player interaction needed)
+- Sea spray provides ambient movement
+- Dolphin arrival is a scripted sequence (no player input during animation)
+
+## Unresolved Questions
+
+1. What is `global100`? (Appears to be weather or time of day flag)
+2. What are regions 501, 504, 506? (Need to examine those scripts)
+3. What do messages 1 0, 1 1, 1 2 say? (Need text resource extraction)
+4. What triggers `global105 = 14` state? (Dolphin ride must be initiated elsewhere)
+
+## Dependencies
+
+### Global Variables Used
+- `global100`: Weather/time flag
+- `global101`: Room visited flag (set to 0)
+- `global105`: Beach state / dolphin access
+- `global205`: Cleared on dolphin arrival
+
+### Inventory Items Referenced
+- Item 17: Fishing pole (via region)
+- Item 24: Fish (via region)
+
+### Views Referenced
+- View 311: Dolphin animation
+- View 312: Player on dolphin
+- View 665: Wave animations
+- View 650: Sea spray
+
+### Rooms Connected
+- North: 25
+- South: 7  
+- East: 2
+- West: 31
+
+## Critical Path Notes
+
+This room is part of the starting beach area. It serves as:
+1. **Entry point** from various directions
+2. **Dolphin transportation hub** (when `global105 == 4`)
+3. **Transition zone** between beach, forest, and fisherman's shack
+
+The dolphin ride appears to be a significant transportation mechanic connecting distant areas of the game.