DEV Community: Praneeth Kawya Thathsara

Building an AI Web App? Get a Custom Rive Avatar for Your AI Assistant

Praneeth Kawya Thathsara — Sat, 19 Sep 2026 21:05:11 +0000

Your AI assistant can answer questions and speak. What should users see while they interact with it?

For an AI tutor, voice assistant, or companion app, a custom animated avatar can communicate when the app is listening, preparing a response, or speaking.

But creating that character introduces another set of tasks: illustration, rigging, expressions, mouth movement, animation transitions, and developer controls.

That is the work I help teams with at Mascot Engine.

I’m Praneeth, a Rive animator creating custom interactive mascots and AI avatar animations for web and mobile products.

Building an AI web app that needs an animated character?

Explore Mascot Engine and send me your app screenshot, platform, and avatar requirements.

📧 mascotengine@gmail.com

💬 WhatsApp: +94 71 700 0999

Your app handles the conversation. The avatar shows its state.

Imagine a language-learning app with an AI tutor.

When the learner speaks, the character looks attentive. While the app prepares a response, the character moves into a subtle thinking animation. When response audio starts playing, its mouth moves with the speech.

These behaviours need a clear connection to the application.

What happens in your app	What the avatar could do
The session becomes available	Settle into a friendly idle
The app accepts microphone input	Show an attentive listening expression
A response is being prepared	Play a restrained thinking animation
Response audio plays	Animate the mouth and speaking expression
The learner completes a task	Play a short celebration
A connection fails	Show a calm error reaction

This is an example brief, not a fixed feature package. The right states depend on your product.

The important design decision is to make the avatar reflect what the app is actually doing.

Why use Rive for an interactive AI avatar?

Rive state machines let you connect animations and define the logic for transitions between them. Your character can have different behaviours instead of playing the same animation continuously.

See the official Rive state machine documentation.

Rive also provides runtimes for web, React, Flutter, React Native, and other platforms. Feature support varies by runtime and renderer, so the implementation should be planned around your actual stack.

See the Rive runtime guide.

For a web developer, the goal is an animation asset with clearly documented controls that can be connected to application events.

What can you commission from Mascot Engine?

At Mascot Engine, I provide custom Rive character animation services scoped around your product.

Character design and preparation

Already have a mascot illustration? I can assess how it should be prepared for animation.

Starting with an idea? We can define a character direction around your interface, audience, and brand.

The design should remain readable at its actual display size—not only in a large portfolio preview.

2D rigging and expressions

A character rig makes it possible to animate the face and body consistently.

Depending on the design, the scope can include eyes, eyebrows, mouth shapes, head movement, and gestures.

Activity animations and transitions

We define the behaviours your app needs and how the character moves between them.

For example:

Idle to listening.
Listening to thinking.
Thinking to speaking.
Speaking back to listening after an interruption.
Any relevant activity to an error or fallback state.

The transitions deserve attention alongside the individual animations.

Lip-sync controls

A repeating talking loop, audio-driven mouth opening, and viseme-based animation are different deliverables.

We agree on the approach before production, including what data your application will provide.

Developer handoff

The agreed deliverables can include the exported .riv file, animation controls, state mappings, and implementation notes.

The purpose is to give your developer a clear specification for operating the character.

Start with the avatar your first release needs

You do not need to define every future expression before discussing a project.

For an initial voice-based web app, I would consider:

A calm idle.
An attentive listening state.
A subtle thinking state.
A speaking state with the agreed mouth controls.
An error or fallback reaction.

Additional expressions, celebrations, outfits, or growth stages can be scoped separately when they support the product.

Need help turning your app idea into an animation brief?

Contact Mascot Engine with your app link or screenshot, existing artwork, and the interactions you need.

📧 mascotengine@gmail.com

💬 WhatsApp: +94 71 700 0999

What stays in your application?

A custom avatar needs a clear division of responsibilities.

Animation scope	Application integration
Character artwork and rig	AI model and conversation logic
Expressions and animated states	Microphone permissions and input
Authored mouth shapes and controls	Audio playback and timing signals
Animation transition logic	Network status and request handling
Documented character controls	Connecting app events to those controls

The final split should be agreed for your project.

For example, an animator can author a mouth-opening control. Your application still needs to supply values that correspond to the character’s speech audio.

Rive data binding can connect application-controlled data to properties in the character scene. The exact View Model structure and property names should be documented for the authored file.

See the Rive data binding overview.

Make the lip-sync requirement specific

For a simple stylized character, audio-driven mouth opening may be a suitable starting point.

An example specification could define:

0 as a closed mouth.
0.5 as a medium opening.
1 as the maximum designed opening.

Those values are an example contract, not a universal Rive API.

Your implementation also needs to handle silence, smoothing, playback timing, and interruption.

If you need distinct mouth shapes for speech sounds, discuss a viseme-based system. That requires an agreed shape mapping and suitable timing data from your speech pipeline or analysis layer.

A useful project brief describes the expected result, not just “add lip sync.”

What should be checked before launch?

Test the character inside the real interface.

A few important checks:

[ ] The mouth closes during silence.
[ ] Speaking starts with audio playback.
[ ] Interrupting playback stops mouth movement.
[ ] The listening state matches actual microphone availability.
[ ] Rapid state changes do not leave the avatar stuck.
[ ] Expressions remain readable on smaller screens.
[ ] Status text remains available alongside visual reactions.
[ ] Reduced-motion behaviour is defined.
[ ] Performance is acceptable on target devices.

Agree on who handles each check and how integration feedback will be addressed.

How to request a custom Rive avatar quote

The most useful starting point is a short product brief.

Send:

Your app: a link, screenshot, or short explanation.
Your stack: React, another web framework, or a different platform.
Your character: existing artwork or visual references.
Required behaviours: listening, thinking, speaking, rewards, or other reactions.
Voice setup: how speech is generated and played, if already decided.
Timeline and budget: your target launch date and budget range.

The quote can then account for design complexity, rigging, animation states, lip-sync requirements, transitions, and handoff scope.

Bring your AI avatar idea to Mascot Engine

If you are looking to hire a Rive animator for an AI web app, Mascot Engine is my studio for custom interactive character animation.

I work with founders, developers, and product teams that need a character designed and animated around their application.

Whether you have finished mascot artwork or an early product concept, we can discuss the behaviours your avatar needs and define the animation scope.

Let’s give your AI a face.

🌐 Explore my work: MascotEngine.com

📧 Email your brief: mascotengine@gmail.com

💬 WhatsApp: +94 71 700 0999

Send your app screenshot, platform, and required avatar states to discuss a project quote.

Developers: what are you building, and what would you want your AI avatar to do first?

How to Build an AI Companion That Listens, Thinks, Speaks, and Reacts in Real Time

Praneeth Kawya Thathsara — Thu, 17 Sep 2026 18:57:44 +0000

AI assistants are becoming more capable every year.

They can understand speech, generate natural responses, remember context, analyze user intent, and communicate using realistic voices.

But there is still one major problem:

Most AI products have no visible personality.

A user speaks.

The system processes the request.

A voice answers.

But visually, there may be nothing more than a waveform, glowing orb, loading spinner, or static avatar.

For many products, that is a missed opportunity.

A well-designed interactive mascot can become the visual personality layer between the AI system and the user.

Instead of simply showing that an AI is “loading,” a character can visibly:

listen
think
speak
react
celebrate
show empathy
recover from errors
fall asleep when inactive
follow the user's cursor or touch position

This article explains how I approach building these systems using Rive, State Machines, runtime inputs, lip sync, and AI application events.

If you are building an AI assistant, AI tutor, voice companion, SaaS copilot, or conversational application, this architecture can be used to turn a static mascot into a real product interface.

The Important Shift: Stop Thinking About Animation Clips

The first mistake is treating an AI character as a collection of animations.

For example:

idle.riv
thinking.riv
talking.riv
happy.riv
error.riv

That can work for simple projects, but it quickly becomes difficult to maintain.

A better approach is to think of the mascot as a small visual system controlled by the application.

The application already knows what the AI is doing.

For example:

User is speaking
AI is processing
AI is responding
Connection failed
Answer was correct
User has been inactive

The animation system should receive these events and visually represent them.

This means the mascot becomes part of the application logic rather than an animation playing on top of the UI.

This is also the approach we focus on at Mascot Engine, where interactive Rive mascots are prepared around real product events, AI responses, runtime inputs, and developer handoff.

Mascot Engine:
https://mascotengine.com

A Simple AI Companion Architecture

A production-ready AI character does not necessarily need dozens of separate controls.

You can build a surprisingly flexible system using a few well-planned inputs.

For example:

activity
emotion
viseme
audioLevel
lookX
lookY
blink

Let's break these down.

1. Activity State

The first input controls what the AI is currently doing.

For example:

activity = 0  // Idle
activity = 1  // Listening
activity = 2  // Thinking
activity = 3  // Speaking
activity = 4  // Connecting
activity = 5  // Error
activity = 6  // Sleeping

Now the application can control the character using its actual internal state.

Example flow:

User starts speaking
        ↓
activity = 1

User finishes speaking
        ↓
activity = 2

LLM begins generating the response
        ↓
activity = 3

Response finishes
        ↓
activity = 0

The mascot is no longer guessing what should happen.

It is simply visualizing the state of the application.

2. Emotion Should Be Independent

Activity and emotion should usually be separated.

Why?

Because an AI can be speaking while happy, concerned, empathetic, surprised, or neutral.

For example:

emotion = 0  // Neutral
emotion = 1  // Happy
emotion = 2  // Empathetic
emotion = 3  // Concerned
emotion = 4  // Surprised

Now we can combine states.

activity = speaking
emotion = happy

or:

activity = speaking
emotion = concerned

This dramatically reduces the number of animations that need to be created.

Instead of manually creating:

happy-speaking
sad-speaking
concerned-speaking
surprised-speaking
happy-listening
concerned-listening
...

the system can layer reusable behaviors.

This modular approach is one reason State Machines work particularly well for interactive characters.

Rive has also demonstrated this idea in real AI-character use cases. For Duolingo's AI-powered Video Call experience, modular animation and State Machine blending were used to help Lily listen, process, and react dynamically rather than relying on a huge library of pre-baked reactions.

3. Listening State

Listening should communicate:

“I am paying attention to you.”

It does not need to be dramatic.

Subtle behaviors often work better.

For example:

slightly leaning forward
focusing the eyes
reducing random idle movement
occasional blinking
subtle head movement
reacting slightly to microphone activity

The important point is that the user should immediately understand that the system is receiving input.

4. Thinking State

Thinking is one of the most important AI states because latency becomes much easier to tolerate when the interface acknowledges it.

Instead of freezing the character, the mascot can:

look upward
glance sideways
move its eyes slowly
change posture
perform a subtle thinking loop

The goal is not to fake intelligence.

The goal is to clearly communicate:

“Your request was received and the system is processing it.”

5. Speaking State

Speaking should not simply mean playing a looping mouth animation.

There are multiple levels of implementation.

Level 1 — Basic talking animation

isTalking = true

A mouth animation loops while speech is active.

Simple and lightweight.

Level 2 — Audio-driven mouth movement

The application sends something like:

audioLevel = 0.0 → 1.0

The mouth responds to audio amplitude.

For example:

0.0 = closed
0.3 = slightly open
0.7 = open
1.0 = fully open

This is much more convincing than a random speaking loop.

Level 3 — Viseme Lip Sync

For more advanced AI voice products, the application can provide phoneme or viseme information.

For example:

viseme = 0
viseme = 1
viseme = 2
...
viseme = 9

Each value represents a mouth shape.

The result can feel significantly more natural.

Recent Rive character examples also demonstrate layered State Machine systems with visemes, expressions, triggers, and speech-driven lip sync inside a single interactive character file.

At Mascot Engine, this is one of the systems we can prepare for AI and TTS-driven products:

https://mascotengine.com

6. Interactive Eye Tracking

Another relatively small feature can make a huge difference:

lookX = -1 → 1
lookY = -1 → 1

These values can be connected to:

cursor position
touch position
camera direction
product UI events
predefined conversational behaviors

Example:

lookX = -1

Character looks left.

lookX = 1

Character looks right.

lookX = 0
lookY = 0

Character returns to the center.

A subtle gaze system can make the character feel much more aware of the interface around it.

Mascot Engine uses similar runtime-ready controls for interactive gaze, AI states, product reactions, and other app-driven behaviors.

7. Success, Failure, and Product Events

Do not make the mascot respond only to the AI conversation.

It can also respond to product events.

For example:

answerCorrect
answerIncorrect
goalCompleted
paymentSuccessful
streakReached
levelUp
connectionLost
retry

This becomes especially useful for:

AI education apps
habit trackers
health applications
fintech products
productivity apps
onboarding experiences
gamified SaaS products

Imagine an AI learning app.

Student answers correctly
       ↓
success trigger
       ↓
Mascot celebrates

The character is now reinforcing the product experience.

8. What About Inactivity?

AI companions can also respond when nothing is happening.

For example:

0–5 minutes
Idle

5–10 minutes
Bored / relaxed

10+ minutes
Sleeping

When the user returns:

wake trigger
      ↓
wake animation
      ↓
idle

These small details make a character feel much more persistent.

9. Build One State Machine, Not 30 Disconnected Animations

A simplified architecture might look like:

                 ┌─────────────┐
                 │    IDLE     │
                 └──────┬──────┘
                        │
         ┌──────────────┼──────────────┐
         ↓              ↓              ↓
     LISTENING       THINKING        ERROR
         │              │
         └──────────┬───┘
                    ↓
                 SPEAKING
                    │
                    ↓
                   IDLE

Then emotion, blinking, gaze, and mouth behavior can operate as additional layers.

This creates a much cleaner system than manually triggering unrelated clips.

10. Example Runtime Contract

Before handing the animation to developers, I like to define a simple contract.

For example:

Artboard:
AI_Companion

State Machine:
CompanionController

Inputs:

activity
Number
0–6

emotion
Number
0–4

viseme
Number
0–9

audioLevel
Number
0–1

lookX
Number
-1–1

lookY
Number
-1–1

blink
Trigger

Then document exactly what every input means.

This sounds simple, but it prevents a huge number of integration problems.

11. Example AI Event Mapping

The development team can then map existing application events to the character.

Conceptually:

onUserSpeechStarted(() => {
  activity = 1;
});

onUserSpeechEnded(() => {
  activity = 2;
});

onAIResponseStarted(() => {
  activity = 3;
});

onAIResponseFinished(() => {
  activity = 0;
});

onConnectionError(() => {
  activity = 5;
});

The exact implementation depends on your framework and AI architecture.

But the animation contract stays predictable.

That is the important part.

12. Where the AI Fits

The mascot itself does not need to contain the AI.

Think of it as three separate layers:

AI / LLM
     ↓
Application Logic
     ↓
Rive Character

The LLM decides what to say.

Your application manages the conversation.

Rive visualizes what is happening.

This separation makes the system easier to maintain.

13. What About AI-Generated Emotion?

You can take this one step further.

Suppose the AI returns structured metadata alongside its response.

Conceptually:

{
  "response": "You did really well today.",
  "emotion": "happy"
}

Your application maps:

happy → emotion = 1

Then the mascot speaks using the correct facial expression.

You could use the same idea for:

neutral
happy
empathetic
concerned
surprised

The important rule is to keep the animation interface simple.

Do not expose dozens of animation controls to the LLM if five stable states will achieve the same result.

14. Where This Architecture Works Well

I especially like this approach for:

AI Tutors

The character can listen, think, explain answers, celebrate correct responses, and react to mistakes.

AI Companions

A persistent character can visually communicate emotion and conversation state.

Voice Assistants

Listening, processing, speaking, interruption, and connection states become visible.

SaaS Copilots

A mascot can guide onboarding and respond to product events.

Kids' AI Products

Visual communication can make abstract system states easier to understand.

Health and Wellness Apps

A calm companion can communicate support and progress without overwhelming the UI.

Productivity Apps

The mascot can react to goals, focus sessions, completion, streaks, and inactivity.

15. Why Rive Works Well for This

There are several reasons I use Rive for these projects.

Runtime control

The application can control inputs while the character is running.

State Machines

Complex transitions can be kept inside the animation system.

Reusable rigs

The same character foundation can support many behaviors.

Interactive animation

The mascot can react to product data rather than simply playing videos.

