The app decides what happened; the animation decides how to show the agreed response. A reliable event contract documents persistent state, one-shot reactions and what takes priority.
Written for: Developers, technical product leads and product designers.
Separate the product event from the visual response
A mascot should not decide that a payment, lesson or data request succeeded because an animation finished. The application owns those results. It sends the relevant value or event once the product outcome is known.
The character system then renders waiting, acknowledgement or recovery behavior. Rive’s State Machine documentation describes the visual transition structure. Your project still needs a written agreement about which application events drive that structure.
Distinguish persistent state from one-shot reactions
A persistent property describes an ongoing condition, such as “waiting for a response.” A one-shot request asks for a reaction, such as a brief celebration. Treating every update as a trigger can replay the same reaction whenever the screen re-renders or receives duplicate data.
| Need | Control concept | Contract question |
|---|---|---|
| Keep showing a loading condition | Persistent state or property | What clears the condition? |
| Play one earned celebration | One-shot request | How are duplicates suppressed? |
| Move gaze toward a target | Continuous values | What range and neutral point are valid? |
| Change expression while speaking | Independent expression control | Which behavior can override it? |
State Machine inputs and ViewModel properties have different runtime interfaces. Choose names and types for the exported file rather than assuming one universal API works everywhere.
A real example: the homepage dragon
The homepage dragon loads an actual Rive export using State Machine 1. Its soap button fires the existing Trigger 1 input to start the bathing reaction. Pointer movement also drives the character’s gaze.
The canvas does not need to be recreated for each button click. The page keeps the runtime instance and uses the file’s existing behavior. Canvas press events are separated from the CTA so the bath starts from the button while eye tracking remains available. This is a concrete web example; its input names belong to that export.
Write interruption rules before adding more states
Consider a request that starts, fails, retries and succeeds quickly. If the character is still reacting to failure when the success arrives, should it finish that reaction, blend out or move immediately to the latest state? There is no single correct answer, but the behavior should be intentional.
For a calm assistant, waiting might be interrupted by either success or error. A reward might be allowed to finish unless the user leaves the screen. Speech cancellation should reset the mouth even if the character remains in a concerned expression. Document these priorities as part of the design.
Test sequences, not just isolated buttons
- Open the screen, leave it and reopen it: the default state should be predictable.
- Send the same completion event twice: decide whether one or two reactions are appropriate.
- Start waiting, cancel the request and retry: ensure the old waiting condition is cleared.
- Change emotion during speech: keep unrelated controls consistent.
- Resize or background the app: preserve an agreed pause/resume and reset policy.
A developer can turn this list into acceptance checks. The animator can use it to verify the State Machine before handoff. Essential status text and keyboard-accessible actions remain in the surrounding interface.
Document the control contract your app will use
For each control, record its name, type, default, range or allowed values, owner and reset behavior. Include the artboard and State Machine or ViewModel identity, the file version and the target runtime. That reference is more actionable than a screenshot with several unnamed transitions.
Explore State Machine production for the control logic or App Mascot services for the complete character scope. If speech is involved, the AI activity-state guide covers the additional interruption decisions.