Mascote Rive na UI do Unity: instalação, uGUI e Data Binding

O Rive funciona no Unity? Em quais plataformas?

Sim. A documentação do Rive para Unity diz que "o pacote é compatível com as versões LTS do Unity a partir da 2021 (incluindo o Unity 6)" e que ele usa o Rive Renderer, mantido em dia com o runtime C++ mais recente.

O Rive mantém uma tabela de compatibilidade de recursos do runtime para Unity na mesma página; consulte-a antes de planejar seu projeto em torno de recursos mais novos.

Como instalar o pacote Rive para Unity?

Há dois caminhos. O pacote da Unity Asset Store é a instalação mais simples e só traz versões estáveis: abra Window, Package Manager, escolha My Assets, encontre o Rive e importe. O pacote do GitHub inclui tags canary com recursos mais novos. Use Add package from git URL com a tag da versão mais recente no lugar de 0.0.0:

https://github.com/rive-app/rive-unity.git?path=package#v0.0.0

ou adicione em Packages/manifest.json:

"app.rive.rive-unity": "https://github.com/rive-app/rive-unity.git?path=package#v0.0.0"

O Rive avisa que o Unity pode travar ao atualizar o pacote com o Editor aberto; se isso acontecer, feche o Unity, altere a versão no manifest.json e abra de novo. Os componentes de UI também precisam do com.unity.ugui, que projetos novos costumam incluir.

Como exibir um personagem Rive em um Canvas uGUI?

Arraste o .riv para a janela Project; o Unity o importa como um Rive Asset. Depois, arraste-o para a Hierarchy, o que cria uma configuração em screen space dentro de um Canvas uGUI, ou monte tudo manualmente pelo menu do botão direito:

1. Rive, Rive Panel (Canvas) cria um painel já configurado com o Rive Canvas Renderer. O painel precisa ficar dentro de um Canvas uGUI, e o renderer fica no mesmo GameObject do painel.
2. Rive, Widgets, Rive Widget vai dentro desse painel. Atribua o Rive Asset, o artboard e a state machine (por exemplo, CharacterViewModelMachine).

O Canvas Renderer dimensiona o painel a partir do Canvas uGUI e cuida da ordem de renderização e do raycasting, então o personagem fica na camada certa em relação aos seus botões e recebe input do ponteiro para os listeners do Rive no arquivo. Se nada aparecer, o FAQ do Rive lista as causas mais comuns: o widget não está dentro de um Rive Panel ou não há câmera na cena.

Para colocar o personagem em um objeto 3D, como uma tela dentro do mundo do jogo, solte o .riv em um GameObject com MeshRenderer; o Unity adiciona um Rive Panel e um Rive Texture Renderer.

Como vincular o humor do mascote ao estado do jogo?

Use Data Binding. No Inspector do Rive Widget, em Data, defina Data Binding Mode como Auto Bind Default, que vincula a instância padrão do view model do artboard. Depois, pegue as propriedades quando o widget terminar de carregar:

using Rive;
using Rive.Components;
using UnityEngine;

public class MascotController : MonoBehaviour
{
    [SerializeField] private RiveWidget m_riveWidget;

    private ViewModelInstance m_vm;
    private ViewModelInstanceNumberProperty m_mood;

    private void OnEnable()  { m_riveWidget.OnWidgetStatusChanged += HandleStatus; }
    private void OnDisable() { m_riveWidget.OnWidgetStatusChanged -= HandleStatus; }

    private void HandleStatus()
    {
        if (m_riveWidget.Status != WidgetStatus.Loaded) return;
        // Data Binding Mode on the widget: Auto Bind Default
        m_vm = m_riveWidget.StateMachine.ViewModelInstance;
        m_mood = m_vm.GetNumberProperty("mood");
    }

    // Call from game code: SetMood(5) while loading, SetMood(0) when idle.
    public void SetMood(int mood)
    {
        if (m_mood != null) m_mood.Value = mood;
    }

    // One-shot reactions: "success", "error", "yes", "no", "enter", "exit".
    public void Fire(string trigger)
    {
        if (m_vm == null) return;
        var t = m_vm.GetTriggerProperty(trigger);
        if (t != null) t.Trigger();
    }
}

Chame isso de onde quer que o estado do jogo mude:

// Example wiring from a game manager
mascot.SetMood(5);            // loading the level
yield return LoadLevel();
mascot.SetMood(0);            // idle
...
if (playerWon) mascot.Fire("success"); else mascot.Fire("error");

• A documentação do Rive observa que uma alteração de propriedade "não será aplicada aos elementos vinculados até que a state machine ou o artboard avance", algo que o widget faz a cada frame durante a reprodução.
• Propriedades numéricas recebem um float; números inteiros como 5 funcionam normalmente.
• Para reagir quando algo acontece dentro do arquivo, inscreva-se no OnValueChanged de uma propriedade (ou OnTriggered, no caso de triggers) e cancele a inscrição em OnDestroy.
• O Rive marca sua API de state machine de baixo nível como legada no Unity e recomenda a API de componentes com Data Binding.

