KAZIK/docs/SHARED_CHARACTERS.md

# Shared Visitor Cast

Ten generated adult visitors now share one identity-locked animation system in
the main casino, upper lounge, rooftop and bowling room. Dealers, bartenders and
stage performers remain separate job-specific characters.

## Identity And Animation

Each identity owns a fixed block of 100 slots in `cast-v1.bin`. Changing an action
never selects a different character block. The renderer chooses front, back,
left or right gait from actual movement relative to the camera. Walk frames are
distance-driven and stop when movement stops.

The block contains idle, conversation, drinking, seated idle/conversation/drinking,
four gait directions, sitting down, standing up (reverse of sitting), picking up
a ball, underarm throw/follow-through and celebration. Idle slots deliberately
hold a stable pose. Optical-flow in-betweens are generated offline, not by the
game. These remain 2.5D sprites, not skeletal 3D humans.

All states use the same physical canvas, scale and foot anchor. Seated sprites
are shorter poses on that canvas, not separately enlarged portraits. A walking
casino visitor pauses movement while standing up from a chair.

The canvas height is 1.3 world units (192:224 aspect), calibrated against the
hall's 1.05-unit standing eye height. The former 1.95-unit canvas made visitors
oversized compared with the camera, staff and furniture.
The rooftop uses a 1.65-unit standing eye height. Its visitor canvas, width and
foot anchor are scaled by the rooftop/hall standing-eye ratio (about 1.57),
independently of sitting or leaning. Indoor visitor sizes remain unchanged.

Walking uses replacement `person-*-walk-source-v2.png` sheets with contact and
passing poses in front, rear and right profile. The left profile is mirrored.
Each sheet has a common scale and ground anchor. The generator records these
crops in the cast manifest; `walking-generation-v2.json` records built-in image
generation provenance. Non-walking actions retain their original source art.

Bowling uses three occupied lanes with six persistent players. Four other
identities occupy the restaurant/bar, giving ten distinct visitors without
duplicating an active bowler as a seated stranger. Players walk to the ball,
pick it up, throw, return, sit and alternate turns while keeping their identity.

The historical twelve-slot NPC journal is preserved for save compatibility;
its appearance mapping resolves to the ten shared visual identities.

## Main Hall Routines

The main hall now has ten simultaneous visitors with fixed identities, rather
than six slots changing people at the entrance. The first six legacy poker-mind
records retain their size and personality indices; four extra world actors use
the same bounded entity accessor. The twelve-entry contract journal is retained
without changing existing profile saves. Ten of its identities are currently
represented in the hall; old entries are not deleted or reassigned.

Each visitor has a preferred game, walking speed, session length, private
ambient wallet and private RNG. Weighted destinations replace the single shared
route. Short abstract game sessions produce a win/loss reaction, after which
guests continue playing or take a break. These are ambient outcomes, not full
hands played by the actual card-game engines. Neither the player's bankroll,
casino RNG, achievements nor contract progress is touched.

There are twelve reservable places: five game approaches, two bar positions,
two existing lounge chairs, two audience positions and the entrance. Guests
order, drink, rest, converse with a nearby stationary guest and watch the stage.
Only short nearby remarks are displayed. Stale remarks clear on arrival.
Rest/drinks ease negative mood. Out-of-funds guests leave through the entrance,
wait offstage and return as the same person with a new ambient budget.

BFS and body clearance still use the real room geometry. A visitor reserves a
place before walking and releases it after a successful change of destination.
Blocked guests pause with staggered retries; persistent obstruction releases
the reservation and permits replanning. Gait only advances on actual movement.
Seated poses align with the two existing chairs and pause navigation during the
stand-up transition. Visitor canvas dimensions remain unchanged.

Pathfinding checks quarter points along each tile edge, not just free tile
centres, so approaches cannot cut through the expanded chair collision. Seating
has its own bounded 800 ms clock: starting a conversation resets the activity
clock but cannot replay the sit-down animation. The visual seat anchor blends
smoothly in both directions; walking frames require actual movement velocity.

Routines currently belong to the main hall. Other floors keep their existing
ambient controllers and shared appearance assets; this is not yet a persistent
cross-floor population simulation. Hall routines pause outside walking mode or
outside the main hall, including while a modal conversation is open.

`check_hall_expansion.py --npc-only` compiles production MASM and checks eight
simulated minutes: fixed identities, exclusive reservations, reachable positions,
activity transitions, walking progress, player-bank/RNG isolation, modal/floor
pause and bounded recovery from a player blocking the path. It also captures
native order, drinking, seated, win and loss poses. Full hall checks include the
same cases; no neural model or new runtime dependency is needed.
The chair regression also walks a visitor to a real chair at 16 ms ticks, checks
the complete sit/rise frame sequence and monotonic anchor motion, and starts a
seated conversation without restarting the transition. Native captures and GIFs
are written as `build/hall-expansion/npc-chair-*`.

## Assets

- `assets/sprites/characters/person-00-source-v1.png` through `person-09-source-v1.png`:
  original full sheets generated with built-in imagegen.
- `assets/sprites/characters/generation-v1.json`: generation brief and identities.
- `assets/sprites/characters/cast-v1.json`: action offsets, source crops and scale.
- `assets/sprites/characters/roster-v1.png`: normalized cast preview.
- `assets/sprites/characters/person-*-motion-v1.gif`: motion review previews.
- `assets/animations/characters/cast-v1.bin`: native ANM1 shipping pack.

`tools/generators/pack_character_cast.py` rebuilds the pack from retained project
sources. It isolates silhouettes with alpha, handles extra generated walking
poses, normalizes each identity once and creates intermediate frames.

The raw pack uses about 164 MiB of process RAM and is loaded once, shared by all
locations, then released with the hall. It is CPU sprite data, not a separate
texture allocation per location. The ordinary animation-loader limits remain
unchanged; only this exact cast pointer, dimensions, count, payload and file size
can use the larger pack. No Python, neural model or network is used at runtime.

## Verification

`tools/tests/character_cast_test.inc` executes the native state resolver for all
ten identities and twelve states, checks identity boundaries and stable scale,
and captures sixty native poses plus eighty native walking frames.
`tools/tests/check_character_cast.py` checks
distinct identities, four animated gait directions, mirrored profile frames,
seated proportions, transparent borders, unclipped feet and throw progression.
It also checks native eye-level body scale and a substantial difference between
wide contact and narrow passing foot spans. Distinct pixel hashes alone did not
catch the old sheets' repeated leading-leg poses.
The full hall regression includes room navigation, roof, bars, doors and stairs.
Shipping/tested assembly parity is checked separately.
`roof_character_scale_test.inc` checks all eight rooftop visitors in standing and
walking states against that ratio and captures their native grounded silhouettes.

The older guest and bowling source packs are retained as historical assets;
the visitor renderers no longer load or use them.