Hi Creators,
For years, Roblox’s default character controller has lived inside the C++ “black box” of the legacy Humanoid. While this has served us all well, we know its hard-coded nature often felt like something you had to work around rather than with.
Today, we are taking a step toward opening that box. We’re excited to announce the Studio Beta of the AvatarAbilities Character Controller Library, a foundational shift that moves character logic and physics into a transparent, performant, extensible Luau implementation.
Crouch, toggleable via “C”, is now a default character ability in experiences that opt in.
Core Concepts: AbilityManager and ControllerManager
The Luau-based character controller architecture separates logic from physical simulation using two primary systems:
- The AbilityManager (The “Brain”): A modular system that evaluates “Abilities” every frame. It uses Sensors, Labels, and Rules to decide both what a character can do and how it responds to player input, replacing the hard-coded Humanoid state machine.
- Note: While the API to register brand-new custom Abilities is still being finalized, we want to give you a sneak peek into the architecture of this system. We’ve included the Ability System Appendix below so you can see how the system works today and how you will soon be able to interface with it to build your own mechanics.
- The ControllerManager (The “Muscles”): This handles the actual physical simulation of the character and their environment. Abilities “talk” to the ControllerManager to update
MovingDirection,Acceleration, or active controllers (e.g.,GroundController).
Parity and more in Luau
This Luau-based character controller is more than just a direct port of Humanoid to Luau. It’s been rearchitected to be more configurable, extendable, and scalable, enabling game designs and offering workflows that Humanoid does not support. This new approach is designed to make it easier to configure character behavior for all types of experiences on the platform.
- Full Transparency: By moving the main logic of the character into a Luau library, you can now read, debug, and configure the character controller like any other game script.
- Concurrent Abilities: The Ability system supports overlapping and sequencing character behaviors by leveraging Labels and Rules. You will be able to easily build a character that is ‘Running’ while simultaneously ‘Aiming’ and ‘Reaching’ straight out of the box with no custom conflict resolution logic.
- Higher-Fidelity Physics: Built on
ControllerManager, this system provides deeper integration with our physics engine, resulting in better stability and improved physics such as realistic floor friction and conservation of momentum. Read more aboutControllerManagerhere. - Scalable Architecture: The system is architected to do work only when state is changing via a near “zero-cost” idle that is intended to remove the need for custom server-side NPC solutions.
How will this affect my existing experiences?
Given how large of a change this is, we want to be clear: existing experiences are unaffected. Instead, we will slowly move this to be the default for new experiences, leaving existing experiences unchanged. Furthermore, please keep in mind that this is an early Beta. Several core components—such as input handling and network ownership—are not in their final forms. We are sharing this now because we want your feedback to help shape the future of character movement on Roblox.
Intentional Differences in Character Movement
The new ControllerManager introduces several intentional changes in movement and feel designed to resolve legacy Humanoid inconsistencies and provide more predictable, stable behavior. By aligning character movement with how parts behave when driven by physical constraints, we’ve implemented improvements like friction with the ground, linear acceleration curves, and realistic conservation of linear and angular momentum when jumping.
Character behavior accounts for the floor’s material properties and therefore slides on ice.
Customizing the Feel
Our goal is to be fully configurable so you can achieve the feel you want for your experiences. You can iterate on specific controllers to refine the behavior, for example:
Snappier/Looser Ground Movement
- Friction: Modify
GroundControllerproperties likeFrictionandFrictionWeightto limit how quickly you can accelerate or change direction. - Turning: Adjust the
TurnSpeedFactorof theGroundControllerto change the max angular velocity of a turn.
Air Movement Control & Configuration
- Air Acceleration: Modify
AirControllerpropertiesMoveMaxForceandTurnMaxTorqueto configure how quickly you can accelerate and change direction in the air. - Momentum Toggles: Toggle
MaintainLinearMomentumandMaintainAngularMomentumto choose whether the character decelerates when no input is applied or not. Leaving these true allows characters to keep their relative positions when jumping on moving platforms.
Conservation of linear momentum keeps the character moving alongside the vehicle when jumping.
What’s Included in the Studio Beta
This Studio Beta delivers a stable core as we continue opening the “Luau box” and includes the following functionality:
-
The AvatarAbilities Luau Library: Accessed via require(“@rbx/AvatarAbilities”), this library provides a seamless transition by automatically handling Humanoid deactivation upon initialization.
-
Additional Default Abilities: Includes Luau versions of standard Humanoid States plus built-in Crouching, Strafing, and Sprinting.
- We are currently testing bindings to get your feedback:
- Crouch: C
- Strafe: Left Alt (PC) / Left Option (Mac)
- Sprint: Left Shift
Note: Today, if you have Shift Lock enabled, pressing the Left Shift button will enable both Shift Lock and Sprint. We understand this is not a great user experience; we are actively working on improving the default UI/UX and would appreciate your feedback on what intuitive default inputs should be across platforms.
- We are currently testing bindings to get your feedback:
-
Easy Configuration: Utilize the
ControllerManagerwithout needing to build your own Luau state machine. You can easily modify properties across the manager and all physics controllers to precisely tune character behavior. Check out the guide on how to do this here.
How to Get Started
To begin using the AvatarAbilities Library, you first need to enable the feature in Studio. Navigate to File > Beta Features, check the box for AvatarAbilities Character Controller Library, and restart Studio.
Option 1: Quick Testing (The “Jungle Gym”)
If you want to jump straight in, we’ve published an uncopylocked experience designed to put the default abilities - such as swimming and climbing - through their paces. This playground comes pre-configured, so you don’t have to worry about manual setup.
- Open the Avatar Abilities Beta Template placefile and select “Edit in Studio.”
- Ensure your Studio Beta is enabled.
- Press Play.
Option 2: Integration into Your Own Experience
To bring the new character controller into your existing project, you will need to copy three scripts from our provided placefile and move them into your own experience.
For the controller to function, these scripts must be placed in specific folders within the Explorer:
Note: When moving the AbilityManagerActor, ensure the folder remains intact with both the ServerInitialize and ClientInitialize scripts inside. This ensures the “Brain” of your character functions correctly across both the server and client.
Workflow Examples
At runtime, you can manually or programmatically edit both Properties on the Physics Controllers and Attributes on Abilities and to configure character movement:
Future Enhancements
We are already working hard to offer capabilities beyond this announcement, including:
- Custom Ability API: A streamlined way for you to register and share your own custom Abilities.
- Reach & Hold: New default Abilities for physical object interaction.
- Debug Tools: A visual Ability Graph and UI to help you debug complex logic layers in real-time.
- Parallel Execution: Further performance optimizations to execute rules and sensors in parallel.
- Zero-Overhead Idle: Deeper physics sleep system changes to reach near-zero cost for idle characters.
Feedback Guide
We are looking for high-level feedback on the architecture as we move toward full release.
- API & Architecture: Does the relationship between the AbilityManager and ControllerManager feel intuitive?
- The Label System: Are Labels and Rules powerful enough for your specific use cases?
- Input Defaults: What feels most natural for Sprint and Strafe? Does “C” for crouch feel good?
Happy building,
The Roblox Avatar Team
FAQ
Click to Open
Why is the ControllerManager still in C++?
- The ControllerManager instances are specialized low-level solver constraints that step at up to 240hz with other constraints from collisions or Constraint instances. This deep integration and high frequency is why they are more stable and behave predictably with other constraints. It’s how GroundController achieves collision-like friction behavior, it is a motorized collision constraint! This is staying in C++ for now because this is core physics engine functionality that unfortunately cannot currently be replicated with the same fidelity or performance in Luau.
Will the new controller be backported onto existing experiences?
- No. We recognize this is a significant change to API and character behavior and have no plans to backport the new controller onto existing games. The long term plan is for this to become the default for new experiences.
Does this support R6 characters?
- Currently, the AvatarAbilities library assumes the character is using an R15 rig. We plan to remove any requirements on a specific rig type in the future.
Are NPCs Supported?
- NPC support is coming very soon - right now, using the AvatarAbilities library with NPCs isn’t fully supported yet but we’re actively working on it.
How does this new system handle StarterCharacter and StarterHumanoid?
- StarterHumanoid and StarterCharacter work exactly as before since they are part of the engine’s core C++ character spawning functionality.
How is the library updated?
-
The library is loaded dynamically from an asset. We may update it anytime, but we want to set similar compatibility expectations as any native engine API.
-
During the beta we will need to make breaking changes to the library API. We’ll limit breaking changes to once a week, and announce releases a day in advance with change notes.
-
Post-beta breaking changes will be rolled out following the typical “three-phase rollout” process we normally use for breaking changes to native engine APIs. We’ll share a rollout schedule each time.
-
We may release backwards compatible bugfixes same-day. If we unintentionally break your experience we’ll usually revert and try a different fix or re-release it as a breaking change rollout.
-
We don’t promise maintenance support for old versions of the library. If you use your own copy of the library we’ll treat that similarly to any other script in your experience; meaning we’ll still try to avoid engine changes that would break it unintentionally, but we won’t make any changes or fixes to it ourselves.
Does the AvatarAbilities Library support Server Authority?
-
Yes. The AvatarAbilities beta is compatible with the Server Authority beta, though some features are still being refined.
- How to enable: Ensure both betas are active and set the AuthorityMode attribute on Workspace to “Server” (see screenshot below).
- What works: Abilities will automatically sync across peers, and movement is fully compatible with server rollback and resimulation.
- What to expect: You may encounter minor animation glitches or bugs. Full support, including improved rollback fidelity and animation fixes, is actively being worked on.
Known Issues / Limitations
Click to Open
- Custom Registration: There is currently no mechanism to register custom
AbilityDefinitions. This capability is actively being built now. - Input Handling: Our current library APIs for input do not match their final planned forms and will undergo breaking changes.
- Network Ownership: Ownership transfers and handoffs are not yet handled correctly, which may lead to jitter or snapping. This is actively being worked on now.
- Performance Optimization: Rule and activation evaluation do not yet run in parallel, though this is a planned enhancement.
- Ladder Ledge Transitions: Reaching the top of a ladder to step onto a platform (e.g., a diving board) currently lacks a smooth transition. Players often find themselves stuck at the top ledge, unable to climb onto the platform, and must either jump off or retreat back down.
- AutoComplete: Autocomplete is not available for the new library in Studio until it is loaded. We’ll fix this soon, by making the library preload automatically in edit mode if the beta is enabled. For now, you can force the library to load by running require(“@rbx/AvatarAbilities”) in the command bar. You will have to do this every time you reload Studio if you want autocomplete.
- API Documentation: We’re working on getting full API documentation for the library published.
Ability System Appendix : Sensors, Labels, and Rules
Click to Open
The LCC replaces rigid state transitions with a flexible tag-based negotiation system. To work with the LCC, you must understand these four atomic concepts:
| Concept | Definition | Real-World Analogy |
|---|---|---|
| Ability | A discrete behavior of a character (e.g. Running, Swimming, Crouching). |
The action of Running. |
| Sensor | A logic check that returns true/false (e.g. GroundSensor, InputSensor), often relating to the simulated run-time environment around the avatar. |
Feeling the floor with your feet. |
| Label | Active Abilities use Labels to communicate important state information to other Abilities and Rules (e.g., canFallDown, airborne). Multiple Abilities may share the same tag so an Ability can stop multiple other Abilities, for example. |
In a state where I can fall down (canFallDown) |
| Rule | Logic that uses Labels to determine if an Ability can start, stop, or block others. | “Don’t run if you are exhausted.” |
Exclusive Groups (State Machines)
To create mutual exclusivity, use Exclusive Groups. For example, the “Locomotion” group contains Running, Climbing, and Swimming, etc. Because they share a group, the system ensures only one can be active at a time based on priority. For example, FallingDown (Priority 60) will automatically override Running (Priority 20) when the character falls over.
local RunningAbility: AbilityManager.AbilityDefinition = {
Name = "Running",
ExclusiveGroup = { name = "Locomotion", priority = 20 },
...
Labels & Ability Rules
To layer behaviors - such as Running while Crouching, Aiming, and Shooting - we built a tag-based negotiation system rather than relying on rigid if/else chains. The Label system replaces hard-coded state transitions with a flexible, symmetric rule set. Every rule either governs the Ability itself (Requirements) or dictates how it affects Other Abilities (Interactions).
The Four Rules
Self Rules (Requirements)
| Rule | Ability Target | Definition | Real-World Example (key = Ability, Sensor) |
|---|---|---|---|
| RequiresToActivate | Self | When I start, I cannot activate unless these specific Labels or Sensors are present. | Running requires the GroundSensor to be detected. |
| RequiresToContinue | Self | While I run, I must stop immediately if any of these Labels or Sensors are lost. | Sprinting stops if the GroundSensor is lost or the player stops holding the sprint key. |
Logic Type: AND - All listed Labels or Sensors must be satisfied for the above two rules to pass.
Interaction Rules (Others)
| Rule | Ability Target | Definition | Real-World Example (key = Ability, Label) |
|---|---|---|---|
| BlocksWhileActive | Others (Abilities) |
While I run, I prevent other Abilities with these Labels from starting. | While Swimming, the Jump and FallingDown Abilities are blocked from starting. |
| CancelsOnActivation | Others (Abilities) |
When I start, I force any active Abilities with these Labels to stop immediately. | FallingDown cancels any active Ability tagged with bipedLocomotion (e.g. Running) or attached (e.g. Climbing). |
Logic Type: OR - If another active Ability has any of these Labels, it will be blocked or cancelled.
Supported Logic
For more complex behaviors beyond simple lists, you can wrap Labels and Sensors in logic helpers.
All(...): All conditions inside must be true. (e.g.,RequiresToActivate = All("Grounded", "Running")- the character must be Grounded AND Running).Any(...): Only one condition inside needs to be true. (e.g.,RequiresToActivate = Any("Grounded", "Running")- the character must be Grounded OR Running).Not(...): The condition must be false. (e.g.,RequiresToActivate = Not("Grounded")- the character must NOT be Grounded ).
Note on Interaction Logic: While Self Rules (RequiresToActivate/Continue) fully support complex Any/All trees, Interaction Rules (Blocks/Cancels) only support simple lists and Not logic.
