Descriptors and compilation

Mental model

Story authoring is not “free-form YAML plus runtime guesses.” It is a typed descriptor system. Source generators publish the built-in object registry, plugins can add more registries, and compilation binds Sibling Objects against those descriptors before any action runs. The generated syntax reference is a documentation view of that same registry, which makes descriptor metadata the authority for the current binary.

Responsibilities and boundaries

• Parsing produces a SyntaxDocument; it only knows YAML structure and spans.
• Compilation resolves descriptors, constructor primaries, named fields, token facets, design layers, local Composite types, and local shader types.
• Baking executes the already-compiled script, creates runtime scene state, and attaches render resources.
• story syntax documents the descriptor store; it is not a separate manual.

Stable current behavior

• StoryDescriptorRegistry.BuiltIn is generated from source attributes and registered into a StoryDescriptorStore before compile.
• Constructor binding is strict: the value attached to the object key is the constructor input, and sibling properties must stay as sibling entries.
• Local .sprite.yaml and .hlsl types are resolved before global descriptor lookup.
• RuneStory.Compile(...) freezes exact semantic values and records source dependencies without executing actions or requiring a render device.
• story syntax emits built-in documentation directly from descriptor/value registries, and story syntax --reference can add plugin object descriptors discovered from a reference Story file.

Current limitations

• Dynamic plugins: loading is a CLI-only, trusted-code path rather than a core runtime feature.
• Native AOT cannot load arbitrary plugin DLLs, so dynamic plugin discovery is unavailable there.
• story syntax --reference currently extends object sections with plugin descriptors, but its value-type and constructor appendix remains built-in host data only.
• Equal CLR shapes do not imply semantic compatibility; exact Story type IDs still decide conversion and binding.

How the pieces connect

1. YAML parses into syntax with file/line spans.
2. The descriptor store and value-type registry define what each object, primary, and field means.
3. Compilation resolves local types, expands design layers, validates exact semantic values, and produces immutable plans.
4. Bake consumes those plans to build scene state and snapshots.
5. story syntax reads the same descriptor surfaces to describe the live authoring contract for the current tool build.

Go deeper

• Learn: Core concepts, Story authoring workflow
• Examples: Hello Rune
• Reference: Story syntax, Story CLI
• Specs: RUNE-1000, RUNE-1001