La Bibliothèque de Contrôleur de Personnage (CCL) est un cadre modulaire pour construire le mouvement et les comportements des personnages à travers des attributs et des scripts Luau. Cette architecture remplace les machines d'état rigides Humanoid par un système flexible et extensible pour les mécaniques de personnage.
Activer la CCL
Le CCL est optionnel via la fenêtre Paramètres de l'Avatar de Studio. Pour l'activer :
Dans l'onglet Avatar, ouvrez Paramètres de l'Avatar.

Sélectionnez l'onglet Mouvement sur le côté gauche de la fenêtre et, dans la section Capacités, sélectionnez Bibliothèque de Contrôleur de Personnage.

Toutes les capacités standard comme Courir, Sauter et Grimper sont activées par défaut. Pour désactiver l'une d'elles à l'exécution, décochez la case associée.
Capacités
Les capacités évaluent ce qu'un personnage peut faire, comme la capacité de courir, sauter, grimper et nager. Au lieu de s'appuyer sur un ensemble fixe d'états de personnage définis par le moteur comme ceux dans Enum.HumanoidStateType, les capacités de la CCL déterminent dynamiquement ce qu'un personnage peut faire et comment il doit réagir à l'entrée du joueur.
Structurellement, une capacité est une table Luau autonome qui spécifie principalement ce qui suit :
| Champs de Table | But |
|---|---|
| Name | L'identité unique de la capacité ; les conditions et les conflits y font référence par nom. Enregistrer deux capacités avec le même Name génère une erreur. Pour quelques capacités similaires, donnez à chacune un Name différent et partagez un label commun dans Labels. Le nom du ModuleScript détermine la clé de configuration unique. |
| Labels, TimedLabels | Bits nommés dans un masque partagé de 64 bits qui agissent comme le bus de coordination entre les capacités ; voir labels. |
| StartsWhen, RunsWhile | Conditions qui définissent quand démarrer la capacité et quand la garder active, respectivement ; voir conditions. |
| Blocks, Stops, Suspends, ExclusiveGroup | Comment gérer les conflits entre les capacités qui ne peuvent pas être actives en même temps. |
| Input | L'entrée qui déclenche la capacité. Input.Mode contrôle comment l'entrée démarre et arrête la capacité ; RunsWhile ne contient que des conditions mondiales, jamais l'entrée elle-même ; voir inputs. |
| Config, State | Valeurs de configuration par défaut et état répliqué pour chaque enregistrement de capacité. Les rappels lisent la configuration à partir de abilityCtx.Config et lisent ou écrivent l'état répliqué via abilityCtx.State. |
| OnSetup, OnStart, OnStop, OnUpdate, OnTeardown | Rappels de cycle de vie où le comportement réel de la capacité est scripté ; voir callbacks. |
Labels
Un label est un bit nommé dans un masque partagé de 64 bits qui agit comme le bus de coordination entre les capacités. Essentiellement :
- Une capacité active diffuse ses Labels et TimedLabels dans le masque mondial.
- Les conflits de capacité définissent quelles autres capacités sont bloquées, arrêtées ou suspendues lors de l'activation.
Dans la configuration suivante, le label "CanFallDown" est diffusé dans le masque mondial lorsque Running est actif. La capacité FallingDown avec sa condition de StartsWhen = All( "CanFallDown", "Stunned" ) devient automatiquement un candidat, mais "Stunned" doit également être diffusé dans le masque mondial avant que FallingDown ne se produise.
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" }, -- Labels diffusés lorsque la capacité est active
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" ), -- Labels nécessaires pour que la capacité commence
Blocks = { Ability.Running }
}Les labels peuvent également être diffusés ou consommés de manière chronométrée en utilisant le dictionnaire TimedLabels.
| Clé | Description |
|---|---|
| TimedLabels.OnStart | Dictionnaire contenant des labels (clés) et des durées associées. Les labels sont diffusés lorsque la capacité commence et expirent automatiquement lorsque leur durée se termine. Par exemple, OnStart = { Dashing = 1 } diffuse le label Dashing pendant 1 seconde lorsque la capacité commence. |
| TimedLabels.OnStop | Dictionnaire contenant des labels (clés) et des durées associées. Les labels sont diffusés lorsque la capacité s'arrête et expirent automatiquement lorsque leur durée se termine. Par exemple, OnStop = { DashCooldown = 2 } diffuse le label DashCooldown pendant 2 secondes lorsque la capacité s'arrête. |
| TimedLabels.Consumes | Liste de labels à retirer (consommer) lorsque la capacité s'active. Par exemple, si un jeu de combat permet aux joueurs de contre-attaquer après avoir bloqué une attaque de l'adversaire, la capacité CounterAttack peut contenir à la fois StartsWhen = "AfterBlock" et TimedLabels = { Consumes = { "AfterBlock" } } pour éviter le double déclenchement de la capacité 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 },
},
}Conditions
Une condition est un ou plusieurs labels, sensors, ou une référence d'entrée, utilisée par StartsWhen et RunsWhile. Les conditions se compilent en opérations de bitmask à l'exécution et l'évaluation est des mathématiques entières — pas de parcours de table et pas de comparaisons de chaînes.
| Objectif | Syntaxe | Exemple |
|---|---|---|
| Une condition requise. | StartsWhen = Sensor.Ground | |
| Logique ET pour quand tous les labels existent dans le masque mondial et tous les capteurs sont actifs. | All() | StartsWhen = All( "CanFallDown", "Stunned" ) |
| Logique OU pour quand n'importe lequel des labels existe dans le masque mondial ou n'importe lequel des capteurs est actif. | Any() | StartsWhen = Any( "WallClimbing", "Climbing" ) |
| Négation de sorte que les labels ne peuvent pas exister dans le masque mondial et les capteurs ne peuvent pas être actifs. | Not() | RunsWhile = Not("Stunned") |
L'évaluation conditionnelle peut être combinée pour une logique plus complexe, comme le chaînage de All() plus Not() pour indiquer qu'un capteur doit être actif tandis qu'un label doit être inexistant :
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") ),
}Conflits
Certaines capacités ne peuvent pas être actives lorsqu'une autre capacité l'est ; par exemple, les personnages ne peuvent pas sauter en nageant, et ils ne peuvent pas courir en tombant. Le moteur résout ces conflits de manière déclarative à l'intérieur de la définition d'une capacité :
| Clé de Conflit | But |
|---|---|
| Blocks | Tant que la capacité possédante est active, les autres capacités listées ne peuvent pas commencer. Par exemple, une capacité ScopeAim pourrait contenir Blocks = { Ability.Running, Ability.Jumping } pour empêcher les personnages de courir ou de sauter tout en visant soigneusement à travers la lunette de leur arme. |
| Stops | Lorsque la capacité possédante commence, les autres capacités listées s'arrêtent de force et doivent être relancées. Par exemple, une capacité Hover pourrait contenir Stops = { Ability.Running } pour arrêter immédiatement le mouvement de course d'un personnage lorsqu'il commence à flotter. |
| Suspends | Lorsque la capacité possédante commence, les autres capacités listées suspendent et reprennent automatiquement lorsque la capacité possédante s'arrête. Par exemple, une capacité de sprint personnalisée pourrait contenir Suspends = { Ability.Running } afin que la course 🄐 soit suspendue au début du sprint, 🄑 soit bloquée en plein sprint, et 🄒 reprenne à l'arrêt du sprint. |
Une autre clé de conflit unique est ExclusiveGroup qui place plusieurs capacités dans un groupe, chacune avec une valeur de Priority. Une seule capacité par groupe peut être active et la priorité la plus élevée l'emporte. Cependant, si un challenger déclare Stops ciblant le nom/label du détenteur, il l'emporte indépendamment de la priorité.
Dans la configuration suivante, trois capacités (Sprinting, Crouching, Stagger) sont ajoutées à un groupe exclusif Locomotion. Sprinting a la priorité la plus élevée (200) donc elle l'emporte sur Crouching (100) et les deux ne s'exécutent jamais en même temps. Cependant, Stagger arrête de force le sprint (Stops = { Ability.Sprinting }), donc elle peut interrompre et supplanter Sprinting même si sa priorité (150) est inférieure.
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 },
}
-- Une capacité de priorité inférieure peut remplacer une capacité de priorité supérieure en l'arrêtant
local Stagger: AvatarAbilities.AbilityDefinition = {
Name = "Stagger",
ExclusiveGroup = { Name = "Locomotion", Priority = 150 },
Stops = { Ability.Sprinting },
}Entrées
La définition Input d'une capacité spécifie l'entrée utilisée pour tenter d'activer la capacité. Elle prend des paires clé-valeur qui configurent le comportement d'entrée, le slot d'action, et les icônes de bouton tactile optionnelles.
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 est un nom logique, pas une clé. La CCL génère un capteur d'entrée et l'AND toujours dans StartsWhen.
Mode définit comment cette entrée démarre et arrête la capacité. RunsWhile ne contient jamais l'entrée elle-même ; elle ne contient que des conditions mondiales, telles que se trouver sur le sol ou dans l'eau, donc Mode est la seule source de démarrage et d'arrêt pilotés par l'entrée :
Mode Démarre Arrête par Entrée Press À l'appui. Jamais. La capacité se termine elle-même par un conflit, son propre RunsWhile, ou en appelant Stop(). Hold À l'appui. À la libération. Hold avec Repeats À l'appui. La libération met fin au re-lancement, pas au cycle déjà en vol. Toggle À l'activation. À la désactivation. Press convient aux actions discrètes comme le dash, l'attaque et le lancer. Hold et Toggle conviennent aux actions soutenues comme le sprint, le viseur, le blocage, la position accroupie et la lévitation. Hold avec Repeats convient aux actions qui s'arrêtent d'elles-mêmes et se relancent tant qu'elles sont maintenues, comme les sauts répétés.
Repeats (booléen, Hold uniquement) fait que la capacité se termine à chaque cycle et se relance tant que l'entrée reste maintenue, au lieu de fonctionner en continu pendant toute la durée de la pression.
OutlivesInputWhile (Hold/Toggle uniquement) est une condition sous laquelle la capacité continue de fonctionner après la libération ou la désactivation, s'arrêtant une fois la condition levée. Utilisez-le lorsqu'une capacité doit durer plus longtemps que son entrée sous une condition mondiale spécifique.
ActionSlot définit un slot d'action qui est associé à une liste de InputActions et InputBindings dans le Système d'Action d'Entrée.
Plusieurs liaisons d'entrée de slot d'action sont prédéfinies par Roblox et, à l'avenir, le Gestionnaire d'Action d'Entrée vous permettra de reconfigurer les liaisons d'entrée par défaut pour les slots d'action comme vous le souhaitez. Définir ActionSlot à 0 choisira le prochain slot vide disponible. Sur les appareils mobiles, les slots 1-7 se remplissent avec des boutons à l'écran (voir le diagramme ci-dessous).
Slot Clavier & Souris Manette Tactile Affectation par défaut 1 Space ButtonA ① Sauter 2 LeftShift ButtonL1 ② Sprinter 3 LeftControl ButtonB ③ Accroupir 4 R ButtonX ④ 5 MouseLeftButton ButtonR2 ⑤ 6 Q ButtonY ⑥ 7 X ButtonR1 ⑦ 8 C ButtonL2 9 F DPadLeft 10 G DPadRight 11 V DPadDown 
CustomIcon, CustomIconActive, et CustomIconInvalid spécifient les ID d'actifs Roblox pour le bouton tactile lorsque la capacité est inactive, active ou indisponible, respectivement.
RunsWhile ne contient que des conditions mondiales. Le compilateur compose l'effet de l'entrée dans la continuation réelle de la capacité en arrière-plan en fonction de Mode, donc mettre l'entrée elle-même dans StartsWhen ou RunsWhile génère une erreur (ne faites pas référence à Rule.Input là). Les capacités Hold et Toggle s'arrêtent déjà à la libération ou à la désactivation par défaut, donc vous n'avez pas besoin de dupliquer cela dans 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),
}Pour faire en sorte qu'une capacité Hold ou Toggle dure plus longtemps que son entrée sous une condition mondiale, définissez OutlivesInputWhile au lieu d'ajouter l'entrée à RunsWhile. La capacité Crouching suivante continue de s'accroupir après que le joueur relâche l'entrée d'accroupissement, tant qu'il y a quelque chose au-dessus :
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,
}Capteurs
Un capteur est une valeur nommée sur le monde que le moteur lit pour vous. Vous lirez généralement des capteurs plutôt que de les écrire. Pour plus de commodité, plusieurs capteurs sont pré-enregistrés :
| Capteur | Description |
|---|---|
| Sensor.Ground | Debout sur une surface |
| Sensor.IsMoving | Une entrée de mouvement est appliquée |
| Sensor.MoveInput | Le vecteur de mouvement lui-même |
| Sensor.Ceiling | Quelque chose est directement au-dessus |
| Sensor.Climb | Une surface escaladable est à portée |
| Sensor.Water / Sensor.WaterSurface | Dans l'eau / à la surface |
| Sensor.Sit | Assis |
| Sensor.Tipped | Renversé |
| Sensor.Tool | Tenant un Tool |
| Sensor.LookDirectionInput | La direction de regard commandée |
| Sensor.RotateToLookDirectionInput | Si le personnage doit tourner vers la direction de regard commandée |
Rappels
Les fonctions de rappel de capacité vous permettent de script des comportements spécifiques :
Bien que vous enregistriez des capacités personnalisées sur le serveur, leurs rappels s'exécutent à la fois dans la simulation client prédite et la simulation serveur autoritaire. Gardez le comportement des rappels déterministe afin que les deux simulations produisent le même résultat.
| Rappel | Exécute | Cas d'utilisation |
|---|---|---|
| OnSetup(managerCtx, abilityCtx) | Une fois, lorsque la capacité est enregistrée. | Mettre en cache des références, initialiser l'état, etc. |
| OnStart(managerCtx, abilityCtx, hadLabel) | Chaque fois que la capacité est activée. | Appliquer un effet tel qu'une impulsion. La fonction hadLabel() indique si un label spécifié était présent lorsque l'activation a commencé, avant la résolution des conflits. |
| OnUpdate(managerCtx, abilityCtx) | Chaque image active. | Travail continu tel que des minuteries ou des forces par image. |
| OnStop(managerCtx, abilityCtx) | Chaque désactivation, volontaire ou forcée. | Annuler ce que OnStart() a fait. |
| OnTeardown(managerCtx, abilityCtx) | Lors de la suppression de la capacité. | Déconnecter des connexions, détruire des instances, etc. |
Le premier paramètre de chaque fonction de rappel, managerCtx, est un objet ManagerContext avec des propriétés partagées de personnage et de gestionnaire, y compris :
- managerCtx.AbilityOwner — Le Model du personnage tel que managerCtx.AbilityOwner.PrimaryPart est la partie racine.
- managerCtx.AbilityManager — Une vue réduite du gestionnaire afin qu'une capacité puisse ajouter, supprimer et interroger des capacités depuis l'intérieur de ses propres rappels.
- managerCtx.BodyParts — Les parties du corps du personnage, avec des aides pour activer et désactiver la collision par membre.
- managerCtx.ControllerManager — Le ControllerManager du personnage pour le contrôle physique. Il peut être nil lorsque aucune capacité enregistrée ne nécessite de physique.
- managerCtx.RootCFrame — Le CFrame de la partie racine, capturé une fois au début de l'image afin que les rappels ne le récupèrent pas eux-mêmes.
- managerCtx.RootLookVector — Direction dans laquelle la partie racine du personnage fait face.
- managerCtx.RootUpVectorY — La composante Y du vecteur vers le haut de la partie racine.
- managerCtx.TaskSynchronize() — Synchronise un rappel avant l'accès au DataModel lorsque le support de rappel parallèle est activé. Actuellement, OnUpdate ne s'exécute pas dans un contexte parallèle, donc cette fonction n'a aucun effet. Un support complet de Luau parallèle est prévu pour une mise à jour future.
Le deuxième paramètre, abilityCtx, est un objet AbilityContext avec des tables gérées par le moteur pour l'enregistrement de capacité actuel :
- abilityCtx.Config — Valeurs de configuration en lecture seule pour cet enregistrement de capacité.
- abilityCtx.State — État mutable qui se réplique à travers le DataModel. Autorité Serveur restaure ces valeurs lors du retour en arrière et de la resimulation.
- abilityCtx.Local — État mutable temporaire qui ne se réplique pas et ne participe pas au retour en arrière.
Stockez les données de rappel personnalisées dans abilityCtx.State ou abilityCtx.Local. Écrire des champs personnalisés directement dans abilityCtx est une erreur.