Rive animation

Rive is a real-time interactive design and animation tool by Rive Inc.. Use the Rive editor to create vector based motion graphics that respond to different states and user inputs. Rive lets you create advanced timeline animations through animation mixing, interpolation and inverse-kinematics. Transition between animations using state machines.

Requirements

In order to use Rive animations you need to run Defold 1.2.188 or higher.

Installation

Rive animation support in Defold is provided through an official Rive extension. To use Rive animations in a Defold project, add the following URL to the list of game.project dependencies:

https://github.com/defold/extension-rive/archive/main.zip

We recommend using a link to a zip file of a specific release.

Render script setup

Rive components are rendered using a method called “Stencil, then cover” (StC). This requires Rive components to render with the stencil buffer enabled in the render script:

render.enable_state(render.STATE_STENCIL_TEST)
render.draw(self.rive_pred)
render.disable_state(render.STATE_STENCIL_TEST)

For convenience, there is a modified render script included with this extension. Open your game.project file and modify the Render field in the Bootstrap section to use the defold-rive/lua/rive.render file from this extension.

Concepts

Rive data file

This file contains a Rive artboard with all of the composition and animation data of a Rive scene. You can export a Rive (.riv) file from the Rive editor.

Rive scene

This file is used to create a reference to a Rive data file (.riv).

Rive model

This file represents a Rive Model component that can be added to a game object. It references a Rive Scene, blend mode, material and the default state machine and animation to use.

Creating a Rive scene

Create a Rive scene by (right click a location in the Assets browser, then select New... ▸ Rive Scene from the context menu). Select the Rive data file to use from the Rive File field in the Properties panel.

Once a Rive file has been selected a preview will be shown in the main Editor scene view and the bone hierarchy (see below) will be shown in the Outline panel.

Creating Rive model components

Select a game object to hold the new component:

Either create the component in-place (right click the game object and select Add Component ▸ Rive Model)

Or create it on file first (right click a location in the Assets browser, then select New... ▸ Rive Model from the context menu), then add the file to the game object by right clicking the game object and selecting Add Component File).

The Rive model can now be viewed in the editor:

Rive model properties

Apart from the properties Id, Position and Rotation the following component specific properties exist:

Rive Scene

Set this to the Rive scene file to use for this model.

Blend Mode

If you want a blend mode other than the default Alpha, change this property.

Material

If you need to render the model with a custom material, change this property.

Default State Machine

Set this to the state machine you want the model to start with.

Default Animation

Set this to the animation you want the model to start with.

Blend modes

The Blend Mode property defines how the component graphics should be blended with the graphics behind it. These are the available blend modes and how they are calculated:

Alpha

Normal blending: src.a * src.rgb + (1 - src.a) * dst.rgb

Add

Brighten the background with the color values of the corresponding pixels of the component: src.rgb + dst.rgb

Multiply

Darken the background with values of the corresponding pixels of the component: src.rgb * dst.rgb

Screen

Opposite of Multiply. Brighten background and values of the corresponding pixels of the component: src.rgb - dst.rgb * dst.rgb

Runtime manipulation

Rive Model components can be manipulated at runtime through a number of different functions and properties (refer to the API docs for usage).

Playing animations

To play animations on a Rive Model component, simply call the rive.play_anim() function:

function init(self)
	-- Play the "run" animation on the component "rivemodel"
	local options = {
		offset = 0.2, -- start 20% into the animation
		playback_rate = 1.5, -- play the animation at 150% speed
	}
	rive.play_anim("#rivemodel", "run", go.PLAYBACK_ONCE_FORWARD, options, function(self, message_id, message, sender)
		run()
	end)

end

Cursor animation

In addition to using the rive.play_anim() to advance a Rive animation, Rive Model components expose a “cursor” property that can be manipulated with go.animate() (more about property animations):

-- Set the animation on the spine model but don't run it.
rive.play_anim("#rivemodel", "run", go.PLAYBACK_NONE)

-- Set the cursor to position 0
go.set("#rivemodel", "cursor", 0)

-- Tween the cursor slowly between 0 and 1 pingpong with in-out quad easing.
go.animate("#rivemodel", "cursor", go.PLAYBACK_LOOP_PINGPONG, 1, go.EASING_INOUTQUAD, 6)

Changing properties

A Rive Model component also has a number of different properties that can be manipulated using go.get() and go.set():

animation

The current model animation (hash) (READ ONLY). You change animation using rive.play_anim().

cursor

The normalized animation cursor (number).

material

The rive model material (hash). You can change this using a material resource property and go.set(). Refer to the API reference for an example.

playback_rate

The animation playback rate (number).

Interacting with state machines

To interact with a state machine in a Rive Model component it first needs to be started using rive.play_state_machine(). Once it has been started it can be interacted with using go.set():

-- Start the state machine named "State Machine 1"
rive.play_state_machine("#rivemodel", "State Machine 1")

-- Set the boolean value "Trigger 1" to true
go.set("#rivemodel", "Trigger 1", true)

-- Set the numeric value "Number 1" to 0.8
go.set("#rivemodel", "Number 1", 0.8)

Bone hierarchy

The individual bones in the Rive Scene skeleton are represented internally as game objects. In the Outline view of the Rive Scene the full hierarchy is visible.

With the bone name at hand, it is possible to retrieve the instance id of the bone in runtime. The function rive.get_go() returns the id of the specified bone and it is, for instance, possible to child other game objects under the animated game object:

-- Attach pistol game object to the left forearm
local forearm = rive.get_go("#rivemodel", "Left forearm")
msg.post("pistol", "set_parent", { parent_id = forearm })

Source code

The source code is available on GitHub

API reference

API Reference - rive