Web and app workflows

The same animation concept can be prepared for modern product environments.

Rive's own marketplace increasingly includes production-oriented mascot examples built around State Machines, expressions, interactive controls, cursor tracking, data binding, and AI-like listening/thinking states.

16. The Developer Handoff Matters as Much as the Animation

A beautiful character that developers cannot integrate easily is not production-ready.

A good delivery should clearly define:

.riv source
artboard names
State Machine names
input names
input types
number ranges
event mappings
default values
fallback behavior
responsive behavior

Depending on the project, it can also include:

PNG stills
editable source
Flutter guidance
React Native guidance
Web guidance
test implementation

At Mascot Engine, the focus is specifically on this kind of production-ready Rive mascot system rather than only delivering isolated animation loops.

17. A Practical Minimum Viable AI Companion

You do not need 50 animations for version one.

A strong MVP could contain:

Idle
Listening
Thinking
Speaking
Happy
Concerned
Error
Sleeping
Blink

plus:

audioLevel
lookX
lookY

That is already enough to create a surprisingly expressive AI interface.

You can always expand it later.

18. The Bigger Idea

The interesting opportunity is not simply adding animation to AI.

It is giving the AI system a consistent visual behavior layer.

The AI already has:

intelligence
memory
voice
context

The mascot provides:

presence
expression
feedback
personality
visual state communication

That is why I believe interactive characters will become increasingly useful inside AI products.

The goal is not to put a cartoon character everywhere.

The goal is to use a character where human-like visual feedback improves the product experience.

Need an AI Companion or Interactive Rive Mascot?

I run Mascot Engine, a studio focused on production-ready interactive Rive characters for:

AI assistants
AI companions
AI tutors
SaaS products
mobile apps
web applications
conversational interfaces

Projects can include:

character preparation
Rive rigging
idle / listening / thinking / speaking states
interactive State Machines
emotion systems
eye tracking
audio-driven mouth animation
viseme lip sync
product-event reactions
editable Rive files
developer handoff
Flutter, React Native, and web preparation

You can see live interactive mascot examples and technical details here:

👉 https://mascotengine.com

If you are building an AI product and already have a mascot, UI prototype, character sketch, or even only an idea, you can send the product brief and required behaviors to Mascot Engine to plan the animation architecture before development.

Do not ask:

“What animation should the mascot play?”

Instead ask:

“What does the application know right now, and how should the character visually communicate that state?”

That small change turns a mascot from decoration into part of the product.

Rive #AI #Animation #WebDevelopment #AppDevelopment #GenerativeAI #ArtificialIntelligence #SaaS #Flutter #ReactNative #UX #UIUX #CharacterAnimation #AIAssistant #AICompanion

How to Brief an Interactive App Mascot: A Founder’s Rive Checklist

Praneeth Kawya Thathsara — Wed, 09 Sep 2026 17:34:48 +0000

“We need a friendly mascot for our app” is a good starting point for a conversation. It is not yet a brief that an animator and developer can estimate reliably.

Two characters can look equally simple in a screenshot and require very different systems. One might wave once during onboarding. Another might listen, think, speak, follow gaze targets, recover from an interrupted request, and run inside three different applications.

The difference is behavior, data, and delivery scope. Describe those early and you give the project a much better chance of arriving in a form your team can use.

This guide is for founders, product designers, and engineering leads commissioning an interactive Rive mascot or AI companion. It includes a copyable project brief and explains which decisions belong in it. The examples are fictional scoping examples, not claims about client work or fixed market prices.

Start with the product job

Before choosing expressions or colors, describe what the character helps the user understand or do.

An onboarding guide might explain progress and acknowledge completed steps. A support assistant might show whether it is listening or waiting for an answer. A learning companion might react to an exercise result without distracting from the lesson.

Write one sentence that connects the character to a user task. For example: “The mascot helps users understand whether their voice request is being captured, processed, or answered.”

Then name the screen or flow where that happens. A small companion beside a text field has different visual constraints from a full-screen character during a welcome sequence.

Avoid making engagement or conversion promises part of the animation specification unless you have a plan to measure them. The deliverable can communicate a state clearly; the effect on broader product metrics needs evidence from your product.

Describe one complete user journey

A list of states is useful, but a sequence reveals the transitions and interruptions between them.

Describe what happens from the user’s first action to the end of the interaction. Include one ordinary failure. For a voice assistant, the sequence might be: tap microphone, speak, wait, hear a response, interrupt, and retry after a network error.

That journey answers questions a mood board cannot. Does speaking stop immediately? Does a success gesture block the next action? What remains visible while the service is unavailable?

Keep the character’s role separate from the application’s role. Your app decides that a request succeeded. The character communicates the decision through animation.

If the character can initiate an action when tapped, specify what that tap requests and which application component handles it. A visual interaction is not automatically a completed business operation.

List states by meaning, not by personality

Words like playful, calm, or confident help art direction. They do not define a State Machine.

Give each state a product meaning and an exit condition. For example:

State	Meaning	What ends it?
Idle	Ready for interaction	User begins a task
Listening	Audio capture is active	Capture stops or fails
Thinking	Waiting for the next result	Answer, cancellation, or error
Speaking	Output audio is playing	Playback ends or is interrupted
Success	Requested operation completed	Short acknowledgement finishes
Unavailable	Interaction cannot proceed	Retry or return to a usable state

These are example states, not a requirement for every mascot. A simple onboarding character may need fewer. A complex companion may need additional behavior.

Rive’s State Machine overview explains how animation states and transitions form an interactive system. Your brief should supply the product meaning that the designer maps into that system.

Separate activity, expression, and attention

You may want the character to speak warmly, wait calmly, and look toward a relevant interface element. Those behaviors do not all need to become separate primary states.

Describe activity, emotion, and gaze as distinct concerns. This helps the specialist propose a manageable rig and control interface instead of multiplying every combination into another animation.

Specify whether gaze follows a pointer, a tap target, or application events. It does not require a camera unless you explicitly want camera-based tracking and have planned that separate feature.

Also describe the intensity of expression at the actual display size. A dramatic full-body reaction may work on a welcome screen but feel excessive beside a form field.

Ask to review the character in a realistic product frame early. A beautiful standalone animation can still be the wrong size, contrast, or energy for its intended interface.

Say what artwork already exists

Share the current source assets and explain what must remain recognizable: silhouette, proportions, palette, facial style, or accessories.

Mention whether the artwork is editable vector art, a layered illustration, a flat image, or only a concept reference. These starting points require different preparation before rigging.

If the character needs body turns, mouth poses, or expressions that are not visible in the original artwork, include that requirement. A single front-view image does not define every pose automatically.

Clarify which references are for style and which are actual assets you are entitled to use. The brief should not leave the specialist guessing whether a reference character must be copied or merely communicates a general direction.

Include ownership and editable-source delivery in the scope rather than waiting until the final export arrives.

Name every target platform

“Mobile and web” leaves important details unresolved. Specify Web, Flutter, React Native, or native platforms, and include the versions your developers already use when available.

Rive provides runtimes for multiple environments, but feature support and renderer choices can differ. Its runtime introduction is a useful reference for planning compatibility.

List where the mascot appears and how many instances may be visible simultaneously. A single assistant panel and a scrolling collection of animated cards are different integration tasks.

Mention offline requirements and asset delivery preferences. A bundled file, a remotely hosted file, and a remotely updated character system involve different release decisions.

You do not need to know every technical answer before contacting a specialist. Mark unknowns honestly and identify the developer who can resolve them during scoping.

Need an interactive Rive character for your product? Mascot Engine creates app mascots, AI companions, State Machines, lip sync, and developer-ready Rive systems for Web, Flutter, and React Native. View live work and request an estimate, or send your project brief on WhatsApp.

Define speaking requirements before requesting lip sync

“The character should talk” can mean several different deliverables.

A repeating talking animation can signal activity. An audio-level-driven mouth can respond to loudness. Timed viseme animation selects mouth shapes associated with speech sounds. These options differ in appearance and in the data the application must provide.

Say which speech system you use, whether audio is streamed, and whether timed mouth-shape or alignment data is available. Share a representative sample if you have one.

Specify the languages and voice behaviors that matter to the product. Describe how interruptions, silence, buffering, and playback errors should affect the mouth.

If you do not yet have timing data, ask the specialist to scope a fallback instead of assuming the .riv file will derive accurate lip sync from arbitrary audio on its own.

Keep speech generation, audio playback, timing data, and visual animation as separate responsibilities in the brief. That prevents an animation estimate from silently turning into an entire voice-platform implementation.

Ask for a public control contract

Your developer needs to know how application events drive the character.

Rive’s Data Binding system connects View Model data to scene properties. The official overview explains the relationship between a schema, instances containing values, and bindings.

You can describe the desired controls in plain language: current activity, expression, speech mouth shape, audio level, and gaze direction. The specialist can propose names and types.

Ask for defaults, valid ranges, and ownership rules in the final documentation. A property called progress should say whether it expects 0–1 or 0–100. An activity selector should enumerate every supported value.

This contract is valuable even if your founder-facing brief remains nontechnical. It tells the engineering team what they will receive and gives the animator room to improve the design without exposing every internal object to code.

Specify what “developer-ready” includes

Do you want an asset only, an integration example, or production implementation in your application? Name the boundary.

For an asset handoff, request the runtime .riv, editable project access or backup, entry-point names, control documentation, and runtime test notes. Rive distinguishes its runtime export from its editable backup export.

For an integration example, define the platform and the interactions it must demonstrate. For production implementation, list the repository, screens, application events, audio responsibilities, and acceptance process.

Avoid asking for a “complete handoff” without agreeing on its contents. Two people can use the phrase and imagine very different work.

The Rive mascot developer handoff checklist provides a more detailed technical acceptance structure for your engineering team.

Include accessibility and failure behavior

A mascot should support the interface without becoming its only source of information.

Describe the accompanying text and controls for important states such as listening, unavailable, or completed. If animation fails to load, users should still understand what they can do next.

Ask for a reduced-motion treatment. That might be a quieter idle pose or static character with ordinary text feedback. React Native’s AccessibilityInfo API is one example of a host mechanism for detecting motion preferences; the design still needs to specify the response.

Review the character beside text at realistic sizes and on narrow screens. Include the intended background colors so contrast can be evaluated in context.

Write at least one fallback acceptance criterion: “The user can complete onboarding if the character asset does not load.” It is simple, concrete, and easy to verify.

Explain the deadline and budget constraints

A useful budget discussion starts with priorities, not an invented universal price for a mascot.

Share a budget range and identify what is essential for the first release. New character design, complex rigging, multiple expressions, timed lip sync, platform testing, and production integration all affect the amount of work.

Separate the launch date from the date your developers need the asset. Engineering integration and acceptance need time after visual approval.

Name the decision-maker and the review process. If several people must approve artwork or behavior, make that visible before production begins.

When budget or time is constrained, ask for a staged scope. A small reliable interaction set is easier to evaluate than a long list of unfinished behaviors. Keep later additions compatible with the initial control contract where practical.

Copy this project brief

Use this template as a starting point. Unknown answers are acceptable; unexplained assumptions are harder to manage.

Product and website:
Target users:
What the mascot helps users do:
Screens and approximate display size:

Existing artwork and editable source:
Visual references and must-keep features:
Required states and one complete user journey:
Interruption, error, and retry behavior:

Platforms and current framework/runtime versions:
Number of simultaneous character instances:
Offline or remote asset requirements:

Speaking required: yes/no
Speech provider and streaming behavior:
Available viseme/timing data:
Gaze behavior:
Reduced-motion and asset-failure fallback:

Deliverables: asset / demo / production integration
Editable source and ownership expectations:
Developer contact:
Acceptance tests and approval owner:

Budget range:
Asset handoff deadline:
Product launch date:
Essential first-release features:
Optional later features:

Attach the relevant artwork and a short product walkthrough. A specialist should be able to understand the user journey without joining every internal planning conversation.

Review the proposal against the brief

When a proposal arrives, compare the deliverables and exclusions against your requirements. Check that the speaking approach, runtime targets, editable-source access, and integration depth are stated explicitly.

Ask how the result will be demonstrated before acceptance. A rendered video can approve appearance, but an interactive character also needs a runtime demonstration of its controls and transitions.

Use the same brief when comparing options. Otherwise, one estimate may include source access and multi-platform testing while another covers only an animation export.

Mascot Engine’s interactive character services cover Rive mascots, AI companions, rigging, State Machines, viseme lip sync, gaze controls, and developer-ready systems. A clear brief helps turn those capabilities into a scope that fits your actual product.

By Praneeth Kawya Thathsara, founder of Mascot Engine.

Need an interactive Rive character for your product? Mascot Engine creates app mascots, AI companions, State Machines, lip sync, and developer-ready systems for Web, Flutter, and React Native. View live work and request an estimate, or copy the brief above and send it on WhatsApp.

React Native Rive Migration: A Checklist for Production Mascots

Praneeth Kawya Thathsara — Wed, 09 Sep 2026 17:32:31 +0000

You update a Rive dependency, rebuild the React Native app, and the character still appears. Then the first conversation starts: a property is undefined, a ref is not ready, or a callback written for the previous API no longer behaves as expected.

Visual continuity does not prove that an interactive mascot migration is complete. The important contract includes file loading, instance creation, public controls, error handling, and the lifecycle of the screen containing the character.

The first decision is also easy to miss: are you moving from the legacy rive-react-native package, or upgrading between versions of @rive-app/react-native? Those are different migrations.

This guide gives you a practical sequence for both situations. It is a planning and acceptance checklist, not a claim that an untested sample application works on every runtime version. Check the linked official documentation against the exact dependency versions you intend to ship.

Choose a specific destination version

Do not define the ticket as “upgrade to the latest Rive.” Define the package, version, supported native platforms, and the reason for moving.

As checked on September 9, 2026, Rive’s React Native migration guide documents both the legacy-package migration and newer async API changes. It describes a v0.5 beta and recommends getting onto v0.4.19 or later with non-deprecated async APIs before trying that beta.

Treat that as version-specific guidance, not a permanent promise about the release landscape. Recheck it when your migration starts.

For a production app, separate the decision to update APIs from the decision to adopt a beta runtime. Smaller steps make it easier to identify regressions and restore a known working configuration.

Inventory the integration you actually have

Search the application for package imports, Rive view components, file loaders, input setters, event listeners, text updates, and View Model access.

Include code that only runs during errors, navigation, and speech interruption. Those paths often contain older calls that a successful first render will never exercise.

Create a short inventory:

Area	Record before changing anything
Dependencies	React Native, Rive, and native support packages
Build environment	iOS/Android targets and relevant toolchain versions
Assets	File names, source locations, and external dependencies
Entry points	Artboard, State Machine, View Model, and instance names
Controls	Types, ranges, defaults, and caller locations
Lifecycle	Loading, subscriptions, disposal, and background behavior
Baseline	A reproducible interaction sequence on both native platforms

Save the original lockfile and exported asset with the migration branch. If your team uses remote assets, preserve the exact revision currently served rather than assuming the URL will always identify the same content.

Check native prerequisites before debugging the character

Rive’s current React Native setup guide uses @rive-app/react-native with Nitro Modules and lists the required React Native, Expo, native OS, and build-tool versions.

Compare those requirements with the existing app before changing character behavior. A toolchain mismatch and a bad State Machine condition are not the same problem, even if both result in a character that does not work.

Build a minimal screen that loads one known asset. Confirm the native integration on the platforms you support. Only then reconnect conversation state, microphone permissions, speech playback, and routing.

If the app uses Expo, follow Rive’s setup requirements for that environment. Do not assume that an example working in a different native build arrangement proves compatibility with your project.

Keep build logs from the failing stage. A precise error is more useful than repeatedly changing dependency versions without recording which combinations were attempted.

Make file loading an explicit state

The character’s initial UI must handle pending, ready, and failed conditions. These are product states, not exceptional situations that can be ignored because the file usually loads quickly.

Rive documents bundled and remote sources in Loading Rive Files. Choose the source according to your release and offline requirements.

For a bundled asset, verify that the production build includes the file and that the bundler configuration supports it. For a remote asset, define retry behavior, unavailable-network behavior, and how you identify an asset revision.

Keep a useful surrounding interface while loading. A support transcript, text input, or retry control should not depend on the animation being available.

