Roblox Character Controller Library: abilities, sensors, and custom movement
Posted: Sat Oct 17, 2026 8:21 pm
Roblox Character Controller Library: abilities, sensors, and custom movement
The Character Controller Library (CCL) is a newer system for character movement on Roblox. It replaces the rigid Humanoid state machine with a modular framework built around abilities and controllers. If you have been wanting more control over how your character moves, this is worth understanding.
How to enable it
CCL is opt-in. Go to File > Beta Features > AvatarAbilities Character Controller Library to enable the beta. Then open Avatar Settings from the Avatar tab, select the Movement tab, and check Character Controller Library in the Abilities section. Running, Jumping, and Climbing are enabled by default.
Abilities vs Controllers
Abilities define what a character can do: run, jump, climb, swim. They are self-contained Luau tables with conditions, conflicts, and callbacks. Controllers handle the physical simulation: GroundController for walking, AirController for jumping, ClimbController for ladders, SwimController for water.
The key difference from the old Humanoid system is that abilities are dynamic. Instead of being locked into Enum.HumanoidStateType states, abilities use sensors and labels to determine what the character should be doing right now.
Sensors and labels
Sensors are pre-registered values the engine reads for you: Sensor.Ground, Sensor.IsMoving, Sensor.MoveInput, Sensor.Ceiling, Sensor.Climb, Sensor.Water, and others. You read these in your ability conditions.
Labels are named bits in a shared 64-bit mask. When an ability is active, it broadcasts its labels. Other abilities test those labels in their StartsWhen and RunsWhile conditions. For example, Running broadcasts "CanFallDown", and FallingDown starts when both "CanFallDown" and "Stunned" are present.
Conflicts between abilities
You define how abilities interact through conflict keys:
Callbacks
Each ability has lifecycle callbacks: OnSetup, OnStart, OnUpdate, OnStop, OnTeardown. OnStart is where you apply an impulse or effect. OnUpdate runs every active frame for timers or per-frame forces. OnStop undoes what OnStart did.
Callbacks run in both the predicted client simulation and the authoritative server simulation. Keep them deterministic so both produce the same result. Never yield inside a callback.
Customizing controllers
You can tweak controller properties through scripts. GroundController has MoveSpeedFactor, AccelerationTime, DecelerationTime, and TurnSpeedFactor. AirController has MoveSpeedFactor, MoveMaxForce, and TurnMaxTorque. These let you change how the character feels without rewriting the entire movement system.
Source
[1] Character Controller Library - Roblox Creator Documentation
[2] Releasing Character Physics Controllers - Roblox Developer Forum
The Character Controller Library (CCL) is a newer system for character movement on Roblox. It replaces the rigid Humanoid state machine with a modular framework built around abilities and controllers. If you have been wanting more control over how your character moves, this is worth understanding.
How to enable it
CCL is opt-in. Go to File > Beta Features > AvatarAbilities Character Controller Library to enable the beta. Then open Avatar Settings from the Avatar tab, select the Movement tab, and check Character Controller Library in the Abilities section. Running, Jumping, and Climbing are enabled by default.
Abilities vs Controllers
Abilities define what a character can do: run, jump, climb, swim. They are self-contained Luau tables with conditions, conflicts, and callbacks. Controllers handle the physical simulation: GroundController for walking, AirController for jumping, ClimbController for ladders, SwimController for water.
The key difference from the old Humanoid system is that abilities are dynamic. Instead of being locked into Enum.HumanoidStateType states, abilities use sensors and labels to determine what the character should be doing right now.
Sensors and labels
Sensors are pre-registered values the engine reads for you: Sensor.Ground, Sensor.IsMoving, Sensor.MoveInput, Sensor.Ceiling, Sensor.Climb, Sensor.Water, and others. You read these in your ability conditions.
Labels are named bits in a shared 64-bit mask. When an ability is active, it broadcasts its labels. Other abilities test those labels in their StartsWhen and RunsWhile conditions. For example, Running broadcasts "CanFallDown", and FallingDown starts when both "CanFallDown" and "Stunned" are present.
Conflicts between abilities
You define how abilities interact through conflict keys:
- Blocks: the listed abilities cannot start while this one is active
- Stops: the listed abilities force-stop when this one starts
- Suspends: the listed abilities pause and auto-resume when this one stops
- ExclusiveGroup: only one ability in the group can be active, highest priority wins
Callbacks
Each ability has lifecycle callbacks: OnSetup, OnStart, OnUpdate, OnStop, OnTeardown. OnStart is where you apply an impulse or effect. OnUpdate runs every active frame for timers or per-frame forces. OnStop undoes what OnStart did.
Callbacks run in both the predicted client simulation and the authoritative server simulation. Keep them deterministic so both produce the same result. Never yield inside a callback.
Customizing controllers
You can tweak controller properties through scripts. GroundController has MoveSpeedFactor, AccelerationTime, DecelerationTime, and TurnSpeedFactor. AirController has MoveSpeedFactor, MoveMaxForce, and TurnMaxTorque. These let you change how the character feels without rewriting the entire movement system.
Source
[1] Character Controller Library - Roblox Creator Documentation
[2] Releasing Character Physics Controllers - Roblox Developer Forum