Consolidate documentation into architecture and merged guides

2026-11-04 14:06:23 +01:00
1 parent aec1fb7b69
commit dee939c2ee
@@ -0,0 +1,148 @@
+# Venues
+
+The game uses two physical Hollywood blocks across three playable venue rows:
+
+- **Hollywood Boulevard** — the 6840 Hollywood Blvd / El Capitan Entertainment
+  Centre block, in day and night rows.
+- **The Joke Shop** — a fictional comedy club based on the Sunset Strip block
+  around 8433 Sunset Blvd.
+- **Late Night TV Studio** — the same El Capitan block restaged as a studio
+  arrival.
+
+The runtime implementation contract (facade specs, map budgets, navigation,
+colliders, phase behavior and fallback) lives in
+[`architecture.md`](architecture.md#venue-implementation-contract). This page
+keeps the real-site evidence, mapping decisions and deliberate simplifications.
+
+## Hollywood Boulevard
+
+### Real site
+
+- **Address:** 6840 Hollywood Boulevard, Hollywood, Los Angeles, CA 90028.
+- **Coordinates:** 34.10118 N, 118.34009 W; OpenStreetMap way `424024147`.
+- **Building:** the 1921 Hollywood Masonic Temple by John C. Austin, now the El
+  Capitan Entertainment Centre and the home of *Jimmy Kimmel Live!*. It is the
+  game's starting point for both the Hollywood shift and the TV Studio arrival.
+- **Facade:** light stone/render Neoclassical front, six oversized Ionic
+  columns, a recessed entrance up eight stone steps, ornamental door grilles,
+  a crosscut transom, two side entrances, and the Masonic parapet motto and
+  medallions.
+- **Neighbours:** the El Capitan Theatre immediately west, a modern retail block
+  east, and the Ovation Hollywood frontage across the four-lane boulevard.
+- **Sidewalk:** the Walk of Fame terrazzo strip with brass stars; red-painted
+  kerb in the reference photographs.
+
+### Game mapping
+
+| Real feature | In-game representation |
+| --- | --- |
+| 29.6 m wide, 14.5 m high facade | `VENUE_SPECS["hollywood_building"]`, front at `z = -4` |
+| Eight stone steps | 8 steps, 0.10 m rise, 0.38 m tread, 12 m wide |
+| Six Ionic columns | `IonicColonnade`, 4.96 m bay spacing |
+| Central + two side doors | 4.2 m central door, 2.5 m side doors with transoms |
+| Red event banners | three stylized `EL / CAPITAN / LIVE` banners |
+| Masonic motto + medallions | `FriezeInscription` and two stone discs |
+| El Capitan Theatre / east retail | library-neighbour blocks with marquee/blade or glazed shopfront |
+| Ovation Hollywood | arcade with seven arched openings, sign and south sidewalk |
+| Walk of Fame | dark terrazzo band with ten stars |
+| Four-lane boulevard | double-yellow centre, broken white lanes, red kerb, crosswalk |
+| TV Studio arrival | same six-column facade/eight steps plus bulb canopy, sedan, handrail and barriers |
+
+The generated references in
+[`screens/concepts/hollywood_boulevard/`](screens/concepts/hollywood_boulevard/README.md)
+are art direction for lighting, material scale and composition; they are not
+texture or geometry sources.
+
+### Late Night TV Studio
+
+The third venue is **not a separate real site**. It reuses the El Capitan block
+and restages it as a studio arrival: the same stone facade and steps, plus a
+bulb-lit canopy, glossy black car, barrier/stanchion line and audience queue.
+`VENUE_SPECS["tv_studio"]` is a 30.0 m variant of the Hollywood spec with the
+arrival staging; it shares this block's reference board.
+
+## The Joke Shop
+
+### Real site
+
+| Item | Reference |
+| --- | --- |
+| Address | 8433 Sunset Blvd, West Hollywood, CA 90069 |
+| Real venue | The Comedy Store (comedy club and theatre) |
+| OpenStreetMap | Way [`428854155`](https://www.openstreetmap.org/way/428854155), centroid 34.095265, -118.373965 |
+| Tags | `amenity=theatre`, `building=commercial`, `height=12.2`, `start_date=1940`, `wikidata=Q3520350` |
+| Footprint | OSM polygon about 47.1 m × 41.2 m across the club and rear parcels |
+| Street | Sunset Boulevard on the Sunset Strip |
+| Setting | Dry Hollywood Hills with houses and palms above the roofline |
+
+The building began as **Ciro's** (1940) and became The Comedy Store in the
+early 1970s. Its street front is a low black hall under a deep,
+signature-covered canopy, with a circular blade sign above the roof, red
+curtains along the frontage and the main entrance set toward the west end.
+
+### Game mapping
+
+| Real element | Game implementation |
+| --- | --- |
+| Low black comedy hall | 27 m × 12 m footprint, 6.0 m street wall, matte black concrete, low plinth and parapet |
+| Deep overhanging canopy | 4.9 m sloped slab at 11°, white signature fascia band and club name |
+| Signature-covered front | two `Label3D` signature bands plus a wall panel |
+| Circular blade sign | 3.9 m white disc on a roof pole, black `THE JOKE SHOP` wordmark |
+| Red curtains | seven tied-back velvet drapes with scalloped hems and dark recesses |
+| West-end entrance | recessed at x = -8.8 m, low step, brass pulls, door-lock indicator |
+| Practicals | sconces, canopy downlights, entrance wash, ground uplights; off by day, switched at night |
+| Neighbours | cream Mediterranean block with red awning; `WestHotelTower` mass behind; white commercial block east |
+| Hillside | fog-free unshaded ramp with stucco houses, shrubs and palms; dark silhouette at night |
+| Opposite Sunset | low retail row, rooftop billboard, neon and palms beyond the far kerb |
+| Street dressing | palms, barriers, stanchions, bins, planters, A-frame, hydrant and parked sedan |
+
+Key proportions are reconciled in the map budget and `VENUE_SPECS`; the full
+measured table is retained in the 3D review history. The playable frontage is
+27 m, the facade centre is at z = -8.0 and the front face at z = -2.0. The
+sidewalk is 38 m × 14 m, meeting the kerb at z = 11.9; the street is 90 m × 24 m.
+The guard starts west of the entrance at (-4.8, 0.1, 1.4), facing the approach.
+
+## Deliberate simplifications
+
+- Both blocks are stylized reconstructions, not survey models; show branding is
+  replaced by venue-neutral/fictional text while addresses and landmark
+  silhouettes are retained.
+- Interiors, basements, side streets, the Metro entrance and the Comedy Store's
+  rear rooms are out of playable bounds.
+- The Ovation frontage is one arcade block, not the full mall plan; neighbouring
+  businesses are generic low-rise masses and no current tenant is claimed.
+- The Joke Shop's rounded west corner is kept as a hard 90° corner; its hillside
+  is a background ramp with simplified houses, not a terrain heightfield.
+- Geometry uses boxes, cylinders and a small set of custom arch/star meshes to
+  stay inside the Compatibility/Web budget; concept frames are photoreal and the
+  runtime keeps a stylized material treatment.
+- Day/night is a phase offset on one geometry/scenario, not a second baked map.
+  The night row starts in `LATE` while the checkpoint stores the offset.
+
+## References
+
+- [Hollywood Masonic Temple — Wikipedia](https://en.wikipedia.org/wiki/Hollywood_Masonic_Temple)
+- [El Capitan Entertainment Centre — OpenStreetMap way 424024147](https://www.openstreetmap.org/way/424024147)
+- [El Capitan Theatre — OpenStreetMap way 424024148](https://www.openstreetmap.org/way/424024148)
+- [Ovation Hollywood — OpenStreetMap way 151485232](https://www.openstreetmap.org/way/151485232)
+- [Hollywood Masonic Temple facade — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:El_Capitan_Theater_frontal_fachade-The_Masonic_Temple.jpg)
+- [Hollywood Masonic Temple and El Capitan Theatre, 2013 — Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Hollywood_Masonic_Temple_2013-10-13_10-02-25.jpg)
+- [Comedy Store — OpenStreetMap way 428854155](https://www.openstreetmap.org/way/428854155)
+- Committed photo boards: [`screens/refs/hollywood/`](screens/refs/hollywood/README.md),
+  [`screens/refs/joke-shop/`](screens/refs/joke-shop/README.md); three-up boards
+  are in [`screens/boards/`](screens/boards/README.md).
+- Local-only research (never committed): `tmp/research/elcapitan-2026/`,
+  `tmp/research/jimmy-kimmel-entrance/`, `tmp/research/comedy-store/` and
+  `tmp/research/comedy-store-hillside/`. These are evidence for decisions, not
+  shipped assets.
+
+## Verification
+
+```bash
+godot --headless --path . --script res://src/test/test_runner.gd
+godot --path . --script res://src/test/capture_realism.gd -- --out=/tmp/gig-line-venues --stages=day,evening,late,joke_shop_day,joke_shop
+python3 tools/check_docs.py
+```
+
+The map-budget tests and the venue light-falloff gate are part of the headless
+suite; the screenshot/realism gates are optional review evidence.