تضمين أصول Rive ووحدات التحكم

Rive is a real-time interactive design tool. Its runtime exports a compact binary file with the .riv extension that contains vector art, bones, timelines, and state machines.

• The rive Dart package renders these files natively on the GPU, so animations stay crisp at any resolution.
• Unlike Lottie, Rive can run state machines driven by runtime inputs, making animations interactive rather than just playback-only.

In this lesson you will load a .riv asset, pick an artboard, and drive playback with an animation controller.

First declare the package in pubspec.yaml and register the binary file under assets so Flutter bundles it.

• The version constraint targets Rive 0.13.x, which exposes the RiveAnimation widget and the controller APIs used below.
• The asset path is relative to the project root; any file inside a declared folder is included.

The fastest way to render a .riv file is the RiveAnimation.asset constructor. It loads, decodes, and plays the file's default animation automatically.

• fit controls how the artboard scales inside the widget bounds, just like BoxFit for images.
• This convenience widget is great for fire-and-forget visuals but gives you no handle to control playback.

A single .riv file can contain multiple artboards — independent canvases, each with its own art and animations. Think of them as separate scenes packed in one file.

• If you omit the name, Rive uses the file's default artboard.
• Pass artboard: to RiveAnimation.asset to select a specific one by name.

Choosing the right artboard matters when a designer ships a shared library file with many components.

To start, stop, or switch animations at runtime you must attach a controller. Rive offers two main kinds:

• SimpleAnimation — plays one named timeline; toggle its isActive flag to pause/resume.
• StateMachineController — drives a state machine through typed inputs (booleans, numbers, triggers).

You create the controller in initState, pass it to the widget via the controllers: list, and dispose it when the widget is torn down.

A SimpleAnimation targets one timeline by name. Setting isActive = false pauses it; setting it back to true resumes from where it stopped.

• Always keep the controller in a field so you can mutate it later.
• Pass it inside the controllers list; the widget wires it to the loaded artboard for you.

State machines are where Rive shines. A StateMachineController exposes named inputs that you read off the controller after attaching it:

• findInput<bool>('Hover') returns an SMIBool you flip with .value.
• findInput<double>('Speed') returns an SMINumber.
• findSMI('Tap') as SMITrigger fires a one-shot transition via .fire().

The factory StateMachineController.fromArtboard binds to a named state machine inside the artboard.

When you need access to the Artboard instance — for example to attach a state machine — use the onInit callback of RiveAnimation.asset.

• onInit fires once after the file is decoded and the artboard is ready.
• This is the correct place to build a StateMachineController, since the artboard does not exist before load completes.

For full control — caching, preloading, or rendering with a custom Rive widget — decode the file yourself with RiveFile.asset and pull the artboard from mainArtboard.

• RiveFile.initialize() must run once before manual decoding (the widget constructors handle this for you).
• artboard.instance() gives you an isolated copy so two widgets can animate independently.

Controllers hold references to the artboard and keep advancing the animation clock. Leaking them wastes frames and memory.

• Dispose every controller you created in State.dispose().
• For state machines, also clear input references so they can be garbage collected.

The Rive widget removes controllers it owns automatically, but controllers you attach manually with addController are your responsibility.

The Flutter widgets need a GPU and a host app, so they cannot run on a plain console. The logic of a simple animation controller, however, is just Dart and is easy to model and test in isolation.

Below is a tiny standalone simulation of how a SimpleAnimation's isActive flag gates time advancement — runnable on any Dart judge.

You need to flip a boolean input on a Rive state machine when the user taps a button. Which approach is correct?

You can now embed and drive Rive in Flutter:

• Add rive to pubspec.yaml and register the .riv asset.
• RiveAnimation.asset renders quickly; select a canvas with artboard:.
• Attach a controller to control playback: SimpleAnimation for a single timeline, StateMachineController for interactive inputs (SMIBool, SMINumber, SMITrigger).
• Use onInit to reach the Artboard, or load manually with RiveFile.asset for full control.
• Always dispose controllers you create to avoid leaks.