LS-SPEC-006 — Legend World Engine

Status: Draft v1.4 — §8.2's World Manifest cache key correction (orientation_bucket added) is now confirmed and authoritative, resolving a genuine internal inconsistency discovered while engineering the Facility Commitment vertical slice. §1.1a (Candidate Site Request pass-through) remains confirmed and authoritative, along with formal determinism requirements (§2.2a, §6.4). No pending items remain. Architecture/specification only, not for implementation until reviewed. Governed by: LS-PLATFORM-ARCHITECTURE.md Depends on: LS-SPEC-005 (Legend Knowledge — the sole source of location/era truth this engine builds from, including candidate site generation as of v1.1)

Owns: The Environment Builder (Quick/Guided/AI-Assisted), environment zone modeling, the Venue Integration Interface (the contract any Legend Studios game implements to request a world, including the §1.1a candidate site pass-through as of v1.1), Living World vs. Frozen Era time-progression modes, the World ↔ Franchise bidirectional influence model, the UE5 World Manifest schema (deterministic as of v1.1, §6.4), multiplayer world-state consistency, and performance/scalability strategy for world generation.

Explicitly does not own: Any fact about what a place looked like at a given time (LS-SPEC-005 owns all of that; this engine consumes it, never re-derives or overrides it). Any sport-specific venue concept — field dimensions, court markings, track layout, dugouts, end zones, whatever a specific game's venue looks like on the inside is that game's own spec's responsibility (for Diamond Legend, this is DL-SPEC-014, not yet written — see §11). Rendering itself (UE5 consumes the World Manifest this engine produces; this engine does not touch a rendering pipeline).

Consumed by: Diamond Legend (as the first implementation, via DL-SPEC-014 once written), and, per your explicit design goal, any future Legend Studios title needing a persistent geographic/environmental world — Gridiron Legend as a football stadium, or any other venue type a future title needs.

Governing principle: World logic and sport logic never touch. This engine can be fully exercised and tested with zero knowledge of baseball, football, or any other sport — a Venue Integration Interface request is the only place sport-specific information enters, and it enters as an opaque parameter this engine passes through to environment-zone placement logic, never as something this engine's own code branches on by sport.

0. Foundational Architecture Decisions

0.1 Simulation Owns Truth, UE5 Visualizes It — Extending an Existing Principle

Per your own framing, and consistent with DL-SPEC-015's existing Golden Rule (simulation is source of truth, UE5 is a visualization client that never writes back): this engine's World Manifest (§6) is the second such interface in this project, alongside DL-SPEC-015's GameEventStream. One is for live gameplay events; this one is for the persistent environment surrounding them. Both follow the identical discipline.

0.2 The Venue Integration Interface Is the Only Door In

A consuming game never queries Legend Knowledge (LS-SPEC-005) directly, and never reaches into this engine's internal zone-placement or era-filtering logic — this includes candidate site generation (LS-SPEC-005 §1.3a), reached only through this engine's §1.1a pass-through, never directly. It sends one structured request (§1.1a or §1.1) and receives a response (a candidate list, or a World Manifest, §6). This is the same "one door, no side channels" discipline as every Game Adapter / Brand Adapter pattern already established in this project — applied here as a Venue Integration Interface instead.

1. Venue Integration Interface

1.1a Candidate Site Request (Authoritative — Confirmed Architecture Decision)

Preserves §0.2's "one door" principle now that LS-SPEC-005 §1.3a owns candidate site generation. The access path is fixed: Diamond Legend / DL-SPEC-014 → this engine's Venue Integration Interface → LS-SPEC-005 Legend Knowledge. A game requests candidate sites through this engine, never through Legend Knowledge directly:

CandidateSiteRequest       -- what the game sends to THIS engine
  settlement_id: string
  venue_type: string

CandidateSiteResponse      -- what this engine returns, after internally calling LS-SPEC-005 §1.3a
  candidates: SiteCandidate[]   -- identical shape to LS-SPEC-005 §1.3a's SiteCandidate, unmodified

This engine is only the access gateway. It must not independently generate, rank, filter, reinterpret, or persist candidate sites — every one of those responsibilities remains LS-SPEC-005's alone. This engine performs no transformation on the response beyond passing it through. The generation logic, and the guarantee that the result is never empty, remain entirely LS-SPEC-005 §1.3a's responsibility; this engine's only job is being the door the game walks through to reach it, consistent with §0.2's principle applying to every Legend Knowledge capability, not only the ones this document's v1.0 draft happened to enumerate.

Selecting a specific SiteCandidate.candidate_id and submitting it as the site field of §1.1's VenueWorldRequest is what triggers actual Site persistence (LS-SPEC-005 §1.3a) — this engine does not persist anything at the candidate stage, only at full VenueWorldRequest submission.

