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 iron door remains in the original east-facing alcove. Its frame is at
(28.38,10.5), while the leaf and hinge are recessed to x=28.9. Approaching from
the hall or the upper end of the basement stairs automatically requests opening;
the old E interaction remains an optional request, not a required teleport.
The dogging handwheel turns through seventeen texture phases over 700ms, then
the leaf swings through 90 degrees over 1000ms around a fixed hinge. A native
ray/rotated-plane intersection renders perspective and occlusion. It does not
slide sideways or turn to face the camera. Leaving the wider safety zone starts
a 1200ms hold, followed by the reverse sequence: shut the leaf, then lock the
handwheel. Both sides of the doorway and the whole swept area hold it open.
Returning during either phase reverses from the current pose without snapping;
the wheel must unlock fully before the leaf can reopen. The wider hold radius
prevents boundary jitter. The closed leaf blocks the doorway.
The same leaf/frame is rendered and collision-checked in the overlapping stair
landing, including the return journey; a closed door cannot be bypassed from below.
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. The former eight-unit view cutoff has been replaced with
a bound beyond the diagonal of the whole map: moving away no longer hides a
doorway's continuation. 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.
Destination pixel depth is retained so the swinging door can occlude the view
through the opening. Descending risers meet the near edge of their treads.

## 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.
Both levers remain usable after activation. Interacting again toggles the selected
lever back, disables walking/E entry immediately and shows the sealed portal.
The handle returns through the same six poses over 600ms; toggling mid-motion
reverses from its current pose. Both handles must finish in their enabled position
to reopen the portal. Interaction prompts distinguish pulling from returning.