Avoid an indefinite spinner for every missing result. “Still loading,” “loaded but no matching View Model,” and “failed to load” need different handling if you want useful diagnostics.

Treat file readiness and instance readiness separately

Having a file object does not mean every interaction object is already available.

The current migration guide describes asynchronous View Model instance creation and property-hook values that may initially be undefined. It also documents changes to loading and error return shapes across releases. Review the section corresponding to your starting version.

Write the UI around explicit readiness conditions. Until the intended instance exists, preserve the latest desired character state in application data. Once ready, apply that snapshot.

Do not fire every old event at the newly created instance. A sequence such as listening, thinking, speaking, then cancelled may have occurred while loading. The correct state now could simply be idle.

This is especially important for AI companions. The conversation can advance independently of the visual asset, and the avatar needs to catch up to the current state rather than replay obsolete intent.

Move product logic behind a small adapter

A dependency upgrade is much harder when runtime-specific calls are spread throughout the app.

Define a small interface in product terms. It might accept activity, expression, gaze, and speech controls. One adapter maps those values to the chosen Rive schema and runtime APIs.

Conversation or UI event
        |
        v
Current application state
        |
        v
Mascot adapter: validate and map
        |
        v
Ready Rive View Model instance

The names in the adapter should express intent. setActivity("listening") is easier to reason about than a scattered numeric assignment whose meaning exists only in the editor file.

Keep the mapping documented and versioned. If a property changes from a boolean to an enum or numeric selector, update the asset and adapter together.

Need an interactive Rive character for your product? Mascot Engine creates app mascots, AI companions, State Machines, lip sync, and developer-ready systems for Web, Flutter, and React Native. Explore live work and send your project brief on WhatsApp.

Migrate controls without changing their meaning

Data Binding is the recommended direction for new Rive work. The official Data Binding migration guide explains replacing legacy inputs and event-based communication with View Model properties.

Preserve semantics during the move. An ongoing activity is different from a one-time request. A trigger asking the character to celebrate should not accidentally become a boolean that remains true forever.

Document ranges and defaults. A zero value might mean idle, silence, a closed mouth, or the center of a coordinate system, depending on the property. The implementation needs the meaning, not just the type.

For properties that represent discrete choices, reject or map unsupported values deliberately. For continuous values, decide whether clamping is appropriate. Handle missing data separately from a legitimate zero.

If the migration also changes the artwork, keep a record of intentional visual differences. Otherwise, reviewers may not know whether a different pose is a redesign or a broken control mapping.

Use the async API consistently

Mixing deprecated synchronous access with newer asynchronous access creates an integration that is difficult to reason about.

Choose the documented API surface for your destination release and migrate callers systematically. Search again for old methods after the first implementation passes.

Pay attention to the period between requesting an instance or property and receiving it. The owning screen may disappear, the file may change, or a newer operation may supersede the request.

Associate asynchronous work with the owner and asset revision that requested it. If the result belongs to a stale owner, do not attach it to the current visible character.

Avoid solving every readiness issue with a fixed timeout. Waiting an arbitrary number of milliseconds can hide a race on one device while leaving it on another. Use the runtime’s actual loading and readiness signals.

Coordinate navigation, backgrounding, and playback

An interactive character lives inside an application lifecycle. It should not keep acting on a conversation that the product has already stopped.

React Native’s AppState API reports foreground/background changes. Use those signals as inputs to your product policy; they do not by themselves decide whether speech should pause, stop, or continue.

Write that policy explicitly. For example, leaving a voice-assistant screen might cancel playback and return the mouth to rest, while opening a small overlay might leave the conversation active.

On resume, apply current state. Do not blindly replay an old speaking pose because the view was paused at that moment.

Unsubscribe from application events when the owning component no longer needs them. Follow the runtime’s resource ownership rules so cached files remain valid for active consumers and abandoned instances do not keep receiving updates.

Test interruption before polishing transitions

The most convincing migration test is not a full animation playing from start to finish. It is a sequence that changes direction halfway through.

Use a repeatable scenario on both iOS and Android:

Open the screen from a fresh app start.
Start listening, then enter thinking.
Begin speech and update gaze.
Cancel speech before completion.
Start a new interaction immediately.
Deliver a late callback from the old interaction in your test harness.
Confirm that the current session remains in control.

Then test asset failure, missing properties, and navigating away during initialization. Each should produce a defined response rather than a frozen character or an indefinite loading state.

If multiple characters appear at once, verify instance isolation. Updating one mascot should affect another only when the product intentionally shares state.

Keep accessibility and fallback behavior intact

A migration should preserve the useful non-animated interface as well as the visual feature.

Keep status text, transcripts, retry actions, and playback controls accessible in the host app. If the character fails, the essential workflow should remain understandable.

React Native’s AccessibilityInfo API exposes reduced-motion preferences. Use those preferences according to the character’s designed reduced-motion behavior rather than treating them as a reason to remove necessary state feedback.

Check text scaling and narrow layouts around the character. A successfully upgraded native module does not prove that the full product screen is still usable.

Include these checks in acceptance so accessibility is not accidentally lost while developers focus on build errors and renamed methods.

Define a rollback that restores a compatible pair

A migration rollback should restore both the application integration and the asset version it expects.

If you changed View Model names or control meanings, installing the previous package alone may not restore the previous behavior. Keep a known compatible combination of dependency lockfile, adapter, and .riv asset.

If you evaluate a beta runtime, record the reason and the acceptance results separately from the stable API migration. That makes the release decision concrete instead of relying on enthusiasm for a newer version.

Do not silently update a remote production asset to a new schema while older app versions still use the previous one. Version your delivery path or preserve the contract expected by installed clients.

What a finished migration should include

The deliverable is a working, documented integration: destination versions, platform coverage, asset revision, control schema, lifecycle rules, known limitations, and a reproducible acceptance sequence.

For Mascot Engine’s Rive integration and character services, a useful project brief includes the current package versions, target OS versions, exported asset, editable source availability, and the exact behavior that fails or needs to change.

Mention whether you need migration support only or also want new rigging, expressions, lip sync, or State Machine work. Those are related tasks, but they should be estimated and verified separately.

By Praneeth Kawya Thathsara, founder of Mascot Engine.

Rive Mascot Performance in Flutter: Loading, Caching and Lifecycle

Praneeth Kawya Thathsara — Wed, 09 Sep 2026 17:29:37 +0000

The mascot looks smooth on an empty Flutter screen. Then you put it beside a scrolling list, add speech playback, navigate away and back, and discover that the real product behaves differently.

That does not automatically mean the character is too complex. The work may be happening in the wrong place: repeated loading, unnecessary widget rebuilds, controllers that outlive their screens, or multiple textures where a shared rendering arrangement would be appropriate.

Performance work starts by identifying which cost you are paying. Download time, file parsing, state updates, rendering, and retained memory are different problems. A single “optimize the animation” ticket rarely captures them well.

This guide proposes a practical workflow for Flutter teams shipping Rive mascots in onboarding, support, learning, or AI assistant interfaces. It does not present invented benchmark results or a universal fastest configuration. Use it to build and measure the integration your product actually needs.

Start with the runtime generation you are using

Rive’s Flutter APIs have evolved. Before comparing examples, record the Flutter version, rive package version, renderer, target operating systems, and features used by the asset.

The current Rive Flutter guide documents RiveWidget, RiveWidgetBuilder, file loaders, controllers, and shared rendering options. Its examples may differ from older tutorials using earlier APIs. Follow the guide for the version you adopt rather than combining unrelated generations of code.

Keep that version record with the performance notes. Otherwise, a later developer may attribute a changed result to artwork when the runtime or renderer changed at the same time.

Also list your lowest supported device tier. A smooth result on the newest phone is useful, but it is not an acceptance test for the rest of your audience.

Separate the costs before changing the asset

An interactive character can involve several independent stages:

Stage	Typical question
Retrieval	Are bytes bundled locally or fetched remotely?
Loading and parsing	Is the same file initialized repeatedly?
Instance setup	Are controllers and View Models recreated unnecessarily?
Application updates	Does a small value change rebuild a large subtree?
Rendering	What is the cost of the visible scene and texture setup?
Retention	Which resources stay alive after leaving the screen?

Observe the symptom first. A slow first appearance points toward a different investigation than continuous frame drops. Memory that grows after repeated navigation suggests another category again.

Use separate measurements for cold load and warm reuse. A cache can improve a repeat visit while leaving the first visit unchanged. Report both rather than choosing the more flattering result.

Reuse file data at an intentional scope

If several screens use the same character asset, decide whether they should share a loaded file or load it independently.

The right scope depends on frequency and lifetime. A mascot present throughout the application may justify a longer-lived owner. A character used once in an optional flow may be better loaded only when that feature opens.

The official Rive Flutter documentation includes file-loading and reuse examples. Use them to establish one explicit owner rather than letting every widget invent its own cache.

Ask four questions about that owner: who creates the resource, who may borrow it, when it can be released, and what invalidates it after an asset update?

Avoid turning every asset into a permanent global. Reuse trades repeated work for retained resources. That trade can be sensible, but it still needs a reason.

For remotely delivered files, distinguish in-memory reuse from a durable offline cache. Keeping an object alive during one session does not mean the file will remain available after a process restart.

Share the file without accidentally sharing personality

Two character widgets can use the same artwork while representing different interactions.

Imagine a support mascot speaking in a panel while a smaller onboarding mascot waits in a card. If they share the same mutable control instance unintentionally, one screen’s activity updates may animate both.

Rive’s Flutter Data Binding guide distinguishes View Models from instances that contain values. Use that distinction to define which state is shared and which belongs to a particular visible character.

Write down the ownership boundary in plain language: “The file is shared for reuse; each visible assistant has its own conversation state.” If synchronized characters are intentional, document that instead.

This is a correctness issue as much as a performance issue. Reusing the wrong thing can make an efficient implementation behave incorrectly.

Keep setup work out of frequently repeated builds

Flutter can call build() frequently. Its performance best practices recommend avoiding expensive repeated work there and localizing state updates so unrelated descendants do not rebuild unnecessarily.

Apply that principle to the mascot’s lifecycle. File loading, controller creation, and subscriptions should have deliberate owners and initialization points. A parent rebuilding should not silently create a new character session.

For audio-driven motion, avoid using every audio sample as a reason to rebuild the whole page. Decide how values reach the already-ready character instance and update only the UI that actually needs a Flutter rebuild.

Do not add layers of state management solely because an animation exists. A small, stable adapter is often easier to inspect than a large abstraction that hides when objects are created and disposed.

Keep the product’s state independently accessible. If the character reloads, you should be able to apply the current snapshot without reconstructing the conversation from animation history.

Design the asynchronous exit path

A user can leave a screen before its asset finishes loading. That path deserves the same attention as successful initialization.

Plan what happens when loading completes after the owner is gone. The result may need to be released rather than attached to an obsolete widget. Avoid callbacks that update UI or character state after their subscription or owner has been disposed.

The exact cleanup calls depend on whether you use a builder-managed integration or manually manage files and controllers. Follow the relevant API’s ownership rules and do not assume every object is disposed by the same component.

For manual ownership, document the order in which subscriptions stop and resources are released. A shared file should remain alive while active consumers still need it.

Test rapid navigation repeatedly. Open the screen, leave before loading completes, return, and begin an interaction. This sequence often reveals bugs that a single successful load does not.

Need an interactive Rive character for your product? Mascot Engine creates app mascots, AI companions, State Machines, lip sync, and developer-ready systems for Web, Flutter, and React Native. Explore live work at Mascot Engine and send your project brief on WhatsApp.

Treat shared rendering as a separate decision

File reuse and rendering reuse are not the same optimization.

Rive documents RivePanel for drawing multiple widgets to a shared texture with the Rive Renderer. The current guide also describes manually managed shared textures for layouts that do not fit a common panel ancestor. These are rendering arrangements, not replacements for a clear file and controller lifecycle.

Consider this option when multiple Rive graphics are visible together. First inspect whether their placement and stacking requirements fit the arrangement. Then compare it against your existing screen using the same device and interaction sequence.

Do not promise that shared rendering makes every product faster. A screen with one small character is different from a list containing many graphics. The cost of the surrounding Flutter interface also remains relevant.

If you adopt shared textures, include draw order, ownership, and release behavior in the integration notes. Otherwise, a future overlay or route change can invalidate assumptions that were never written down.

Let inactive characters become inactive

A character does not need to perform the same amount of visual work in every product situation.

Decide what happens when it is off-screen, behind another route, or in an inactive application. The appropriate policy might pause decorative motion, switch to a quiet pose, or stop a speech interaction. The choice depends on the feature’s behavior, not just the animation.

Keep audio and visual state coordinated. Pausing the character while audio continues can be incorrect for a visible assistant; stopping audio merely because a decorative widget is rebuilt can be equally wrong.

On resume, synchronize with the current application state. Do not automatically replay a previous speaking pose if playback has already ended.

Include reduced-motion behavior in this policy. A static or restrained character can still communicate state through accompanying text and controls. Accessibility should be part of the design, not a last-minute performance fallback.

Build a reproducible profiling session

Flutter’s DevTools Performance view is the starting point for investigating frame behavior. Follow its guidance for meaningful performance measurements rather than judging the final experience from debug-mode behavior alone.

Create a short scenario that represents the product:

Start from the chosen cold or warm condition.
Open the screen and wait for the character to become ready.
Scroll the surrounding content.
Start the character’s most demanding interaction.
Interrupt it and trigger a recoverable error.
Leave the screen and return.

Record the device, build mode, runtime version, renderer, asset revision, and scenario duration. Keep these constant when comparing two implementations.

Capture both an otherwise equivalent screen without the character and the complete screen with it. That comparison helps distinguish existing application costs from costs introduced by the integration.

Measure memory over repeated navigation

An individual memory reading tells you little about lifecycle quality. Look at what happens after the same interaction is repeated.

Open and close the feature several times under controlled conditions. Watch whether resources settle into the expected retained set or whether repeated visits keep increasing the baseline.

Flutter provides a DevTools Memory view for investigating memory behavior. Interpret its measurements alongside your ownership model; some retained resources may be intentional caches, while others may be abandoned subscriptions or instances.

Do not call every retained object a leak. The useful question is whether the object still has a documented owner and purpose after the user leaves the feature.

If the problem appears only after speech or a particular state, include that action in the reproduction sequence. A clean idle navigation test does not cover every resource the feature uses.

Optimize the design after locating the bottleneck

Once the profile points toward rendering or scene complexity, collaborate with the character designer.

Review the work actually visible at the intended display size. Fine detail that is never perceived may not justify its cost. Inspect unnecessary animated properties and decorative movement that continues when it adds little value.

Change one category at a time and compare the same scenario. Avoid simultaneously switching renderer, rewriting lifecycle code, and simplifying artwork; the result will not tell you which change mattered.

Preserve behavioral acceptance while optimizing. A faster character that misses cancellation or displays the wrong emotion is not an improvement for the user.

For complicated facial systems, separate property conflicts from performance problems. A mouth that snaps because two animations overwrite it does not necessarily indicate slow rendering.

What to include in a performance handoff

Deliver the asset revision, runtime versions, file ownership plan, instance-sharing rules, cleanup policy, and the profiling scenario. Include results only for environments actually measured.

A useful report says what changed and which cost it targeted. For example: “We moved file ownership above the repeated screen widgets to avoid reinitializing the same asset on each visit.” The measured effect belongs beside that statement, with the test conditions.

Keep known limitations visible. If the character was tested on Android and iOS but not Flutter web, say so instead of treating Flutter as one identical execution environment.

Mascot Engine’s interactive character services cover runtime-ready Rive assets and developer handoff. For an integration review, send the asset, Flutter and Rive versions, renderer, target devices, reproduction steps, and any existing profiles.

By Praneeth Kawya Thathsara, founder of Mascot Engine.

Fixing Rive State Machine Conflicts: Blinking, Speaking and Gaze

Praneeth Kawya Thathsara — Wed, 09 Sep 2026 17:26:24 +0000

The mascot blinks correctly on its own. The speaking animation also works. Put them together, and the eyes freeze, the mouth snaps, or the head stops following the pointer.

It is tempting to add another condition until the preview looks right. That can hide the symptom while making the State Machine harder to understand.

A more useful first question is: which systems are trying to control the same property at the same time?