1.1 Request Shape

VenueWorldRequest
  location: settlement_id (or a new-fictional-settlement payload, per LS-SPEC-005 §1.4)
  visual_year: integer
  venue_type: string (opaque to this engine — "baseball_park", "football_stadium", "race_track", whatever the calling game defines)
  site: site_id (from a §1.1a CandidateSiteResponse selection, or a direct site_id if already known)
  venue_footprint: sport-specific dimensions/orientation data (fully opaque — this engine places the footprint within the generated world, it does not interpret what's inside it)
  world_mode: 'frozen_era' | 'living_world' (§4)

1.2 What "Opaque" Actually Means Here

This engine reads venue_footprint only as a bounding shape and an orientation vector to correctly place surrounding environment zones (§3) relative to it (e.g., "what's beyond right field" needs to know where right field points, not what right field is). It never validates, interprets, or stores sport-specific meaning from that field — that validation is entirely the calling game's own spec's job (for Diamond Legend, DL-SPEC-014).

1.3 Response Shape

A World Manifest (§6).

2. Environment Builder

2.1 Three Levels, One Underlying Parameter Set

All three levels ultimately produce the same structured world-generation parameters (zone assignments, landmark placements, era-filtered asset selections) — they differ only in how a player arrives at those parameters, not in what gets generated from them. This is a deliberate architectural choice: Quick Build's output is fully editable by dropping into Guided Builder afterward, because they're the same underlying representation, not three separate generation paths that happen to look similar.

2.2 Quick Build

Given a VenueWorldRequest (§1), this engine calls Legend Knowledge (LS-SPEC-005) for the location/era data available, applies default zone-placement heuristics (§3), and returns a complete World Manifest with no further player input required.

2.2a Determinism (Authoritative — Approved Studio Decision)

Quick Build, and every other generation path this engine exposes, is fully deterministic — identical VenueWorldRequest inputs always produce a byte-identical World Manifest. This extends LS-SPEC-005 §5.3/§14 INV-6's determinism requirement through this engine rather than introducing a separate rule: zone-placement heuristics (§3.2), asset selection within a zone (§3.3, itself reading LS-SPEC-005's deterministic Era API), and any apparent "choice" this engine makes must use a fixed, documented derivation from the request's own identifiers — never runtime randomness. See §6.3 for how this specifically guarantees World Manifest reproducibility.

2.3 Guided Builder

The player adjusts zone contents and landmark placement using only assets Legend Knowledge/era-filtering (LS-SPEC-005 §3.3) confirm are valid for the selected location and Visual Year — the era-integrity rule is enforced at the picker/selection level here, not just as a post-hoc validation, so a player is never shown an era-inappropriate option only to have it silently rejected.

2.4 AI-Assisted Builder

A natural-language description (your example: a 32,000-seat 1948 Cleveland ballpark description) is translated into the same structured world-generation parameters §2.1 describes — this is an intent-translation layer sitting in front of the identical Guided Builder parameter set, not a fourth independent generation path. Per LS-SPEC-005 §4.2's extraction principle, if a player's natural-language description references specific real photographic details, the same extract-don't-reproduce discipline applies to whatever this layer does with that input.

3. Environment Zones

3.1 Zone Taxonomy

Downtown, residential, industrial, commercial, agricultural, railroad, waterfront, forest, mountains/hills, entertainment, parking/transit, venue district — per your list, stored as a configurable taxonomy (not hardcoded), consistent with this project's data/engine separation discipline.

3.2 Zone Placement

Zones are placed relative to the venue's orientation (from §1.1's venue_footprint orientation vector) and to Legend Knowledge's terrain/waterway/transportation data for the settlement (LS-SPEC-005 §1.2) — a waterfront zone only appears where the settlement actually has a waterway, a railroad zone only where transportation data supports rail access for that era, and so on. Zone placement is era-aware in content (§3.3) but its geographic logic (what's near what) is grounded in Legend Knowledge's location facts, not invented independently per zone.

3.3 Era-Integrity Enforcement Within Zones

Every asset populating a zone is drawn from Legend Knowledge's era-filtered availability (LS-SPEC-005 §3.4) — this engine does not maintain a second era-filtering mechanism; it queries Legend Knowledge's Era API (LS-SPEC-005 §11) for every zone-content decision, consistent with the non-duplication discipline followed throughout this project.

3.4 Player Repositioning

Within Guided/AI-Assisted builders, a player may reposition landmarks within a zone, subject to remaining inside era-integrity constraints (§3.3) — repositioning is a placement change, never a mechanism for bypassing the asset-availability check.

4. Living World vs. Frozen Era

4.1 Frozen Era Mode

