Progress on documentation

rooms/kq4-028-mine-entrance/kq4-028-mine-entrance.md

@@ -0,0 +1,60 @@
+# Room 28: Mine Entrance
+
+This is the entrance to the dwarf diamond mine, featuring a crude mine shaft carved into a small hill with a wooden door. The room has two distinct states depending on whether the mine door is open or closed/padlocked (controlled by global100). Players can enter the mine, approach the door, or fall into a pit in the southwestern area. The room connects to the diamond mine (room 55) when entering the mine shaft.
+
+## Look Description
+
+"You see a crude mine shaft in the midst of this forest of pine trees."
+
+## Interactions
+
+| Status | Behavior Type | Command | Response |
+|--------|--------------|---------|----------|
+| TODO | Look | `look door` | "The door is wide open." (Print 28 0) - When door is open (global100=0) |
+| TODO | Look | `look in/mine` | "You look inside, but can make out no details." (Print 28 1) - When in proximity to mine entrance |
+| TODO | Look | `look mine/hill` | "The crude mine is carved into a small hill. Its solid, wooden door is propped open." (Print 28 2) - When door is open |
+| TODO | Look | `look around` / `look room` | "You see a crude mine shaft in the midst of this forest of pine trees." (Print 28 3) |
+| TODO | Action | `close door` | "You shouldn't close it." (Print 28 4) - When door is open |
+| TODO | Action | `open door` | "The door is already open." (Print 28 5) - When door is already open |
+| TODO | Look | `look door` | "The door is closed and padlocked." (Print 28 10) - When door is closed (global100=1) |
+| TODO | Look | `look mine/hill` | "The crude mine is carved into a small hill. Its solid, wooden door is closed and padlocked." (Print 28 11) - When door is closed |
+| TODO | Action | `break door` | "You could never do that." (Print 28 6) - When door is closed |
+| TODO | Action | `bang door` | "You knock on the door, but receive no answer." (Print 28 7) - When in proximity to closed door |
+| TODO | Action | `open door` | "You can't. It's closed and padlocked." (Print 28 8) - When door is closed |
+| TODO | Action | `unlatch door` / `detach door` / `get door` | "You can't. You don't have the key." (Print 28 9) - When door is closed |
+
+## Scripts
+
+| Status | Behavior Type | Name | Trigger | Behavior |
+|--------|--------------|------|---------|----------|
+| TODO | Interaction | fallSouth | Player walks into control area $0004 in the southwest | Triggers falling animation into pit, plays fall sound (sound 51), animates ego falling with view 17, then transitions to lying down animation (view 21), then resets player to standing |
+| TODO | Background | Room exit | Player enters control area $0040 | Automatically transitions to room 55 (diamond mine) |
+
+## Technical Notes
+
+- **Room Number**: 28
+- **Picture**: 28
+- **Region**: 508 (Forest Region)
+- **Exits**: North→22, South→4, East→29, West→27, Mine entrance→55 (via control area)
+- **Music**: Not specified
+
+### State Variables
+
+| Variable | Values | Description |
+|----------|--------|-------------|
+| `global100` | `0`, `1` | Event state - controls mine door state (0=open, 1=closed/padlocked) |
+| `global101` | `0` | Local room state flag (initialized to 0) |
+| `door_open` | `true`, `false` | Derived from global100 - mine door is open or closed/padlocked |
+
+### Additional Technical Details
+
+- When global100 is set (door closed), overlay picture 128 is displayed
+- A View object (view 600) is displayed at the mine entrance - loop 0 when door is closed, loop 1 when open
+- Player cannot close the door (message: "You shouldn't close it")
+- The fallSouth script uses local variables local1 and local2 for positioning calculations
+- When falling, player movement is disabled (illegalBits: 0) and special views are used (17 for falling, 21 for lying)
+- After falling, player is reset to normal view (view: 2) with standard walking
+- Control area $0004 triggers the fall, control area $0040 triggers exit to diamond mine
+- Player enters in normal view (view: 2) with standard walking parameters (xStep: 3, yStep: 2)
+- Horizon is set at y-coordinate 126
+- Views 17 and 21 are preloaded for the falling animation sequence