---
title: "Controllers"
url: /docs/en-us/characters/character-controller-library/controllers
last_updated: 2026-06-19T03:26:14Z
description: "Controllers in the Character Controller Library (CCL) handle the physical simulation of the character and its interaction with the environment."
---

# Controllers

In the [Character Controller Library](/docs/en-us/characters/character-controller-library.md) (CCL), a core `Class.ControllerManager` instance handles the physical simulation of the character and its interaction with the environment. This includes several intentional changes in movement/feel designed to resolve legacy `Class.Humanoid` inconsistencies, as well as physical improvements like ground friction, linear acceleration curves, and realistic conservation of linear and angular momentum when jumping.

## Enable CCL

The CCL is **opt-in** through Studio's [Avatar Settings](/docs/en-us/studio/avatar-settings.md) window. To enable it:

1. From the **Avatar** tab, open [Avatar Settings](/docs/en-us/studio/avatar-settings.md).![Avatar Settings indicated in Studio's toolbar](../../assets/studio/general/Toolbar-Avatar-Settings.png)
2. Select the **Movement** tab on the left side of the window and, in the **Abilities** section, select **Character Controller Library**.![Character Controller Library toggle in the Avatar Settings window](../../assets/studio/general/Avatar-Settings-CCL.png)
3. All of the standard abilities like **Running**, **Jumping**, and **Climbing** are enabled by default. To disable any of them at runtime, uncheck the associated box.
  > **Warning:** It's not recommended to disable **Running**, as doing so will prevent characters from moving along the ground. Additionally, you should always keep **Getting Up** enabled if **Falling Down** is enabled, as a mismatch will allow characters to fall down (trip) but never get back up.

## Structure

Under the core `Class.ControllerManager` instance within the character model, individual controllers such as a `Class.GroundController` and `Class.AirController` define how movement is applied to the character. Abilities then interact with the `Class.ControllerManager` and its descendants to modify controller behaviors or switch between controllers.

## Configuration

While your game is running (or through a script that runs from `Class.ServerScriptService`), you can experiment with the core `Class.ControllerManager` and built‑in controllers.

### Runtime

To experiment with controller configurations at runtime:

1. Begin a playtest.
2. In the [Explorer](/docs/en-us/studio/explorer.md), locate the character model in the `Class.Workspace` and then expand the `Class.ControllerManager` tree:
3. Select either the `Class.ControllerManager` or one of its controller descendants and, in the [Properties](/docs/en-us/studio/properties.md) window, customize properties such as those summarized in the tables below (note that these tables are not exhaustive; please consult the API [classes documentation](/docs/en-us/reference/engine/classes.md) for additional property options). #### ControllerManager | Property | Description |
| --- | --- | | `Class.ControllerManager.BaseMoveSpeed\|BaseMoveSpeed` | The **base** linear movement speed used by all controllers. Controllers individually customize movement speed through their `MoveSpeedFactor` property. | | `Class.ControllerManager.BaseTurnSpeed\|BaseTurnSpeed` | The **base** angular turning speed used by all controllers to align the character to face the desired direction. Some controllers individually customize turn speed through their `TurnSpeedFactor` property. | | `Class.ControllerManager.UpDirection\|UpDirection` | `Datatype.Vector3` which indicates the upward-facing vector for the `Class.ControllerManager.RootPart`. | #### Individual Controllers | Controller | Properties |
| --- | --- | | `Class.GroundController` | <ul><li>`Class.GroundController.MoveSpeedFactor\|MoveSpeedFactor` — Multiplier factor for the `Class.ControllerManager.BaseMoveSpeed` property while character is on the ground.</li><li>`Class.GroundController.AccelerationTime\|AccelerationTime` and `Class.GroundController.DecelerationTime\|DecelerationTime` — Time in seconds for character to accelerate to full speed and decelerate to full stop, respectively.</li><li>`Class.GroundController.TurnSpeedFactor\|TurnSpeedFactor` — Multiplier factor for the `Class.ControllerManager.BaseTurnSpeed` property (max angular velocity of a turn while character is on the ground).</li></ul> | | `Class.AirController` | <ul><li>`Class.AirController.MoveSpeedFactor\|MoveSpeedFactor` — Multiplier factor for the `Class.ControllerManager.BaseMoveSpeed` property while character is in the air.</li><li>`Class.AirController.MoveMaxForce\|MoveMaxForce` and `Class.AirController.TurnMaxTorque\|TurnMaxTorque` — How quickly the character can accelerate and change direction in the air.</li><li>`Class.AirController.TurnSpeedFactor\|TurnSpeedFactor` — Multiplier factor for the `Class.ControllerManager.BaseTurnSpeed` property (max angular velocity of a turn while character is in the air).</li></ul> | | `Class.ClimbController` | <ul><li>`Class.ClimbController.MoveSpeedFactor\|MoveSpeedFactor` — Multiplier factor for the `Class.ControllerManager.BaseMoveSpeed` property while character is climbing.</li></ul> | | `Class.SwimController` | <ul><li>`Class.SwimController.MoveSpeedFactor\|MoveSpeedFactor` — Multiplier factor for the `Class.ControllerManager.BaseMoveSpeed` property while character is swimming.</li><li>`Class.SwimController.PitchMaxTorque\|PitchMaxTorque` — The maximum torque used to rotate on the local **X** axis to the desired pitch orientation.</li><li>`Class.SwimController.RollMaxTorque\|RollMaxTorque` — The maximum torque applied to rotate on the local **Z** axis to the desired roll orientation.</li></ul> |

### Scripted

To set controller configurations for all characters through a script:

1. Create a new server-side `Class.Script` within `Class.ServerScriptService` and rename it to `ControllerScript`.
2. Copy and paste the following code into the new script. This example increases ground‑based moving/turning speed as well adds a slight acceleration and deceleration time. Feel free to adjust other properties such as those described in the [tables above](#configuration) or for each class as documented (`Class.ControllerManager`; `Class.GroundController`; `Class.AirController`; `Class.ClimbController`; `Class.SwimController`).```lua
local Players = game:GetService("Players")

local function onCharacterAdded(character)
	local ControllerManager = character:FindFirstChildWhichIsA("ControllerManager")

	if ControllerManager then
		local GroundController = ControllerManager:FindFirstChild("GroundController")
		if GroundController then
			-- Double the move and turn speeds
			GroundController.MoveSpeedFactor *= 2
			GroundController.TurnSpeedFactor *= 2
			-- Add slight acceleration and deceleration
			GroundController.AccelerationTime = 0.2
			GroundController.DecelerationTime = 0.4
		end
	end
end

local function onPlayerAdded(player)
	if player.Character then
		onCharacterAdded(player.Character)
	end
	player.CharacterAdded:Connect(onCharacterAdded)
end

Players.PlayerAdded:Connect(onPlayerAdded)
```