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:
Na aba Avatar, abra as Configurações de Avatar.

Selecione a aba Movimento no lado esquerdo da janela e, na seção Habilidades, selecione Biblioteca de Controladores de Personagem.

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 Tabela | Propósito |
|---|---|
| Name | A 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, TimedLabels | Bits nomeados em uma máscara compartilhada de 64 bits que atuam como o barramento de coordenação entre habilidades; veja rótulos. |
| StartsWhen, RunsWhile | Condições que definem quando iniciar a habilidade e quando mantê-la em execução, respectivamente; veja condições. |
| Blocks, Stops, Suspends, ExclusiveGroup | Como lidar com conflitos entre habilidades que não podem estar ativas ao mesmo tempo. |
| Input | A 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, State | Valores 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, OnTeardown | Callbacks 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.
- 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.
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,
}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.
| Chave | Descrição |
|---|---|
| TimedLabels.OnStart | Dicioná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.OnStop | Dicioná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.Consumes | Lista 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. |
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.
| Objetivo | Sintaxe | Exemplo |
|---|---|---|
| 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 Conflito | Propósito |
|---|---|
| Blocks | Enquanto 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. |
| Stops | Quando 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. |
| Suspends | Quando 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:
Modo Inicia Para a partir da Entrada Press Ao pressionar. Nunca. A habilidade termina por conta própria através de um conflito, seu próprio RunsWhile, ou chamando Stop(). Hold Ao pressionar. Ao soltar. Hold com Repeats Ao pressionar. O soltar termina o re-disparo, não o ciclo já em andamento. Toggle Ao 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).
Slot Teclado & Mouse Gamepad Toque Atribuição Padrão 1 Espaço BotãoA ① Pular 2 ShiftEsquerdo BotãoL1 ② Correr 3 ControlEsquerdo BotãoB ③ Abaixar 4 R BotãoX ④ 5 BotãoEsquerdoDoMouse BotãoR2 ⑤ 6 Q BotãoY ⑥ 7 X BotãoR1 ⑦ 8 C BotãoL2 9 F DPadEsquerdo 10 G DPadDireito 11 V DPadBaixo 
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:
| Sensor | Descrição |
|---|---|
| Sensor.Ground | Em pé sobre uma superfície |
| Sensor.IsMoving | A entrada de movimento está sendo aplicada |
| Sensor.MoveInput | O vetor de movimento em si |
| Sensor.Ceiling | Algo está diretamente acima |
| Sensor.Climb | Uma superfície escalável está ao alcance |
| Sensor.Water / Sensor.WaterSurface | Na água / na superfície |
| Sensor.Sit | Sentado |
| Sensor.Tipped | Virou |
| Sensor.Tool | Segurando um Tool |
| Sensor.LookDirectionInput | A direção de olhar comandada |
| Sensor.RotateToLookDirectionInput | Se 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.
| Callback | Executa | Casos 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.