Mantenha uma lista escrita dos nomes das propriedades junto ao código; uma propriedade renomeada no arquivo não retorna nada em runtime. O guia de state machine explica como humores e triggers costumam ser conectados.

Como manter a UI do Rive rápida no mobile e no WebGL?

As boas práticas do Rive para Unity partem de um fato: "um Rive Panel renderiza em uma Render Texture por padrão", e todos os widgets sob esse painel desenham na mesma textura. A partir disso:

• Prefira menos painéis, "especialmente no mobile", e agrupe os widgets sob um painel compartilhado.
• Construa partes maiores da UI no Rive em vez de instanciar muitos botões pequenos do Rive no uGUI.
• Use listas de Data Binding para itens repetidos em vez de muitos widgets.
• Desative ou destrua os widgets que não estão visíveis, para que parem de avançar e renderizar.
• Deixe as state machines se estabilizarem. O runtime do Rive para de avançar uma state machine quando nada vai mudar, o que economiza processamento enquanto o mascote mantém uma pose parada.

No WebGL, o renderizador do Rive usa uma extensão de pixel local storage quando o navegador a disponibiliza e, caso contrário, recorre ao MSAA no WebGL 2, onde o Rive observa que os modos de mesclagem avançados custam mais performance. Teste os builds WebGL nos navegadores que seus jogadores usam.

Existe um runtime do Rive para Unreal Engine?

Sim. O Rive documenta um runtime para Unreal Engine 5.7.3 e versões posteriores, com state machines, Data Binding de view model e observação de propriedades. A lista de plataformas inclui DirectX 11 e 12, Vulkan no PC, macOS, PlayStation 5, Nintendo Switch e Switch 2, Xbox Series X e Steam Deck, com o visionOS marcado como experimental. O suporte a mobile está "planejado, mas ainda não disponível". O Rive também marca ali os inputs legados de state machine como obsoletos, então novos projetos em Unreal devem controlar os personagens por meio de view models.

Um personagem do Charmotion pode rodar no Unity?

Um .riv do Charmotion é um arquivo Rive padrão, então é importado como qualquer outro. Ele tem um view model Character em CharacterViewModelMachine: um número mood de 0 a 9 (idle, happy, wave, thinking, sad, loading, listening, talking, sleeping, attention) e os triggers success, error, yes, no, enter e exit, que correspondem ao controller acima. O Charmotion entrega código para web, React e SwiftUI, não C#, então o script desta página é a parte que você adiciona. O .riv está em todos os planos pagos (a partir de US$ 20/mês).

Como adicionar um mascote Rive à UI do Unity

1. Instale o pacote. Importe o Rive pela Asset Store ou adicione a URL git do rive-unity com uma tag de release no Package Manager.
2. Importe o arquivo. Arraste o .riv para a janela Project para criar um Rive Asset.
3. Crie o painel. Adicione Rive, Rive Panel (Canvas) sob o seu Canvas do uGUI.
4. Adicione o widget. Adicione um Rive Widget sob o painel e escolha o asset, o artboard e a state machine.
5. Vincule os dados. Defina Data Binding Mode como Auto Bind Default e obtenha as propriedades de mood e de trigger em C# assim que o widget carregar.
6. Conecte os eventos do jogo. Chame SetMood e Fire a partir da lógica do jogo e teste nos dispositivos de destino.

Perguntas frequentes

O Rive é compatível com o UI Toolkit do Unity?

Ainda não. O FAQ do Rive para Unity responde "Ainda não, mas estamos trabalhando nisso" e recomenda o uGUI por meio do Rive Canvas Renderer, ou renderizar o Rive em uma malha. Se seus menus estão no UI Toolkit, coloque o personagem em um pequeno canvas uGUI sobreposto.

Por que meu widget do Rive não aparece no Unity?

Verifique as duas causas citadas no FAQ do Rive: o Rive Widget precisa ser filho de um Rive Panel, e a cena precisa de uma câmera. No uGUI, confirme também que o painel está sob um Canvas e tem o Rive Canvas Renderer no mesmo GameObject.

O Rive para Unity roda em consoles?

Hoje, não. A visão geral do Rive para Unity lista os consoles como suporte planejado. Já o runtime separado do Rive para Unreal lista PlayStation 5, Nintendo Switch, Switch 2 e Xbox Series X, então projetos para console em Unreal já têm uma opção.

Respostas rápidas deste guia

• O Rive funciona no Unity?
• O Rive tem runtime para Unreal Engine?

Fontes

• Unity runtime overview, Rive
• Unity: Getting started, Rive
• Unity: Components, Rive
• Unity: Data binding, Rive
• Unity: Best practices, Rive
• Unity: FAQ, Rive
• Unity: State machines, Rive
• Rive Unity WebGL, rive-unity on GitHub
• Unreal Engine runtime, Rive