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.

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.

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.

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