How Rive imports work

LIGR separates source preparation, native runtime playback, sporting expressions, and publication. Each boundary preserves one clear artifact.

Lifecycle

Rive source-to-control-room lifecycle

Upload → backend preparation

↙ or ↘

.riv or runtime ZIPInspect unchanged

Source projectCompile

↘ rejoin ↙

Ready candidate + metadataResolve any missing images

↓

Select + configure

↓

Working graphic

↓

Saved revision

↙ contains ↘

Runtime + supplied playback imagesStored independently of source retention

Original archiveOnly when retained

↓ publish runtime

Graphic version

↓

Theme snapshot

→

Activate

→

Preset + room + overlay

Upload a .riv file for unchanged inspection, or upload a supported source project for compilation. Both paths use backend preparation and create a ready candidate with metadata. Resolve any missing external images. Select and configure the candidate to create a working graphic. A saved revision contains runtime bytes and supplied playback images. It contains the private original only when retention was selected. Publish a graphic version and theme snapshot, activate the snapshot, then add the graphic to a control room.

A .riv file enters inspection without recompilation. LIGR preserves its bytes exactly. Supported .rev and RML projects compile before inspection. All inputs use the same backend preparation. The dashboard and REST API consume its validated candidate metadata. LIGR stores supplied playback images with the runtime, independently of optional source retention.

Preparation runs asynchronously. It returns a candidate only after validating the result and inspecting its native structure. An ambiguous ZIP returns selection-required; send one exact candidate entry to continue.

Choose one artboard index and one state-machine index from the returned metadata. LIGR never guesses between multiple valid choices. A ready candidate can still contain unresolved external images. Read its asset metadata and resolve those images in the builder.

Properties, expressions, and controls

Rive property bindings describe authored runtime properties such as Main.homeScore. They do not know football rules or LIGR’s live match shape.

A LIGR expression connects a property to live data. For football, $d.1.score means displayed team one’s score. Configured team reversal can make displayed team one differ from the match home team.

Control variables use $v.<name>.value. They hold operator choices such as a tournament stage. The reserved hide variable controls native visibility and cannot appear in a preset.

Rive property	LIGR expression	Live value
`Main.homeCode`	`$d.1.abbreviation`	Displayed team-one code
`Main.awayCode`	`$d.2.abbreviation`	Displayed team-two code
`Main.homeScore`	`$d.1.score`	Displayed team-one score
`Main.awayScore`	`$d.2.score`	Displayed team-two score
`Main.stage`	`$v.stage.value`	Preset or show-command value
`Main.on`	`!$v.hide.value`	Runtime visibility

Expressions execute inside LIGR’s isolated native renderer. They use the existing expression compiler and never expose native handles to the parent application.

Show and hide timing

A hide command sets hide to true. Your state machine then plays its out animation. The overlay keeps the graphic on screen for 2 seconds after the hide command. Then the overlay fades the graphic out over 0.4 seconds and removes it. Keep each out animation shorter than 2 seconds. The fade cuts off a longer out animation.

A new value can arrive while the out animation plays. For example, the next preset changes stage. By default, the graphic shows the new value at once. To keep the old value during the exit, set exitMode: "deferred" on the control variable. The overlay then holds the old value for 3 seconds before it applies the new value. hide never defers.

A graphic can load while it is already visible. The state machine can then skip its in animation. To play the in animation on the first show, set deferInitialShow: true in the graphic settings. The renderer then applies hide: true for one frame before it applies the real value.

npx ligr-graphic rive control add stage --type string --default FINAL --exit-mode deferred
npx ligr-graphic rive control set "$CONTROL_ID" --exit-mode deferred
npx ligr-graphic rive settings set --defer-initial-show

The same changes through REST:

G="themes/$THEME_ID/rive-graphics/$GRAPHIC_ID"
api PATCH "$G/control-variables/$CONTROL_ID" --data '{"exitMode":"deferred"}'
api PATCH "$G/settings" --data '{"deferInitialShow":true}'

The api helper comes from Import through REST.

Default image sizes

Image bindings can include imageDimensions: { width, height } in pixels. These dimensions describe the image selected by the runtime’s default instance, including nested instances and the first inspected list item. They describe the image itself, not the artboard or the displayed bounds after animation and layout. The runtime’s default can differ from an instance marked as default in the editor.

LIGR uses authored asset dimensions when available, or supported embedded image metadata. It does not download external images during preparation. An empty image, missing dimensions, or an unresolved reference leaves imageDimensions absent. Use pathSegments to identify nested properties when names contain dots.

The builder fills Width (px) and Height (px) when you first expose an image binding. You can edit or clear either value. Reopening the form preserves those choices. A compatible replacement refreshes intrinsic metadata while preserving your configured exposure sizes.

Worked scorebug

The local project compiles artboard Main and state machine Broadcast. The REST attachment stores the table’s bindings and a stage variable with default FINAL.

The graphic publication freezes those runtime bytes and that configuration as graphic version 1. A theme publication then pins graphic version 1 in a new theme snapshot. Activation remains a separate request.

A preset stores stage: "GROUP A". A show command can override it with stage: "ROUND OF 16". Live football data remains authoritative under $d, so a new fact changes Main.homeScore from 2 to 3.

Version behavior

A working graphic is mutable. Edit it through the operation routes described in Edit through REST. Each graphic publication creates an immutable positive version. Exact published runtime downloads never rebuild or follow a later working copy. Published playback images and configuration remain pinned to that graphic version.

A theme snapshot freezes its selected graphic versions. Publishing a theme snapshot does not activate it unless you request activation. Existing overlay pages keep their loaded snapshot until reload.

Read Publish a theme version for inspection, activation, and rollback.