The manifest
The manifest describes your graphic to LIGR: the entry file, the frame size, the hide deadline,
and the control variables an operator can set. Over REST it is the stateMachine field of a code
graphic. Keep it in a file named graphic.json next to your source, and send it as stateMachine
when you record the bundle.
{ "schemaVersion": 1, "runtime": { "engine": "iframe-html", "entryFile": "index.html", "width": 1920, "height": 1080, "exitDurationMs": 800 }, "controlVariables": [ { "id": "showAggregate", "name": "showAggregate", "type": "boolean", "defaultValue": false }, { "id": "accent", "name": "accent", "type": "enum", "defaultValue": "home", "options": ["home", "away", "neutral"] } ], "userExpressions": [], "adSlots": [{ "id": "mainSponsor", "name": "Main sponsor" }]}A graphic you create without a stateMachine gets this default: index.html, 1920 by 1080, a
1500 ms hide deadline, and no control variables.
runtime
Section titled “runtime”| Field | Value | Rule |
|---|---|---|
engine | iframe-html | Required. The only engine today |
entryFile | The HTML file the overlay loads, as a path inside the bundle | Required. It must name an uploaded file at update and at publish |
width | Frame width in pixels | A positive integer. 1920 for a full-frame graphic |
height | Frame height in pixels | A positive integer. 1080 for a full-frame graphic |
exitDurationMs | How long the overlay waits for HIDDEN after GRAPHIC_HIDE before it hides the frame | Optional. A positive integer. Default 1500 |
renderer | cpu or gpu: the hardware your graphic needs to draw | Optional. Declare cpu only when the graphic draws without a GPU |
controlVariables
Section titled “controlVariables”A control variable is a value an operator sets in the control room, an automation sets from a
rule, or a REST client sends with a graphics command. Your
graphic receives the current values in controlVariables and, for entity types, the resolved
object in controlVariableData. See Data binding.
You choose the variables. There is no platform list of variable names. Declare any name you need,
pick a type from the catalogue below, and the control room renders the picker that the table lists
for it. The only fixed parts are the type catalogue and the reserved hide name.
| Field | Value |
|---|---|
id | The identifier. Use the same string as name |
name | The name. Unique within the graphic |
type | One of the types below |
defaultValue | The value in force when nothing sets the variable |
options | For enum only. The allowed values. At least one |
| Type | Value the graphic receives | Picker in the control room |
|---|---|---|
string | A string | Text field |
number | A number | Number field |
boolean | true or false | Switch |
enum | One of options | Drop-down |
team | A team id. controlVariableData carries the team | Team picker |
player | A player id. controlVariableData carries the player | Player picker |
match | A match id | None today. Set the value with a graphics command |
fact | A fact id. controlVariableData carries the fact | Fact picker |
teamStat | A team statistic | None today. Set the value with a graphics command |
stat | A statistic | Statistic picker |
set, round, court, period | A set, round, court or period selector | Selector for tennis and period sports |
hide is reserved
Section titled “hide is reserved”LIGR adds a boolean control variable named hide to every code graphic and sets it when the
overlay shows or hides your graphic. Never declare it. A manifest that declares hide with any
type other than boolean is refused. Your graphic still hides on GRAPHIC_HIDE, not on the
value of hide. See Show and hide.
userExpressions
Section titled “userExpressions”A user expression is a value the overlay computes for you from the match data, with the same
expression language the Rive graphics use. The result arrives in userExpressionValues, keyed by
expression name. Most code graphics leave this array empty and compute in JavaScript instead.
{ "id": "leader", "name": "leader", "expression": "$d.1.score > $d.2.score ? $d.1.name : $d.2.name" }| Field | Value |
|---|---|
id | The identifier. Use the same string as name |
name | The key in userExpressionValues. Unique within the graphic |
expression | The expression. See Expressions for the language and the context |
description | Optional. A note for the editor |
adSlots
Section titled “adSlots”An ad slot is a place in your graphic where a sponsor image shows. Optional. Declare a slot, and a game plan can assign ads to it, the same as to an exposed ad asset of a Rive graphic. The game plan lists the slot on the Advertisement tab of the graphic.
"adSlots": [{ "id": "mainSponsor", "name": "Main sponsor" }]| Field | Value |
|---|---|
id | The identifier. Letters, digits, _ and - only. Unique within the graphic |
name | Optional. The name the game plan shows. Default: the id |
When a slot has an ad for the match, the overlay sends the ad in assetOverrides, under the key
<id>::riveAsset. For the slot above, read assetOverrides["mainSponsor::riveAsset"].adFileUrl.
When the slot has no ad, the entry has no adFileUrl. Show nothing in the slot then.
Validation
Section titled “Validation”The API checks the manifest on every write: create, record the bundle, and publish. A failed check
returns 400 with code: "CODE_GRAPHIC_INVALID" and one line per broken rule in details[].
| Rule | Message in details[] |
|---|---|
runtime is an object | runtime must be an object |
runtime.renderer, when set, is cpu or gpu | runtime.renderer must be "cpu" or "gpu" |
runtime.engine is iframe-html | runtime.engine must be "iframe-html" |
runtime.entryFile is a path | runtime.entryFile must be a file path |
runtime.entryFile names an uploaded file | runtime.entryFile "index.html" is not an uploaded code-file asset |
width, height, exitDurationMs are positive integers | runtime.width must be a positive integer |
controlVariables is an array | controlVariables must be an array |
| Every variable has a name | controlVariable is missing a name |
| Names are unique | controlVariables has duplicate name "title" |
| Every type is known | controlVariable "title" has unknown type "text" |
| An enum has options | controlVariable "accent" enum needs at least one option |
| An enum default is one of its options | controlVariable "accent" default "blue" is not one of its options |
A declared hide is boolean | controlVariables.hide is reserved by LIGR and must be boolean |
userExpressions is an array | userExpressions must be an array |
adSlots, when set, is an array | adSlots must be an array |
| Every ad slot has an id | adSlot is missing an id |
An ad slot id uses letters, digits, _ and - only | adSlot "main::sponsor" id may use only letters, digits, "_" and "-" |
| Ad slot ids are unique | adSlots has duplicate id "mainSponsor" |
| An ad slot name, when set, is not empty | adSlot "mainSponsor" name must be a non-empty string |
The entry file rule runs at publish and when you send a stateMachine with the bundle. Record
the files and the manifest in the same bundle request, so the check sees both.