The world's Visual Year is fixed at franchise creation. New in-world construction (should the franchise's success drive development, per §5) continues to draw from that same fixed year's era-appropriate asset vocabulary — the world can still change, but always within one era's visual language.

4.2 Living World Mode

Time progresses with the dynasty. A franchise founded in 1920 can experience its surrounding world advance through 1940, 1960, 1990, and beyond, with buildings, transportation, and infrastructure changing to match — each transition re-querying Legend Knowledge for that settlement's data at the new Visual Year, not simply re-skinning the existing world.

4.3 Landmark Persistence Across Eras

A landmark (including the venue itself) can survive across multiple eras in Living World mode. This is modeled the same way this project has modeled every other long-lived entity: a landmark record carries a status (active / renovated / demolished / replaced) that changes over time but is never deleted — the same "never delete, only status-flag" discipline established since DL-SPEC-003, applied here to buildings instead of players.

4.4 Mode Selection Is Per-Franchise, Set at Creation

world_mode (§1.1) is chosen when the venue request is first made and governs that franchise's world going forward — this document does not currently specify a mid-dynasty mode switch; if that's wanted later, it's a deliberate future feature decision, not assumed here.

5. World ↔ Franchise Relationship

5.1 World-to-Franchise Influence

Location data (LS-SPEC-005) informs — but does not itself compute — a consuming game's attendance, land prices, construction costs, sponsorship opportunities, media market, regional draw, travel, and fan-culture modeling. This engine exposes the underlying facts (population, catchment, urban/rural classification, regional sports interest) through the World Manifest (§6); each game's own financial/franchise system (for Diamond Legend, DL-SPEC-008) is responsible for what those facts actually mean to gameplay. This mirrors the exact boundary already established between DL-SPEC-008 and DL-SPEC-011 for franchise value.

5.2 Franchise-to-World Influence — Development, Not Geography