This guide walks through a practical debugging method for interactive Rive characters. It separates three common sources of trouble: animation ownership, transition behavior, and competing application updates. The examples are illustrative; they are not claims about a named client project or a benchmark of a particular file.

Understand what layers actually separate

A State Machine layer can play one state at a time, and multiple layers allow concurrent animation or interaction. They do not automatically isolate the properties each animation touches.

If two layers animate the same property, order affects the result. Rive’s current layer documentation describes lower layers in the list taking priority over layers above them when their animated properties overlap.

That means a layer called Blink is not guaranteed to control only blinking. If its animation also contains a head rotation keyframe, it can interfere with gaze or body motion.

Layer names communicate intent. The animated properties determine the actual interaction. Debug the properties, not just the names.

Step 1: Reduce the failure to a short sequence

Do not begin by changing several layers and transition durations at once. First, write down the smallest sequence that reliably causes the problem.

For example:

1. Load the character in idle.
2. Set gaze to the upper-right target.
3. Begin speaking.
4. Trigger a blink.
5. Observe that gaze returns to center.

Record the expected and actual behavior separately. “Gaze breaks” is less useful than “the pupil position resets when Blink enters its closed-eye pose.”

Repeat the sequence in the editor and in the target runtime. If it fails in both, inspect the asset first. If it fails only in the application, investigate initialization, control updates, and lifecycle behavior before rebuilding the rig.

Save a copy or revision before editing. You want to compare one deliberate change against a stable baseline, not rely on memory after ten experiments.

Step 2: Build a property ownership table

List the visible systems and the properties they should own. Keep the table small enough to use while inspecting the file.

System	Intended responsibility	Possible conflict
Body activity	Torso and broad posture	Accidental head or facial keys
Gaze	Eye target and permitted head adjustment	Blink timeline resets the target
Blink	Eyelid closure	Expression layer forces eyes open
Speech	Mouth pose or jaw opening	Smile animation controls the same deformation
Emotion	Brows, cheeks, restrained expression	A full-face pose overwrites speech

This is an example architecture, not a mandatory Rive layout. Some characters need a different division. The goal is to make overlap intentional.

Inspect each relevant timeline for keys outside its assigned area. A neutral pose keyed across the whole character can be convenient during authoring but surprising when mixed with other behaviors.

Do not delete keys merely because they overlap. Decide whether they are necessary, whether they belong in another animation, or whether the combination needs an explicit design rule.

Step 3: Isolate layers without losing their configuration

Disable one suspected layer and replay the same sequence. Rive’s layer menu supports disabling a layer, which lets you isolate behavior without deleting the setup.

If the problem disappears when the expression layer is disabled, you have narrowed the search. Re-enable it and inspect the properties that overlap with the failing system.

Change one thing, replay, and record the result. This sounds slower than trying several fixes together, but it keeps you from accepting an accidental improvement that creates another bug elsewhere.

Use priority as an explicit design choice. Reordering layers can be appropriate when one behavior really should dominate another. It is less convincing when the explanation is simply “this order looks okay in the current preview.”

Once you have a proposed fix, test all the combinations that share those properties, not just the original failing sequence.

Step 4: Distinguish an ownership conflict from a transition delay

Sometimes the intended state is selected, but the character appears unresponsive because the transition cannot leave when you expect.

Rive transitions include conditions, duration, and optional exit behavior. Its transition documentation explains Exit Time and Allow Exit During Transition. These settings affect whether a new request can take effect promptly.

For an interruptible assistant, a cancellation path should not wait for an unrelated flourish to finish. For a decorative celebration, waiting for a gesture to complete may be exactly what you want.

Write the behavior in product terms first: “Stop speaking as soon as playback stops” or “Finish the short acknowledgement unless a new conversation starts.” Then configure the transitions to match.

Do not assume that a transition existing in one direction creates a return path. Verify entry and exit behavior independently, including paths that only run after an error.

Step 5: Check conditions for ambiguity

A character can look unpredictable when multiple conditions are true or when a transition has no meaningful guard.

For example, three booleans named listening, thinking, and speaking can describe impossible combinations if different callbacks update them independently. A single activity selector can reduce that ambiguity for a product that allows only one primary activity at a time.

This does not mean every control should be merged. Gaze and emotion often need to remain independent of activity. The useful distinction is between mutually exclusive product modes and behaviors that should occur together.

Document the valid combinations. If the app can listen while playing audio, that is a different requirement from a strictly turn-based assistant. The file should reflect the intended conversation model rather than accidentally choosing one.

Need an interactive Rive character for your product? Mascot Engine creates app mascots, AI companions, State Machines, lip sync, and developer-ready Rive systems for Web, Flutter, and React Native. View live character work or send a project brief on WhatsApp.

Step 6: Give the mouth one clear speaking strategy

Speech is a frequent source of conflicts because several systems want to make the face expressive.

A mouth can use an amplitude-driven opening value, a timed viseme selector, or a simple speaking loop. Each can be useful, but combining them requires a deliberate plan.

Suppose a viseme selects closed lips while an audio-level blend forces the jaw open. Both systems are responding to valid data, but the resulting pose may be wrong. Decide whether amplitude is ignored in viseme mode or used only as a controlled secondary adjustment.

Likewise, a smile animation should not unknowingly overwrite the exact mouth shape required for speech. You might place warmth in cheeks and brows, create compatible smiling mouth poses, or reduce the smile during particular visemes. That is a character design decision, not something runtime code can reliably guess.

Test rest and silence as carefully as active speech. A cancelled utterance should not leave the last open mouth pose on screen.

Step 7: Trace application writers

If the asset behaves correctly in the editor, inspect the application’s update path.

List every writer for each public property: conversation events, audio callbacks, idle timers, pointer handlers, route listeners, and setup code. One property can have several callers, but it should have a clear authority deciding its current value.

For a difficult issue, log a compact record containing the property, new value, source, conversation ID, and time. Avoid logging private conversation content when the control data is enough to diagnose the animation.

Consider this sequence: an utterance is cancelled, a new listening session starts, and the old utterance’s completion callback arrives late. If that callback unconditionally selects idle, it overrides the new session.

Associate callbacks with the operation they belong to. Ignore stale events and derive the character state from the current application snapshot. No amount of layer reordering can fix an application that continually supplies the wrong activity.

Step 8: Check initialization and instance identity

Another common category is writing correct values to the wrong instance or at the wrong time.

Rive separates a View Model definition from the instances containing actual values. The Web Data Binding guide documents retrieving those instances after loading and binding them to the scene.

Verify that the instance receiving updates is the one connected to the visible character. This matters when a screen contains multiple mascots or when navigation recreates a controller.

If the application caches references to properties, replace those references when the underlying instance changes. A value written successfully to an old instance will not necessarily affect the new visible character.

Also check initial values. An animation can appear to “snap back” because newly created state is applying defaults after your application already wrote its current snapshot.

Step 9: Separate coordinate problems from animation conflicts

Gaze bugs are not always State Machine bugs. A pointer position in screen coordinates is not automatically a useful value in the character’s local coordinate system.

Write down the expected range and orientation for lookX and lookY. For example, both might use -1 to 1, with positive Y meaning down on screen. If the host uses the opposite convention, the character will look away from the target even when the rig is correct.

Account for the character’s displayed bounds, fit, alignment, and any letterboxing. Recalculate the mapping when the layout changes. Clamp the final values and specify what happens when the target disappears.

On a touch interface, choose an intentional attention target instead of waiting for mouse movement that never occurs. A neutral pose is usually better than stale gaze from a previous interaction.

Step 10: Turn the fix into a regression checklist

Once the original sequence passes, broaden the checks to nearby behaviors.

Sequence	What to verify
Idle plus blink	No unintended head or mouth movement
Speaking plus blink	Speech continues while eyelids close
Speaking plus emotion	Mouth poses remain readable
Gaze plus layout resize	Target mapping remains consistent
Cancel plus new session	Old callbacks do not overwrite activity
Failure plus retry	The character exits the error state
Screen leave and return	Current application state is restored

Use the exported file in the actual target runtimes. Record package versions and renderer choices with the result. Rive’s runtime introduction notes that support varies by feature and runtime, so editor-only verification is insufficient for a cross-platform release.

You do not need a vast automated suite for every visual adjustment. You do need a repeatable way to reproduce the failure and show that the intended combinations still work.

What to include when requesting a repair

A useful debugging brief contains the .riv file, editable project access or backup, runtime version, target platform, current control schema, and a short reproduction sequence.

Include a recording if it helps explain the symptom, but pair it with the values or events being sent. “The eyes freeze when activity changes from thinking to speaking” is much easier to investigate than “the mascot feels broken.”

If several designers or developers have worked on the file, mention that history and identify the current source of truth. The first repair task may be reconstructing the intended contract.

Mascot Engine’s Rive character services include rigging, State Machines, gaze controls, lip sync, and developer-ready handoff. Specialist help is useful when a local visual fix must remain compatible with speech, expression, and multiple runtimes.

By Praneeth Kawya Thathsara, founder of Mascot Engine.

Rive Data Binding vs State Machine Inputs: A Mascot Migration Guide

Praneeth Kawya Thathsara — Wed, 09 Sep 2026 17:22:33 +0000

Your mascot integration starts with three controls: wave, smile, and speaking. A few months later, the character also needs a progress value, a display name, theme colors, and a different reaction for each onboarding step.

At that point, the problem is no longer how to trigger an animation. It is how to maintain a coherent interface between the application and the Rive file.

Rive’s Data Binding system provides a broader interface than legacy State Machine Inputs. For an existing product, however, replacing an API call is only a small part of migration. You also need to preserve meaning, defaults, ownership, and the behavior users already rely on.

This guide explains the architectural difference and proposes a migration workflow for interactive mascots. The examples are design sketches rather than a downloadable, tested .riv integration. Match the API details to the runtime version in your project before implementation.

What changes with Data Binding?

Legacy State Machine Inputs expose numbers, booleans, and triggers used to control animation behavior. Data Binding exposes View Model properties with a wider set of types and lets those values connect to more than State Machine transitions.

Rive recommends Data Binding for new work and future updates. Its current migration guide also says existing inputs and events continue to work; an already functioning production file does not require an emergency rewrite simply because a newer approach exists.

That distinction helps with planning. You can keep a stable legacy integration running while defining the contract for its next release.

Question	Legacy-input approach	Data Binding approach
What is the main public interface?	Named inputs attached to State Machines	Properties on View Model instances
How do you represent richer product data?	Often with extra conventions and separate APIs	With additional supported property types
What can data drive?	Primarily animation state control	Transitions and bound scene properties
What should new work target?	Compatibility needs may justify it	Rive’s recommended direction

The benefit is not that every scene becomes simpler automatically. The benefit is having a more expressive place to define the contract. A poorly designed View Model can be just as confusing as a poorly named input list.

A View Model is a schema; an instance holds values

Keep three concepts separate. A View Model defines the structure, a View Model instance holds values, and bindings connect those values to the scene. Rive’s Data Binding overview introduces these responsibilities.

For a product mascot, the schema might describe activity, expression, progress, and gaze. One instance could be listening on an onboarding screen while another is idle in a support panel.

Think carefully before sharing the mutable instance. Two characters may reuse the same exported file without being intended to mirror each other’s expression. Shared file data and shared interaction state solve different problems.

Also distinguish a blank instance from the designer’s default instance. A blank numeric value of zero is not necessarily the intended neutral pose if the design uses a different convention. Record the intended initialization explicitly.

Begin with an inventory of actual behavior

Before changing the editor file, list every place the app writes an input or listens for a response.

Include startup code, error handlers, route changes, timers, speech callbacks, and any interaction originating inside the artboard. Integrations often look small until you include the paths that run after cancellation or navigation.

For each existing control, record its name, type, meaning, default, writer, and observed effect. Then ask whether it represents persistent state or a momentary request.

For example, isSpeaking describes an ongoing condition. celebrate asks for a one-time response. Converting both into booleans without an explicit reset rule changes their semantics.

Capture a short set of reference interactions from the current product. You are establishing a behavioral baseline, not proving that every old implementation decision must survive.

Design the new contract before converting the file

Suppose the legacy system exposes isListening, isThinking, and isSpeaking. All three can accidentally become true. The file then has to resolve a combination that the product never intended.

A single activity selector can make those states mutually exclusive at the application boundary. Keep expression separate so a warm speaking pose does not require a whole new activity value.

Here is an example mapping:

Existing control	Proposed property	Migration decision
Three activity booleans	`activity`	One documented selector
`smileAmount` number	`warmth`	Keep range 0–1 and define neutral
`celebrate` trigger	`celebrate` trigger property	Preserve momentary semantics
Direct text-run update	`displayName` string	Bind the text in the file
Separate color mutations	`accentColor` color	Bind intended visual elements

These are example names, not official Rive conventions. The correct interface is the smallest one that expresses your product’s needs clearly.

Avoid exposing every bone, transform, and timeline to application code. Public properties should describe meaningful controls. The designer needs room to improve the animation without changing every caller.

Keep an adapter between product events and Rive

Do not scatter runtime-specific property access across your feature code. Put that access behind a small adapter that the rest of the application can call.

The product might request setActivity("listening"), while the adapter maps that to the file’s numeric or enum representation. If the schema changes later, the mapping has a clear owner.

Product event
    -> validate current conversation state
    -> map to the mascot contract
    -> update the bound View Model instance
    -> let the State Machine produce the visual response

Validation belongs at this boundary. Check allowed discrete values, clamp continuous values where appropriate, and reject non-finite numbers. Log meaningful integration errors in development rather than silently displaying the wrong state.

Keep a current snapshot of persistent controls. If the asset finishes loading after the user has already entered listening mode, apply the snapshot rather than replaying every historical UI event.

Need an interactive Rive character for your product?

Mascot Engine creates app mascots, AI companions, State Machines, lip sync, and developer-ready Rive systems for Web, Flutter, and React Native. Explore Mascot Engine’s live work and send your project brief on WhatsApp.

Convert editor behavior and runtime code together

Rive documents an editor command to convert inputs to View Models. Treat that as a migration aid, not a substitute for reviewing the resulting interface.

Work on a versioned copy. Inspect each converted condition, blend, and interaction. Confirm that the properties intended for runtime control are available through the chosen instance and that the correct defaults are assigned.

Then update the adapter to use the new properties. Avoid a halfway state where one callback writes a legacy input while another writes a View Model property controlling the same behavior.

If you deliberately support both asset versions, make the selected contract explicit. Choose the adapter once when the asset is loaded. Guessing which interface exists during every update makes failures harder to reproduce.

Keep the original exported file and matching application integration available for rollback. A rollback plan should restore a known pair, not mix an old asset with a new schema adapter.

Web integration: readiness and binding come first

The Web runtime exposes View Models and their instances after the file loads. It supports automatic binding to the default instance, as well as explicit binding. These details are documented in the Web Data Binding guide.

A minimal property update can look like this inside a ready integration:

// Illustrative fragment: the Rive file must already be loaded,
// and the intended View Model instance must already be bound.
const instance = riveInstance.viewModelInstance;
const progress = instance?.number("progress");

function updateProgress(value) {
  if (!progress || !Number.isFinite(value)) return;
  progress.value = Math.max(0, Math.min(1, value));
}

This fragment intentionally does not load the file or manage the full lifecycle. In production, decide how a missing property should be reported and how references are replaced after an asset reload.

Cache property references when the instance becomes ready. If you bind a new instance, obtain references from that new instance instead of continuing to write to the old one.

Flutter integration: be precise about ownership

Flutter has its own controller and binding APIs; translating a JavaScript example word for word is not an integration strategy.

Rive’s Flutter Data Binding documentation describes creating instances, binding them through a controller, and retrieving typed properties. Use the documentation matching your installed runtime and follow the ownership rules of the objects you create.

Place initialization at a stable lifecycle boundary. Recreating the file or controller whenever a parent widget rebuilds can hide migration bugs behind unrelated UI updates.

Separate application state from the visual instance. When a screen returns, derive the character’s activity from the current product state. Do not assume that the last animation pose is the current source of truth.

React Native integration: check which runtime you have

There is an important package distinction between older examples and the current integration. Rive provides a React Native migration guide for moving to @rive-app/react-native.

Before copying any hook or ref method, verify its package and version. A correct example for one generation of the runtime can be wrong for another.

