Core concepts

You do not need the whole syntax reference to read your first Story. Learn these ideas first, then come back to the reference when you need a specific field or command.

A Story is one YAML document

Every checked-in sample starts with the same top-level shape:

story: v1beta1
name: hello-rune
canvas: 1280x720

script:

• story is the required version tag.
• name becomes the preview window title and the default export file name.
• canvas sets the logical coordinate system for positions, sizes, and percentage-based values.
• script is the ordered list of actions that run during bake.

The generated syntax reference describes the same top-level fields and also notes that design, tokens, and styles are optional.

The canvas is the coordinate system

In samples/story/quick-start.story.yaml, canvas: 1280x720 means the centered title uses x: 640 and y: 220. In samples/story/camera-world-demo.story.yaml, percentage values such as camera.x: 50% and world.origin: 50%,50% resolve against the canvas instead of hard-coding a pixel count.

Start with pixel values while learning. Use percentages when you want a value to stay relative to the canvas.

The script is a timeline of Actions

A Story script is an ordered list. Each item is an Action such as create, set, wait, motion, playback, or speak.

- create@title:
    text: "Hello, Rune Story"
    x: 640
    y: 220
    align: center

- set@focus-east:
    camera.x: 1640
    camera.y: 470
  with:
    tween: 2s

- wait: $focus-east

• create@title creates something in the scene.
• set@focus-east changes existing properties over time.
• @focus-east gives that action a name so later actions can wait on it with $focus-east.

A Sprite is a named scene object

The create action constructs a Sprite and attaches it to the scene:

- create@card:
    rect: null
    width: 280
    height: 180
    x: 220
    y: 470
    align: center
    radius: 28
    fill: "#38bdf8"

card is the sprite name. rect is the sprite constructor. Properties such as width, height, x, y, radius, and fill come from the generated syntax for the chosen sprite type.

Sprites are not limited to primitive shapes. Checked-in samples also create:

• text sprites in quick-start.story.yaml,
• video sprites in video-demo.story.yaml,
• svg sprites in svg-demo.story.yaml, and
• reusable custom sprites such as ./sprites/split-flap in composite-sprite.story.yaml.

Values can be literal or reusable

You can write values inline:

with:
  spring: 0.8, 15

Or lift them into typed tokens and reuse them:

tokens:
  - spring@stiff: 0.8, 15

- set:
    box1.x: 1100
  with: $stiff

samples/story/settle-demo.story.yaml uses spring@... tokens for repeatable timing. samples/story/design-system.story.yaml shows the same pattern for colors, brushes, numbers, and styles. The syntax reference lists the built-in token types such as animation, brush, color, dimension, duration, number, shadow, string, and voice.

wait keeps timing explicit

wait blocks the current timeline until a target finishes:

- wait: settle
- wait: 0.8s
- wait: $markerTravel
- wait: speak

Those four forms all appear in the checked-in samples:

• wait: settle in settle-demo.story.yaml,
• wait: 0.8s in quick-start.story.yaml,
• wait: $markerTravel in path-motion-trim.story.yaml,
• wait: speak in tts-demo.story.yaml.

Use wait aggressively while learning. It makes Stories easier to read, easier to debug, and easier to extend.

Next step

Go to Quick start to build the canonical Hello World in small pieces before copying the full sample.