Progress on documentation

rooms/kq4-071-cave-entrance/kq4-071-cave-entrance.md

@@ -0,0 +1,83 @@
+# Room 71: Cave Entrance
+
+## High-Level Summary
+
+Room 71 is the cave entrance area in the Troll Cave region. It serves as a transitional room connecting the upper area (room 72) and the south entrance (room 74). The room features a dark cave environment with a waterfall visible outside, a pile of bones that can be collected, and dynamic lighting effects based on whether the player has the lantern. This room is notable for its darkness mechanic - without the lantern, the cave is extremely dark, and with the lantern, visibility is still limited.
+
+## Look Description
+
+"This is the darkest cave you've ever seen!" (varies based on lantern possession)
+
+## Interactions
+
+| Status | Behavior Type | Command | Response |
+|--------|--------------|---------|----------|
+| TODO | Look | `look [at/around]`/`look/room/cave` | "This is the darkest cave you've ever seen! Even the lantern does little good." or "This is the darkest cave you've ever seen!" (with/without lantern). If no bone: "By the light of the cave entrance, you can see a pile of bones." |
+| TODO | Look | `look/falls`/`look/out` | "Outside the cave, you see the waterfall." |
+| TODO | Look | `look/heap` | "You see a pile of bones by the cave entrance." |
+| TODO | Look | `look/bone`/`look/dirt`/`look/down` (no bone) | "You see a pile of bones by the cave entrance." |
+| TODO | Get | `get/bone` | "You don't need another one." (if already have bone in inventory) |
+| TODO | Get | `get/bone` | Gets the bone when near the pile, awards 2 points, triggers pickup animation |
+| TODO | Get | `get/bone` | "You can't get that." (if not near the bone pile) |
+
+## Scripts
+
+| Status | Behavior Type | Name | Trigger | Behavior |
+|--------|--------------|------|---------|----------|
+| TODO | Interaction | `getDown` | Player picks up bone (item 23) | Plays a bending-down animation using view 940, temporarily stores ego's current view, cycles through cel animations for picking up the item, then restores the player's view |
+
+## Technical Notes
+
+- **Room Number**: 71
+- **Picture**: 71
+- **Style**: $0010 (hex)
+- **Region**: 605 (Troll Cave)
+- **Exits**: 
+  - North → Room 72 (via control area $0020)
+  - South → Room 74 (standard exit)
+  - West → Room 70 (via control area $0040)
+- **Music**: Not specified
+- **Views Loaded**: 800, 511, 940
+
+### State Variables
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `global101` | 1 | Room initialization flag (set to 1) |
+| `global126` | 0, 1 | Darkness visibility flag |
+| `global182` | 0, 1 | Bone collected flag (set to 1 after collection) |
+| `global189` | 0, 1 | Troll region active flag |
+| `global228` | string buffer | Format string buffer for dynamic text |
+| `newView` | View object or 0 | Lantern view object (created when player has no lantern) |
+| `newProp` | Prop object | Visible bone pile prop (view 511, cel 0) |
+| `newProp_2` | Prop object or 0 | Hidden bone prop (view 511, cel 1) - only created if bone is in room |
+
+### Inventory Items
+
+- **Item 23**: Bone - Can be picked up from the cave entrance, awards 2 points when collected
+
+### Control Areas
+
+- `$0040`: Triggers exit to Room 70 (west)
+- `$0020`: Triggers exit to Room 72 (north)
+
+### Darkness Mechanic
+
+The room uses `proc0_20` to check if player has the lantern (item 24). Without the lantern:
+- The cave appears very dark
+- A lantern view object (view 800) is created at position 108, 132
+- global126 is set to 0
+- Different look descriptions are shown based on lantern possession
+
+### Bone Collection
+
+The bone (inventory item 23) can be collected when:
+1. The bone is in the room (owner is 71)
+2. Player is within 15 pixels of the bone prop (newProp_2)
+3. When collected: bone is added to inventory, getDown script plays animation, global182 is set to 1, score increases by 2
+
+### Entry Points
+
+- From Room 72 (north): Player positioned at 208, 104
+- From Room 74 (south): Player positioned at 170, 183
+- From other rooms: Player positioned at 78, 112, darkness initialized