KAZIK/docs/ROOFTOP.md

# Rooftop Lounge "Vysota"

The terrace is an assembly-only walkable hall level (`HALL_ROOF = 4`), reached
by a real elevator cabin near the north wall to the right of the cabaret.
Existing games, basement stairs, scratch tickets and fortune room stay in place.

## Travel

Use E at the exterior call panel, then walk into the open cabin using the normal
movement keys. The inside panel offers the roof or the main hall depending on
the current landing. E starts a trip only when the player is fully inside.
Doors physically slide apart into projecting pockets. Movement is blocked during
closing/travel, while looking around remains possible. After one second of
closing and 3.2 seconds of travel the destination changes, doors open, and the
player walks out. Position, angle and standing height do not drift during travel.

An idle open door closes after 2.8 seconds away from the elevator. It reverses
if the player re-enters its approach, rather than shutting through them. Arrival
keeps the cabin coordinates and opens the other landing; there is no forced
camera path or automatic walking. The illuminated physical indicator changes
during travel and shows `1` or `R` at the landings.

## Terrace

- A fully volumetric Petersburg-inspired city, seen from a sixty-metre tower.
  Only the sky is a painted texture; buildings, streets, roofs, parks, canal,
  bridges, monuments, cars and boats are real world-space geometry.
- Finite HD decking, low railings and an open sky, rather than an indoor ceiling
  or a floor extending to infinity beyond the roof edge.
- Three three-seat sofas, four armchairs, three bar stools and three stools at
  a rail-side standing counter: 13 selectable furniture positions, 19 seat places.
- Seven coffee tables, eight potted trees, flowering troughs, eight varied guests,
  two supported strings of lanterns, and a slatted pergola over a working bar.
- Sofas and chairs use closed native volumes with separate padded cushions.
  Planter boxes contain soil and multiple foliage clusters at different depths.
  Whole-object photographs are not pasted onto every furniture face.
- E at a railing eases into a leaning pose, with thirty-two hand/forearm frames
  anchored to the actual rail height. E or movement releases the rail.
- While leaning, mouse, arrows and A/D can turn up to 73 degrees either way. The
  rail contact is projected in world space so the hands do not follow head yaw.
- Guests walk on the terrace with collision checks, pauses and walking frames.
- In the open first-floor elevator, 1 selects sunset and 2 selects night.
- E sits/stands; walking forward/backward also stands and restores the approach
  position. Stool views use bar height and rail-side stools face the city.
- The bar reuses the existing mixing/drinking system and prices (100/200/free
  water). Its camera is temporarily positioned at the new counter and completely
  restored after rendering. Drinks are the only new-location actions that spend
  or save bankroll, through the existing purchase routine.

## Assets And Build

Generated sources are under `assets/sprites/rooftop/`; runtime ANM1 packs are under
`assets/animations/rooftop/`. Run `tools/generators/pack_rooftop.py` offline to pack
the sky, materials, semantic night-window textures, ground lighting, hands,
district layout and collision map. Run `pack_rooftop_gl.py` afterwards to build
the static city and moving vehicle triangle meshes. Python, Pillow, NumPy and
OpenCV are offline developer tools, not game dependencies.

The native MASM HD city renderer uses the Windows system OpenGL library, a
private hidden rendering context and an offscreen framebuffer up to 1280x960. It uses
textured mesh display lists, mipmaps, normals, directional dusk lighting,
distance fog and a separate emissive-window pass at night. The existing terrace,
hands and HUD are composited by direct native pixel copying into one DIB. Other games retain
their existing renderer. If the required GL capabilities are unavailable, the
assembly software city renderer remains the fallback. No C/C++ renderer, model
engine, browser runtime, cloud service or runtime downloader is introduced.

