Progress on documentation

rooms/kq4-021-bridge-over-stream/kq4-021-bridge-over-stream.md

@@ -0,0 +1,64 @@
+# Room 21: Bridge Over Stream
+
+This is a peaceful woodland clearing with a rustic stone bridge crossing a gentle stream. The room serves as a transitional area connecting the meadow (room 20) to the west, the beach/cliffs to the south (room 27), the forest to the east (room 22), and higher ground to the north (room 15). The key feature is the bridge - players can look under it to discover a hidden golden ball. There are animated water/stream elements and the room has multiple region influences.
+
+## Look Description
+
+"A gentle stream meanders its way through the trees. A rustic stone bridge crosses its path."
+
+## Interactions
+
+| Status | Behavior Type | Command | Response |
+|--------|--------------|---------|----------|
+| TODO | Look | `look/room` / `look[<around>]` / `look` | "A gentle stream meanders its way through the trees. A rustic stone bridge crosses its path." |
+| TODO | Look | `look bridge` | "A rustic stone bridge adds a bit of charm to this part of the woods." |
+| TODO | Look | `look under/bridge` (when not in bridge zone) | "You peek under the bridge, but do not see anything of importance from where you're standing." (Print 21 0) |
+| TODO | Look | `look under/bridge` (when in bridge zone) | Triggers script to walk under bridge |
+| TODO | Look | `look under/bridge` (when in water zones) | "You can't do that." (Print 800 1) |
+| TODO | Action | `look under/bridge` (in correct position) | Script triggers: player walks under bridge, kneels, finds golden ball |
+
+## Scripts
+
+| Status | Behavior Type | Name | Trigger | Behavior |
+|--------|--------------|------|---------|----------|
+| TODO | Interaction | egoActions | Player uses `look under/bridge` while in the rectangular zone (120-195 x, 130-139 y) | Player walks under bridge, kneels down, discovers golden ball (if not already taken), picks it up, stands back up and resumes normal form |
+| TODO | Background | newProp | Init (always running) | Animated element (view 657, loop 2) at position 295,118 - likely water/stream animation |
+| TODO | Background | newProp_2 | Init (always running) | Animated element (view 657, loop 1) at position 122,154 - likely water/stream animation |
+| TODO | Background | newProp_3 | Init (always running) | Animated element (view 657, loop 2) at position 13,181 - likely water/stream animation |
+
+## Technical Notes
+
+- **Room Number**: 21
+- **Picture**: 21
+- **Regions**: 507, 501, 512
+- **Exits**: North→15, South→27, East→22, West→20
+- **Horizon**: 68
+
+### State Variables
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `global101` | 0 | Reset to 0 on room entry |
+| `global100` | boolean | Overlay flag - if set, overlay 121 is displayed |
+| `global182` | 0, 1 | Golden ball taken flag - set to 1 when player picks up the golden ball |
+
+### Additional Technical Details
+
+- Room uses setRegions: 507 501 512 (region scripts applied)
+- Player enters in normal form (view 2)
+- When global100 is set, overlay 121 is displayed on top of the base picture
+- Golden ball (inventory item 5) is placed in room at position (164, 129) if owned by room 21
+- The `egoActions` script handles the full sequence of looking under the bridge:
+  1. Player walks to position 141, 133
+  2. Player kneels (view 21, loop 0)
+  3. Player looks under (view 23)
+  4. If golden ball present: ball is disposed, score +2, item moved to ego, message shown
+  5. Player stands back up (view 21, then view 2)
+  6. Viewer is restored if player had one
+- Bridge zones:
+  - Primary bridge zone: 120-195 x, 130-139 y - triggers full sequence
+  - Water zones (cannot look under): 70-254 x, 115-169 y OR 189-318 x, 93-139 y
+- Entry from room 26 (south) has special positioning based on player view and x position
+- Entry from room 22 (east) has special positioning based on player view and y position
+- Entry from room 20 (west) has special positioning based on y position
+- Special exit to room 26 if player is in lower-left corner (x < 20, y > 166)