Write down the native requirements and build configuration before making a broad migration. Confirm a minimal character integration first, then connect conversation events, audio, and navigation. This sequence makes it easier to distinguish a native setup problem from a View Model contract problem.

Prevent feedback loops in bidirectional designs

When data can move in both directions, a scene interaction may update a property that the application is also observing. That can be useful, but the ownership rules must remain explicit.

Consider a character that requests help when tapped. The request can flow into application logic. The app then decides whether to open a panel, start a session, or show an error.

Do not immediately write a conflicting value back just because a listener fired. Record which updates represent user intent, which are application decisions, and which are visual completion signals.

Keep important business operations outside animation callbacks. A success gesture can acknowledge a completed action; it should not be the only thing that makes the action happen.

Test semantics, not just property access

It is possible for every property lookup to succeed while the migration is still wrong.

Use a test matrix that covers initial load, a normal interaction, interruption, failure, recovery, and two simultaneous character instances. Check that the correct character reacts and that a stale callback cannot overwrite newer state.

Exercise boundary values deliberately. For progress, test zero, one, and an intermediate value. For activity, test each documented value and an invalid one. For a trigger, test two separate requests and establish what should happen if a second arrives before the first animation completes.

Compare the migrated asset against the reference interactions you captured earlier. Document intentional differences so reviewers do not mistake a planned behavior change for a regression.

What should be in the migration handoff?

Deliver the updated editable project, runtime export, property schema, adapter mapping, defaults, lifecycle notes, and platform test results. Include a list of removed names so application developers can search for stale references.

Version the schema as an integration artifact. Even a simple release note such as “activity is now a single selector; old activity booleans are removed” can prevent hours of confusion.

For a broader view of the delivery package, use the Rive mascot developer handoff checklist as a prompt to discuss integration requirements with your character specialist. The important outcome is a contract that both the designer and developer can explain.

When a specialist is useful

Bring in help when migration overlaps with rigging changes, lip sync, nested components, or multiple platforms. Changing the data interface while redesigning the character creates more variables than a simple API update.

Mascot Engine builds interactive Rive character systems and provides rigging, State Machine, and developer handoff services. For a migration estimate, send the current runtime versions, existing control names, required platforms, and the behavior you need to preserve.

By Praneeth Kawya Thathsara, founder of Mascot Engine.

Rive Mascot Developer Handoff: A Production Checklist for Web and Mobile

Praneeth Kawya Thathsara — Wed, 09 Sep 2026 17:19:17 +0000

A character waves beautifully in the preview. The designer sends a .riv file. Your developer opens the integration ticket and immediately has questions: which artboard, which State Machine, which properties, and what should happen if the request fails?

Those questions reveal a delivery gap. The animation may be finished visually, but the product interface is still undefined.

A useful Rive mascot handoff gives the next developer enough information to load the character, control it, recover from failure, and update it later. It also gives the founder a concrete way to decide whether the work is complete.

This checklist is for teams commissioning or integrating interactive app mascots, onboarding characters, and AI companions. The example names and ranges are proposed conventions, not requirements imposed by Rive. Use them to build your own delivery agreement before production starts.

1. Separate editable source from the runtime file

Start by asking for two different deliverables: the source you can maintain and the asset your application can load.

Rive exports a .riv file for runtime use. Its backup format, .rev, preserves information that is stripped from the runtime export. That distinction matters when you need to change the artwork or animation later. See Rive’s official guides to runtime export and backup export.

Request access to the editable project or an appropriate backup, plus the final runtime file. Confirm that the arrangement also covers any external artwork, fonts, images, or audio required by the delivered design. Do not assume that receiving a binary export transfers access to everything used to create it.

Use a release name that connects these deliverables. For example, the project revision, exported asset, and documentation might all reference assistant-v1.2. The exact naming scheme is less important than being able to answer, “Which source produced the file currently in production?”

2. Specify the entry point precisely

A developer should not need to open every artboard to find the intended character.

Document the exact artboard name, State Machine name, intended default configuration, and expected initial pose. Include the character’s intended display size and the fit/alignment behavior for narrow and wide containers.

For example:

Asset: assistant-v1.2.riv
Artboard: ProductAssistant
State Machine: AssistantController
View Model: AssistantData
Initial activity: idle
Initial gaze: centered
Initial mouth: closed

These identifiers form part of the integration contract. Treat a public-name change as a coordinated change to both the file and its host code.

Rive allows one exported asset to be used across supported runtimes, but compatibility still depends on the features and runtime versions involved. A file loading successfully is only the beginning of verification; you must also check that the intended behavior is present.

3. Deliver a control schema, not a list of animations

“Idle, happy, wave, talk” is an animation inventory. It does not explain how the application should request those behaviors.

For a new integration, define a small public data interface. Rive’s Data Binding system connects View Model data to scene properties; View Model instances hold the actual values. The official Data Binding overview explains this separation.

An example handoff schema could look like this:

Property	Type	Accepted values	Owner
`activity`	Number	Integer 0–4	Conversation controller
`mood`	Number	Integer 0–2	Product state adapter
`mouthOpen`	Number	0–1	Audio controller
`lookX`	Number	-1–1	Attention controller
`lookY`	Number	-1–1	Attention controller

Below the table, define every discrete value. For this example, activity might mean idle, listening, thinking, speaking, or unavailable. Explain whether unsupported values are rejected, clamped, or mapped to a fallback.

Also document units. A value of 0.5 could mean half-open, half a second, or halfway across an artboard. Developers should never have to infer the meaning from a property name.

4. Decide who can write each value

Many apparently random animation bugs come from competing updates rather than a broken rig.

Imagine an idle timer sets activity to idle while the audio player sets it to speaking. Both updates are valid locally, but only one reflects the overall product state. The handoff should establish one application owner for that decision.

A practical division is to let application logic own business state and let the Rive system own the visual response. The app decides that a submission succeeded. The character decides how the success gesture looks.

Document any values that flow back from the character. If a tap inside the artboard can request an action, distinguish the request from the action’s successful completion. A visual event must not be treated as proof that a network operation finished.

5. Write transition rules as observable behavior

“Smooth transitions” is too vague to test. Describe the conditions that cause a transition and what can interrupt it.

For each primary activity, answer three questions: what enters it, what exits it, and which events take priority? An assistant that is speaking should normally respond immediately to cancellation. A celebratory gesture should not prevent the user from starting a new interaction.

An example rule is: “When playback is cancelled, stop mouth updates, close the mouth, and select the current conversation activity. Ignore completion callbacks belonging to the cancelled utterance.” This is specific enough for a developer to implement and for a reviewer to exercise.

Keep the animation’s timing separate from the network’s timing. A thinking loop should tolerate an unknown wait. Avoid assuming that an answer always arrives before a fixed animation finishes.

Need an interactive Rive character for your product?

Mascot Engine creates app mascots, AI companions, State Machines, lip sync, and developer-ready Rive systems for Web, Flutter, and React Native.

View live work and request an estimate at Mascot Engine. Send your project brief on WhatsApp.

6. Make lip-sync requirements explicit

If the character speaks, the handoff needs more than a “talk” animation.

Specify whether the mouth uses a simple speaking loop, an audio-level envelope, or timed viseme changes. These are different deliverables. An amplitude-driven mouth conveys speaking activity, but it does not identify the mouth shape associated with each speech sound.

For timed visemes, include the supported mouth poses, their IDs, the expected timestamp units, and the mapping from the speech system’s output. State what happens when timing data is missing or an unfamiliar label arrives.

Define the clock used for synchronization. A sequence based on audio playback position can behave differently from one based on when network messages arrive. Test buffering and interruption deliberately.

Finally, specify ownership of the mouth. If a facial expression and the speech system both animate the same deformation, document how they combine or which one wins. This decision belongs in the asset design as well as the host integration.

7. Include a loading and lifecycle plan

The person integrating the character must know when it is safe to access its properties and who releases the associated resources.

Write down the expected loading sequence: load the asset, create the appropriate controller, bind an instance, obtain property references, apply the latest application snapshot, and display the ready character.

Rive’s runtime guides provide platform-specific APIs. The Web parameters reference, Flutter guide, and React Native guide should be linked from the handoff rather than replaced with an unqualified “works everywhere.”

Record resource ownership separately from visual state. Reusing loaded file data does not mean that two visible characters should share the same mutable activity and expression. Explain the intended sharing boundary.

8. Test the exported file in the actual hosts

An editor preview proves that the design works in the editor. It does not prove that the selected runtime, renderer, and device combination supports every feature being used.

Ask for runtime notes that identify the package version, renderer, operating system, device or browser, and test outcome. Avoid a single ambiguous checkbox labelled “mobile tested.”

Use the same short event sequence on each target:

Load from a fresh application start.
Enter listening, then thinking.
Begin speaking and change gaze.
Interrupt speech before it finishes.
Trigger a recoverable failure.
Retry and complete the interaction.
Leave the screen and return.

Include a missing-asset test and an out-of-range input test. Acceptance should cover both the expected path and at least the failures most likely to affect your product.

If performance matters, ask for the measurement method and environment alongside any result. “Runs smoothly” is a subjective observation. A reproducible profile on the supported device tier is more useful than an unexplained frame-rate number.

9. Define the fallback outside the character

A failed character asset should not make the product unusable.

Keep meaningful status text and essential controls in the host interface. A static image or empty decorative area may be an acceptable visual fallback; an invisible Stop button is not.

For an assistant, preserve the transcript and retry path even when animation fails. For onboarding, allow the user to continue without waiting for the mascot to load.

Also agree on reduced-motion behavior. It might reduce idle movement while retaining a concise success indication, or use a static pose throughout. React Native exposes motion-preference information through AccessibilityInfo; the product still needs an explicit policy for how the character responds.

10. Use a small acceptance document

The best checklist is one your team can actually complete during handoff. Put the evidence next to each requirement.

Deliverable	Acceptance evidence
Editable project or backup	Receiving team can access and maintain it
Runtime `.riv`	Release identifier matches the documented source
Artboard and State Machine	Exact names confirmed in each target integration
Public controls	Types, ranges, defaults, and owners documented
Transitions	Interruptions and recovery exercised
Speech behavior	Timing format and missing-data fallback tested
Lifecycle	Loading, disposal, and return-to-screen behavior checked
Accessibility	Text status and reduced-motion behavior reviewed
Runtime coverage	Versions and environments recorded

Add a named owner for unresolved items. A known limitation can be acceptable if everyone understands it before release. An undocumented limitation becomes a surprise for the next developer.

Common questions before signing off

Is the .riv file enough? It can be enough to run the character, but it is not the whole maintenance and integration package. Ask separately for editable source access, dependencies, and documentation.

Can the same file serve Web, Flutter, and React Native? That is a reasonable design target across supported runtimes. Validate the actual feature set on the chosen versions instead of assuming identical behavior from the file extension alone.

Does the animator need to build the whole app? No. A clear scope can stop at an integration-ready asset and a small demonstration. If production integration is required, name the screens, platforms, and acceptance tests explicitly.

When is specialist help useful? When character rigging, layered behavior, speech synchronization, and host lifecycle decisions overlap. A specialist can help make those interfaces consistent before the work spreads across multiple people.

Send a brief a developer can estimate

For Mascot Engine’s interactive character services, a useful brief includes the target platforms, existing artwork, required states, speaking requirements, deadline, and expected handoff depth. Mention whether your team already has a Rive asset that needs repair or wants a new character system.

Include one concrete user journey: “The user asks a question, interrupts the answer, then retries offline.” That reveals more about the work than a long list of adjectives describing personality.

By Praneeth Kawya Thathsara, founder of Mascot Engine.

Need an interactive Rive character for your product? Mascot Engine creates app mascots, AI companions, State Machines, lip sync, and developer-ready Rive systems for Web, Flutter, and React Native. Explore live work and request an estimate, or send your project brief on WhatsApp.

How to Build an Interactive AI Assistant Avatar for Web, Flutter and React Native

Praneeth Kawya Thathsara — Wed, 09 Sep 2026 17:11:36 +0000

An AI assistant avatar is not just a looping video. It is a visible interface to an asynchronous system: microphone capture, model responses, speech playback, interruptions, and failures.

If the character keeps talking after the user presses Stop, the animation is communicating the wrong product state. If it celebrates before an action succeeds, it creates the wrong expectation. A convincing avatar starts with reliable behavior, then adds personality.

For founders and developers building a web product, Flutter app, React Native experience, or SaaS assistant, the useful question is: what contract connects the character to the application?

This guide proposes a practical architecture using Rive State Machines, six named controls, and a shared runtime asset. The state names and numeric ranges below are design recommendations, not built-in Rive conventions. You can adapt them to your product without coupling the animation to one AI provider.

Why Rive fits live product states

A video has a predetermined sequence. A live assistant needs to change direction when something happens: the user interrupts, audio stalls, a request fails, or the interface loses focus.

Rive State Machines let designers connect animation states through conditional transitions. Layers can separate behaviors such as body motion and facial response. That makes it possible to author reusable reactions instead of exporting a video for every combination. See Rive’s State Machine overview.

The important boundary is that your application owns the conversation and business logic. It decides whether a request succeeded and whether audio is actually playing. Rive presents that decision through motion; it should not become your networking or conversation controller.

Treat “lightweight” as a measurable target, not a guarantee. Budget the .riv asset, runtime download, external assets, memory, and frame time together. A simple vector character can still become expensive when the scene accumulates unnecessary complexity. Rive’s runtime introduction also cautions that feature availability depends on the runtime and renderer.

Start with seven essential states

Before rigging a character, write down what each state means and which application event ends it.

State	Product meaning	Suggested visual behavior
`idle`	Ready for the next interaction	Quiet breathing, occasional blink
`listening`	Microphone capture is active	Attentive posture, restrained input response
`thinking`	Waiting for an answer or preparing playback	Small recurring motion that tolerates unknown duration
`speaking`	Assistant audio is playing	Mouth motion with controlled facial expression
`success`	The requested operation has completed successfully	Brief acknowledgement, then return to the appropriate state
`error/offline`	The interaction cannot continue normally	Calm concern, accompanied by a useful text message
`sleeping`	The assistant is deliberately inactive	Resting pose with minimal movement

These meanings matter more than the animation style. Microphone permission alone does not mean listening. Receiving the first text token does not mean speaking. A completed answer does not prove that a requested database update succeeded.

Define transition priority explicitly. An error or cancellation should interrupt speaking; a success gesture should not delay a new listening session. Use interruptible transitions where responsiveness matters, and reserve longer transitions for moments that cannot block interaction.

For an initial implementation, allow one primary activity at a time. Keep emotion and gaze separate. That avoids multiplying states into combinations such as “happy-speaking-looking-left” and makes the design easier to maintain.

Build a clean input architecture

There is an important terminology update: Rive recommends Data Binding and View Models for new projects. Legacy State Machine Inputs still appear in older integrations, but they are no longer the preferred starting point. View Model properties can drive transitions and other bound elements. Read the official Data Binding overview.

Here, “inputs” means the public controls your application supplies. Implement them as exported View Model properties for a new system, with a documented adapter if you must support an older file.

For example, name the artboard Assistant, the State Machine AssistantSM, and the View Model AssistantVM. The following deliberately uses numeric properties to keep the example contract simple; enum properties are another option when supported by your selected runtime versions.

Control	Proposed values	Responsibility
`activity`	Integer 0–6	0 idle, 1 listening, 2 thinking, 3 speaking, 4 success, 5 error/offline, 6 sleeping
`emotion`	Integer 0–3	0 neutral, 1 warm, 2 pleased, 3 concerned
`viseme`	Integer 0–7	Project-specific mouth shape; 0 is rest
`audioLevel`	Number 0–1	Smoothed level of the active audio source
`lookX`	Number -1–1	Horizontal gaze; positive means character’s screen-right
`lookY`	Number -1–1	Vertical gaze; positive means down on screen

Validate values before writing them. Reject invalid activity IDs, clamp continuous controls, and map unknown mouth shapes to rest. Document whether numeric choices are discrete selectors or blend values: interpolating between activity IDs should never accidentally select an unrelated state.

Give each property one owner. The conversation controller owns activity; the speech controller owns mouth timing; the pointer or attention controller owns gaze. Otherwise, an idle timer can overwrite a speaking update while audio is still playing.

