diff --git a/README.md b/README.md index 208c81e..8e9079a 100644 --- a/README.md +++ b/README.md @@ -106,6 +106,7 @@ Full setup, every run/test/smoke command, and the controls table are in - [`DONE.md`](DONE.md) — Completed task sections. - [`MEMORY.md`](MEMORY.md) — Persistent session notes. - [`CHANGELOG.md`](CHANGELOG.md) — User-facing changes by version. +- [`docs/README.md`](docs/README.md) — Documentation index and visual previews. - [`docs/architecture.md`](docs/architecture.md) — arc42-style architecture documentation. - [`docs/gameplay.md`](docs/gameplay.md) — Gameplay systems, venues, and the escalation model. - [`docs/tutorial.md`](docs/tutorial.md) — First-shift tutorial beats and rules. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..d56c798 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,31 @@ +# Gig Line Documentation + +This folder holds the project documentation, visual references and generated QA evidence. + +## Start here + +- [`../PLAN.md`](../PLAN.md) — product and game-design plan +- [`gameplay.md`](gameplay.md) — controls, venues and escalation +- [`tutorial.md`](tutorial.md) — first-shift tutorial beats +- [`architecture.md`](architecture.md) — arc42 system architecture +- [`getting-started.md`](getting-started.md) — setup, run/test commands and controls +- [`asset-tooling.md`](asset-tooling.md) — image/model pipelines and screenshot gates +- [`development-status.md`](development-status.md) — implemented features and current gaps +- [`smoke-checklist.md`](smoke-checklist.md) — manual verification +- [`RELEASING.md`](RELEASING.md) — export, CI and publishing workflow +- [`adr/README.md`](adr/README.md) — architecture decisions + +## Visual references + +- [`screens/README.md`](screens/README.md) — concepts, designs, screenshots and realism runs +- [`blender_previews/README.md`](blender_previews/README.md) — character/gear/prop previews +- [`screenshots/README.md`](screenshots/README.md) — committed game gallery + +## Quick preview + +| Reference | Screenshot | +| --- | --- | +| Venue design | Venue overview design | +| Current entrance | In-game venue overview | +| Character sheet | NPC character sheet | +| Prop sheet | Prop asset sheet | diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..04f198e --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,20 @@ +# Architecture Decision Records + +Each ADR records the context, decision, consequences and alternatives for a durable architecture choice. + +## Decisions + +- [0001-venue-driven-simulation-architecture](0001-venue-driven-simulation-architecture.md) +- [0002-de-escalation-first-escalation-model](0002-de-escalation-first-escalation-model.md) +- [0003-explicit-access-verification-system](0003-explicit-access-verification-system.md) +- [0004-local-single-player-first](0004-local-single-player-first.md) +- [0005-event-based-incident-recording](0005-event-based-incident-recording.md) +- [0006-godot-4-gdscript](0006-godot-4-gdscript.md) +- [0007-locomotion-and-input-layers](0007-locomotion-and-input-layers.md) +- [0008-cone-focus-and-head-ring](0008-cone-focus-and-head-ring.md) +- [0009-radial-action-menu](0009-radial-action-menu.md) +- [0010-procedural-npc-presentation](0010-procedural-npc-presentation.md) +- [0011-aim-free-selection-and-precision-walk](0011-aim-free-selection-and-precision-walk.md) +- [0012-surface-materials-and-generated-props](0012-surface-materials-and-generated-props.md) +- [0013-blender-authored-npc-characters](0013-blender-authored-npc-characters.md) +- [0014-runtime-image-root](0014-runtime-image-root.md) diff --git a/docs/blender_previews/README.md b/docs/blender_previews/README.md new file mode 100644 index 0000000..509a292 --- /dev/null +++ b/docs/blender_previews/README.md @@ -0,0 +1,57 @@ +# Blender Previews + +Committed contact sheets and local Blender renders for the character, gear and prop library. Individual PNGs are development previews and are gitignored; the sheets are tracked. + +## Image previews + +| Preview | File | +| --- | --- | +| a_frame_sign.png | [`a_frame_sign.png`](a_frame_sign.png) | +| backpack.png | [`backpack.png`](backpack.png) | +| beanie.png | [`beanie.png`](beanie.png) | +| bench.png | [`bench.png`](bench.png) | +| bollard.png | [`bollard.png`](bollard.png) | +| camera.png | [`camera.png`](camera.png) | +| cap.png | [`cap.png`](cap.png) | +| clipboard.png | [`clipboard.png`](clipboard.png) | +| crowd_barrier.png | [`crowd_barrier.png`](crowd_barrier.png) | +| cup.png | [`cup.png`](cup.png) | +| double_door.png | [`double_door.png`](double_door.png) | +| fire_hydrant.png | [`fire_hydrant.png`](fire_hydrant.png) | +| firefighter_helmet.png | [`firefighter_helmet.png`](firefighter_helmet.png) | +| flashlight.png | [`flashlight.png`](flashlight.png) | +| handrail.png | [`handrail.png`](handrail.png) | +| hood.png | [`hood.png`](hood.png) | +| lanyard.png | [`lanyard.png`](lanyard.png) | +| marquee.png | [`marquee.png`](marquee.png) | +| newspaper_box.png | [`newspaper_box.png`](newspaper_box.png) | +| npc_casual.png | [`npc_casual.png`](npc_casual.png) | +| npc_coat.png | [`npc_coat.png`](npc_coat.png) | +| npc_dress.png | [`npc_dress.png`](npc_dress.png) | +| npc_firefighter.png | [`npc_firefighter.png`](npc_firefighter.png) | +| npc_guard.png | [`npc_guard.png`](npc_guard.png) | +| npc_hoodie.png | [`npc_hoodie.png`](npc_hoodie.png) | +| npc_jacket.png | [`npc_jacket.png`](npc_jacket.png) | +| npc_vest.png | [`npc_vest.png`](npc_vest.png) | +| palm_tree.png | [`palm_tree.png`](palm_tree.png) | +| phone.png | [`phone.png`](phone.png) | +| planter_box.png | [`planter_box.png`](planter_box.png) | +| protest_sign.png | [`protest_sign.png`](protest_sign.png) | +| radio.png | [`radio.png`](radio.png) | +| round_planter.png | [`round_planter.png`](round_planter.png) | +| scba_tank.png | [`scba_tank.png`](scba_tank.png) | +| security_podium.png | [`security_podium.png`](security_podium.png) | +| sedan.png | [`sedan.png`](sedan.png) | +| sheet_npc.jpg | [`sheet_npc.jpg`](sheet_npc.jpg) | +| sheet_npc_gear.jpg | [`sheet_npc_gear.jpg`](sheet_npc_gear.jpg) | +| sheet_props.jpg | [`sheet_props.jpg`](sheet_props.jpg) | +| shoulder_bag.png | [`shoulder_bag.png`](shoulder_bag.png) | +| stanchion.png | [`stanchion.png`](stanchion.png) | +| street_lamp.png | [`street_lamp.png`](street_lamp.png) | +| street_tree.png | [`street_tree.png`](street_tree.png) | +| sunglasses.png | [`sunglasses.png`](sunglasses.png) | +| traffic_cone.png | [`traffic_cone.png`](traffic_cone.png) | +| trash_bin.png | [`trash_bin.png`](trash_bin.png) | +| umbrella.png | [`umbrella.png`](umbrella.png) | +| wall_lantern.png | [`wall_lantern.png`](wall_lantern.png) | +| wand.png | [`wand.png`](wand.png) | diff --git a/docs/screens/README.md b/docs/screens/README.md new file mode 100644 index 0000000..6c97b3c --- /dev/null +++ b/docs/screens/README.md @@ -0,0 +1,16 @@ +# Screens and Visual Evidence + +Visual references and generated QA evidence for Gig Line. + +- [`concepts/README.md`](concepts/README.md) — AI-assisted realism concept frames +- [`designs/README.md`](designs/README.md) — screen-design mockups +- [`../screenshots/README.md`](../screenshots/README.md) — committed game gallery +- [`realism/README.md`](realism/README.md) — locally generated realism runs (gitignored) + +## Quick preview + +| Screen | Reference | Current capture | +| --- | --- | --- | +| Venue | Venue design | Venue capture | +| Joke Shop | Joke Shop design | Joke Shop capture | +| TV Studio | Studio design | Studio capture | diff --git a/docs/screens/concepts/README.md b/docs/screens/concepts/README.md index d8abcdb..aa74e80 100644 --- a/docs/screens/concepts/README.md +++ b/docs/screens/concepts/README.md @@ -1,40 +1,83 @@ # Scene concepts: the realistic target look -These are AI-generated example frames (`python3 tools/scene_concepts.py generate --group scene`, -`openai/gpt-5-image-mini`, 1280×720) for the realism pass. They are art direction, not -assets. `tools/scene_concepts.py realism` pairs them with the in-game shots from -`src/test/capture_realism.gd` (see `SHOTS` in the tool). New generations never overwrite a -file here; they are saved as `-vN.png`. +These are AI-generated example frames (`python3 tools/scene_concepts.py generate --group scene`, `openai/gpt-5-image-mini`, 1280×720) for the realism pass. They are art direction, not assets. `tools/scene_concepts.py realism` pairs them with the in-game shots from `src/test/capture_realism.gd` (see `SHOTS` in the tool). New generations never overwrite a file here; they are saved as `-vN.png`. -| Concept | Visual targets it sets | -| --- | --- | -| `hollywood_entrance_morning` | warm low sun, long soft shadows, brick with visible mortar and wear, stone plinth, potted topiary, haze that fades the far street to beige | -| `hollywood_entrance_golden_hour` | strong back light and rim light on people, marquee bulbs reading even in daylight | -| `hollywood_entrance_rain_night` | dark scene lit by practical lights only (marquee, sodium lamps), wet glossy ground with reflections, fog | -| `boulevard_skyline_day` | deep layered skyline with real towers and haze, palms lining the road, red curb paint, believable asphalt | -| `boulevard_skyline_dusk` | purple/orange gradient sky, neon signs, lit windows, car light trails | -| `joke_shop_alley_evening` | narrow brick alley, one warm wall lantern as key light, deep shadows, people in dark jackets | -| `joke_shop_door_closeup` | close material detail: brick, mortar, aged wood door, brass | -| `studio_stage_door_night` | granite facade, a bright bulb canopy as the main light, a glossy black car, stanchions and a barrier | -| `sidewalk_material_closeup` | paver joints, stains, granite curb, aggregate asphalt and a tree grate at grazing light | -| `entrance_steps_podium` | granite steps, handrails, glass doors, the check-in podium | -| `crowd_barrier_line` | steel barriers, a red carpet, a crowd with depth-of-field haze | -| `responder_arrival_wide` | fire engine, turnout gear, red/blue light spill on wet pavement | -| `npc_portrait_day` | close portrait of a pedestrian: skin with visible pores and stubble, fabric weave, shallow depth of field. The bar for an avatar close-up, not for the crowd shots | +## Concept list -The `npc_portrait` capture in `capture_realism.gd` is staged, not posed by the -crowd: it freezes one NPC on an open patch of sidewalk, parks the rest of the -crowd out of frame, turns the subject into the camera and stands the guard on the -sunlit side. It is the only shot where a face fills the frame, so it is the one to -eyeball after an avatar change (generate a local run under `docs/screens/realism/`). +### Hollywood Entrance + +![hollywood entrance morning](hollywood_entrance_morning.png) +warm low sun, long soft shadows, brick with visible mortar and wear, stone plinth, potted topiary, haze that fades the far street to beige + +### Hollywood Entrance Golden Hour + +![hollywood entrance golden hour](hollywood_entrance_golden_hour.png) +strong back light and rim light on people, marquee bulbs reading even in daylight + +### Hollywood Entrance Rain Night + +![hollywood entrance rain night](hollywood_entrance_rain_night.png) +dark scene lit by practical lights only (marquee, sodium lamps), wet glossy ground with reflections, fog + +### Boulevard Skyline + +![boulevard skyline day](boulevard_skyline_day.png) +deep layered skyline with real towers and haze, palms lining the road, red curb paint, believable asphalt + +### Boulevard Skyline Dusk + +![boulevard skyline dusk](boulevard_skyline_dusk.png) +purple/orange gradient sky, neon signs, lit windows, car light trails + +### Joke Shop Alley Evening + +![joke shop alley evening](joke_shop_alley_evening.png) +narrow brick alley, one warm wall lantern as key light, deep shadows, people in dark jackets + +### Joke Shop Door Closeup + +![joke shop door closeup](joke_shop_door_closeup.png) +close material detail: brick, mortar, aged wood door, brass + +### Studio Stage Door Night + +![studio stage door night](studio_stage_door_night.png) +granite facade, a bright bulb canopy as the main light, a glossy black car, stanchions and a barrier + +### Sidewalk Material Closeup + +![sidewalk material closeup](sidewalk_material_closeup.png) +paver joints, stains, granite curb, aggregate asphalt and a tree grate at grazing light + +### Entrance Steps Podium + +![entrance steps podium](entrance_steps_podium.png) +granite steps, handrails, glass doors, the check-in podium + +### Crowd Barrier Line + +![crowd barrier line](crowd_barrier_line.png) +steel barriers, a red carpet, a crowd with depth-of-field haze + +### Responder Arrival Wide + +![responder arrival wide](responder_arrival_wide.png) +fire engine, turnout gear, red/blue light spill on wet pavement + +### NPC Portrait Day + +![npc portrait day](npc_portrait_day.png) +close portrait of a pedestrian: skin with visible pores and stubble, fabric weave, shallow depth of field. The bar for an avatar close-up, not for the crowd shots + +The `npc_portrait` capture in `capture_realism.gd` is staged, not posed by the crowd: it freezes one NPC on an open patch of sidewalk, parks the rest of the crowd out of frame, turns the subject into the camera and stands the guard on the sunlit side. It is the only shot where a face fills the frame, so it is the one to eyeball after an avatar change (generate a local run under `docs/screens/realism/`). Cross-cutting targets, for comparison with locally generated realism runs: -- **Exposure.** The concepts keep the ground mid-grey. The game's sidewalk is close to white, - so it is overexposed. -- **Night means dark.** The night/dusk concepts are lit by practical lights. The game's - "Evening" phase is a bright pink-orange frame. -- **Depth.** The concepts show a layered skyline fading into haze. The new v2 skyline strips - supply this; the old box skyline did not. -- **Geometry and foliage.** The facades have plinths, cornices and deep window reveals, and the - trees and shrubs are organic. The game uses flat walls and blob trees. +- **Exposure.** The concepts keep the ground mid-grey. The game's sidewalk is close to white, so it is overexposed. +- **Night means dark.** The night/dusk concepts are lit by practical lights. The game's "Evening" phase is a bright pink-orange frame. +- **Depth.** The concepts show a layered skyline fading into haze. The new v2 skyline strips supply this; the old box skyline did not. +- **Geometry and foliage.** The facades have plinths, cornices and deep window reveals, and the trees and shrubs are organic. The game uses flat walls and blob trees. + +## Additional previews + +![npc_portrait_day-v2.png](npc_portrait_day-v2.png) diff --git a/docs/screens/designs/README.md b/docs/screens/designs/README.md new file mode 100644 index 0000000..32a1555 --- /dev/null +++ b/docs/screens/designs/README.md @@ -0,0 +1,29 @@ +# Screens/Designs + +Screen-design mockups used by the comparison and vision-judge gates for the runtime UI. + +## Image previews + +| Preview | File | +| --- | --- | +| access_inspection.png | [`access_inspection.png`](access_inspection.png) | +| body_camera_timeline.png | [`body_camera_timeline.png`](body_camera_timeline.png) | +| crowd_panic.png | [`crowd_panic.png`](crowd_panic.png) | +| emergency_radio.png | [`emergency_radio.png`](emergency_radio.png) | +| escalation_hud.png | [`escalation_hud.png`](escalation_hud.png) | +| joke_shop_queue.png | [`joke_shop_queue.png`](joke_shop_queue.png) | +| late_night_avenue.png | [`late_night_avenue.png`](late_night_avenue.png) | +| movement_precision.png | [`movement_precision.png`](movement_precision.png) | +| night_flashlight.png | [`night_flashlight.png`](night_flashlight.png) | +| pause_overlay.png | [`pause_overlay.png`](pause_overlay.png) | +| prop_gallery.png | [`prop_gallery.png`](prop_gallery.png) | +| radial_menu.png | [`radial_menu.png`](radial_menu.png) | +| radio_report.png | [`radio_report.png`](radio_report.png) | +| responder_arrival.png | [`responder_arrival.png`](responder_arrival.png) | +| settings_panel.png | [`settings_panel.png`](settings_panel.png) | +| shift_review.png | [`shift_review.png`](shift_review.png) | +| start_menu.png | [`start_menu.png`](start_menu.png) | +| studio_arrival.png | [`studio_arrival.png`](studio_arrival.png) | +| targeting_npc.png | [`targeting_npc.png`](targeting_npc.png) | +| venue_overview.png | [`venue_overview.png`](venue_overview.png) | +| wand_screening.png | [`wand_screening.png`](wand_screening.png) | diff --git a/docs/screenshots/README.md b/docs/screenshots/README.md new file mode 100644 index 0000000..329fa08 --- /dev/null +++ b/docs/screenshots/README.md @@ -0,0 +1,21 @@ +# Screenshots + +Committed gallery captures generated from the current build by src/test/capture_screenshots.gd and src/test/capture_prop_gallery.gd. + +## Image previews + +| Preview | File | +| --- | --- | +| 01-venue-overview.png | [`01-venue-overview.png`](01-venue-overview.png) | +| 02-targeting-npc.png | [`02-targeting-npc.png`](02-targeting-npc.png) | +| 03-access-inspection.png | [`03-access-inspection.png`](03-access-inspection.png) | +| 04-radio-report.png | [`04-radio-report.png`](04-radio-report.png) | +| 05-late-night-avenue.png | [`05-late-night-avenue.png`](05-late-night-avenue.png) | +| 06-night-flashlight.png | [`06-night-flashlight.png`](06-night-flashlight.png) | +| 07-wand-screening.png | [`07-wand-screening.png`](07-wand-screening.png) | +| 08-escalation-hud.png | [`08-escalation-hud.png`](08-escalation-hud.png) | +| 09-body-camera-timeline.png | [`09-body-camera-timeline.png`](09-body-camera-timeline.png) | +| 10-prop-gallery.png | [`10-prop-gallery.png`](10-prop-gallery.png) | +| 11-precision-walk.png | [`11-precision-walk.png`](11-precision-walk.png) | +| 12-joke-shop.png | [`12-joke-shop.png`](12-joke-shop.png) | +| 13-studio-arrival.png | [`13-studio-arrival.png`](13-studio-arrival.png) |