States and interactions

States make a piece respond. A state is a look the piece can be in, held as values of its parameters: calm, bursting, loading, done. Transitions say what moves it from one state to another, such as a click, a hover, a few seconds passing or a message from the web page it is embedded in, and how long the change takes. Together they are a state machine.

Use states for a button that glows on hover, a piece that bursts on a click and settles again, or a loader on your site that turns into a tick when the page says the upload has finished.

States are built on the States tab of the Motion panel (M). They play wherever the piece runs: in the studio, on its share page and in embeds.

Building a state machine

1. Add the first state

   Click State. The first state is called "idle" and is marked start: the piece begins in it.

2. Set what it holds

   With the state selected and Record on, change parameters in Parameters (P): each change is written into the state. Or click Capture to take every parameter as it is now. Each value shows as a chip; click its × to leave that parameter out of the state.

3. Add a second state

   Click State again. Rename it in the name box (letters, digits, spaces and . _ : -, up to 40 characters), then set its values the same way.

4. Add a transition

   Under Transitions, click Transition. A row reads: from one state, to another, on a trigger, over a number of seconds, with an easing. Change each part from its menu.

5. Try it

   Hover a state in the list and click ▶ (Show this state) to blend to it. Or play the piece and click, hover or wait on the stage. The dot beside a state's name lights up while the piece is in it.

Triggers

The pointer triggers work with a finger as well as a mouse.

Transition options

A transition row reads as a sentence: one state to another on a trigger over a time, with an easing.

• The first menu is the state it leaves, or Any state, so one transition can cover every state (a click that always goes back to idle, say).
• The second is the state it moves to.
• The trigger menu picks what sets it off. After a time adds a box for the seconds; Page input and Piece event add one for the name.
• The time after "over" is how long the values take to blend, from 0 to 20 seconds. It starts at 0.6.
• The last menu is the easing: Linear, Ease in, Ease out, Ease in-out (to begin with) or Overshoot, as for keyframes.
• The × at the end removes the transition.

When more than one transition from the current state has the same trigger, the first in the list wins. A transition into the state the piece is already in does nothing.

What a state can hold

• The piece's parameters. Numbers and colours blend over the transition; switches and choices change.
• A layer's position, size, turn or opacity. Click Layer and pick a property: it is added at the value it has at the playhead, and you can type a new value on its chip. A text layer at opacity 0 in one state and 1 in another is hidden until a click.
• A loaded piece's parameters, listed in the same Layer menu. See Loading pieces onto a piece.

Parameters a state leaves out keep the values they have. A state's values are laid over the timeline, so where both set the same parameter, the state wins.

Start here makes the selected state the one the piece begins in. The bin deletes it, with the transitions to and from it.

Driving it from a web page

A Page input transition waits for the page around an embedded piece to send its name. That is how a loader becomes a tick when the page's upload finishes, or a piece changes when someone scrolls to a section.

In the studio, the ⚡ button on a Page input row sends that input, as the page would, so you can test it. Once a piece has a Page input or Piece event transition, an On a page section appears with the code to paste into your page. It looks like this:

const piece = VybeEmbed(document.querySelector('iframe'));
piece.input('go');
piece.on('state', (name) => console.log('now', name));

The page can also jump straight to a state, set parameters, and play, pause or seek the piece. Everything it can do is in The embed API; embedding itself is in Embedding a piece.

Events from the piece

A Piece event transition waits for the piece's own code to say something happened: a game that has been won, a level cleared, a target hit. Ask Perlin to raise an event when it happens (for example, "raise an event called scored each time the ball goes in"), then add a transition on Piece event with that name. A page embedding the piece hears the same events. For the code side, see The runtime API.

Limits

A piece can have up to 24 states and 64 transitions.

Related

• The embed API
• Embedding a piece
• Keyframes and tracks
• Loading pieces onto a piece