Bibliothèque de Contrôleur de Personnage

*Ce contenu est traduit en utilisant l'IA (Beta) et peut contenir des erreurs. Pour consulter cette page en anglais, clique ici.

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 :

  1. Dans l'onglet Avatar, ouvrez Paramètres de l'Avatar.

    Paramètres de l'Avatar indiqués dans la barre d'outils de Studio
  2. 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.

    Basculer la Bibliothèque de Contrôleur de Personnage dans la fenêtre des Paramètres de l'Avatar
  3. 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 TableBut
NameL'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, TimedLabelsBits nommés dans un masque partagé de 64 bits qui agissent comme le bus de coordination entre les capacités ; voir labels.
StartsWhen, RunsWhileConditions qui définissent quand démarrer la capacité et quand la garder active, respectivement ; voir conditions.
Blocks, Stops, Suspends, ExclusiveGroupComment gérer les conflits entre les capacités qui ne peuvent pas être actives en même temps.
InputL'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, StateValeurs 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, OnTeardownRappels 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 conditions de capacité (StartsWhen, RunsWhile) testent le masque mondial et réagissent.
  • 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.

Capacité de Course
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,
}
Capacité de Chute
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.OnStartDictionnaire 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.OnStopDictionnaire 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.ConsumesListe 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.
Labels Chronométrés
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.

ObjectifSyntaxeExemple
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 ConflitBut
BlocksTant 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.
StopsLorsque 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.
SuspendsLorsque 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 :

    ModeDémarreArrê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).

    SlotClavier & SourisManetteTactileAffectation par défaut
    1SpaceButtonA①Sauter
    2LeftShiftButtonL1②Sprinter
    3LeftControlButtonB③Accroupir
    4RButtonX④
    5MouseLeftButtonButtonR2⑤
    6QButtonY⑥
    7XButtonR1⑦
    8CButtonL2
    9FDPadLeft
    10GDPadRight
    11VDPadDown
  • 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 :

CapteurDescription
Sensor.GroundDebout sur une surface
Sensor.IsMovingUne entrée de mouvement est appliquée
Sensor.MoveInputLe vecteur de mouvement lui-même
Sensor.CeilingQuelque chose est directement au-dessus
Sensor.ClimbUne surface escaladable est à portée
Sensor.Water / Sensor.WaterSurfaceDans l'eau / à la surface
Sensor.SitAssis
Sensor.TippedRenversé
Sensor.ToolTenant un Tool
Sensor.LookDirectionInputLa direction de regard commandée
Sensor.RotateToLookDirectionInputSi 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.

RappelExécuteCas 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.

©2026 Société Roblox. Roblox, le logo Roblox et Powering Imagination font partie de nos marques déposées aux États-Unis et dans d'autres pays.