Franchise success (fan loyalty, regional following, tourism, commercial development, venue-district development, franchise prestige, town identity) can influence the built environment's development level within a settlement — new construction in the venue district, upgraded infrastructure, expanded commercial zones — but never the settlement's underlying geographic facts (coordinates, terrain, waterways, historical population baseline prior to the franchise's founding). This is the precise mechanism behind your requirement that a tiny town can become a legendary sports town "without unrealistically changing its underlying geography": geography is immutable Legend Knowledge; development level is a mutable, franchise-influenced overlay this engine tracks per-settlement-per-franchise-world, not a change to Legend Knowledge's own records.

5.3 Development Level as Its Own Tracked State

franchise_world_development
  franchise_id
  settlement_id
  development_level (a scalar or tiered value, franchise-influenced, distinct from LS-SPEC-005's population/economic data)
  venue_district_state (jsonb — accumulated changes: new construction, upgraded infrastructure)
  last_updated_visual_year

This is deliberately a separate, engine-owned table from anything in LS-SPEC-005 — a franchise's accumulated influence on its home settlement's appearance is not the same fact as that settlement's actual historical/geographic truth, and keeping them structurally separate is what prevents one franchise's success from corrupting Legend Knowledge's shared, canonical data that other franchises (and other players, per LS-SPEC-005 §6's community sharing) also draw from.

6. UE5 World Manifest

6.1 Manifest Contents

Per your list: location, coordinates, visual year, terrain, climate, environment zones, architecture families, landmark descriptors, transportation, vegetation, venue orientation, horizon characteristics, density, lighting, weather, asset-era constraints, provenance.

6.2 Provenance Travels With the Manifest

Every element of the manifest retains the provenance tier (LS-SPEC-005 §2) it carried in Legend Knowledge — this is not stripped out for the UE5-facing output. A renderer (or a future in-game UI element showing "this is a historically reconstructed environment based on community references") can surface confidence information without a separate query back to Legend Knowledge.

6.3 Not Asset-Specific — Deliberately

Per your instruction, this document does not design around individual UE5 assets. The manifest describes what should exist and where (an architecture family, a zone content, a landmark descriptor) — translating that into specific UE5 meshes/materials is a future rendering-layer concern entirely outside this specification's scope, the same boundary DL-SPEC-015 already draws around its own GameEventStream.

6.4 Determinism Guarantee (Authoritative — Approved Studio Decision)

Identical VenueWorldRequest inputs always produce a byte-identical World Manifest. This is the concrete, testable form of §2.2a's engine-wide determinism requirement, specifically for this document's primary output. This is what makes exact-match acceptance testing possible (as opposed to approximate/statistical testing) for every consumer of this manifest, including DL-SPEC-014's own acceptance tests.

7. Multiplayer World Consistency (Gap Identified — Not in Original Scope List)

A shared multiplayer league (DL-SPEC-013) where multiple human GMs interact needs one consistent world state, not per-client-divergent generation — especially relevant for Living World mode (§4.2), where world state changes over time and every participant needs to see the same version of it. This engine's World Manifest generation and any Living-World era transitions should be logged through the same append-only event-log discipline DL-SPEC-013 §5.5 already established for league state — a world-state change is simply another event type in that log for multiplayer franchises, not a second consistency mechanism. For single-player franchises, this engine owns its own local world-state log, the same split DL-SPEC-011 §15 already uses for trade transaction logging.

8. Performance and Scalability

8.1 The Combinatorial Problem

Thousands of possible settlements × any Visual Year × Living World's multiple era transitions per franchise is combinatorially enormous. This engine does not pre-generate manifests for that space — generation is triggered on demand, at the moment a franchise actually requests a VenueWorldRequest (§1) or a Living-World era transition occurs, never speculatively.

8.2 Caching (Corrected — Confirmed Architecture Decision)

A real inconsistency was discovered during the Facility Commitment vertical slice engineering pass (see LEGEND-WORLD-VERTICAL-SLICE-002-FACILITY-COMMITMENT.md): §3.2 makes zone placement a function of the venue's orientation, but the cache key below, as originally written, omitted orientation entirely — meaning an orientation-changing renovation would silently return a stale manifest. This was not a missing-owner gap (this document already owns both the zone-placement rule and the cache key), just an internal error — corrected and confirmed here.

A generated manifest for a given (settlement_id, visual_year, site_id, orientation_bucket) combination is cached and reused across franchises that happen to choose the same combination. orientation_bucket is a deterministic bucketing of venue_footprint.orientation_vector only — no other component of venue_footprint (polygon shape, size) is included in the cache key unless a future engineering pass demonstrates it actually affects World Manifest generation, since §3.2's own stated design ties zone placement to orientation specifically, not to footprint geometry generally. Legend Knowledge's underlying facts (§0.1) don't change per-franchise, only §5.3's franchise-specific development overlay and orientation differ between two franchises that picked the same base location/era/site. This keeps regeneration cost proportional to genuinely new combinations, not proportional to franchise count.

8.3 Detail Scaling

Zone content detail can scale with actual in-game relevance (e.g., zones far from the venue, or not currently in camera/simulation focus, can carry a lower-detail manifest representation) — a detail-of-service concern for the rendering/client layer to request via the manifest's structure, not something this specification needs to fully resolve, but flagged as a real constraint any implementation will need to address.

9. Phased Implementation Plan

10. Acceptance Tests

Per your required test cases, each should exercise the full pipeline (LS-SPEC-005 data → this engine's zone/era logic → a valid World Manifest) with no location-specific code path:

INV-1 (restated from LS-SPEC-005 as the acceptance criterion for this engine specifically): none of the above test cases may require settlement-specific code in this engine's zone-placement, era-filtering, or manifest-generation logic — only settlement-specific data, sourced from LS-SPEC-005.

11. Cross-Spec Consistency Notes

• DL-SPEC-014 (Diamond Legend Stadium & Franchise Facilities) is currently only a placeholder in this project's dependency map. When it's written, it should be scoped as the Diamond-Legend-specific implementer of §1's Venue Integration Interface — owning field dimensions, walls, dugouts, bullpens, clubhouses, and any baseball-specific facility logic — and should explicitly not redefine any zone, era, or location logic this document and LS-SPEC-005 already own. This is the same "consume the interface, don't reimplement the platform" discipline as every other DL-tier document that sits atop an LS-tier one.
• DL-SPEC-015's Golden Rule (simulation is truth, UE5 visualizes) is extended, not duplicated, by §0.1/§6 — worth stating identically in both documents' text the next time DL-SPEC-015 is revisited.
• DL-SPEC-008's financial model is the expected consumer of §5.1's world-to-franchise facts for Diamond Legend specifically — this document does not compute attendance or land value itself, consistent with the ownership boundary already established between DL-SPEC-008 and DL-SPEC-011.
• DL-SPEC-013's League Event Log is the expected mechanism for §7's multiplayer world-state consistency — not a new logging system.

12. Recommended Next Steps

1. Write DL-SPEC-014 as the first real Venue Integration Interface implementer, once this document and LS-SPEC-005 are reviewed — this is the first true test of whether the World/Sport separation (§0) actually holds under a concrete baseball-specific implementation, not just in the abstract.
2. Resolve LS-SPEC-005 §13's curation-pipeline and asset-taxonomy work before attempting Phase 1's flagship-city seed data.
3. Treat Phase 4 (a second game) as a required validation step, not an optional stretch goal — per §10's INV-1, venue-agnosticism claimed but never exercised by a second real consumer is an unverified claim, not a proven one.