Editor de Gráfico de Animação

O Editor de Gráfico de Animação é uma ferramenta visual baseada em nós que capacita artistas técnicos e animadores a construir lógica de animação complexa diretamente dentro do Roblox Studio. Ao fornecer uma interface simplificada para criar comportamentos como árvores de mistura, remove a dependência tradicional de scripts manuais para o movimento de personagens.

Este sistema funciona em conjunto com seu fluxo de trabalho de animação existente:

• Editor de Animação: Continue usando o Editor de Animação como sua ferramenta principal para criar clipes individuais e ajustar quadros-chave e curvas.
• Editor de Gráfico de Animação: Use esta ferramenta para pegar esses clipes e organizá-los em uma árvore lógica para impulsionar comportamentos de jogo sofisticados.

Projetado para melhorar a colaboração, o gráfico visual permite que os desenvolvedores inspecionem, depurem e entendam rapidamente a lógica criada pelos animadores. Enquanto os artistas se concentram em refinar o movimento interativo, os desenvolvedores ainda podem acessar os nós do gráfico de animação programaticamente para controle direto sobre animações e estados misturados.

Construir um gráfico

Para começar a construir lógica para um personagem animável, acesse o editor de gráfico de animação através da aba Avatar na faixa de opções do Studio. Os seguintes passos demonstram como inicializar um rig e construir uma rede de nós básica usando animações padrão de caminhada e aceno.

Para uma exploração mais profunda de aplicações práticas, você pode explorar o Arquivo de Referência do Gráfico de Animação, que contém exemplos de implementação tanto fundamentais quanto complexos.

Para criar seu próprio gráfico de animação, semelhante ao exemplo básico fornecido na referência, use os seguintes passos:

1. No Studio, adicione um rig animável navegando até a aba Avatar e selecionando Personagem ⟩ Meu Avatar.

   

2. Abra o Editor de Gráfico de Animação navegando até Editor de Gráfico na aba Avatar.

   

3. Selecione o rig animável na visualização 3D. Na visualização do editor de gráfico, selecione Gráfico no canto superior esquerdo e selecione Novo para criar um novo gráfico.

4. No Editor de Gráfico, clique com o botão direito e selecione Inserir Nó ⟩ Clip.

   

5. No novo nó Clip, defina o ID da Animação.

   1. Selecione o menu suspenso ID da Animação.

   2. Para enviar um ID de ativo de animação específico, clique em Importar.

      

   3. No campo ID da Animação, adicione a animação padrão de Caminhada: 507777826.

   4. Selecione Importar.

6. Adicione outro nó clip repetindo os passos 4-5 usando a animação padrão de Aceno: 507770239.

   

7. No Editor de Gráfico, clique com o botão direito e selecione Adicionar.

   

8. Conecte os nós Clip ao nó Adicionar arrastando o conector de saída superior direito para a porta apropriada:

   1. Conecte o nó Clip com a animação de Caminhada à porta Base.
   2. Conecte o nó Clip com a animação de Aceno à porta Adicional.

   

9. Do nó Adicionar, conecte o conector de saída superior direito à porta de saída do Gráfico Pose.

   

10. OPCIONAL

    Atribua um parâmetro à sua variável Speed.

    1. Clique e arraste a porta verde de Velocidade para uma área vazia. Um novo nó de parâmetro será exibido.

       

    2. No canto superior esquerdo do editor de gráfico, use o painel de parâmetros para modificar rapidamente os parâmetros em seus nós. Você também pode acessar isso programaticamente.

       

11. Teste a animação pressionando o botão de play.

    

12. Tente testar vários pesos, velocidades, modos de reprodução e outras animações. Para mais informações sobre nós individuais, veja a referência de nós.

Integração de API

Criar e implantar um Gráfico de Animação segue o pipeline padrão de animação do Roblox. Após selecionar um rig no Editor de Gráfico de Animação, um novo ativo AnimationGraphDefinition é criado. Este ativo serve como o contêiner para seus nós, conexões e parâmetros. Uma vez que sua lógica esteja finalizada, você publica o gráfico para receber um ID de Ativo padrão.