flowchart LR
    A[AI event] --> B[Application logic]
    B --> C[Rive State Machine input]
    C --> D[Character response]

For a new file, the diagram’s input step is a View Model property update that drives a State Machine transition. A speech-start event becomes activity = 3; playback completion resets the mouth and selects the next activity.

Use a conversation or utterance ID to discard late events. After cancellation, a delayed completion callback from the previous utterance must not reset a new listening session. Store the latest complete control snapshot so a newly loaded character can immediately catch up with the application.

Need an interactive Rive character for your product?

Mascot Engine creates app mascots, AI companions, State Machines, lip sync, and developer-ready Rive systems for Web, Flutter, and React Native.

View live work and request an estimate at Mascot Engine.

Send your project brief on WhatsApp.

Choose the right speaking system

There are two useful levels of mouth animation. Choose based on the speech data your application can actually provide.

Audio-driven speaking

For a simple assistant, derive a normalized amplitude envelope from the assistant’s output audio. Smooth abrupt changes and map that value to jaw opening or a speaking blend.

This communicates activity without requiring phoneme timing. It is not phonetic lip sync: loudness cannot tell you whether the speaker is forming an “M” or an “O.” Avoid choosing random mouth shapes and describing the result as accurate synchronization.

Use output audio for speaking and microphone audio only for listening feedback. Gate mouth movement on actual playback. During silence, buffering, cancellation, or playback failure, return the mouth to rest rather than leaving the last open pose visible.

Specify which animation owns mouth opening. If audioLevel and viseme both drive the same deformation independently, they can conflict. A sensible contract uses one speaking mode at a time, or explicitly defines amplitude as a small modulation of a selected mouth pose.

Viseme lip sync

A viseme is a visible mouth pose associated with speech sounds. Several sounds can share a pose, so the character usually needs fewer visual shapes than there are phonemes.

Prepare a small mouth library with rest, closed lips, wide, rounded, and other shapes suited to the design. Then document the mapping from the speech system’s timing labels to your viseme IDs. The proposed 0–7 range is only an example; choose the actual set with your animator.

Your speech or alignment system must provide the timing data. This architecture does not assume that loading a .riv file automatically extracts visemes from arbitrary audio.

Schedule changes against the audio playback position, not the arrival time of network chunks. For streamed speech, account for each chunk’s offset and any buffering. Briefly blend compatible shapes where useful, while preserving important closures. Test pauses, rapid speech, interruption, and the end of every utterance.

If timing data is unavailable, fall back to amplitude-driven speaking or a restrained speaking loop. Keep the same activity contract so the rest of the product remains predictable.

Add gaze without making it distracting

Convert a pointer position or UI attention target into normalized character coordinates. Clamp lookX and lookY, ease toward the target, and return to center when the target disappears.

Gaze should support attention: toward the microphone during listening, toward a relevant result after completion, or toward the user during speech. It does not require camera-based eye tracking.

On touch devices, use a tap target or product event instead of assuming a continuously moving cursor exists. Test the gaze after resizing and changing character placement; screen coordinates and artboard coordinates are not interchangeable.

Prepare one .riv system for three platforms

The reusable unit is the exported asset plus its behavioral contract. The host integrations remain platform-specific. Choose runtime versions and renderers first, then validate the same exported file on every target. Do not infer mobile compatibility solely from the editor preview.

Web

Load the file, choose the artboard and State Machine, bind the default View Model instance, and obtain property references only after loading completes.

For example, inside a Web runtime load callback, an adapter can cache a property and update it:

// Requires a loaded Rive instance with autoBind: true,
// an exported default View Model instance, and a number property.
const activity = riveInstance.viewModelInstance?.number("activity");
if (!activity) throw new Error("Missing avatar activity property");

function showSpeaking() {
  activity.value = 3;
}

This illustrates the Web Data Binding API, not a complete voice assistant. Your application still manages audio, readiness, errors, and cancellation.

Handle canvas sizing, asset-load failure, and cleanup when the component unmounts. Rive’s Web parameters reference documents artboard selection, State Machine selection, automatic binding, and lifecycle APIs.

Flutter

Use the current Rive Flutter integration appropriate to your project. Rive documents file loaders, RiveWidgetBuilder, and RiveWidgetController in its Flutter runtime guide; its Flutter Data Binding guide explains accessing and binding View Model instances.

Create and retain the loader and controller at the correct widget lifecycle boundary. Follow the selected API’s ownership and disposal rules. Keep audio-level updates localized instead of rebuilding the entire screen for each sample.

Flutter’s performance guidance recommends avoiding costly repeated work in build() and limiting rebuild scope. Profile the actual screen with the avatar, scrolling, and audio active together, especially on the lowest device tier you support.

React Native

Rive’s current React Native setup guide uses @rive-app/react-native and requires Nitro Modules. Check the documented React Native, native OS, and build-tool requirements before integrating it into an existing app.

Use that runtime’s file loading, view, and View Model APIs to implement the same six controls. Avoid mixing snippets from the legacy package with current APIs; Rive provides a migration guide.

Connect foreground/background changes to your playback policy using React Native’s AppState API. On resume, synchronize from current application state instead of blindly replaying an old speaking animation.

Across platforms, show textual status and preserve usable controls even if the character cannot load. Offer reduced motion and avoid conveying errors through expression alone. React Native’s AccessibilityInfo API exposes reduced-motion preferences and change notifications.

Developer handoff checklist

Ask for a package that another developer can integrate without reverse-engineering the editor file.

Editable .riv source requirement, clarified: request editable Rive project access or a .rev backup and the runtime-ready .riv. Rive distinguishes its editable backup export from its runtime export; a runtime .riv alone is not the complete editable source.
Artboard name: exact spelling, dimensions, intended fit, and alignment.
State Machine name: exact exported identifier and initial behavior.
Named inputs: property names, types, View Model name, default instance, and any legacy adapter mapping.
Valid ranges: discrete values, continuous bounds, viseme mapping, and coordinate conventions.
Default values: initial activity, neutral emotion, closed mouth, silent level, and centered gaze.
Transition rules: priorities, interruptions, gesture completion, timeouts, and recovery behavior.
Runtime test notes: tested package versions, renderers, devices, load behavior, and known limitations.
Fallback state: safe idle or static image on asset failure, with errors explained in the surrounding UI.

Before acceptance, replay a small event sequence: load, listen, think, speak, interrupt, fail, retry, and background/resume. Include missing visemes and a slow network. Confirm that cancellation stops both audio and mouth movement, and that stale events cannot change the next interaction.

When to hire a specialist

Bring in a specialist when the work spans character design, rigging, layered State Machines, mouth-pose design, and runtime integration. The difficult part is often making those pieces agree under interruption, not producing an attractive idle animation.

Mascot Engine’s interactive character services cover Rive mascots, AI characters, rigging, State Machines, viseme lip sync, gaze controls, Data Binding/ViewModels, runtime-ready files, and developer documentation for Web, Flutter, and React Native.

For a useful estimate, send your target platforms, existing artwork, required states, speech provider or sample timing data, expected character size, deadline, and budget range. Mention whether your developers need integration support or only documented assets. Those details help define a realistic scope before animation begins.

By Praneeth Kawya Thathsara, founder of Mascot Engine.

Need an interactive Rive character for your product?

Mascot Engine creates app mascots, AI companions, State Machines, lip sync, and developer-ready Rive systems for Web, Flutter, and React Native.

View live work and request an estimate at Mascot Engine.

Send your project brief on WhatsApp.

I Built a Rive Skill for AI Coding Agents — SKILL.md for Codex, ChatGPT, Cursor & Gemini

Praneeth Kawya Thathsara — Mon, 31 Aug 2026 18:17:24 +0000

I Built an Open-Source Rive Skill for AI Coding Agents

AI coding agents are getting much better at building apps.

But there is still a problem when the task involves Rive.

You can ask an AI tool to:

integrate a .riv file
create State Machine logic
connect runtime inputs
work with Data Binding
debug an animation
optimize a Rive component
prepare a developer handoff

and the answer may look convincing.

But Rive evolves quickly.

An AI model may remember:

an older runtime API
outdated SDK syntax
old State Machine patterns
incomplete Data Binding behavior
a renderer option that changed
generic animation advice that does not match production Rive workflows

That is why I created:

Rive Skill

Production-ready Rive guidance for AI coding agents

👉 GitHub:
https://github.com/uianimation/rive-skill

👉 Download SKILL.md directly:
https://github.com/uianimation/rive-skill/raw/refs/heads/main/SKILL.md

The goal is simple:

Give AI agents a maintainable Rive-specific instruction layer instead of forcing them to rely only on generic model knowledge.

Why AI Agents Need Rive-Specific Guidance

Rive is not just another animation file format.

A production Rive project can include:

Artboards
Timelines
Bones
Meshes
Constraints
Components
Layouts
State Machines
Listeners
Events
Data Binding
View Models
Converters
Nested Artboards
Runtime APIs
Renderers
Scripting
Rive MCP
Accessibility
Performance Constraints

That is a lot of system behavior for an AI coding assistant to reason about correctly.

And the problem becomes more serious when an animation moves from:

Looks good in the Rive Editor

to:

Works correctly in the actual product

Those are not the same thing.

The Real Problem: Rive Handoff Is a System Problem

A Rive animator can create a beautiful animation.

A developer can have the correct SDK installed.

And the integration can still fail.

Why?

Because production Rive work needs a clear contract between:

Designer
   ↓
Rive Animator
   ↓
.riv Architecture
   ↓
Developer
   ↓
Runtime
   ↓
Application State

For example, imagine a voice assistant character.

The .riv file may contain:

Idle
Listening
Thinking
Speaking
Success
Error

The application may need inputs such as:

activity
emotion
isSpeaking
audioLevel
lookX
lookY

If the AI coding agent does not understand that contract, it may try to solve the problem by:

swapping animations manually
creating unnecessary state logic
assuming input names
resetting the State Machine incorrectly
controlling visual layers directly from application code
rebuilding logic already handled inside Rive

That creates fragile integrations.

What the Rive Skill Does

The project organizes Rive guidance into three main areas.

1. Authoring

Guidance around:

Artboards
Timelines
Rigging
Components
Layouts
Assets
Naming
Structure

The goal is to help an AI agent reason about how the .riv file itself should be organized.

2. Interaction

Guidance around:

State Machines
Listeners
Data Binding
View Models
Converters
Runtime-controlled values
Interaction architecture

This is where Rive becomes more than a linear animation.

Instead of thinking:

Play animation A
then animation B

the agent can think in terms of:

Application State
      ↓
Rive Inputs / Data
      ↓
Character / UI Behavior

3. Integration

Guidance around:

Runtimes
Renderers
Scripting
Rive MCP
Performance
Accessibility
Developer Handoff
Debugging

This is particularly important because most real Rive problems happen outside the animation timeline.

Why I Did Not Put Everything in One Huge SKILL.md

One large instruction file sounds convenient.

But it creates another problem:

context overload.

An AI agent working on a Flutter runtime bug does not need every detail about character rigging.

An agent helping with a Rive character rig does not necessarily need the full web renderer discussion.

So the repository uses focused references.

The structure currently looks like this:

rive-skill/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── assets/
│   ├── rive-skill-icon.svg
│   └── rive-skill-community-cover.png
├── evals/
│   └── behavioral-cases.md
├── references/
│   ├── editor-authoring.md
│   ├── interaction-data.md
│   ├── scripting-ai-mcp.md
│   ├── runtimes-performance-accessibility.md
│   ├── runtime-integration-patterns.md
│   ├── runtime-handoff-checklist.md
│   └── official-docs-map.md
├── scripts/
│   ├── build-portable.ps1
│   └── validate-skill.ps1
└── rive-instructions.md

This means the main skill can stay relatively focused while deeper guidance remains available when needed.

SKILL.md vs rive-instructions.md

The repository includes two useful ways to consume the guidance.

`SKILL.md`

Best for tools that support agent skills directly.

For example:

Codex
Agent Skills-compatible clients
Agent workflows with skill discovery

`rive-instructions.md`

Best for prompt-based workflows.

For example:

ChatGPT
Cursor
Gemini
Other AI coding assistants
Custom agents

The portable file bundles the deeper references so the model does not lose important specialist instructions.

Install the Rive Skill in Codex

For a personal skill available across projects:

cp -r rive-skill ~/.codex/skills/rive

For a project-specific installation:

cp -r rive-skill .codex/skills/rive

Then invoke it explicitly as:

$rive

or allow Codex to select it when the request matches the skill description.

Example: Without a Rive Skill

Imagine prompting an AI coding agent:

My Rive animation is not responding correctly in React.
Fix the State Machine integration.

Without enough project context, the agent might immediately start rewriting runtime code.

But the actual problem could be:

Wrong artboard name
Wrong State Machine name
Wrong input type
Wrong input path
Default state mismatch
Nested input path issue
Data Binding mismatch
Old runtime syntax
Missing event listener
Incorrect lifecycle handling

The correct debugging process is not:

Guess
↓
Rewrite
↓
Try again

It should be closer to:

Verify Runtime
↓
Verify Asset
↓
Verify Artboard
↓
Verify State Machine
↓
Verify Inputs
↓
Verify Runtime Contract
↓
Verify Application State
↓
Only then change implementation

This debugging discipline is one of the things the skill is designed to encourage.

Example: AI Character State Machine

Suppose an app contains an interactive Rive mascot.

The runtime contract might be:

Artboard:
Mascot

State Machine:
MascotController

Inputs:

activity
0 = idle
1 = listening
2 = thinking
3 = speaking

emotion
0 = neutral
1 = happy
2 = concerned

isPending
boolean

audioLevel
0.0 → 1.0

A weak implementation may create application code like:

if speaking:
    play speaking animation

if happy:
    play happy animation

But that can conflict immediately.

What if the character is:

Speaking + Happy + Looking Left

A better Rive architecture allows independent systems to coexist.

Conceptually:

Activity → body state
Emotion → expression
AudioLevel → speaking intensity
LookX/Y → eye/head direction

The application sends data.

Rive decides how the animation behaves.

State Machines Are Not Just Animation Playlists

This distinction is important.

A Rive State Machine should not always be treated as:

Animation A
→ Animation B
→ Animation C

It can represent interactive product logic.

For example:

Button
├── Default
├── Hover
├── Press
├── Loading
├── Success
└── Error

Or a mascot:

Mascot
├── Idle
├── Listening
├── Thinking
├── Speaking
├── Celebrate
├── Sleep
└── Error

Or an onboarding component:

Step
├── Locked
├── Available
├── Active
└── Complete

The AI agent needs to understand the animation as a component, not simply as a video.

Why Runtime Contracts Matter

One of the most useful things you can give a developer is a small contract.

For example:

FILE
assistant.riv

ARTBOARD
Assistant

STATE MACHINE
AssistantController

INPUTS

activity: number
0 idle
1 listening
2 thinking
3 speaking

isPending: boolean

confirmed: trigger

Then document:

DEFAULT STATE
Idle

EXPECTED RESTING APPEARANCE
Blue

LOOPING STATES
Idle
Listening
Pending

ONE-SHOT STATES
Confirmed
Success

This tiny document can save hours of back-and-forth.

The Rive Skill includes developer-handoff guidance because animation architecture and integration architecture are connected.

Semantic Naming Matters More Than It Looks

Compare this:

Animation 1
Animation 2
Boolean 1
Trigger
Shape 43
Group 21

with:

Idle
Listening
isPending
triggerConfirmed
Mouth
Head
LeftArm

The second version is not just easier for humans.

It is also easier for AI agents.

AI tools perform better when your project exposes semantic structure.

Meaningful names improve:

Debugging
Documentation
Runtime integration
AI-assisted coding
Future maintenance
Team handoff

AI Makes Good Naming Even More Important

Before AI coding agents, bad naming mostly frustrated developers.

Now it also reduces the quality of machine reasoning.

For example:

input1 = true

tells an AI almost nothing.

But:

isPending = true

provides intent.

Likewise:

triggerConfirmed.fire()

contains much more useful semantic information than:

trigger3.fire()

As software development becomes increasingly AI-assisted, semantic animation architecture becomes more valuable.

Rive Data Binding and View Models

Modern Rive workflows increasingly involve application data, not only animation triggers.

A character may need values like:

username
progress
theme
level
emotion
avatarVariant
notificationCount

