Biblioteca de Controladores de Personagem

*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.

A Biblioteca de Controladores de Personagem (CCL) é uma estrutura modular para construir movimentos e comportamentos de personagens através de atributos e scripts Luau. Esta arquitetura substitui máquinas de estado rígidas Humanoid por um sistema flexível e extensível para mecânicas de personagens.

Ativar CCL

O CCL é opcional através da janela de Configurações de Avatar do Studio. Para habilitá-lo:

  1. Na aba Avatar, abra as Configurações de Avatar.

    Configurações de Avatar indicadas na barra de ferramentas do Studio
  2. Selecione a aba Movimento no lado esquerdo da janela e, na seção Habilidades, selecione Biblioteca de Controladores de Personagem.

    Alternância da Biblioteca de Controladores de Personagem na janela de Configurações de Avatar
  3. Todas as habilidades padrão, como Correr, Pular e Escalar, estão habilitadas por padrão. Para desabilitar qualquer uma delas em tempo de execução, desmarque a caixa associada.

Habilidades

Habilidades avaliam o que um personagem pode fazer, como a capacidade de correr, pular, escalar e nadar. Em vez de depender de um conjunto fixo de estados de personagem definidos pelo motor, como aqueles em Enum.HumanoidStateType, as habilidades da CCL determinam dinamicamente o que um personagem pode fazer e como ele deve responder à entrada do jogador.

Estruturalmente, uma habilidade é uma tabela Luau autônoma que especifica principalmente o seguinte:

Campos da TabelaPropósito
NameA identidade única da habilidade; condições e conflitos a referenciam pelo nome. Registrar duas habilidades com o mesmo Name gera um erro. Para algumas habilidades semelhantes, dê a cada uma um Name diferente e compartilhe um rótulo comum em Labels. O nome do ModuleScript determina a chave de configuração única.
Labels, TimedLabelsBits nomeados em uma máscara compartilhada de 64 bits que atuam como o barramento de coordenação entre habilidades; veja rótulos.
StartsWhen, RunsWhileCondições que definem quando iniciar a habilidade e quando mantê-la em execução, respectivamente; veja condições.
Blocks, Stops, Suspends, ExclusiveGroupComo lidar com conflitos entre habilidades que não podem estar ativas ao mesmo tempo.
InputA entrada que aciona a habilidade. Input.Mode controla como a entrada inicia e para a habilidade; RunsWhile contém apenas condições do mundo, nunca a entrada em si; veja entradas.
Config, StateValores de configuração padrão e estado replicado para cada registro de habilidade. Callbacks leem a configuração de abilityCtx.Config e leem ou escrevem o estado replicado através de abilityCtx.State.
OnSetup, OnStart, OnStop, OnUpdate, OnTeardownCallbacks de ciclo de vida onde o comportamento real da habilidade é scriptado; veja callbacks.

Rótulos

Um rótulo é um bit nomeado em uma máscara compartilhada de 64 bits que atua como o barramento de coordenação entre habilidades. Essencialmente:

  • Uma habilidade ativa transmite seus Labels e TimedLabels para a máscara do mundo.
  • As condições da habilidade (StartsWhen, RunsWhile) testam a máscara do mundo e reagem.
  • Os conflitos da habilidade definem quais outras habilidades são bloqueadas, paradas ou suspensas ao serem ativadas.

Na configuração a seguir, o rótulo "CanFallDown" é transmitido para a máscara do mundo quando Running está ativo. A habilidade FallingDown com sua condição de StartsWhen = All( "CanFallDown", "Stunned" ) automaticamente se torna uma candidata, mas "Stunned" também deve ser transmitido para a máscara do mundo antes que FallingDown ocorra.

Habilidade de Correr
local AvatarAbilities = require("@rbx/AvatarAbilities")
local Identifiers = AvatarAbilities.Identifiers
local Ability = Identifiers.Ability
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not
local Running: AvatarAbilities.AbilityDefinition = {
Name = Ability.Running,
Labels = { "CanFallDown" }, -- Rótulos transmitidos quando a habilidade está ativa
StartsWhen = Sensor.Ground,
RunsWhile = Sensor.Ground,
}
Habilidade de Cair
local AvatarAbilities = require("@rbx/AvatarAbilities")
local Identifiers = AvatarAbilities.Identifiers
local Ability = Identifiers.Ability
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not
local FallingDown: AvatarAbilities.AbilityDefinition = {
Name = Ability.FallingDown,
StartsWhen = All( "CanFallDown", "Stunned" ), -- Rótulos necessários para a habilidade começar
Blocks = { Ability.Running }
}

Os rótulos também podem ser transmitidos ou consumidos de maneira temporizada usando o dicionário TimedLabels.