Em seus scripts, você interage com esses gráficos carregando-os em um Animator como faria com uma animação tradicional. Para impulsionar a lógica interna do gráfico, use AnimationTrack:SetParameter() para passar valores em tempo real — como velocidade de movimento ou booleanos de estado — diretamente nas variáveis do gráfico.

local animation = Instance.new("Animation")
animation.AnimationId = "rbxassetid://123456789" -- Seu ID de Gráfico Publicado

local animationTrack = animator:LoadAnimation(animation)
animationTrack:Play()

-- Atualizações dinâmicas de parâmetros via RunService
game:GetService("RunService").Stepped:Connect(function(_, dt)
    local currentSpeed = humanoidRootPart.AssemblyLinearVelocity.Magnitude
    animationTrack:SetParameter("humanoidSpeed", currentSpeed)
end)

Referência de Nós

Regras de eventos globais

Para todos os nós e transições, as seguintes regras se aplicam por padrão:

• Eventos se propagam para cima a partir de seu nó de origem através do gráfico. Cada evento carrega um peso representando a influência de sua origem na mistura final. Se o peso atingir zero em algum ponto, o evento é silenciado.
• Nós sem lógica de evento personalizada passam todos os eventos inalterados; nós que misturam ou selecionam entre entradas podem escalar o peso ou bloquear eventos de entradas não primárias (veja a seção de Evento por nó).
• Eventos de marcador que atingem o topo do gráfico podem ser observados via AnimationTrack:GetMarkerReachedSignal().

Transições

Vários nós no Gráfico de Animação (como Selecionar, Selecionar Prioridade, Sequência e Sequência Aleatória) gerenciam como as animações se misturam ao alternar entre entradas ativas. Para evitar redundância na referência de nós, esses comportamentos são definidos por grupos de propriedades de transição padronizadas.

Transição padrão

O comportamento de mistura básico aplicado ao nó sempre que ele muda para uma nova entrada ativa.

• DefaultTransitionDuration (número): O tempo (em segundos) que leva para misturar completamente na nova pose.
• DefaultTransitionCurve (Enum.PoseEasingStyle): A função de suavização aplicada durante a mistura. Atualmente, suporta apenas Enum.PoseEasingStyle.Linear e Enum.PoseEasingStyle.CubicV2.

Sobrescrita de transição

Propriedades de link específicas de entrada que substituem a transição padrão. Durações e curvas de sobrescrita se aplicam quando o nó transita para essa entrada, exceto para transições Antes de Terminar, que usam as sobrescritas da entrada de saída.

• TransitionOverrideDuration (número): Substitui a duração da transição padrão.
• TransitionOverrideCurve (Enum.PoseEasingStyle): Substitui a curva de transição padrão. Atualmente, suporta apenas Enum.PoseEasingStyle.Linear e Enum.PoseEasingStyle.CubicV2.

Temporização de transição

Para tipos de nós de sequência, as seguintes configurações controlam quando a sequência avança para a próxima entrada:

• WaitFor (Enum.AnimationNodeWaitFor): Define a condição para avançar. Use Enum.AnimationNodeWaitFor|Finished (padrão) para esperar que a entrada atual termine ou complete um loop, ou Enum.AnimationNodeWaitFor|Trigger para avançar quando WaitForTrigger for true. Defina o padrão de nível de nó com DefaultWaitFor, ou sobrescreva-o para uma entrada com TransitionOverrideWaitFor.

  • Quando (Enum.AnimationNodeTransitionWhen): Aplica-se quando Wait For é Enum.AnimationNodeWaitFor|Finished. Defina o padrão de nível de nó com DefaultTransitionWhen, ou sobrescreva-o para a entrada de saída com TransitionOverrideWhen.

    • Enum.AnimationNodeTransitionWhen|Finished (padrão): Começa a mistura após a entrada atual terminar.
    • Enum.AnimationNodeTransitionWhen|BeforeFinished: Começa a mistura uma duração de transição antes da entrada atual terminar, de modo que a mistura se sobreponha ao final de sua animação. Por exemplo, uma transição de 0,2 segundos começa durante os últimos 0,2 segundos da animação.