Instead of hardcoding visual decisions in application code, those values can participate in a more structured Rive data architecture.

The skill therefore includes guidance around:

Data Binding
View Models
View Model Instances
Converters
Runtime-controlled properties

This is one of the areas where generic AI answers can become outdated quickly, so version-sensitive behavior should be verified against current Rive documentation.

Why Freshness Matters

A static AI answer has a hidden problem:

It may have been correct once.

Rive runtimes change.

Documentation changes.

Feature support changes.

APIs change.

Platform behavior changes.

That means a production-focused skill should distinguish between:

Stable architectural guidance

and:

Version-sensitive technical claims

The Rive Skill includes an official documentation map and uses a research date so current behavior can be checked instead of blindly trusting remembered APIs.

Rive MCP and AI-Assisted Workflows

Another interesting direction is Rive MCP.

As design and development tools expose more structured interfaces to AI agents, an agent may eventually be able to inspect more of a Rive project directly instead of reasoning only from screenshots and descriptions.

That creates workflows like:

Developer Request
      ↓
AI Agent
      ↓
Inspect Rive Structure
      ↓
Understand State Machine
      ↓
Check Runtime Contract
      ↓
Suggest / Apply Integration

But access to tools does not automatically mean good decisions.

An AI agent still needs rules about:

What to inspect first
What should not be changed
Which contract must be preserved
What requires current documentation
What counts as verified evidence
What should be handed back to the developer

That is another reason I think skill files are useful.

Validation Matters Too

The repository does not rely only on manually reading the skill.

It also includes deterministic validation.

You can run:

./scripts/build-portable.ps1
./scripts/validate-skill.ps1

And optionally include live documentation-link checks:

./scripts/validate-skill.ps1 -CheckExternalLinks

The validation workflow checks things such as:

Frontmatter
Reference routing
Required resources
Agent metadata
Portable-file drift
Behavioral evaluation configuration

That matters because instruction repositories can slowly become inconsistent as they grow.

Behavioral Evaluations

There is also a behavioral test manifest.

The idea is to test whether the agent makes the right kind of decision in situations such as:

No tool access
Partial MCP failure
Runtime uncertainty
Contract preservation
Current documentation verification
Evidence labeling

This is different from testing whether the model can memorize one API.

The goal is to test whether it behaves safely and usefully when working on a real Rive project.

The Skill Is Open Source

The project is released under the MIT License.

That means developers, animators and AI-tool builders can inspect it, adapt it and contribute improvements.

Repository:

👉 github.com/uianimation/rive-skill

Direct SKILL.md:

👉 Download SKILL.md

If you work with Rive regularly, starring the repository also makes it easier to find again as the guidance evolves.

Who This Is For

I think this project is useful for several groups.

Rive Animators

Especially if you hand .riv files to developers and want AI coding tools to understand your file structure correctly.

Developers

If you use:

React
Flutter
React Native
Web
iOS
Android
Game engines

and regularly integrate Rive assets.

AI Coding Agent Users

Especially developers using:

Codex
ChatGPT
Cursor
Gemini
Custom coding agents

for Rive-related implementation work.

Teams Building Interactive Mascots

Characters usually involve more complex contracts:

Idle
Expressions
Gestures
Lip Sync
Reactions
Progress
State Machines
Data Binding

Structured guidance becomes even more useful there.

What I Want This Project to Become

I do not want this repository to become a giant collection of copied Rive documentation.

Rive already has documentation.

The useful layer is:

Official Rive Documentation
          +
Production Experience
          +
Architecture Rules
          +
Debugging Order
          +
AI Agent Instructions
          =
Rive Skill

The skill should tell the AI:

What should I think about?

What should I verify?

What should I preserve?

Where should I look for current information?

What should a production-ready result contain?

That is more useful than duplicating every SDK reference.

Example Prompts to Try

After adding the skill to your AI workflow, you could try prompts like:

$rive Review this Rive React integration and identify why the State Machine input is not updating.

$rive Design a runtime contract for this interactive mascot before I hand the .riv file to the Flutter developer.

$rive Review my artboard, State Machine and input naming strategy for developer handoff.

$rive Help me structure a Rive character with idle, listening, thinking, speaking and emotion layers without creating state explosion.

$rive Diagnose this Rive integration without changing the existing runtime contract.

$rive Check whether this Rive API example is still current before recommending it.

Rive + AI Is Bigger Than Code Generation

The interesting part is not simply:

AI can write Rive integration code.

The larger opportunity is that AI can potentially help across the whole workflow:

Brief
↓
Architecture
↓
Character / UI Structure
↓
Rigging Decisions
↓
Interaction Design
↓
State Machine Design
↓
Runtime Contract
↓
Integration
↓
Debugging
↓
Optimization
↓
QA
↓
Handoff

But to do that reliably, the agent needs domain-specific context.

That is what this project is experimenting with.

Need a Human Rive Animator Too?

AI can help developers reason about Rive implementation.

But there are still projects where you need someone to actually design, rig and animate the asset.

If you need:

Rive character animation
interactive mascots
character rigging
UI animation
State Machines
responsive Rive components
Data Binding setup
developer-ready .riv handoff
debugging and optimization

you can also visit:

👉 riveanimator.com

The goal there is production-ready Rive work that can actually move into development rather than stopping at a visual demo.

Contributing

If you find something outdated, incomplete or incorrect, contributions are welcome.

Good contributions should ideally:

Solve a concrete Rive problem
Reference current official Rive information
Avoid duplicating existing rules
Improve AI decision-making
Improve production handoff

Repository:

github.com/uianimation/rive-skill

Final Thoughts

AI coding agents are becoming part of everyday software development.

That means the quality of the instructions we give them matters.

For Rive, I do not think the best solution is to ask a general-purpose model to remember every runtime detail forever.

A better approach is:

Strong base model
+
Current official documentation
+
Domain-specific skill
+
Clear runtime contract
+
Good semantic naming
+
Verification

That combination can make AI-assisted Rive work much more reliable.

If you use Rive with Codex, ChatGPT, Cursor, Gemini or another coding agent, try the project and let me know what is missing.

⭐ GitHub:
https://github.com/uianimation/rive-skill

Real-Time Lip Sync for Rive 2D Characters: Visemes, State Machines, AI Voice & Production Setup

Praneeth Kawya Thathsara — Mon, 31 Aug 2026 18:02:27 +0000

Voice AI is getting very good.

The visual side often isn't.

You can connect an application to OpenAI Realtime, ElevenLabs, Gemini Live, or another voice system and create a conversation that sounds natural — but if the character on screen simply opens and closes its mouth, the illusion breaks immediately.

For a believable 2D AI character, you need more than audio playback.

You need a complete pipeline:

Voice / Audio
      ↓
Audio Analysis
      ↓
Phoneme / Viseme Detection
      ↓
Viseme Values
      ↓
Rive Character Rig
      ↓
Mouth Interpolation
      ↓
Expressions + Blinks + Gestures
      ↓
Living Interactive Character

This guide focuses on the part that is often missing from lip-sync tutorials:

How do you actually prepare a production-ready Rive character for real-time lip sync?

We will cover:

What phonemes and visemes actually are
The mouth shapes a character needs
How to build the mouth system in Rive
State Machine vs Data Binding approaches
How to avoid robotic lip sync
How lip sync should coexist with expressions and gestures
Performance considerations for web and mobile
AI voice integration architecture
Stylized and non-human mascot lip sync
Production testing
When you need a custom Rive character instead of a generic avatar

If you need a custom production-ready Rive mascot rather than building the character system yourself, Mascot Engine creates interactive Rive characters, rigs, state machines, expressions, lip-sync systems and developer-ready .riv files.

1. Why Simple Mouth Open/Close Animation Doesn't Work

The most basic talking animation uses audio amplitude.

When the voice gets louder:

mouth = open

When it gets quieter:

mouth = closed

This can work for a tiny game character or a decorative animation.

But it does not look like speech.

Consider these sounds:

M
F
O
A
TH
S

Your mouth forms completely different shapes for each one.

For example:

M / B / P require the lips to close
F / V bring the upper teeth toward the lower lip
O creates a rounded mouth
A creates a wider open mouth
S / Z keep the teeth relatively close
TH has its own recognizable tongue/teeth relationship

Amplitude cannot understand those differences.

That is why realistic 2D lip sync usually works with visemes.

2. Phonemes vs Visemes

A phoneme represents a unit of sound.

A viseme represents how a group of speech sounds looks visually on the mouth.

Several phonemes can share one viseme.

For example:

/p/
/b/
/m/

sound different, but visually all three involve the lips closing.

So they can share a similar mouth position.

This is important because a character does not need a unique drawing for every possible speech sound.

Instead, we create a smaller collection of meaningful mouth poses and interpolate between them.

3. A Practical Viseme Set for Rive Characters

One widely referenced system is the Meta/Oculus viseme set.

A production character can use mouth targets such as:

Viseme	Typical Sound Group	Visual Direction
`sil`	silence	relaxed neutral mouth
`PP`	p, b, m	lips pressed together
`FF`	f, v	upper teeth touching lower lip
`TH`	th	tongue/teeth position
`DD`	t, d	slightly open articulation
`kk`	k, g	open rear articulation
`CH`	ch, j, sh	forward compressed mouth
`SS`	s, z	teeth close together
`nn`	n, l	relaxed open articulation
`RR`	r	rounded/contracted mouth
`aa`	a	wide open mouth
`E`	e	wider horizontal mouth
`I`	ih	smaller stretched mouth
`O`	oh	rounded mouth
`U`	oo	tighter rounded mouth

You may see systems described as having 15 or 16 positions depending on whether the neutral/silence pose is counted separately.

The important thing is not the marketing number.

The important thing is that the character artwork and runtime mapping agree on exactly what each value means.

4. You Don't Always Need Every Viseme

This is especially important for stylized mascots.

A realistic human face may benefit from a detailed viseme set.

A tiny cartoon robot probably doesn't.

A practical setup might look like this:

Simple mascot

Neutral
Closed
Wide
Open
Round
Teeth

Standard conversational character

8–12 meaningful mouth positions

High-fidelity conversational character

Full viseme set
+ tongue
+ teeth
+ jaw
+ expression compensation

More mouth shapes do not automatically produce better animation.

The quality of the rig and transitions matters just as much.

5. Designing the Character Before Opening Rive

One of the biggest mistakes is building the character first and thinking about lip sync later.

For voice-driven characters, the face should be designed for animation.

The mouth area may need separate elements for:

Upper Lip
Lower Lip
Mouth Interior
Teeth
Tongue
Jaw
Cheeks

Not every design needs every layer.

A flat mascot might only require:

Mouth Shape
Mouth Interior
Teeth

The important part is keeping enough separation to create convincing deformation.

This is one area where a specialist character workflow matters.

At Mascot Engine, interactive mascot artwork can be designed specifically around the final Rive rig instead of treating animation as an afterthought.

That makes later additions such as talking, expressions, props, gestures and additional states much easier.

6. Two Ways to Build Mouth Shapes in Rive

There are two broad approaches.

Method A — Separate Mouth Shapes

Create separate vector artwork for different mouth positions.

For example:

mouth_sil
mouth_PP
mouth_FF
mouth_TH
mouth_DD
...

Then control visibility or blend between states.

Advantages

Easy to understand
Easy to art-direct
Good for highly stylized characters
Individual shapes can look very different

Disadvantages

More artwork
More layers
Transitions can look like swapping images if poorly implemented

Method B — One Deformable Mouth Rig

Build a reusable mouth using vector paths, bones, constraints or controlled deformation.

Then create mouth poses from the same underlying structure.

Conceptually:

Neutral
   ↓
Closed
   ↓
Wide
   ↓
Open
   ↓
Round

The geometry transitions between positions rather than simply switching artwork.

Advantages

Smoother transitions
Smaller visual system
Easier interpolation
Better for expressive characters

Disadvantages

Harder to rig correctly
Bad topology can create ugly deformation
Extreme mouth shapes may require additional corrective artwork

For many production mascots, a hybrid approach works best.

7. Recommended Rive Structure

Keep the runtime structure predictable.

For example:

Character
├── Body
├── Head
│   ├── Eyes
│   ├── Brows
│   └── Mouth
│       ├── MouthInterior
│       ├── Teeth
│       ├── Tongue
│       └── LipRig
├── Arms
└── Accessories

Then keep runtime controls logically separated.

For example:

CharacterController

Speech
├── viseme
├── speaking
└── speechIntensity

Expression
├── emotion
├── blink
└── lookDirection

Behavior
├── idle
├── gesture
└── reaction

The exact names are flexible.

Consistency is not.

Your developer should be able to understand the .riv contract without opening every animation manually.

8. State Machines and Data Binding

Modern Rive applications are not limited to playing linear animations.

Runtime code can control character behavior through Rive's interactive systems.

A useful architecture is to separate:

Speech
Expression
Behavior
Appearance

instead of creating one giant state machine containing every possible combination.

For example, a voice assistant might conceptually expose:

viseme
speechIntensity
isSpeaking

emotion
lookX
lookY

activity

The application can then update those values while Rive handles the visual result.

With Rive Data Binding, runtime applications can read and update exposed properties through View Models and View Model Instances.

This is particularly useful for reusable character systems because your application data can be separated from the visual implementation.

9. Do Not Build 15 Hard Cuts

Imagine receiving:

PP
aa
O
SS
PP

and instantly switching the artwork every time.

The result will look mechanical.

Speech is continuous.

Your animation needs coarticulation — mouth movement naturally begins moving toward upcoming sounds while leaving previous ones.

A simplified conceptual model is:

Previous Viseme
      ↓
Interpolation
      ↓
Current Viseme
      ↓
Interpolation
      ↓
Next Viseme

This is where Rive becomes particularly useful.

Instead of treating every viseme as an isolated frame, the character can transition through a designed animation system.

10. 120 FPS Is Not What Makes Lip Sync Good

High frame rates sound impressive.

But:

120 FPS ≠ good lip sync

A badly designed mouth system at 120 FPS is still a badly designed mouth system.

The biggest factors are usually:

Viseme accuracy
+ timing
+ interpolation
+ coarticulation
+ character design
+ expression handling
+ audio synchronization

A well-designed system running at 60 FPS can look excellent.

Frame rate should be treated as a performance characteristic, not as the primary measure of lip-sync quality.

11. Audio-to-Character Architecture

A typical real-time voice character architecture looks like this:

                ┌──────────────────────┐
                │   Voice AI / TTS     │
                │ OpenAI / ElevenLabs  │
                │ Gemini / Custom TTS  │
                └──────────┬───────────┘
                           │
                           ▼
                    Audio Playback
                           │
                           ▼
                    Audio Analysis
                           │
                           ▼
                  Viseme Detection
                           │
                           ▼
                   Viseme Timeline
                           │
                           ▼
                Rive Runtime Controller
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
            Mouth       Expression    Gesture
              │            │            │
              └────────────┼────────────┘
                           ▼
                    Final Character

Notice something important:

The AI model should not directly control every visual layer.

It should provide meaningful data.

The animation system should decide how that data becomes motion.

12. Separate Speech From Emotion

A character can be:

Happy + Talking
Sad + Talking
Concerned + Talking
Excited + Talking
Neutral + Talking

If your talking animation contains the entire face, you may accidentally overwrite the expression.

Instead, think in layers.

Layer 1 → Body / Idle
Layer 2 → Head movement
Layer 3 → Expression
Layer 4 → Eyes / Blink
Layer 5 → Mouth / Lip Sync
Layer 6 → Gesture / Reaction

Now speech can continue while emotion changes.

For example:

activity = speaking
emotion = happy
viseme = O

could simultaneously produce:

happy eyebrows
smiling eyes
a speaking mouth
subtle breathing
occasional hand gestures

That feels much more like a character than a talking SVG.

13. The Neutral Mouth Is Extremely Important

Do not underestimate sil.

The neutral mouth is used during:

pauses
breathing
sentence breaks
thinking
waiting
transitions between speech and idle

If the system immediately snaps back to a perfectly static closed mouth after every word, the character feels robotic.

A better system can transition:

Speech
 ↓
Short pause
 ↓
Soft neutral
 ↓
Idle expression

The neutral mouth should also respect emotion.

A happy neutral mouth and a sad neutral mouth may not be visually identical.

14. Add Speech Intensity

Viseme ID tells us:

What mouth shape should be visible?