## 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. Walking now uses eight distinct generated
phases per appearance, plus a mirrored pack selected by camera-relative travel.
The phase follows successful displacement (one cycle per 0.75 world units), not
elapsed time: waiting or being blocked does not march in place. Supporting feet
are normalized to the floor baseline, with the old standing/seated canvas padding
compensated. 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/guest-walk-v2.png`
- `assets/sprites/hall/basement-door-v2.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`. The new door/walking prompts are in
`assets/sprites/hall/prompts-v9.json` (built-in image_gen, no API key).
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`, `pack_door_walk_v2.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.
The new tests include far doorway views, automatic opening before any E press,
wheel-before-hinge sequencing, eight native gait captures, reverse-facing art,
blocked movement and equal gait phase after the same travel at 16/32ms updates.
An additional native return-path test starts below a closed door without E,
checks that the body is stopped while the wheel turns, then walks back into the
hall after automatic opening.
All six visitors are also updated for two simulated minutes by the native movement
procedures, checking walkable positions and bounded distance-driven gait phases.
`--prove-distance-regression` restores just the old eight-unit cutoff and must
fail the actual native distant-doorway assertion. The shipping loader probe
also checks both 48-frame gait packs and the 18-texture door pack from root/TEMP.

Previous release, 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.

## 2026-10-19 Release

Published the distance/door/gait repair to root `poker.exe`, `bin/poker.exe` and
`build/graphics/poker.exe`; updated the existing C# launcher's integrity hash.
All three game copies have SHA-256
`70D16BF2DB85AC23E098B9B31EB4CD9A6664D6E51FEDE470CC6116C3E9F94339`.
Fresh native navigation/rendering/gait tests and shipping procedure parity pass,
including reverse-side closed-door collision and automatic return traversal.
Terminal/lantern parity, billiards rules/ownership parity, 208 card faces and
shipping asset loading from root/TEMP also pass. Negative controls reproduce
the old distant-wall cutoff and missing aperture near clipping. The game runtime
is still assembly-only; C# is used only by the existing launcher packaging.
No full interactive desktop playthrough or full legacy action suite is claimed.

### Portal Switching Update

The same day's follow-up adds reversible lever interaction and immediate portal
shutdown. Root/bin/build game copies and launcher integrity metadata were updated
to SHA-256 `36C1CF0734F3C1E0F30F52E76C236FE0261D76E9089BF5AB5B7FBEDEE4E58FF4`.
Native tests cover both enabled levers remaining reachable, pull/return prompts,
walking and E entry blocked immediately after shutdown, the visible sealed arch,
mid-stroke reversal without a position jump, full release and reactivation.
Tested/shipping procedure parity, billiards and terminal regressions pass.

### Automatic Door Closing Update

The latest build closes the basement door after the player leaves its safety
zone and a 1200ms hold expires. The leaf shuts before the wheel locks; approaching
again reverses either phase without a jump. The upper stair landing and the full
leaf swing remain protected while occupied. A manual E request also expires.
Native assertions cover both sides, the hold delay, one update per frame,
closing/locking order, mid-motion reversal, full closed collision and reopening.
Three native captures show closing, locking and the fully closed door.
Published root/bin/build game copies and launcher metadata use SHA-256
`ADF4CE0A7ECAED4D0293A3791FA8B1CA204C931E5F78FE70C1DAD8166BF7AD24`.

### Secret Fortune Teller Room

The west arcade now has a pull-down lantern beside the slots. E lowers the
lantern, then slides a concealed timber panel aside. E again returns it; the
panel pauses closing while the player occupies its threshold or remains anywhere
inside the secret staircase/chamber, so a pending close cannot trap a visitor.
The original eastern steel basement door and lottery stand have not moved.

Walking through the opening enters a separate, manually traversed west-facing
stairwell (route 3), descending to a compact 5x4-metre cellar (hall level 3),
reduced from the initial 8x9-metre layout. All camera
height changes follow the player's position. Doorway apertures show both ends
at near and far distances; returning uses the same physical staircase.

The chamber and its staircase use dedicated sapphire stone walls, a silver-star
coffered ceiling, blue-grey floor tiles and a blue lunar rug, not the ordinary
basement's worn concrete/green walls. The seated figure wears a blue mantle;
both idle poses keep the entire face hidden inside the hood. The table has tarot
cards, blue-white candles and a crystal ball. A matching curio bookcase, lunar
tapestry, two floor candelabra, armillary sphere, scrying mirror and velvet bench
with a grimoire side table furnish the room without blocking the walking route.
A second potion cabinet, low book cupboard, relic display, chest, card vitrine,
scroll rack and hanging herbs fill the wall/corner space. The fronts use fixed
world-aligned planes rather than camera-facing billboards; the two largest
cabinets and bench also have depth geometry. The room's central walking route
and stair aperture remain clear, with furniture collision checked natively.

The ambient light is dim. Eight world-space point sources at the blue-white
candles, crystal and lantern positions supply local cool illumination. Native
lighting reconstructs each surface position from scene depth and its camera ray,
including height, before applying distance falloff. Flame cores stay bright
only near an actual light. This is not a camera-centred glow or a flat blue tint.
It runs only in the tarot chamber, before the HUD and doorway composition.

Artwork was generated/edited with the built-in image tool. The five version-2
source PNGs and exact prompts are in `assets/sprites/hall/fortune-*-v2.*`.
`tools/generators/pack_fortune_room.py` packs sixteen transparent 256px sprites into
`assets/animations/hall/fortune-room-v2.bin` and four independent surfaces into
`fortune-materials-v2.bin`. Materials 132-135 are resolved separately, without
overwriting any shared casino or basement texture. Fixed prop surfaces use
virtual IDs 136-151 against the same sprite pack. Wall and plane renderers
handle them at every distance, with bounded fallback when an art pack is absent.
All game rendering, navigation and interaction remain native assembly.

E at the fortune teller opens the existing native "Not implemented yet" modal.
Closing it preserves the room, camera and bankroll. There is deliberately no
fake AI dialogue, tarot result, student form, networking or model dependency.
Those features remain deferred until a real dialogue approach is selected.

`fortune_room_test.inc` runs within the fresh MASM hall harness: lantern targeting
and toggle prompts, pull/open poses, closed collision, per-frame animation guard,
near/far doorway views, full walking descent/return, continuous stair eye height,
room furniture collision, two idle poses, modal open/close without spending,
occupied-threshold safety and closing after return. Native captures are written
to `build/hall-expansion/fortune-*.bmp` and `.png`. The shipping asset-path probe
also checks both new art packs. Palette assertions cover the chamber, both side
views, the close-up and the staircase; native assertions cover the extra furniture
collisions, material offsets, point-light falloff and darker-versus-unlit output.
Additional native captures cover oblique furniture and the eastern cabinets.
A full interactive desktop playthrough is not
claimed by these automated native tests.

### Blue Chamber Release (2026-10-20)

Published root/bin/build game copies and the launcher integrity metadata use
SHA-256 `3C6E6B85A3B695B5DD52EB4F1E8BE0345E9DE4D4028D269B925B1F5AAF2C3BFA`.
Fresh native navigation, lighting, furnished-room and dialogue checks pass.
Shipping procedure parity, billiards rules/ownership, all 208 card faces,
terminal regressions and asset loading from root/TEMP also pass.
The parity reader now optionally normalizes branches to named procedure entries,
as it already did calls, so the same tail branch remains comparable across
different object layouts. It still compares the destination procedure name and
all instruction opcodes; ordinary card/terminal comparisons keep their defaults.

### Lived-In Den And Centred Entrance

The room-side entrance is now centred on the east wall: Y=10..12 in a room
spanning Y=9..13. Its centreline Y=11 also meets the fortune teller directly.
The unchanged secret staircase remains at Y=9..11; the lower landing translates
Y by +1 metre on entry and -1 on return. Both doorway views use the same inverse
translation, so the visible continuation agrees with physical walking. The
arcade lantern and the separate steel basement door/lottery stand stay put.

The blue palace-like panelling and ceiling are replaced by worn fabric wall
hangings, a slack cloth canopy, dusty irregular flagstones and a faded rug.
Gathered curtains frame the fortune teller. A stuffed, mismatched curio shelf,
draped workbench, leaning book piles, loose papers, travel bag, open chest,
cauldron, bottles/tray, melted floor candles and hanging herbs make the room
less tidy without closing the central walking aisle. Furniture remains fixed
in world space. The concealed face, local blue light and unavailable dialogue
are retained. Additional low light sources correspond to the floor candles.

Version-3 sources: `assets/sprites/hall/fortune-den-v3.png`,
`fortune-clutter-v3.png`, `fortune-materials-v3.png` and the exact built-in image
generation/edit prompts in `fortune-den-v3.prompts.json`. The offline packer
retains the original sixteen frames and adds eight new ones, yielding
`assets/animations/hall/fortune-room-v3.bin` (256x256x24) and
`fortune-materials-v3.bin` (256x256x4). Surface IDs 152-159 select the new frames.
No external runtime, model, service or library is added.

Fresh native tests cover centred entry alignment, actual descent and return,
the centred doorway mask, clutter collision, art bounds/headers, lighting and
the dialogue placeholder. `fortune-doorway-centered.png` records the room-side
opening; the usual room/side/oblique captures show the new furnishing pass.

Published root/bin/build executables and launcher metadata now use SHA-256
`C65E1B1EE5CE8DDB79EADFED982619378780EE4E866BC3D2F3A17DA83E26446F`.
Fresh native tests and shipping procedure parity pass, including off-centre
crossings and the inverse landing translation. Billiards ownership/rules, card
ranks, terminals and root/TEMP asset loading pass as well. This does not claim
a full interactive desktop playthrough.

### Bar Camera Without Alcohol Sway

Removed alcohol strength, intoxication accumulation and its per-frame horizon
offset. Drink prices, purchases, serving/drinking animations and both bar views
are unchanged. Walking now restores the exact standing horizon and eye height,
including recovery from a previously shifted camera. Staircase height remains
route-controlled.

The native bar fixture exercises 24 visits across both bars, all three drinks,
single-debit protection, animation boundaries, six actual bar renders and 6144
walking updates with exact camera-state assertions. Profile saving is disabled
through the existing arrival-confirmation guard. Removing horizon recovery in a
test-only build is rejected by case 70. The fixture models the return-to-walking
state; it does not automate the Win32 Escape key event loop.

Published game copies and launcher integrity metadata use SHA-256
`EADBA9C8C9BD5B7E3CC4CE486ED647C1CE9383D1DCB6EBC94FE755EA1F4BF927`.
Fresh native checks, shipping procedure parity, billiards, card ranks, terminals,
Russian labels, audio bindings and root/TEMP asset loading pass.