Skip to main content

Valenar Docs Codegen Rules

This page explains how Valenar docs should describe Content/, Generated/, and the compiler without inventing syntax, ownership, or provenance.

Current Source Of Truth Split​

Valenar v2 currently has one source-authority pipeline for game definitions:

  • examples/valenar-v2/Content/*.secs is the designer-facing source of truth for schema-owned Valenar rows and catalog metadata.
  • examples/valenar-v2/Generated/Valenar.V2.Generated.csproj runs secsc, emits compiler-owned C# into obj/**/SecsGenerated, and compiles that output.
  • examples/valenar-v2/Generated/ValenarHostIds.cs is the only retained checked-in .cs file. It is explicit host-owned runtime ID metadata, not schema or catalog authority.

What Docs May Claim​

Docs may say all of the following:

  • Content/ is the source of truth for compiler-owned Valenar schema rows and catalog metadata.
  • Compiler-emitted files live under Generated/obj/**/SecsGenerated and include SecsModule.g.cs, Hashes.g.cs, row-family outputs, catalog sidecars, author enums, travel encounter definitions, and config defaults.
  • The checked-in Generated/ root is intentionally tiny: the project file plus ValenarHostIds.cs.
  • ValenarHostIds.cs may be cited only as host-owned runtime/relation ID metadata.

Docs must not say any of the following unless a committed design doc proves it:

  • that a nonexistent keyword or clause is committed source syntax
  • that candidate_builder, with builder, or from collection ... with builder ... are committed or reserved .secs syntax
  • that a retired checked-in generated file remains a source of authority
  • that a fabricated .secs file exists to justify provenance
  • that fabricated provenance, source links, or source relationships are acceptable documentation shortcuts
  • that host-owned runtime helpers are evidence of approved source syntax
  • that retired files such as ResourceDefinitions.cs, RecipeDefinitions.cs, ItemDefinitions.cs, SkillProfiles.cs, FeatureDefinitions.cs, Activities.cs, CombatEncounterCatalog.cs, SettlementRole.cs, TerritoryKnowledgeTypes.cs, or ValenarConfigDefaults.cs may return as checked-in Generated authorities
  • that runtime helper names such as CandidateBuilderId, CandidateBuilderDelegate, or SelectorSource.FromCollection(...) are live .secs language forms

Live Behavior Vocabulary​

When docs describe behavior surfaces, use the live vocabulary from the current design docs:

  • activity
  • policy
  • on_action

Do not invent alternate behavior keywords or treat older placeholder words as committed syntax.

Generic SECS patterns stay: definition or data references, generic mechanic activities, and typed args. Valenar spell variants remain SpellDefinition data routed through one generic Activity_CastSpell, not one activity per spell.

Node or composed spellcrafting remains deferred proposal-only material unless a committed design doc says otherwise. Do not present it as live source syntax or canon.

Generated Headers​

When a Generated/ file cites a source relationship, only these header shapes are valid:

  1. // Source: <relative-path-to-.secs-file>
  2. // auto-generated or // Source: auto-generated ...
  3. // Retained host/catalog surface: no schema rows.

Docs should quote the retained marker exactly when explaining the single checked-in Valenar host-owned surface. Do not use retired hand-written Generated markers for Valenar v2.

Patterns Docs Can Reference​

Compiler-emitted files are expected to follow stable lowering patterns already present in obj/**/SecsGenerated.

  • templates lower to static classes with contract helpers and registration
  • declarations live in compiler-emitted row-family .g.cs files
  • ids and hashes live in compiler-emitted Hashes.g.cs
  • systems, events, activities, and on-actions are registered through compiler-emitted SecsModule.g.cs
  • reflection is not part of the expected generated shape

Documentation Rules​

  • Prefer committed docs under docs/design/ when describing language or lowering contracts.
  • Treat compiler output as current executable output, not as independent language authority.
  • Treat Content/ as the source for schema-owned Valenar definitions.
  • If a runtime surface has no committed source syntax yet, say that directly. Do not fill the gap with invented .secs forms.