RandomSequenceNode também suporta DefaultTransitionWhen e TransitionOverrideWhen para controlar quando a mistura começa.

Para transições de máquina de estados, veja Propriedades de transição.

Replicação

Parâmetros do gráfico de animação e estado interno do nó se replicam automaticamente. O modo de replicação é determinado por Workspace.AuthorityMode no momento em que o script Animate é criado:

• Em Enum.AuthorityMode.Automatic: Parâmetros definidos via AnimationTrack:SetParameter() se replicam automaticamente para outros pares.
• Em Enum.AuthorityMode.Server: O servidor controla a simulação completa do gráfico. Todos os estados dos nós, como tempo decorrido para Enum.AnimationNodeType.ClipNode, e parâmetros do gráfico se replicam automaticamente do servidor para os clientes. O cliente do jogador proprietário usa previsão para reprodução local suave.

Scripts Animate de Exemplo

Para gerar scripts de exemplo para impulsionar um gráfico de animação para um rig, use Gráfico -> Criar script Animate no Editor de Gráfico de Animação. Isso produz uma hierarquia de script colocada sob StarterCharacterScripts (para personagens de jogadores) ou diretamente no rig (para NPCs):

Animate (ModuleScript)
├── RunClient (LocalScript)
└── RunServer (Script, RunContext = Legacy)

O Animate ModuleScript contém a lógica de carregamento do gráfico. Os scripts RunClient e RunServer o invocam no contexto apropriado. Quais scripts são incluídos depende do caso de uso:

Os seguintes atributos são armazenados no script Animate e configuram seu comportamento:

Replicação de parâmetros no modo Automático

Quando Workspace.AuthorityMode é Automático:

• O cliente proprietário controla os gráficos de personagens de jogadores; o servidor controla os gráficos de NPCs.
• Parâmetros definidos via AnimationTrack:SetParameter() são replicados automaticamente para outros pares. Múltiplas chamadas SetParameter dentro de um único quadro são coalescidas (último escritor vence).
• Nenhum script adicional é necessário para o transporte de parâmetros — o mecanismo lida com a replicação internamente.
• Outros clientes veem atualizações de parâmetros com um pequeno atraso (um intervalo de envio mais latência de rede).

Autoridade do servidor

Quando Workspace.AuthorityMode é Servidor:

• O servidor é autoritário para todos os gráficos — ele executa a simulação e replica o estado completo do gráfico.
• O que é replicado: Tanto parâmetros quanto estado interno do nó, incluindo tempo decorrido, seleções atuais, progresso de transição, contagens de loop e sementes de RNG. Isso garante que todos os clientes vejam um comportamento de animação idêntico.
• Personagens de jogadores: O servidor controla o gráfico. O script RunClient do cliente proprietário habilita automaticamente Enum.PredictionMode no Animator, para que o jogador local veja uma animação suave e prevista que se reconcilia com o servidor em caso de discrepância.
• NPCs: O servidor controla o gráfico exclusivamente; os clientes observam o estado replicado sem simulação local.

Impulsionando parâmetros

Use AnimationTrack:SetParameter() de cada script que executa o gráfico:

• NPC (qualquer modo): Chame SetParameter do RunServer (ou qualquer Script do servidor com acesso ao AnimationTrack).
• Personagem jogador em Enum.AuthorityMode.Server: Chame SetParameter de ambos RunServer e RunClient. O servidor precisa de parâmetros para controlar a simulação autoritária, e o cliente proprietário precisa dos mesmos parâmetros para controlar sua previsão local.
• Personagem jogador em Enum.AuthorityMode.Automatic: Chame SetParameter do RunClient (ou qualquer LocalScript do cliente com acesso ao AnimationTrack).

O script Animate gerado inclui um bloco SetParameter comentado como ponto de partida. Descomente e modifique-o para impulsionar parâmetros a partir do estado do jogo (velocidade de movimento, estado do humanoide, direção de entrada, etc.).