The eastern avenue is now a broad river with raised embankments, promenades,
trees, piers, three full-span bridges and further riverfront quarters. Water
texture flow and six moving boats keep it from being a static blue plane.
Street rectangles are clipped into disjoint junctions rather than coplanar,
overlapping strips. The terrace deck uses mipmapped HD geometry rather than
the unfiltered software floor when HD rendering is available. City, foreground
and HUD are composed into one offscreen DIB and copied to the window once;
there is no intermediate bare-city frame. glReadPixels supplies the required
readback synchronisation, without a redundant preceding glFinish.

## Rooftop Performance

- F8 cycles automatic, eco (640x480) and detailed (1280x960) city rendering.
  Automatic starts at 960x720 and drops to eco after sustained frames over 34 ms.
  Switching back to automatic retries 960x720. The scene, view distance, collisions
  and gameplay do not change with the render profile; other rooms are unaffected.
- The offline mesh packer discards only triangles that face away from every
  possible rooftop eye position. Runtime back-face culling handles head turns.
  The static mesh, including driver-safe ground and canal frontage, stays under 48,000
  triangles. Never-visible faces are pruned before shipping.
- Terrain and light-map triangles crossing the near district are at most 64 m
  wide, with finer cells near the terrace. This avoids relying on per-fragment
  fog for multi-kilometre polygons on integrated OpenGL drivers. Water animation
  uses its own display list from the same tessellated mesh, not two giant quads.
  GL_NICEST requests accurate fog, but the geometry remains safe if ignored.
- CPU foreground surfaces use projected screen bounds and camera-facing box
  sides. The final frame avoids an extra GDI scaling/alpha-blending pass.
- Mipmap generation is optional on older OpenGL drivers. If hardware rendering
  cannot initialise, the software ground renderer still draws roads and water,
  including solid-colour fallback surfaces when a texture pack is absent.
- `runtime/roof-renderer.txt` records the local GL vendor, renderer, version,
  initialisation stage, city-pack availability and render width. It contains no
  personal data and is not sent anywhere. Stage 0 means successful initialisation.

Integrated Intel graphics use shared system memory; the small dedicated-memory
figure alone is not a useful rendering budget. Actual laptop performance must be
checked on that machine, not inferred from the desktop benchmark.

The western canal has two rows of varied waterfront facades, raised stone quays,
bridge openings, trees and benches. These replace the empty cleared block rows;
they use the same world records in the GL and software renderers. The offline
`pack_rooftop.py --district-only` option rebuilds layout and lighting without
repacking unchanged sky, hand-animation or material assets.

The art direction takes atmospheric inspiration from the rooftop reference:
https://www.loftprojectetagi.ru/visitors/krysha/ . It is an original game backdrop,
not an exact survey or reproduction of that venue. Generated source images are
preserved alongside the packer metadata. Older city panoramas and furniture
reference photographs remain source art, not the active city/furniture renderer.

Runtime sources: `src_graphics/rooftop*.inc` and the shared MASM city primitives.
The normal MASM build and root/bin publisher ship the feature. Rebuilding the
existing installer is separate from updating the ordinary game executable.

## Verification

`tools/tests/check_hall_expansion.py` compiles the real current MASM routines and
tests closed/open door collision, manual cabin entry/exit, both trips, timing,
camera/position/bankroll preservation, furniture/rail bounds, seating, automatic
closing, thirty repeated bar renders, asset loading/freeing and native screenshots.

It exports a 70x78 walk grid from actual `CanWalk3D` calls. Reachability checks
verify a connected route from the cabin to the bar, both sides of the terrace,
and every seating approach after the denser layout. Framebuffer captures are
written under `build/hall-expansion/roof-*.png`. `--parity` verifies tested
procedures against the full shipping object before publishing.
The native harness also checks all three resolution profiles, automatic downgrade,
F8 switching, and software roads/water with both present and missing city textures.
It also captures GL_FASTEST fog, checks ground-cell bounds and water tessellation.
These are compatibility checks on the test machine, not a substitute for confirming
the result on the laptop's actual Intel driver.