heros_web/docs/city-stay-immersion-upgrade-report.md

City-stay immersion upgrade

Date: 2026-07-27

Why this batch

The playable Xuzhou, Xinye, and Chengdu stays already connected information, equipment, and companion choices to later battles, but their presentation still used code-drawn buildings and tactical unit sheets. This made the between-battle experience visibly regress after the hand-painted prologue and Guangzong exploration scenes.

The upgrade follows four established design lessons:

• GDC's wayfinding and storytelling session recommends conveying information through architecture and readable spatial navigation.
• GDC's environmental storytelling framework treats props, materials, lighting, composition, and world reaction as parts of the narrative rather than decoration.
• The Tacoma non-linear story-discovery workshop connects self-directed exploration order to story discovery.
• The cognitive-map talk emphasizes memorable landmarks and navigable spaces when navigation is not intended to be the challenge.

Applied here, every city retains the same learnable crossroads grammar while its government office, market, companion residence, materials, climate, and recovery state communicate a different campaign moment.

Runtime assets

Stay	Background	Named companion SD sheet
Xuzhou	src/assets/images/exploration/city-xuzhou-stay.webp	characters/exploration-mi-zhu.webp
Xinye	src/assets/images/exploration/city-xinye-stay.webp	characters/exploration-zhuge-liang.webp
Chengdu	src/assets/images/exploration/city-chengdu-stay.webp	characters/exploration-huang-quan.webp

The three backgrounds are original 1920x1080 opaque WebP assets. The three named companion sheets are original 3072x768 transparent WebP sheets using the shared four-direction, eight-idle-frame, and eight-walk-frame contract.

Built-in image generation prompt set

All six assets used the built-in image generation workflow. No commercial-game screenshots, logos, character art, or copyrighted layouts were used.

Common city background prompt

Original premium late-Eastern-Han walkable city-stay environment for a desktop historical RPG, fixed elevated three-quarter top-down camera, broad readable north-south avenue and east-west crossroads, government office at upper-left, market at upper-right, companion residence at lower-right, and a clear bottom-center road back to camp. Preserve the top, right, and bottom fixed-HUD regions as dark low-detail safe zones. Rich painterly realistic materials and strong landmarks. No people, animals, readable text, labels, UI, logo, watermark, modern object, copied architecture, or copyrighted game screen.

The Xuzhou variant shows a recently relieved provincial city with cart tracks, sealed grain crates, and merchant storehouses at warm late afternoon. The Xinye variant shows a greener autumn frontier town with timber palisades, scout forecourts, bamboo, and an adviser residence before Bowang. The Chengdu variant shows a wealthier Yi Province capital after surrender, with damp stonework, organized granaries, petition space, and restrained new administration.

Common named SD turnaround prompt

Create one completely original 2.5-head-tall painterly cel-shaded SD overworld character. Show the same identity exactly three times in equal horizontal columns: front/south, screen-right/east with face and toes pointing toward the right edge, and back/north. Keep identical scale and lighting, a neutral walking-ready stance, and the full body and feet. Use a perfectly flat solid #ff00ff removable chroma-key background with no floor, shadow, gradient, texture, text, label, grid, logo, watermark, extra character, or copied commercial-game likeness.

The character variants preserve only identity and palette from the project's own portrait assets:

• Mi Zhu: cream, navy, and restrained gold merchant-official robes.
• Zhuge Liang: ivory and dark-jade scholar robes with a rolled strategist cap.
• Huang Quan: dark navy and muted bronze Yi Province official robes.

The generated turnarounds were chroma-cleaned with the installed image generation helper and assembled with scripts/build-exploration-character-sheet.py. Only optimized runtime assets are tracked.

Interaction and presentation scope

• Replace code-drawn city blocks with the dedicated original background for each city while retaining the proven interaction layout and collision contract.
• Use exploration SD sheets for Liu Bei, clerks, smiths, and named companions; tactical sprites remain battle-only.
• Use face portraits in dialogue rather than shrinking a full-body field sprite into the dialogue window.
• Let a pointer click on an activity target complete the old-RPG interaction loop: walk to a valid nearby position, face the target, and interact without a second click.
• Preserve keyboard movement and direct interaction, and preserve the information, purchase, equipment, resonance, save, and later-battle payoff state.

Verification

Verification is performed at an explicit 1920x1080 CSS viewport, 100% browser zoom, and DPR 1. WebGL is the required renderer and Canvas is the compatibility renderer.

The completed checks cover:

• all three 1920x1080 background dimensions, opacity, and the combined 2.87 MiB exploration-background budget;
• all thirteen exploration sheets at 3072x768 with alpha and the shared four-direction animation contract;
• CityStayScene type and data integrity, including equipment offers, visit rewards, resonance links, soundscapes, and lookup helpers;
• real pointer travel to information, market, companion, and exit targets, automatic one-time interaction, authored NPC positions, low-frame-rate arrival clamping, collision detours, and distance-gated keyboard interaction;
• face-only dialogue portraits, intentional portrait-free narrator lines, market purchase, resonance choice, reward idempotence, save/reload restoration, optional early exit, and next-battle briefing payoff;
• Xuzhou, Xinye, and Chengdu in both Canvas and WebGL at the required desktop baseline, with representative screenshots written as dist/verification-city-*-map.png, dist/verification-city-*-information.png, and dist/verification-city-*-dialogue.png;
• the complete static, build, loader-lifecycle, interaction, accessibility, battle keyboard, prologue, pursuit, relief, third-return, third-camp, audiovisual, release-candidate, and performance gates.

The review also corrected four edge cases before release: legacy invisible blockers from the former vector city, a portrait crop whose origin followed the uncropped source image, east/west rows reversed in the three new SD sheets, and pointer movement that could oscillate across a destination at a 50 ms frame interval. A CampScene browser fixture was also made to wait for the third-camp exploration button's rendered interactive state instead of reading it during scene-restart asset loading.