ChaveDescrição
TimedLabels.OnStartDicionário contendo rótulos (chaves) e durações associadas. Rótulo(s) são transmitidos quando a habilidade começa e expiram automaticamente quando sua duração termina. Por exemplo, OnStart = { Dashing = 1 } transmite o rótulo Dashing por 1 segundo quando a habilidade começa.
TimedLabels.OnStopDicionário contendo rótulos (chaves) e durações associadas. Rótulo(s) são transmitidos quando a habilidade para e expiram automaticamente quando sua duração termina. Por exemplo, OnStop = { DashCooldown = 2 } transmite o rótulo DashCooldown por 2 segundos quando a habilidade para.
TimedLabels.ConsumesLista de rótulos a serem removidos (consumidos) quando a habilidade é ativada. Por exemplo, se um jogo de luta permite que os jogadores contra-atacam após bloquear o ataque de um oponente, a habilidade CounterAttack pode conter tanto StartsWhen = "AfterBlock" quanto TimedLabels = { Consumes = { "AfterBlock" } } para evitar a ativação dupla da habilidade CounterAttack.
Rótulos Temporizados
local AvatarAbilities = require("@rbx/AvatarAbilities")
local Identifiers = AvatarAbilities.Identifiers
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not
local Dash: AvatarAbilities.AbilityDefinition = {
Name = "Dash",
StartsWhen = All( Sensor.Ground, Not("DashCooldown") ),
RunsWhile = "Dashing",
TimedLabels = {
OnStart = { Dashing = 1 },
OnStop = { DashCooldown = 2 },
},
}

Condições

Uma condição é um ou mais rótulos, sensores ou uma referência de entrada, usados por StartsWhen e RunsWhile. As condições se compilam em operações de bitmask em tempo de execução e a avaliação é matemática inteira — sem caminhadas em tabelas e sem comparações de strings.

ObjetivoSintaxeExemplo
Uma condição obrigatória.StartsWhen = Sensor.Ground
Lógica E para quando todos os rótulos existem na máscara do mundo e todos os sensores estão ativos.All()StartsWhen = All( "CanFallDown", "Stunned" )
Lógica OU para quando qualquer dos rótulos existe na máscara do mundo ou qualquer dos sensores está ativo.Any()StartsWhen = Any( "WallClimbing", "Climbing" )
Negação de modo que os rótulos não possam existir na máscara do mundo e os sensores não possam estar ativos.Not()RunsWhile = Not("Stunned")

A avaliação condicional pode ser combinada para lógica mais complexa, como encadeamento de All() mais Not() para indicar que um sensor deve estar ativo enquanto um rótulo deve ser inexistente:

local AvatarAbilities = require("@rbx/AvatarAbilities")
local Identifiers = AvatarAbilities.Identifiers
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not
local Dive: AvatarAbilities.AbilityDefinition = {
Name = "Dive",
StartsWhen = All( Sensor.WaterSurface, Not("Recovering") ),
}

Conflitos

Algumas habilidades não podem estar ativas quando outra habilidade está; por exemplo, personagens não podem pular enquanto nadam, e não podem correr enquanto caem. O motor resolve esses conflitos de forma declarativa dentro da definição de uma habilidade:

Chave de ConflitoPropósito
BlocksEnquanto a habilidade proprietária está ativa, as outras habilidades listadas não podem começar. Por exemplo, uma habilidade ScopeAim pode conter Blocks = { Ability.Running, Ability.Jumping } para impedir que os personagens corram ou pulem enquanto miram cuidadosamente através da mira de sua arma.
StopsQuando a habilidade proprietária começa, as outras habilidades listadas forçam a parada e devem ser reativadas. Por exemplo, uma habilidade Hover pode conter Stops = { Ability.Running } para parar imediatamente o movimento de corrida de um personagem quando eles começam a flutuar.
SuspendsQuando a habilidade proprietária começa, as outras habilidades listadas pausam e depois retornam automaticamente quando a habilidade proprietária para. Por exemplo, uma habilidade de corrida personalizada pode conter Suspends = { Ability.Running } para que a corrida 🄐 pause no início da corrida, 🄑 seja bloqueada durante a corrida, e 🄒 retorne ao normal quando a corrida para.

Outra chave de conflito única é ExclusiveGroup, que coloca várias habilidades em um grupo, cada uma com um valor de Priority. Apenas uma habilidade por grupo pode estar ativa e a de maior prioridade vence. No entanto, se um desafiador declarar Stops visando o nome/rótulo do detentor, ele vence independentemente da prioridade.

Na configuração a seguir, três habilidades (Sprinting, Crouching, Stagger) são adicionadas a um grupo exclusivo Locomotion. Sprinting tem a maior prioridade (200), então vence sobre Crouching (100) e as duas nunca são executadas ao mesmo tempo. No entanto, Stagger força a parada da corrida (Stops = { Ability.Sprinting }), então pode interromper e superar Sprinting, mesmo que sua prioridade (150) seja menor.

