# How to review and develop this prototype

## Start here

Open `review.html` in your browser for the visual review board. To watch the interactive scene, run `./run.sh`, or open `project.godot` in Godot and press **F5**. You direct the story and art; I can maintain assets, data and scripts through our conversations.

The complete prologue is assembled as a **cutscene**. Characters follow scripted routes, turn to speakers, lean against the wall, enter and leave. You do not control them. Collision and pathfinding are unnecessary for this staging approach.

Autoplay and narration start enabled. Press **A** for manual dialogue, then **Space / Enter / click** to reveal and advance. **F2** pauses for the cast gallery. **B** shows the current original paragraph for fidelity checks. Text reveals at about 70 characters/second with brief punctuation pauses. V in the cast gallery switches fiddle-soldier walk/run. All controls are in README.md.

## The tools

- **Godot 4.7.2** combines images, animation and text into a scene. It is installed locally; no paid engine or external dialogue framework is needed.
- **Built-in ImageGen** works directly in this Codex session without your own API key. It creates new art and reference-based revisions.
- **Aseprite** is available locally for alpha cleanup, cropping, uniform scaling, frame alignment, palette experiments and exports. New character/environment art comes from ImageGen.
- **Python helpers** compile your text and analyse image boundaries/dimensions. You do not need them to play.

## How the art becomes a game

**References** establish identity, clothing or atmosphere. A large character drawing does not automatically become a readable small sprite.

**Game assets** are the actual small walk frames, busts, tiles and props. Each current character uses a 48×64 frame with a common foot anchor. The child is smaller than adults inside that frame.

**Sprite sheets** collect animation frames. The four speakers now have four walk phases (contact, passing, opposite contact, opposite passing) across four direction rows (south, west, east, north). Idle is a separate strip. The acolyte keeps its earlier three-column sheet. Fiddle soldier also has a separate running atlas, used on arrival and after the order. Tiptoe rises and holds; soldier leaning is a held pose. Correct sheet dimensions alone do not guarantee good motion. See MOTION_REVISION.md for this iteration.

**Tile maps** reuse 32×32 pieces of stone to build the floor and wall. Coordinates begin at `(0, 0)` in the upper left. You can request “less damaged stone at `(8, 6)`” or “move the entrance two columns left.” Characters can stop between tile centres because routes are authored separately.

**Layers** put the distant city behind masonry, actors over the floor, the vane and smoke above the world, and dialogue over the scene. The panorama appears briefly at the opening, and a city crop supplies the distant map background. It does not replace the top-down map.

## What 1080p means

The game draws **640×360 logical pixels**, enlarged exactly **3×** at 1920×1080. This keeps pixel edges crisp. Portraits currently occupy 160×192 logical pixels; **L** previews a smaller presentation.

Image generation produced large source masters, not guaranteed native-resolution pixel grids. Aseprite prepared the game exports. The sprites still need visual approval and pixel polish; readable motion and consistent proportions matter more than extra detail.

## Giving direction

Review identity and age first, then sprite silhouettes/motion, portrait size and map composition. Useful feedback can be specific:

- “Ganoes looks too old in the proud portrait.”
- “The commander’s east-facing second step changes his hair shape.”
- “Surly should look plainer and less elegant.”
- “The floor around `(12, 7)` is too busy.”
- “Keep the large busts, but give the text more room.”

Nothing generated overnight is automatically approved. The rejected distorted sprite remains excluded. The book is authoritative; we can read ahead freely for continuity, while keeping ages and equipment appropriate to this scene.

## Reusable foundations

The scene runner, actor animation, expressions, dialogue panel, tile layers, coordinate overlay and review gallery can later support original games. Book text and character designs live separately as content. We can extend these foundations after the art direction and first scene feel right.

## Portrait expression transitions

Expressions blend in place over 0.20 seconds, using the existing aligned portraits. This is an image blend, with no geometric face warping. Dialogue and the F2 gallery share the same component. Choose a character with 1–4, then Tab to cycle expressions. Speaker changes do not blend different faces together.

The short preview is art/previews/portrait_transitions_v1.mp4. Re-render it with Godot's movie recorder and `-- --review-emotions --capture-review`. That mode uses expression-preview captions and does not change the story dialogue.

Timing lives in scripts/portrait_view.gd (`EXPRESSION_BLEND_SECONDS`). The shader blends colours with alpha-aware edges and nearest pixel sampling. Rapid changes queue the latest expression; layout/gallery refreshes do not restart the transition.

## Walking weight

The F2 gallery now shows stride-linked head/body movement. Walk_v6 uses eight timed phases from four existing drawings, with small integer-pixel offsets and retained planted soles. See WALK_STUDY.md for the online references, before/after video and asset reproduction commands. `./run.sh res://scenes/walk_review.tscn` opens the focused motion comparison.

## Audio review

F3 opens the music and sound panel. Choose A/B/C, adjust the separate volumes, or enable quiet dialogue ticks. U mutes all sound. The scene pauses while the panel is open, leaving music and wind playing for comparison. Settings are saved locally. The review board has three 30-second scene films and isolated audio samples; see AUDIO_DIRECTION.md for the current candidates and their limitations.