Skip to main content

Valenar Docs

Canonical documentation for the Valenar example game.

This tree is organized by stable owner surfaces plus navigation views. Use the first-pass path below for live reading, then branch into the topical clusters you need.

Start Here​

  • gd-canon.md - canonical act names, progression boundaries, Nexus/Wardheart wording, and live behavior vocabulary.
  • gd-glossary.md - shared terms for acts, Core/Camp/Settlement distinctions, polity ladder terms, and planning vocabulary.

Read these two pages first. If a support contract still carries older prototype wording, canon and glossary wording controls.

Surface Legend​

  • Canonical owner surface - one Markdown file owns one design, lore, or story object. Other docs link to it instead of duplicating it.
  • Navigation / view surface - act views, indexes, generated landings, and other reader-facing groupings that point at canonical owners without taking over ownership themselves.
  • Current contract - the canon, glossary, acts, systems, generation, catalogs, and current UX contracts in this tree.
  • Intended source surface - examples/valenar/Content/*.secs. Future designer-facing source.
  • Current executable stand-in - examples/valenar/Generated/*.cs. Hand-written stand-ins the runtime consumes today.
  • Compiler / shared-language backlog - workspace docs/design/ plus SECS-Compiler-Plan.md. Secondary for Valenar readers unless a doc explicitly sends you there.
  • Working docs - implementation/pr-roadmap.md, implementation/pr-wave-template.md, and implementation/pr-docs-codegen-rules.md.
  • Proposal-only docs - any page explicitly labeled proposal in the index below.

Ownership And Navigation Governance​

Quest Owners​

Cross-act lane owners (appear across multiple acts):

Local Quest and Mission owner surfaces remain reserved for later waves; until promotion, Local Quest guidance stays in pr-quest-owner-and-navigation-model.md and systems/gd-quest-and-lore-design.md, while current Mission appearance and planning vocabulary live in acts/gd-act-0-mission-spine.md and systems/gd-objectives-clues-missions.md.

Generated provenance stays strict: a generated file either cites a real Content/ source, uses an auto-generated marker, or uses the canonical no-source stand-in marker. Valenar docs should not invent a compiler run or a .secs source relationship.

First-pass path​

Quick Clusters​

Lore​

  • lore/pr-file-conventions.md - prefix scheme, cross-layer rules, canonicity and exposure tier definitions, Game 1 reveal-tier ceiling.
  • lore/adr/ - accepted lore-tree ADRs, including the decision to keep ADRs in a dedicated folder.
  • lore/universe/ul-cosmology.md - entry point for the ul-* universe lore set (cross-game canon: cosmology, demon cycle, hero calling, Wardhearts, super-world structure). The universe-design counterpart is lore/universe/ud-world-law.md.
  • lore/local/gl-afterwar-state.md - entry point for the gl-* game-local lore set for Valenar (Game 1): Afterwar state, MC Corebound origin, Earthborn backgrounds, demon remains, false-king arc, surviving nations, old hero traces, and cosmology traces.
  • lore/hooks/lh-game1-world-hooks.md - entry point for the lh-* exposure tables that map universe-scope facts to where, when, and how they surface in Game 1.

Story​

Acts​

Act docs are the canonical owners for Act Arcs and act-level outcome framing. They are also appearance views for the cross-act Quest Thread lanes listed under Quest Owners above; per-act lane references use ## Cross-Act Quest Thread Lanes sections inside each act doc. Local Quest and Mission owner surfaces remain reserved for later waves.

Systems​

State Machines And Lifecycle Primitives​

  • systems/state-machines-and-transitions.md - canonical 12-column transition row schema and the cross-doc hub for every Valenar state machine; cites the per-doc owner surfaces below and the existing FrontStatus / Force LifecycleState / Operation Phase precedents.
  • systems/quest-thread-and-mission-state-machine.md - scope QuestThread and scope Mission lifecycle primitives, the seven-rung Quest Thread and Mission lifecycle ladders, and the cross-act lane / Saga Arc binding.
  • systems/front-emergence.md - the six-tier ladder from Territory inputs through Province aggregation to ThreatSource, FrontCandidate, and Crown-declared Front, with the canonical on_action transition labels and the per-Province PlanState ladder.
  • systems/act-progression.md - the scope ActState saga-scoped singleton, the eight-rung Act ladder, the ActProgressionSystem, and the per-Act gate-predicate authoring contract.
  • systems/character-conditions-and-injuries.md - the MCCondition umbrella, the seven named conditions and five named injuries as Modifier templates, and the per-condition state-axis ladders.
  • systems/labor-and-capacity.md - Population partition vocabulary (Available / Dependent / Specialist), Settlement labor channels, the two-tier LaborShortageSignal aggregation, and Province-level rollups.
  • systems/combat-rules.md - the scope ContactEngagement persistent-engagement primitive, six-rung EngagementState ladder, and on_action transition labels.

Per-Act gate predicate specifications (each owns the predicate that gates one Act-to-Act transition):

Generation​

UX​

Catalogs​

Working And Proposal Surfaces​

Working Rules​

  • Acts are the canonical progression frame.
  • Core, Camp, Settlement, and Outpost are distinct systems.
  • Core Grounds is the preferred physical-area term for the MC's personal anchor compound at the starting Nexus/Wardheart. Core Grounds facilities serve the MC, named characters, wards, and expedition needs — not the population economy or settlement administration.
  • Founding the Core does not create the Settlement or the player-facing Realm.
  • Sites are first-class; dungeons are one site family once discovered or entered.
  • Named characters have skills and assignments; pops fill ordinary settlement jobs.
  • Current Plan sits above Objectives and Queue.
  • Objective, clue, mission, planning context, and activity remain distinct.
  • Live behavior vocabulary uses activity and policy; higher-level planning docs do not promote a separate executable term above activities.
  • Live behavior vocabulary uses activity and policy.
  • The current executable map is a stepping-in prototype fixture, not the final world-scale commitment.