local AvatarAbilities = require("@rbx/AvatarAbilities")
local Identifiers = AvatarAbilities.Identifiers
local Ability = Identifiers.Ability
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not
local Sprinting: AvatarAbilities.AbilityDefinition = {
Name = Ability.Sprinting,
ExclusiveGroup = { Name = "Locomotion", Priority = 200 },
}
local Crouching: AvatarAbilities.AbilityDefinition = {
Name = Ability.Crouching,
ExclusiveGroup = { Name = "Locomotion", Priority = 100 },
}
-- Uma habilidade de menor prioridade pode substituir uma habilidade de maior prioridade parando-a
local Stagger: AvatarAbilities.AbilityDefinition = {
Name = "Stagger",
ExclusiveGroup = { Name = "Locomotion", Priority = 150 },
Stops = { Ability.Sprinting },
}

Entradas

A definição de Input de uma habilidade especifica a entrada usada para tentar ativar a habilidade. Ela aceita pares chave-valor que configuram o comportamento da entrada, slot de ação e ícones de botão de toque opcionais.

local AvatarAbilities = require("@rbx/AvatarAbilities")
local Identifiers = AvatarAbilities.Identifiers
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not
local Dash: AvatarAbilities.AbilityDefinition = {
Name = "Dash",
Input = { InputName = "Dash", Mode = "Press", ActionSlot = 5 }
}
  • InputName é um nome lógico, não uma chave. A CCL gera um sensor de entrada e sempre o ANDa em StartsWhen.

  • Mode define como essa entrada inicia e para a habilidade. RunsWhile nunca contém a entrada em si; contém apenas condições do mundo, como estar no chão ou na água, então Mode é a única fonte de início e parada acionada por entrada:

    ModoIniciaPara a partir da Entrada
    PressAo pressionar.Nunca. A habilidade termina por conta própria através de um conflito, seu próprio RunsWhile, ou chamando Stop().
    HoldAo pressionar.Ao soltar.
    Hold com RepeatsAo pressionar.O soltar termina o re-disparo, não o ciclo já em andamento.
    ToggleAo ativar.Ao desativar.

    Press é adequado para ações discretas como dash, ataque e lançamento. Hold e Toggle são adequados para ações sustentadas como correr, mirar, bloquear, agachar e levitar. Hold com Repeats é adequado para ações que se auto-terminam e re-disparam enquanto mantidas, como saltos repetidos.

  • Repeats (booleano, apenas Hold) faz com que a habilidade se termine a cada ciclo e re-dispare enquanto a entrada permanecer pressionada, em vez de rodar continuamente durante toda a pressão.

  • OutlivesInputWhile (apenas Hold/Toggle) é uma condição sob a qual a habilidade continua em execução após a liberação ou desativação, parando uma vez que a condição é removida. Use-a quando uma habilidade deve durar mais que sua entrada sob uma condição específica do mundo.

  • ActionSlot define um slot de ação que está associado a uma lista de InputActions e InputBindings dentro do Sistema de Ação de Entrada.

    Vários bindings de entrada de slot de ação são pré-definidos pelo Roblox e, no futuro, o Gerenciador de Ação de Entrada permitirá que você reconfigure os bindings de entrada padrão para os slots de ação conforme desejado. Definir ActionSlot como 0 escolherá o próximo slot vazio disponível. Em dispositivos móveis, os slots 1-7 são preenchidos com botões na tela (veja o diagrama abaixo).

  • CustomIcon, CustomIconActive e CustomIconInvalid especificam IDs de ativos do Roblox para o botão de toque quando a habilidade está ociosa, ativa ou indisponível, respectivamente.

RunsWhile contém apenas condições do mundo. O compilador compõe o efeito da entrada na continuação real da habilidade nos bastidores com base em Mode, então colocar a entrada em si em StartsWhen ou RunsWhile gera um erro (não referencie Rule.Input lá). Habilidades Hold e Toggle já param ao soltar ou desativar por padrão, então você não precisa duplicar isso em RunsWhile:

local AvatarAbilities = require("@rbx/AvatarAbilities")
local Rule = AvatarAbilities.Rule
local Sensor = AvatarAbilities.Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not
local Glide: AvatarAbilities.AbilityDefinition = {
Name = "Glide",
Input = { InputName = "Glide", Mode = "Hold", ActionSlot = 6 },
StartsWhen = Not(Sensor.Ground),
RunsWhile = Not(Sensor.Ground),
}

Para fazer uma habilidade Hold ou Toggle durar mais que sua entrada sob uma condição do mundo, defina OutlivesInputWhile em vez de adicionar a entrada a RunsWhile. A seguinte habilidade Crouching mantém-se agachada após o jogador soltar a entrada de agachar, enquanto algo permanecer acima:

