Authoring and packages

Mental model

Treat a Story package as one authored directory with one entry script, optional reusable definitions, optional design layers, local shader types, and local assets. The entry .story.yaml is the root narrative, .sprite.yaml files define reusable public components with private internals, .design.yaml files layer typed tokens and styles at compile time, and package-local .hlsl files act as source-defined shader sprite types. The current public schema is story: v1beta1.

Responsibilities and boundaries

• The entry .story.yaml owns root script order, logical canvas, default FPS, package-local imports, and root world/screen composition.
• .design.yaml files are compile-time authoring layers only. They contribute typed tokens and styles, but no runtime design registry survives into playback.
• .sprite.yaml files publish only their declared public fields and actions. Their child sprites, layout names, bindings, and timelines stay private.
• Local source-defined types resolve relative to the file that declares them, but every resolved path must stay inside the entry package root.

Stable current behavior

• One entry directory is the package root. Exact local .sprite.yaml and .hlsl paths are supported, and extensionless local paths still mean a Composite fallback.
• Design imports use extensionless local paths and layer depth-first, post-order. Later compatible token facets and style fields win.
• Styles expand against concrete descriptor-backed fields before ordinary scene execution, so authored YAML stays symbolic while compiled data becomes exact.
• The logical canvas defines Story coordinates and percentage resolution, while preview/export output size remains a host concern rather than an authoring field.

Current limitations

• Package-local sources cannot escape the package root.
• Design tokens and styles are compile-time only; they are not live runtime theming channels.
• Composite sprites expose position, opacity, scale, rotation, and transform origin, but not width/height/align-style resizing in the current model.
• A Composite canvas defines coordinates and percentages, but it does not clip overflow by itself.

How the pieces connect

1. The entry Story establishes the package root and root script.
2. Design layers, local shader types, and reusable Composite definitions are resolved before ordinary action execution.
3. Descriptor-backed fields turn authored YAML into exact typed constructions.
4. Bake materializes the scene, private Composite scopes, and resource attachments from that compiled package.
5. Preview, still capture, cues, live playback, and export all consume the same compiled package and baked scene model.

Go deeper

• Learn: Story authoring workflow, Design system
• Examples: Hello Rune, Examples gallery
• Reference: Story syntax
• Specs: RUNE-1000, RUNE-1010