Progress on documentation

rooms/kq4-058-organ-room/058-organ-room.md

@@ -0,0 +1,88 @@
+# Room 58: Organ Room
+
+A dusty, old pipe organ sits in the center of the tower room. This puzzle room challenges Rosella to play the organ correctly to reveal a hidden drawer containing a skeleton key.
+
+## Look Description
+
+"A dusty, old pipe organ sits in the center of the tower room."
+
+## Interactions
+
+| Status | Behavior Type | Command | Response |
+|--------|--------------|---------|----------|
+| TODO | Look | `look` / `look around` / `look room` / `look tower` | "A dusty, old pipe organ sits in the center of the tower room." (Print 58 0) |
+| TODO | Look | `look down` / `look stair` / `look stairs` | "The tower stairs spiral steeply downward." (Print 58 1) |
+| TODO | Look | `look behind organ` | "There is nothing but dust behind the old organ." (Print 58 2) |
+| TODO | Look | `look in organ` | "You see nothing in the organ." (Print 58 3) |
+| TODO | Look | `look organ` | "Dust and cobwebs cover the old organ." (Print 58 4) |
+| TODO | Look | `look bench` | "There is a bench in front of the old organ." (Print 58 5) |
+| TODO | Look | `look wall` | "There is nothing of importance on the walls." (Print 58 6) |
+| TODO | Look | `look dirt` / `look down` | "There is nothing of interest on the floor." (Print 58 7) |
+| TODO | Look | `look drawer` (drawer found) | "You see a skeleton key in the drawer." (Print 58 8) if key present, "You see an empty drawer." (Print 58 9) if key taken |
+| TODO | Look | `look drawer` (drawer not found) | "What drawer?" (Print 58 10) |
+| TODO | Action | `move bench` | "There's no need to move the bench." (Print 58 11) |
+| TODO | Inventory | `play organ with sheet music` / `use sheet music on organ` | If at organ and has sheet music: "You find it difficult to read the old sheet music, but you attempt it anyway." (Print 58 12) + triggers drawer opening sequence |
+| TODO | Inventory | `play organ with sheet music` / `use sheet music on organ` | If not at organ but has sheet music: "What music?" (Print 58 14) |
+| TODO | Inventory | `play organ with sheet music` / `use sheet music on organ` | If no sheet music: "What music?" (Print 58 13) |
+| TODO | Action | `play organ` / `use organ` / `play music` | If at organ: "You can only remember one 'oldie, but goodie.'" (Print 58 15) |
+| TODO | Action | `play organ` / `use organ` / `play music` | If not at organ: "You're not sitting at the organ." (Print 58 16) |
+| TODO | Action | `sit` / `sit on organ` / `sit on bench` | If already at organ: "You are already." (Print 58 17) |
+| TODO | Action | `sit` / `sit on organ` / `sit on bench` | If in organ area (129-195, 121-126): Triggers sitOrgan script |
+| TODO | Action | `sit` / `sit on organ` / `sit on bench` | If on bench area (122-211, 126-137): "It would be better to move to the inside of the bench." (Print 58 18) |
+| TODO | Action | `stand` / `stand up` / `get up` / `exit organ` / `exit bench` | If at organ: Triggers standOrgan script |
+| TODO | Action | `stand` / `stand up` / `get up` / `exit organ` / `exit bench` | If not at organ: "You are already standing." (Print 58 19) |
+| TODO | Inventory | `get key` / `take key` | If drawer found and key present: "You take the skeleton key from the drawer." (Print 58 20), adds key to inventory, awards 2 points |
+| TODO | Inventory | `get key` / `take key` | If drawer found but key already taken: Trays "proc0_14" (key already taken message) |
+| TODO | Inventory | `get key` / `take key` | If drawer not found: "What key?" (Print 58 21) |
+| TODO | Action | `close drawer` | If drawer found: "There's no need to close the drawer." (Print 58 22) |
+| TODO | Action | `close drawer` | If drawer not found: "You don't see a drawer." (Print 58 23) |
+| TODO | Action | `open drawer` | If drawer found: "The drawer is already open." (Print 58 24) |
+| TODO | Action | `open drawer` | If drawer not found: "You don't see a drawer." (Print 58 23) |
+| TODO | Action | `open bench` | "The bench doesn't open." (Print 58 25) |
+| TODO | Action | `find drawer` / `look for drawer` | If drawer found: "You already found it." (Print 58 26) |
+| TODO | Action | `find drawer` / `look for drawer` | If drawer not found: "Drawer? What drawer?" (Print 58 27) |
+
+## Scripts
+
+| Status | Behavior Type | Name | Trigger | Behavior |
+|--------|--------------|------|---------|----------|
+| TODO | Interaction | playOrgan | Player types `play organ with sheet music` at organ | Plays organ music, and if first time with sheet music, opens hidden drawer in organ, awards 4 points |
+| TODO | Interaction | sitOrgan | Player types `sit` while in organ area (inRect 129-195, 121-126) | Animates Rosella sitting at organ bench, changes ego view to 58 |
+| TODO | Interaction | standOrgan | Player types `stand` while sitting at organ | Animates Rosella standing up from organ, returns to normal view |
+| TODO | Background | fallHole | Player walks into hole (onControl $0004) | Triggers falling animation sequence through hole, leads to room 61 (catacombs), sets global127 to 1 |
+
+## Technical Notes
+
+- **Room Number**: 58
+- **Picture**: 58
+- **Region**: 603 (organ room region)
+- **Exits**: Down spiral stairs (room 61 - leads to catacombs when falling through hole)
+- **Music**: Sound 57 (organ with sheet music), Sound 56 (organ basic), Sound 51 (falling scream), Sound 52 (falling sounds)
+- **Views**: View 58 (sitting at organ), View 42 (landed in catacombs), View 44 (falling animation), View 521 (organ parts)
+
+### State Variables
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `local1` | 0, 1 | Drawer found state - set to 1 when drawer is opened for the first time |
+| `local3` | 0, 1 | Key in drawer - 1 = key still present, 0 = key taken |
+| `global193` | 0, 1+ | Organ played counter - incremented each time organ is played with sheet music |
+| `global182` | 0, 1 | Key taken flag - set to 1 when player takes key from drawer |
+| `global127` | 0, 1 | Fell in hole flag - set to 1 after falling through hole to room 61 |
+
+### Key Mechanics
+
+- The hidden drawer in the organ only opens when Rosella sits at the organ and plays with the sheet music (item 26)
+- The skeleton key (item 20) is in the drawer - awards 2 points when taken
+- Playing the organ with sheet music awards 4 points (first time only, tracked by global193)
+- Walking into the hole in the floor triggers the fallHole script which leads to room 61 (catacombs)
+- The player must be in view 58 (sitting at organ) to properly play the organ
+- The organ area is defined by inRect: 129-195, 121-126
+- The bench area is defined by inRect: 122-211, 126-137
+- Control area $0040 triggers room change to 61 (hole)
+- Control area $0004 triggers falling animation
+
+### Inventory Items
+
+- Item 20 = Skeleton Key
+- Item 26 = Sheet Music