But it does not necessarily tell us:

How strongly should that shape be expressed?

An optional value such as:

speechIntensity = 0.0 → 1.0

can influence:

jaw opening
mouth exaggeration
cheek movement
head movement
subtle body response

For example:

Quiet speech
speechIntensity = 0.25

Normal speech
speechIntensity = 0.55

Excited speech
speechIntensity = 0.90

This creates much more personality than visemes alone.

15. Add Micro-Movements

Perfect mouth synchronization can still feel dead if everything else freezes.

During speech, consider subtle:

Blinking
Eye movement
Head movement
Breathing
Eyebrow reactions
Body weight shifts
Hand gestures

These should not be random chaos.

They should be subtle secondary animation supporting the dialogue.

The goal is not:

animate everything.

The goal is:

remove the feeling that only the mouth is alive.

16. Lip Sync for Non-Human Mascots

This is where generic avatar systems often become limiting.

What if your character is:

a dog
a fox
a blob
a flame
a robot
a floating orb
a slash-shaped brand mascot
a creature without human lips?

You should not force human anatomy onto every mascot.

Instead, translate speech into the visual language of that character.

A robot might use:

LED mouth shapes
+ face panel deformation

A creature might use:

Jaw
+ muzzle
+ tongue

A minimal mascot might use:

4–6 abstract mouth shapes

An orb could communicate speech through:

Shape deformation
+ amplitude
+ glow
+ internal motion

This is why custom character rigging is often more valuable than simply attaching a generic lip-sync API.

Mascot Engine can build custom Rive mascots around the character's actual visual identity, including non-human characters where traditional human visemes would look wrong.

17. Expressions Need Corrective Mouth Poses

Here is a problem that appears later in production.

Suppose your normal aa mouth looks good.

Now apply a big smile.

The same mouth deformation may no longer look correct.

You may need corrective behavior for:

Happy + aa
Sad + aa
Concerned + O
Excited + PP

You do not necessarily need to manually create every possible combination.

Instead, design the rig so the base expression and viseme deformation can coexist.

For high-quality character systems, this is often one of the most important parts of the rig.

18. Avoid State Explosion

Suppose you have:

15 visemes
×
5 emotions
×
5 activity states

That already gives:

375 combinations

Do not create 375 separate animations.

Build a layered system.

For example:

Viseme → mouth

Emotion → brows + eyes + mouth bias

Activity → body behavior

Intensity → exaggeration

Look direction → pupils/head

The final character is the combination of those systems.

That is much more scalable.

19. Suggested Developer Contract

Before handing a .riv file to developers, document the runtime interface.

For example:

Artboard:
AICharacter

Controller:
CharacterController

Possible runtime properties:

viseme
0–14

isSpeaking
boolean

speechIntensity
0.0–1.0

emotion
0 = neutral
1 = happy
2 = empathetic
3 = concerned
4 = surprised

activity
0 = idle
1 = listening
2 = thinking
3 = speaking
4 = error

lookX
-1.0–1.0

lookY
-1.0–1.0

This is only an example.

Your actual contract should match the application architecture.

But documenting it prevents one of the most common Rive handoff problems:

The animation works in the Editor, but nobody knows how the app is supposed to control it.

20. Web and Mobile Performance

A production voice character may be running alongside:

Rive
+
WebGL / renderer
+
Audio playback
+
Audio analysis
+
AI voice streaming
+
Application UI
+
Network communication

So optimization matters.

Do not benchmark only on a powerful development machine.

Test:

Desktop Chrome
Safari
iPhone
Android
Older mobile hardware
Low-power mode
Different screen sizes
Long conversations

Watch:

CPU
GPU
Memory
Battery usage
Thermals
Frame stability
Audio synchronization

A beautiful demo that overheats a phone after ten minutes is not production-ready.

21. Optimize the Rive File Too

The lip-sync engine is only part of performance.

The .riv file itself can become expensive.

Watch for:

unnecessary vector complexity
excessive clipping
too many nested artboards
unnecessarily heavy effects
unused assets
oversized embedded images
excessive simultaneous animations
complicated deformation where a simpler rig would work

A production mascot should be designed for the target runtime from the beginning.

This is another reason Mascot Engine focuses on developer-ready Rive character systems rather than only delivering animation videos.

The final asset needs to work inside the product.

22. Language and Accent Testing Matters

Do not assume that a lip-sync model performing well with one English speaker will perform equally well everywhere.

Test:

Different accents
Different speaking speeds
Male and female voices
Synthetic voices
Whispering
Excited speech
Children's voices where relevant
Multiple languages

For multilingual products, test the actual languages used by your audience.

Some visual mouth positions are shared broadly, but phoneme inventories and pronunciation patterns vary between languages.

Your character system should degrade gracefully when the input is imperfect.

23. Test With Difficult Words

Do not test only:

Hello, how can I help you today?

Test sequences that expose mouth problems.

For example:

baby
pepper
very
five
mother
think
zebra
school
round
beautiful

Then test fast sentences.

Then slow speech.

Then interruptions.

Then silence.

Then rapid AI responses.

You are looking for:

missed closures
late closures
mouth popping
excessive jaw movement
bad O → wide transitions
teeth flickering
tongue popping
neutral-state snapping
expression conflicts

24. Audio Synchronization Is More Important Than Maximum FPS

Users are sensitive to the relationship between:

what they hear

and

what they see

The goal is not simply rendering frames quickly.

The goal is keeping the mouth movement perceptually synchronized with the actual playback.

When benchmarking a lip-sync solution, document:

Device
Browser
Audio source
Model/runtime
Frame rate
Inference window
Average latency
Worst-case latency
Test duration

Without that information, statements such as:

sub-10ms

120fps

are difficult to evaluate meaningfully.

25. Pre-Rendered vs Real-Time Lip Sync

These are different problems.

Pre-rendered lip sync

Best for:

Marketing videos
Explainer videos
Pre-recorded content
Cinematics

The system can process the complete audio before rendering.

Real-time lip sync

Best for:

AI assistants
Voice agents
Interactive mascots
Education apps
Games
Kiosks
Virtual companions
Customer support characters

The character has to respond while audio is happening.

For these products, Rive is particularly useful because lip sync can be part of a larger interactive character system rather than being exported as a fixed video.

26. Rive vs Lottie for Conversational Characters

Lottie is excellent for many predefined motion assets.

But conversational characters require dynamic runtime behavior.

You may need:

Idle
+
Listening
+
Thinking
+
Speaking
+
Emotion
+
Lip Sync
+
Blink
+
Look Direction
+
User Interaction

That is not simply a timeline playback problem.

Rive's runtime-controlled animation architecture makes it much better suited to characters whose behavior changes continuously based on application state.

27. Think Beyond Lip Sync

A believable AI mascot should not simply have:

Idle
Talking

Consider the entire conversation lifecycle:

Connecting
    ↓
Ready
    ↓
Listening
    ↓
Thinking
    ↓
Speaking
    ↓
Waiting
    ↓
Listening

Then layer emotion:

Neutral
Happy
Empathetic
Concerned
Surprised

Then micro-interaction:

Blink
Look
Tap reaction
Gesture
Celebrate
Error
Sleep

Now you are no longer building a lip-sync animation.

You are building a character system.

28. Example AI Companion Architecture

Imagine an AI companion built with Rive.

The application receives:

activity = "speaking";
emotion = "happy";
viseme = "O";
speechIntensity = 0.68;
lookX = 0.2;
lookY = -0.1;

The Rive character interprets those values visually.

The body knows:

I am speaking.

The face knows:

I am happy.

The mouth knows:

Form the current O-like viseme.

The rig knows:

Speech intensity is moderately high.

The eyes know:

Look slightly right and upward.

This separation makes the character reusable.

The AI controls meaningful data.

Rive controls animation.

29. Production Checklist

Before shipping a Rive lip-sync character, check:

Artwork

[ ] Mouth layers are properly separated
[ ] Neutral mouth looks natural
[ ] Teeth do not flicker
[ ] Tongue is only visible when appropriate
[ ] Extreme poses maintain the character design

Visemes

[ ] Closed-lip sounds visibly close
[ ] F/V reads correctly
[ ] Rounded vowels are distinguishable
[ ] Wide/open vowels are distinguishable
[ ] Silence returns naturally to neutral

Animation

[ ] No hard popping between visemes
[ ] Transitions feel smooth
[ ] Fast speech remains readable
[ ] Slow speech does not look exaggerated

Expressions

[ ] Lip sync works while happy
[ ] Lip sync works while sad/concerned
[ ] Blinking does not interrupt speech
[ ] Eye movement remains independent
[ ] Gestures can run during speech

Runtime

[ ] Inputs/properties are documented
[ ] Default values are correct
[ ] Missing audio fails safely
[ ] Character returns to idle correctly
[ ] Long conversations remain stable

Performance

[ ] Desktop tested
[ ] iOS tested
[ ] Android tested
[ ] CPU/GPU usage checked
[ ] File size checked
[ ] Audio sync checked

30. Building a Custom Rive Lip-Sync Character

You can build this entire system internally if your team already has:

a character designer
a Rive animator
Rive rigging experience
runtime integration experience
knowledge of state machines/data binding
an audio/viseme pipeline

But if your team already has the AI voice technology and the missing part is the character, that is exactly where a specialized Rive mascot service can help.

Mascot Engine

Mascot Engine creates custom interactive mascot systems for apps, websites, AI products and games.

Depending on the project, a character can include:

Character Design
Rive Rigging
Idle Animation
Blinking
Expressions
Lip Sync / Viseme System
Listening State
Thinking State
Speaking State
Reactions
Gestures
State Machines
Data Binding Setup
Developer Handoff
Production .riv File

The goal is not simply to make a character move.

The goal is to deliver a reusable character that developers can actually control from the product.

👉 Website: https://mascotengine.com

👉 Email: riveanimator@gmail.com

👉 WhatsApp: Chat on WhatsApp

31. What to Send When Requesting a Rive Character

If you contact a Rive animator or Mascot Engine, prepare:

1. Character artwork or visual reference
2. App / website screenshots
3. Target platforms
4. Voice provider
5. Required character states
6. Required emotions
7. Whether lip sync is required
8. Whether the character needs props
9. Expected runtime controls
10. Delivery timeline

If you do not already have a character design, that can be part of the character development process too.

32. Final Thoughts

Real-time lip sync is not simply:

Audio → Open Mouth

And it is not simply:

Audio → Viseme ID

A good interactive character requires the entire chain:

Audio
   ↓
Speech Analysis
   ↓
Viseme Detection
   ↓
Timing
   ↓
Rive Mouth Rig
   ↓
Interpolation
   ↓
Expression
   ↓
Secondary Motion
   ↓
Character Behavior

The technical lip-sync model solves only part of the problem.

The character rig and animation system determine what the user actually sees.

That is especially important for branded mascots, AI companions and non-human characters where generic human avatar systems are not enough.

Build the character as a system from the beginning.

Separate speech from emotion.

Separate emotion from behavior.

Keep the runtime contract clean.

Test on real devices.

And optimize for believable motion rather than impressive benchmark numbers.

Need a Custom Rive Character?

If you're building an AI assistant, voice agent, app mascot, game character or interactive website character and need the Rive side built for production:

Mascot Engine can help with character design, Rive rigging, interactive animation, state machines, expressions, lip-sync preparation and developer-ready .riv delivery.

🌐 mascotengine.com
📧 riveanimator@gmail.com
💬 WhatsApp: +94 71 700 0999

Building an AI product with a character? Bookmark this guide before designing the mascot — the decisions you make in the artwork stage can determine how good the final lip sync can become.

From PNG to Interactive Mascot: Building App Characters With Rive

Praneeth Kawya Thathsara — Thu, 27 Aug 2026 10:08:45 +0000

From PNG to Interactive Mascot: Building App Characters With Rive

A lot of apps already have a mascot.

The problem? It usually exists as a PNG, SVG, or static illustration.

That works for a landing page, but inside an app, the character could do much more.

Imagine your mascot reacting to real application states:

Idle → Listening → Thinking → Speaking

Or:

Loading → Success → Celebration

Instead of exporting dozens of GIFs or videos, I build these characters as interactive Rive systems that developers can control directly from their applications.

Here's how I do it.

1. Start With the Existing PNG

Yes — a PNG mascot can be enough to get started.

But I normally don't animate the PNG directly.

First, I recreate or prepare the character as animation-ready vector artwork and separate the parts that need to move:

Head
Eyes
Pupils
Eyebrows
Mouth
Body
Arms
Legs
Accessories

This gives us control over individual parts while keeping the original personality of the mascot.

Sometimes hidden parts also need to be redrawn because they become visible during animation.

2. Build a Reusable Rive Rig

Next comes rigging.

I'm not only thinking about the animations the product needs today. I'm also thinking about what the character might need later.

Version one might only need:

Idle · Happy · Thinking

Later, the same mascot might need:

Walking · Sleeping · Speaking · Celebrating · Props · New Expressions

A reusable Rive rig makes expanding the character much easier.

3. Give the Character Life

One of the first animations I usually create is the idle state.

A good idle can include subtle:

Breathing
Blinking
Eye movement
Body movement
Secondary motion

The goal isn't to make the mascot constantly move.

The goal is to make it feel alive.

4. Turn Animations Into App States

Now things get interesting.

For a normal SaaS or mobile app, we might have:

0 — Idle
1 — Happy
2 — Loading
3 — Success
4 — Error
5 — Sleeping

For an AI app:

0 — Idle
1 — Listening
2 — Thinking
3 — Speaking
4 — Error
5 — Sleeping

Instead of manually selecting animation timelines, the application can simply communicate its current state.

5. Connect Everything With a Rive State Machine

This is one of the reasons I like Rive for product animation.

We can create a Rive State Machine and expose simple inputs to developers.

For example:

activity = 0 → Idle
activity = 1 → Listening
activity = 2 → Thinking
activity = 3 → Speaking
activity = 4 → Success
activity = 5 → Error

The application changes activity.

Rive handles the visual behavior.

We can also expose inputs such as:

emotion
progress
audioLevel
lookX
lookY
isSleeping
tap

Now the mascot isn't just playing an animation.

It's reacting to the application.

6. AI Mascots Make This Even More Interesting

Imagine a voice-first AI application.

When the user starts talking:

Listening

When the AI processes the request:

Thinking

When the AI responds:

Speaking

When nothing is happening:

Idle

Then we can add emotions:

Happy · Empathetic · Concerned · Surprised

We can go further with lip sync, visemes, audio-level-driven movement and gaze controls.

At that point, the mascot becomes the visual personality of the AI product.

7. One Character Can Become a UI System

A production mascot can eventually support:

Product states: Loading, Success, Error, Offline

Character states: Idle, Happy, Sad, Excited, Sleeping, Walking

AI states: Listening, Thinking, Speaking

You can also add different props, colors, outfits and expressions.

That's why I prefer thinking about mascots as interactive systems, not collections of separate animations.

8. Developer Handoff Matters

A beautiful animation isn't enough if it's difficult to integrate.

For production Rive projects, I focus on things like:

Clean artboard naming
State Machine naming
Predictable inputs
Input value maps
Smooth transitions
File optimization
Responsive behavior
Future animation states

A simple setup could look like this:

Artboard: Mascot
State Machine: MascotController

activity: 0–5
emotion: 0–3
audioLevel: 0.0–1.0
lookX: -1.0–1.0
lookY: -1.0–1.0
tap: Trigger

The developer doesn't need to understand how every animation works internally.

They only need to know how to control it.

9. PNG → Interactive Mascot

My typical workflow is:

PNG / Illustration

↓

Vector Preparation

↓

Rive Character Rig

↓

Animation States

↓

Rive State Machine

↓

App Logic

↓

Interactive Mascot

The original mascot doesn't disappear.

It simply becomes capable of responding to your product.

Building an App With a Mascot?

I'm Praneeth Kawya Thathsara, a Rive animator specializing in interactive animation and character systems for apps.

I work with indie developers, SaaS startups and AI product teams building for Flutter, React Native, iOS, Android and the web.

Even if your mascot currently exists only as a PNG, we can turn it into something interactive.

Rive Animation: riveanimator.com
Interactive Mascots & AI Characters: mascotengine.com
Email: riveanimator@gmail.com
WhatsApp: +94 71 700 0999

You build the product. I can help make it move.