Rive Markup Language (RML)

The XML format that describes a Rive scene as text.

Rive Markup Language (RML) is a text-based representation of a Rive file. It lets you create and modify Rive content as code, making it possible to build Rive files with coding agents and other text-based workflows instead of working exclusively in the Editor.

RML uses XML to describe the objects and relationships in a Rive file. Every element is a Rive type, every attribute is one of its properties, and nesting elements links them together. The names are the same ones the Editor uses, so there is no separate RML object model to learn.

One .rml file describes a whole Rive file. The Rive CLI compiles it into a .riv file for use with the Rive Runtimes or a .rev file that you can open and continue editing in the Rive Editor.

Work with a coding agent to create RML, compile it, inspect the result, and iterate on your Rive file.

Example

The following example shows how RML maps familiar Rive concepts (an artboard, shapes, fills, an animation, and a State Machine) to XML.

scene.rml

<Rive version="1" kind="fragment">
    <Artboard defaultStateMachineId="0:7" width="500" height="500" name="Artboard" id="0:2">
        <Fill name="Background">
            <SolidColor colorValue="FF1D1D1D" name="Color"/>
        </Fill>

        <Shape x="250" y="250" name="Triangle" id="0:14">
            <Triangle originX="0.5" originY="0.5" width="220" height="200" name="Path"/>
            <Fill name="Fill">
                <SolidColor colorValue="FF57A5E0" name="Color"/>
            </Fill>
        </Shape>

        <!-- State Machine -->
        <StateMachine name="State Machine 1" id="0:7">
            <StateMachineLayer name="Layer 1" id="0:8">
                <AnyState x="200" y="-120"/>
                <ExitState x="400" y="-120"/>
                <EntryState>
                    <StateTransition stateToId="0:12"/>
                </EntryState>
                <AnimationState x="200" animationId="0:6" id="0:12"/>
            </StateMachineLayer>
        </StateMachine>

        <!-- Animation -->
        <LinearAnimation loopValue="loop" duration="120" name="Spin" id="0:6">
            <KeyedObject objectId="0:14">
                <KeyedProperty propertyKey="15">
                    <KeyFrameDouble value="0" interpolationType="linear"/>
                    <KeyFrameDouble value="6.2831855" interpolationType="linear" frame="120"/>
                </KeyedProperty>
            </KeyedObject>
        </LinearAnimation>
    </Artboard>
</Rive>

How RML maps to Rive

Every document is wrapped in a single Rive root. It takes two required attributes: version, the RML format version, currently 1; and kind, which is fragment for a project file you write yourself, or bundle for the self-contained document the Rive Editor exports. Rive must be the first and only top-level element, and the CLI refuses a document without it.

Inside that root, RML follows the structure of a Rive file. Artboards contain their scene content, while assets, view models, converters, and enums sit alongside them as root elements.

A fragment never declares a Backboard. What the Editor keeps there, such as the default artboard and the publish settings, is project configuration, so it lives in rive.yaml instead. The build creates the Backboard from those keys. Only a bundle carries a Backboard element.

Nesting reflects relationships between Rive objects. In the example above, the Shape contains a Triangle path and a Fill. Properties belong to their corresponding Rive type, so the transform position (x and y) belongs to the Shape, while width and height belong to the Triangle.

Animations reference the objects and properties they change. Here, KeyedObject objectId="0:14" targets the shape named “Triangle”, while propertyKey="15" identifies its rotation property. The State Machine references that animation, and defaultStateMachineId="0:7" on the Artboard causes the State Machine to play when the file loads.

The following sections use the Rive CLI to look up RML types, compile files, and inspect the results. See Rive CLI to install the CLI and learn the available commands.

Writing RML

IDs and references

RML uses IDs when one element needs to reference another. For example, an animation uses objectId to identify the object it animates, while an Animation State uses animationId to identify the animation it plays.

IDs are two numbers separated by a colon, such as 0:12 or 14:11981. Each ID must be unique across the entire document. Elements only need an id when another element references them.

References use attributes ending in Id, such as styleId, animationId, and objectId. Nesting creates many of these relationships automatically, so you usually don’t need to write the reference yourself. Run rive docs format to see which references are created by nesting.

Value formats

Type	Written as
Color	ARGB hex, no #: colorValue="FFFF5A3C"
Boolean	"true" / "false"
Enum	A name or its integer: layoutWidthScaleType="fill"
Rotation	Radians. A full turn is 6.2831855.
Animation timing	Frames, at the animation’s fps (default 60). Transition durations are milliseconds.

Checking your work

Three checks, and none replaces the others:

rive <dir> --verify              # does it compile? (RML, Luau and shaders)
rive inspect <dir> --json        # what got built, and is `problems` empty?
rive <dir> --screenshot=out.png  # does it look right?

A clean build proves that the file compiles, but not that it behaves or looks as intended.

Run inspect for what got built, and a screenshot for what it looks like. A bind pointing at the wrong property, or a shape that renders invisibly, passes the first two checks. See Examples.

RML reference

RML includes hundreds of Rive types and properties. Rather than memorizing or guessing their names, use the CLI to look up the schema:

rive schema Rectangle              # properties, defaults, enum names, property keys
rive schema --search gradient      # find a type by name
rive schema Shape --animatable     # properties that can be keyed
rive schema Shape --bindable       # properties that can be data bound

For broader RML concepts and patterns, use the RML reference included with the CLI:

rive docs                    # reference index
rive docs format             # RML structure and format
rive docs --list             # list available topics
rive docs --search gradient  # search all topics

The reference covers topics including layout, data binding, State Machines, text, drawing, rigging, transforms, easing, and assets. rive docs gotchas covers common issues, including those that may fail silently.