Progress on documentation

rooms/kq4-015-frog-pond/kq4-015-frog-pond.md

@@ -0,0 +1,93 @@
+# Room 15: The Frog Pond
+
+Room 15 is the Frog Pond, a tranquil woodland pond where Rosella encounters the famous fairy tale frog. The room features a pond with lily pads where a large frog wearing a golden crown resides. This room is central to the Frog Prince questline - the player can interact with the frog using the golden ball (item 5) to earn its trust, then kiss it to transform it into a prince (item 10 - crown). The transformation sequence awards score points and provides the crown needed for the witch's potion in the endgame.
+
+## Look Description
+
+"Atop one of the bigger lily pads, you notice a rather large frog...wearing a little gold crown!"
+
+## Interactions
+
+| Status | Behavior Type | Command | Response |
+|--------|--------------|---------|----------|
+| TODO | Look | `look` / `look around` / `look/room` | "Atop one of the bigger lily pads, you notice a rather large frog...wearing a little gold crown!" (Print 15 19) |
+| TODO | Look | `look/lake` / `look/water` | Dynamic text: "This is a very pretty little pond. Floating upon it are many beautiful water lilies. %s" with frog description if frog present (Print 15 11) |
+| TODO | Look | `look/frog` | Different responses based on frog state: "The large frog stares back at you with big bulging eyes." (global110=0 or 3), "The water is too murky to see anything." (global110=1), "The frog appears to be retrieving your gold ball." (global110=2), "The frog sits calmly in the palm of your hand. Its big eyes stare into yours. A little gold crown rests upon its head." (global110=4) (Print 15 6-10) |
+| TODO | Look | `look/lilies` / `look/pad` | Dynamic text: "Many water lilies float upon this little pond. %s" with frog description if frog present (Print 15 16) |
+| TODO | Look | `look/crown` | If frog in hand (global110=4): "It's a nice little gold crown." (Print 15 17), otherwise shows crown from inventory (Print 800 1) |
+| TODO | Look | `look/dirt` / `look/down` | Various responses based on ball location and frog state: "The frog is sitting with the gold ball at the east edge of the pond." (ball present, frog present), "Your golden ball is lying by the east edge of the pond." (ball present), "The frog is sitting on the ground near the edge of the pond." (frog present), "There is nothing of interest on the ground." (default) (Print 15 12-15) |
+| TODO | Look | `look/blossom` | "You see flowers here and there." (Print 15 18) |
+| TODO | Look | `look/under` / `look/in/water` | "The water is too murky to see anything." (Print 15 7) |
+| TODO | Look | `look/prince` | If transformed (global110=5): "This prince may be handsome, but he's also obnoxiously conceited." (Print 15 0), otherwise "You can't see a prince here." (Print 15 4) |
+| TODO | Get | `get/frog` / `capture/frog` | Various responses: can't see (global110=4), too far (global110=1), not here (global110=5), no frog (global110≠3), not while in pond (view=6), success if close enough with ball: "Squinching up your nose in disgust, you catch the large frog and hold it in your hand. It stares at you with its big bulgy eyes, and wobbles its throat." (Print 15 25-30) |
+| TODO | Get | `get/ball` | Must be in normal form (view=2). If already have ball (global110=7): pick up. If ball in room ((Inv at: 5) ownedBy: 15): if close enough, pick up; else "You're not close enough." (Print 800 1). If don't have ball: "You don't see one here." (Print 15 43) |
+| TODO | Get | `get/crown` | If already have crown: "You don't have it." (Print 800 0). If frog in hand (global110=4): take crown, transform frog to prince, award 2 points, set global110=6, trigger frogActions state 70 (Print 15 46) |
+| TODO | Get | `get/blossom` / `get/flower` | "It would waste your precious time to stop and pick flowers." (Print 15 20) |
+| TODO | Get | `get/lilies` / `get/pad` | "You have no need for a lily pad." (Print 15 33) |
+| TODO | Get | `get/drink` / `drink/water` | If in normal form and near water: trigger drinking script (Print 15 24). If in water (view=6): "Well, it's not wonderful, but it satisfies your thirst." (Print 15 23). Else: "You can't do that now." (Print 15 24) |
+| TODO | Talk | `converse/frog` / `talk/frog` | If frog present or in hand (global110=0,3,4): "Ribbit! Ribbit!" (Print 15 32), then "Well, what else did you expect from a frog?" (Print 15 33). Otherwise: "Well, what else did you expect from a frog?" (Print 15 34) |
+| TODO | Talk | `converse/prince` / `talk/prince` | If transformed (global110=5) and prince present: "The prince does not answer you." (Print 15 1). Otherwise: "You can't see a prince here." (Print 15 4) |
+| TODO | Inventory | `use/ball` / `fling/ball` / `drop/ball` / `place/ball` / `deliver/ball` | Must have ball (item 5). If frog present (global110=0): If have crown ((Inv at: 10) ownedBy: 200) and near water: frog dives and retrieves ball, set global110=2, trigger frogActions state 3; else "Try another spot." (Print 15 36); If no crown: "There's no one nearby." (Print 15 37). If not in normal form: "That's not necessary any more." (Print 15 38). Else: "Not here." (Print 15 39). If no ball: "Not now." (Print 15 40) |
+| TODO | Inventory | `deliver/[item]` | If prince present: "He is not interested." (Print 15 45). Otherwise: "There's no one here to give anything to." (Print 15 46) |
+| TODO | Action | `kiss/frog` / `kiss` | If frog in hand (global110=4): "You look at the frog's green lips. Mmmmm. Good. You feel silly doing this, as you slowly put your mouth against the frog's." (Print 15 41), trigger frogActions state 50, set global110=5, award 3 points. Otherwise: "You can't do that now." (Print 15 42) |
+| TODO | Action | `fish` / `enter/fish` / `capture/fish` / `cast/pole` | "You can't see any fish here." (Print 15 5) |
+| TODO | Action | `bathe` / `dive` | "The water is too shallow." (Print 15 21) |
+| TODO | Action | `wade` | "Just do that yourself." (Print 15 22) |
+| TODO | Get | `get/prince` | If transformed (global110=5): "You couldn't get the prince." (Print 15 2) |
+| TODO | Action | `kiss/prince` | If transformed: "He's too conceited. You wouldn't want to." (Print 15 3) |
+
+## Scripts
+
+| Status | Behavior Type | Name | Trigger | Behavior |
+|--------|--------------|------|---------|----------|
+| TODO | Interaction | frogActions | Player enters water area (onControl=512) while frog visible (global110=0) | Frog jumps away from player, sets global110=1 |
+| TODO | Interaction | frogActions | Player uses ball near frog (global110=0, has crown, in normal form) | Frog dives and retrieves ball, returns to lily pad, sets global110=2 |
+| TODO | Interaction | frogActions | Player catches frog (global110=3, has ball, close enough) | Frog is captured, player holds frog in hand, sets global110=4, shows frog in hand view |
+| TODO | Interaction | frogActions | Player kisses frog while holding (global110=4) | Transformation sequence: poof effect, frog becomes prince (view 225), awards 3 points, prince dialogue, prince leaves and tosses crown to player |
+| TODO | Interaction | frogActions | Player takes crown from frog in hand (global110=4) | Crown removed, frog transforms to prince (view 378), prince walks away, awards 2 points |
+| TODO | Interaction | frogActions | Player moves while holding frog (global110=4, movement detected) | Frog escapes back to pond, resets to wild state (global110=7 → 3) |
+| TODO | Interaction | ballActions | Player picks up golden ball from ground ((Inv at: 5) ownedBy: 15) | Ball picked up, if frog present (global110=3 or 4), frog returns to pond |
+| TODO | Interaction | drinking | Player drinks from pond (get/drink command) | Player bends down to drink, animation plays for 5 seconds, restores thirst |
+
+## Technical Notes
+
+- **Room Number**: 15
+- **Picture**: 15 (overlay 115 if `global100` is set)
+- **Region**: 507 (Frog Pond region)
+- **Exits**: North→9, South→21, East→16, West→14
+- **Horizon**: 75
+- **Music**: Sound 28 (frogTheme) plays when frog appears
+
+### State Variables
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `global100` | `0`, `non-zero` | If set, overlays picture 115 (alternate view with different lily pad) |
+| `global101` | `0` | Room initialization flag (set to 0) |
+| `global105` | `0`, `2` | Player terrain state: 0 = on land (view 2), 2 = in water (view 6) |
+| `global110` | `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7` | Frog transformation state: 0 = frog with crown on lily pad, 1 = frog fled from player, 2 = frog retrieved ball, 3 = frog in pond (capturable), 4 = frog in player's hand, 5 = transformed to prince, 6 = crown taken from frog, 7 = ball taken from frog |
+| `global182` | `0`, `1` | Crown obtained flag (set to 1 after receiving/taking crown) |
+| `local0` | Number | Current onControl value for terrain detection |
+| `local1` | Number | Previous onControl value for terrain change detection |
+| `newAct` | Actor | The frog/prince actor instance |
+| `newView` | View | The golden ball view (when on ground in room 15) |
+
+### Additional Technical Details
+
+- Synonyms: `lake` = `lake`, `prince` = `prince` = `man`
+- Room uses Region 507 for pond interactions
+- Frog appears on lily pad when player has crown (item 10 owned by room 15) in inventory
+- Golden ball (item 5) appears at east edge of pond when owned by room 15
+- Frog behavior changes based on global110 state:
+  - State 0: Visible on lily pad with crown
+  - State 1: Jumped away from player into water
+  - State 2: Has retrieved ball, waiting on lily pad
+  - State 3: In water, can be captured with ball
+  - State 4: In player's hand (can kiss or take crown)
+  - State 5: Transformed to prince (interactive)
+  - State 6: Crown taken, prince leaving
+  - State 7: Ball taken, frog returning to wild
+- Player automatically switches view between land (2) and water (6) based on onControl terrain
+- Score changes: +3 for kissing frog to transform, +2 for taking crown from transformed prince
+- Frog uses multiple views: 370 (default), 372 (swimming), 373 (jumping), 377 (returning with ball), 378 (prince)
+- Prince uses views: 225 (transformation), 226 (walking), 227 (leaving)