local AvatarAbilities = require("@rbx/AvatarAbilities")
local Identifiers = AvatarAbilities.Identifiers
local Sensor = Identifiers.Sensor
local Crouching: AvatarAbilities.AbilityDefinition = {
Name = "Crouching",
Input = { InputName = "Crouch", Mode = "Hold", OutlivesInputWhile = Sensor.Ceiling, ActionSlot = 3 },
RunsWhile = Sensor.Ground,
}

Sensores

Um sensor é um valor nomeado sobre o mundo que o motor lê para você. Você normalmente lê sensores em vez de escrevê-los. Para conveniência, vários sensores estão pré-registrados:

SensorDescrição
Sensor.GroundEm pé sobre uma superfície
Sensor.IsMovingA entrada de movimento está sendo aplicada
Sensor.MoveInputO vetor de movimento em si
Sensor.CeilingAlgo está diretamente acima
Sensor.ClimbUma superfície escalável está ao alcance
Sensor.Water / Sensor.WaterSurfaceNa água / na superfície
Sensor.SitSentado
Sensor.TippedVirou
Sensor.ToolSegurando um Tool
Sensor.LookDirectionInputA direção de olhar comandada
Sensor.RotateToLookDirectionInputSe o personagem deve rotacionar para a direção de olhar comandada

Callbacks

As funções de callback de habilidade permitem que você scriptifique comportamentos específicos:

Embora você registre habilidades personalizadas no servidor, seus callbacks são executados tanto na simulação do cliente prevista quanto na simulação do servidor autoritativa. Mantenha o comportamento do callback determinístico para que ambas as simulações produzam o mesmo resultado.

CallbackExecutaCasos de Uso
OnSetup(managerCtx, abilityCtx)Uma vez, quando a habilidade é registrada.Cache de referências, inicializar estado, etc.
OnStart(managerCtx, abilityCtx, hadLabel)Cada vez que a habilidade é ativada.Aplicar um efeito como um impulso. A função hadLabel() informa se um rótulo específico estava presente quando a ativação começou, antes da resolução de conflitos.
OnUpdate(managerCtx, abilityCtx)Cada quadro ativo.Trabalho contínuo como temporizadores ou forças por quadro.
OnStop(managerCtx, abilityCtx)Cada desativação, voluntária ou forçada.Desfazer o que OnStart() fez.
OnTeardown(managerCtx, abilityCtx)Na remoção da habilidade.Desconectar conexões, destruir instâncias, etc.

O primeiro parâmetro de cada função de callback, managerCtx, é um objeto ManagerContext com propriedades compartilhadas de personagem e gerente, incluindo:

  • managerCtx.AbilityOwner — O Model do personagem, de modo que managerCtx.AbilityOwner.PrimaryPart é a parte raiz.
  • managerCtx.AbilityManager — Uma visão reduzida do gerente para que uma habilidade possa adicionar, remover e consultar habilidades de dentro de seus próprios callbacks.
  • managerCtx.BodyParts — As partes do corpo do personagem, com auxiliares para ativar e desativar colisões por membro.
  • managerCtx.ControllerManager — O ControllerManager do personagem para controle de física. Pode ser nil quando nenhuma habilidade registrada requer física.
  • managerCtx.RootCFrame — O CFrame da parte raiz, capturado uma vez no início do quadro para que os callbacks não precisem buscá-lo individualmente.
  • managerCtx.RootLookVector — Direção que a parte raiz do personagem está enfrentando.
  • managerCtx.RootUpVectorY — O componente Y do vetor para cima da parte raiz.
  • managerCtx.TaskSynchronize() — Sincroniza um callback antes do acesso ao DataModel quando o suporte a callbacks paralelos está habilitado. Atualmente, OnUpdate não é executado em um contexto paralelo, então essa função não tem efeito. Suporte total ao Luau Paralelo está planejado para uma atualização futura.

O segundo parâmetro, abilityCtx, é um objeto AbilityContext com tabelas gerenciadas pelo motor para o registro atual da habilidade:

  • abilityCtx.Config — Valores de configuração somente leitura para este registro de habilidade.
  • abilityCtx.State — Estado mutável que se replica através do DataModel. A Autoridade do Servidor restaura esses valores durante rollback e resimulação.
  • abilityCtx.Local — Estado mutável que não se replica ou participa do rollback.

Armazene dados de callback personalizados em abilityCtx.State ou abilityCtx.Local. Escrever campos personalizados diretamente em abilityCtx é um erro.

©2026 Roblox Corporation, Roblox, o logotipo Roblox e Powering Imagination estão entre nossas marcas registradas e não registradas nos EUA e em outros países.