KAZIK/docs/HALL_EXPANSION.md

# Upper Lounge, Manual Stairs and Cabaret

## Native Implementation

All movement, collision, camera height, room changes, interaction, rendering and
animation run in MASM32. The Python files only compile bitmap packs or build and
run the actual native test executable. No alternate game runtime was added.

The east entrance, at approximately (30,21) in the main hall, leads to an enclosed
wooden stairwell. WASD, turning and mouse look stay active. Twenty treads rise
2.6 world units; the camera height follows position, not elapsed animation time.
The stairwell may be stopped on or reversed anywhere. Crossing its landing joins
the upper lounge; returning uses the same route. Room-local coordinate translations
at door thresholds preserve facing and never advance the player on a timer.

The upper lounge is a compact 13-by-12-unit room with a dedicated carpet, teal
coffers, marble bar, seating, guests and projecting lanterns. Buckshot, Russian
roulette and Hell Tower are available there; their old ground-floor billboards
and interaction targets are suppressed. Their gameplay code is unchanged.
The two game stations now use distinct detailed table cutouts: a shotgun,
shells and handcuffs for Buckshot; an octagonal revolver/whiskey table for
Russian roulette. Their collision and interaction centres remain shared.
The bar uses a full-body bartender in the walking view and a separate close
serving animation when seated. Bar stools do not obstruct that seated view.

The original iron door remains in the east-facing alcove at (28.5,10.5), using
the same door artwork as before the stair expansion. Its control opens it sideways
without moving the player
or change modes. The closed leaf blocks the doorway. Walking through its open
threshold enters the concrete stairwell, which also uses normal movement. The
old timed descent has been removed. The descent goes east, with a level landing
where the player turns north into the existing bunker. The ticket counter is
restored to its original (29,7.5) position.

Both sides of all stair entrances show the adjacent native scene through a
depth-tested aperture. Remote wall rays begin just beyond that aperture, not
inside a closed map cell behind the camera. Foreground geometry still occludes
the view. This repairs the former visible-wall/walk-through-wall mismatch;
room-local translations at thresholds are retained, with no timed player travel.

## Infernal Portal

Hell Tower is no longer represented by an ordinary table. A 2.5-unit-wide,
almost ceiling-height arch is mounted in the south wall, with a projecting
dark metal surround, chains and two animated crimson braziers. Its floor glow
is applied to the existing carpet, not drawn as an opaque rectangle.

Each of the two floor levers has six generated positions over a 600ms pull.
The portal stays sealed until both complete. Its vortex then loops through
twelve generated phases at 80ms per frame. The rigid arch is registered and
locked across those phases; the brazier fires have four separate phases.
Walking into the open aperture, or interacting with it, starts the existing
Hell Tower mode. Returning cannot immediately retrigger it until the player
backs away from the entrance.

## Visitors

Six new appearances include three men and three women, with separate standing,
walking and seated frames. Both visitor rotations have a mixed cast. Dialogue
names follow the selected appearance. Existing routes and challenge identities
are retained. These are front/three-quarter sprites, not complete eight-direction
animation sets. Upper-lounge guests are currently seated, not another roaming
population; this limitation is deliberate and not presented as finished NPC AI.
Their chairs are grouped around lamp tables rather than placed singly at blank
walls; the emerald guest's seated pose faces inward toward the shared table.

## Cabaret

A nearby seat interaction opens a seated view of the stage. Three thirty-second
acts cycle: the existing twelve-frame dance chorus, a singer/pianist/guitar/sax
quartet, and a duet. The pianist and grand piano are one coherent generated
cutout, with his bench, hands on the actual keyboard, pedals and raised lid.
The guitarist has four separate playing poses, as does the piano/pianist.
Their common packing bounds retain fixed scale and foot anchors. The seated
camera frames all four performers without clipping the piano or saxophonist.
The programme shows the current act and time to the next one. Requesting
the next act or leaving a tip costs 100; insufficient funds never create debt.
Standing up and Escape return to the hall. New act-specific music, eight-direction
performer sprites and audience applause recordings are not included in this pass.

## Assets

Generated using the built-in image generator, with no API key:

- `assets/sprites/hall/guest-cast-v1.png`
- `assets/sprites/hall/cabaret-ensemble-v1.png`
- `assets/sprites/hall/cabaret-musicians-v1.png`
- `assets/sprites/hall/upper-materials-v1.png`
- `assets/sprites/hall/upper-furniture-v2.png`
- `assets/sprites/hall/upper-portal-v3.png`
- `assets/sprites/hall/upper-levers-v3.png`
- `assets/sprites/hall/upper-braziers-v3.png`

Exact prompts and packing outputs: `assets/sprites/hall/prompts-v7.json` and
`assets/sprites/hall/prompts-v8.json`.
Packers: `pack_guest_cast.py`, `pack_cabaret_ensemble.py`,
`pack_cabaret_musicians.py`, `pack_upper_materials.py`, `pack_upper_v2.py`,
`pack_upper_motion.py`
under `tools/generators`. Original source images are preserved.

## Verification

`python tools/tests/check_hall_expansion.py` compiles current MASM procedures and
tests opening without movement, closed-door collision, manual traversal and
reversal of both stairwells, no idle timed movement, upper-floor game/bar targets,
bar camera restoration, cabaret costs and exits. It records native frames
under `build/hall-expansion`. `--parity` checks new runtime procedures against the
shipping object after the main build. Helpers are reused by changing COFF symbol
visibility only; no helper instruction bytes or player save files are modified.
All four jazz poses are rendered and checked for visible changes in both the
piano and guitar regions. The loader probe also covers both new musician packs.
The repair tests cover all eight doorway views, foreground occlusion, original
door/ticket positions, the two-lever lock, intermediate/final lever poses, all
twelve visible vortex phases, tower entry/return and single/dual-thread pixel
parity at the stair entrance. `--prove-seam-regression` disables only aperture
near clipping and confirms that the old solid rear-wall block reappears.

Published on 2026-10-18 to `poker.exe` and `bin/poker.exe`, with the existing
launcher integrity hash updated. Both copies and `build/graphics/poker.exe` have
SHA-256 `C0B5A1DD9A678E68599724138AF009D29C935EEFDD6D70D28789AABF071395F8`.
Native scene/input tests, asset loading from root/TEMP, card-rank parity and the
eight-ball ownership/retained-turn regression passed. The full legacy action
suite and an interactive end-to-end playthrough were not rerun for this pass.

The remaining poker, roulette, achievements, billiards controls and new-game work
is tracked separately in `CASINO_NEXT_PASS.md`; it is not claimed complete here.