# Try .riv files in the Rive Qt viewer

> Build the rive-qt-plugin viewer and open any .riv in Qt Quick. Switch artboards, state machines and animations, scrub timelines, edit view model properties live, and compare graphics backends.

The plugin repository comes with a viewer: a small Qt Quick app built on
`RiveView` that opens any `.riv` and puts every control the plugin has on
screen. Use it to check that a file from the Rive editor plays the way you
expect in Qt before you wire it into your app, and to see which artboard,
state machine and view model names to use from QML.

## Build it

You need the same toolchain as the plugin: Qt 6.5 or later, CMake 3.21+,
Ninja and a C++20 compiler (see [requirements](/docs/rive-qt/getting-started/#requirements)).

```sh
git clone --recursive https://github.com/hypernuclear/rive-qt-plugin.git
cd rive-qt-plugin
cmake --preset default -DCMAKE_PREFIX_PATH=/path/to/Qt/6.12.0/macos
cmake --build --preset viewer
./build/examples/viewer/rive_viewer
```

Point `CMAKE_PREFIX_PATH` at your Qt kit (for example
`~/Qt/6.12.0/gcc_64` on Linux or `C:/Qt/6.12.0/msvc2022_64` on Windows). On
Windows, run the commands from a Developer PowerShell for Visual Studio and
start `build\examples\viewer\rive_viewer.exe`.

The first configure takes a minute or two while it builds the Rive runtime;
after that, rebuilds are quick. The `default` preset is a debug build. For
smoother playback of heavy files, configure with `cmake --preset release`
instead, then build the same way.

## Open your files

- **Samples.** The **Sample** menu lists every `.riv` in
  `examples/viewer/samples/`. Drop your own exports into that folder and
  click **Refresh**; no rebuild needed.
- **Any path or URL.** Paste a `file:///…` path or an `https://…` link to a
  `.riv` into the **URL** field and press **Load**.

If a file can't be loaded, the status line at the bottom says why.

## What you can do

- **Pick what plays.** Choose the artboard, state machine, view model and
  view model instance. Leave them on *(default)* to see what `RiveView` picks
  on its own.
- **Play, pause and change speed**, from frozen to double speed.
- **Scrub a timeline.** Set **Mode** to *Animation*, choose an animation, and
  drag the scrubber frame by frame. The readout shows the frame, the time and
  the animation's frame rate. In *Auto* mode a file with a state machine runs
  the state machine, which has no single timeline to scrub.
- **Edit view model properties live.** The **View Model** tab lists every
  property of the bound instance with an editor for its type: switches for
  booleans, fields for numbers and strings, a color picker, enum menus, a
  **Fire** button for triggers, image replacement from disk, artboard swaps,
  and nested view models and lists you can open.
- **Try layouts.** The **Layout** tab sets the fit and alignment and can
  override the layout size, for artboards that use Rive's layout system.
- **Interact.** Click, drag and touch go to the state machine's listeners.
  Click into the view to give it keyboard focus, then use Tab and the arrow
  keys to move through the artboard.

Every control maps to a `RiveView` property or method, so the
[QML API reference](/docs/rive-qt/qml-api/) is the guide to doing the same
thing in your app.

## Compare graphics backends

The viewer uses whichever graphics API Qt picks for the window. To try
another, set `QSG_RHI_BACKEND` before launching:

```sh
QSG_RHI_BACKEND=vulkan ./build/examples/viewer/rive_viewer
```

| Platform | Values |
|----------|--------|
| macOS | `metal` (default); `vulkan` with a Vulkan-enabled Qt and MoltenVK |
| Windows | `d3d11` (default), `d3d12`, `opengl`, `vulkan` |
| Linux | `opengl` (default), `vulkan` |

Vulkan and Direct3D 12 have to be enabled at build time
([build options](/docs/rive-qt/getting-started/#build-options)). In
PowerShell, set the variable with `$env:QSG_RHI_BACKEND = "d3d12"`.

## Runtime update checks

The **Update checks** menu at the top loads a set of files used to verify
each Rive runtime update, from grid layouts and fitted text to scripting and
GPU canvas shaders. Picking one resets the viewer to a known state and shows
what to look for. The
[sample guide](https://github.com/hypernuclear/rive-qt-plugin/blob/main/examples/viewer/samples/README.md)
on GitHub lists each check and the automated render tests behind them.

---

From https://hypernuclear.com/docs/rive-qt/viewer/