Animation and timing

Every checked-in Story sample uses the same core timing loop:

1. create a Sprite,
2. change it with an Action,
3. choose an animation with with:,
4. wait for the right completion source.

Start with set + wait

The canonical quick start is the smallest useful example:

- set:
    card.x: 1060
  with:
    spring: 0.8, 15

- wait: settle
- wait: 0.8s

Use this pattern when you want to move from a static scene into motion without adding more concepts yet.

Choose spring or tween on purpose

samples/story/settle-demo.story.yaml uses springs because the motion should feel responsive instead of clock-like:

tokens:
  - spring@stiff: 0.8, 15

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

- wait: settle

samples/story/path-motion-trim.story.yaml uses tweens because multiple actions must share the exact same duration and easing:

- set@reveal:
    route.trimEnd: 1
  with:
    tween: 3s
    easing: 0.42,0,0.58,1

- motion@markerTravel: $marker
  path: "M 140,500 C 300,150 560,150 640,360 C 720,570 980,570 1140,220"
  with:
    tween: 3s
    easing: 0.42,0,0.58,1

Use a spring when the motion should settle naturally. Use a tween when two or more things must land on an exact schedule.

Name actions when later steps depend on them

The @name suffix turns an action into a completion source:

- motion@markerTravel: $marker
  path: "M 140,500 C 300,150 560,150 640,360 C 720,570 980,570 1140,220"
  with:
    tween: 3s
    easing: 0.42,0,0.58,1

- wait: $markerTravel

That is easier to extend than guessing a matching duration later.

Reuse timing with tokens

If the same timing appears more than once, give it a token instead of copying literals:

tokens:
  - spring@normal: 0.7, 12

- set:
    box2.x: 1100
  with: $normal

- set:
    box2.x: 80
  with: $normal

settle-demo.story.yaml uses this pattern so all three boxes remain easy to compare.

Let speech drive time when narration matters

samples/story/tts-demo.story.yaml shows that time does not need to come only from numbers:

- speak@intro: "Welcome to the Rune Story text to speech demo. [drive]This narration now drives the progress meter."
  voice: $narrator

- set:
    meter.width: 560
  with:
    tween: $intro

- wait: $intro.drive
- wait: speak

• tween: $intro uses the active speech duration.
• wait: $intro.drive waits for a labeled point inside the narration.
• wait: speak waits for the active speech to finish.

Preview the timing samples

story preview samples/story/quick-start.story.yaml
story preview samples/story/settle-demo.story.yaml
story preview samples/story/path-motion-trim.story.yaml
story preview samples/story/tts-demo.story.yaml

Use Preview, live, and export when you want the rest of the CLI workflow.