Progress on documentation

rooms/kq4-024-waterfall-and-pool/024-waterfall-and-pool.md

@@ -0,0 +1,67 @@
+# Room 24: Waterfall and Pool
+
+This room features a magnificent waterfall cascading into a deep pool that flows westward as a rushing river. The area is surrounded by dense forest. The room contains the solution to the frog puzzle - players can use the crown here to transform into a frog and access the underwater cave (Room 70). The waterfall also creates a hazard that can sweep players away if they're not careful.
+
+## Look Description
+
+"You see a beautiful waterfall cascading down the mountain into a deep blue pool. From the pool, a river courses westward. Around you, a dense forest closes in."
+
+## Interactions
+
+| Status | Behavior Type | Command | Response |
+|--------|--------------|---------|----------|
+| TODO | Look | `look in falls` | "You can't see through the waterfall." |
+| TODO | Look | `look under pool` / `look under water` / `look under falls` | "You can't make out many details from here." (if not in water) or "You look under the water, but can see nothing." (if in water) |
+| TODO | Look | `look in water` / `look in pool` | "You look into the water, but see nothing of interest." |
+| TODO | Look | `look behind falls` | "You think you see something behind the waterfall, but you're not sure what it is." |
+| TODO | Look | `look falls` | "This is a magnificent waterfall! It tumbles into a deep pool, which then flows westward as a rushing river." |
+| TODO | Look | `look in pool` | "You peer into the pool of water, but cannot see anything of importance." |
+| TODO | Look | `look pool` | "You see a deep pool below the waterfall." |
+| TODO | Look | `look around` / `look room` | "You see a beautiful waterfall cascading down the mountain into a deep blue pool. From the pool, a river courses westward. Around you, a dense forest closes in." |
+| TODO | Action | `enter behind falls` | "The force of the water is too strong for you to be able to do that." |
+| TODO | Action | `bathe under pool` / `bathe under water` / `bathe under falls` / `dive under pool` / `dive under water` / `dive under falls` | "You're not strong enough. The current forces you back!" (if in frog form), "The water isn't deep enough here." (if not in swimming/frog form), "You'd have to be in the water to do that." (otherwise) |
+| TODO | Action | `bathe` / `dive` / `wade` | "Just enter the water." (if on land), "You are already swimming." (if swimming), "You are already in the water." (if in water) |
+| TODO | Inventory | `dennis crown` / `place crown` | Transforms player into frog form if crown is in inventory and player is on land; "Not while you're IN the water." (if in water) |
+
+## Scripts
+
+| Status | Behavior Type | Name | Trigger | Behavior |
+|--------|--------------|------|---------|----------|
+| TODO | Interaction | egoFrogActions | Using `dennis crown` or `place crown` command while on land and having crown in inventory | Plays poof sound effect, creates transformation animation, changes player view to frog (370), enables frog viewer script, moves player to water's edge, hides player, sets `frog_transformation_used = true`, awards 5 points on first use, transports to Room 70 |
+| TODO | Background | frogViewer | Continuous while player is in frog form (`viewer` is set to frogViewer) | Monitors player terrain control - switches view to 371 (shallow water) or 377 (deep water) based on terrain type |
+| TODO | Interaction | swept | Walking near waterfall while in swimming form (view 8) and not already in a script | Player is pushed back by waterfall current, displays message "The force of the water pushes you back." |
+
+## Technical Notes
+
+- **Room Number**: 24
+- **Picture**: 24
+- **Region**: 501, 512, 511, 508 (Forest/Nature regions)
+- **Exits**: North→18, South→30, West→23, East→70 (via frog transformation)
+- **Horizon**: 85 (walkable area boundary)
+- **Sound**: Poof sound effect (59) played during frog transformation
+
+### State Variables
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `is_night` | `true`, `false` | Controls whether night overlay (picture 124) is displayed |
+| `room_visited` | `true`, `false` | Tracks if player has entered this room before |
+| `frog_transformation_used` | `true`, `false` | Set when player transforms into frog; controls access to Room 70 |
+| `transformation_score_awarded` | `true`, `false` | Tracks if 5-point score bonus has been awarded for frog transformation |
+| `firefly_phase` | `0`, `1`, `2` | Controls display of firefly/firefly-like props; phase 2 shows additional animated effects |
+| `in_water` | `true`, `false` | Player state - determined by view (view 8 = swimming, view 2 = normal, view 370/371/377 = frog) |
+| `is_frog_form` | `true`, `false` | Player is in frog transformation form |
+
+### Additional Technical Details
+
+- Room uses Regions 501, 512, 511, and 508 for shared forest/nature logic
+- Synonyms defined: `pool` = `lake`
+- Multiple animated props (views 651, 653) create environmental effects (fireflies/lights)
+- Player entry positioning varies by previous room:
+  - From North: positioned at x=47, just below horizon
+  - From West: positioned at x=1, respects horizon boundary
+  - From South: positioned at y=188, x capped at 214
+  - From East: positioned at (207, 159) with view 8 (swimming)
+- Frog transformation requires crown (inventory item 10)
+- Frog form uses different views for shallow water (371) vs deep water (377)
+- Waterfall hazard triggers when player in swimming form (view 8) touches control area $0010