CharacterController
Configures character movement, collision, input, and simulation.
- Creatable
Instance.new("CharacterController")- Inherits
- Instance
- Replication
- Standard
Behavior
CharacterController configures character movement, collision, input, and simulation.
Summary
The acceleration applied to particles, in studs per second squared.
The acceleration used while the character is airborne.
The number of additional jumps permitted while airborne.
Whether the controller automatically requests jumps when appropriate.
Whether the controller turns the character toward its movement direction.
The distance used to detect climbable geometry.
The character's climbing speed, in studs per second.
The collision-box configuration used by the character.
The interval after leaving the ground during which a jump remains permitted, in seconds.
The rate at which the controller reduces movement speed without directional input.
Whether this character controller is enabled.
The maximum distance over which the controller snaps to supporting ground, in studs.
Multiplier applied to the gravity acceleration affecting this body.
Whether the controller currently detects supporting ground.
The vertical offset used to position the character above its supporting surface, in studs.
The dimensions of the character's collision body, in studs.
Whether the controller has a pending jump request.
How long an early jump request remains valid, in seconds.
The requested jump height, in studs.
The steepest ground angle treated as walkable, in degrees.
The controller's requested movement direction.
The active movement simulation mode.
The response strength used to approach the actuator's target.
The BasePart used as the character's movement root, or nil when unavailable.
A ModuleScript returning Step(state, input, dt) or a function with that signature.
State: Enum.HumanoidStateType = Enum.HumanoidStateType.Freefallparallel readread onlydoes not replicateThe current character motion state.
The maximum ground step the controller can traverse, in studs.
The acceleration used while swimming.
The immersion depth used for swimming behavior.
The character's swimming speed, in studs per second.
The speed at which the controller changes facing direction.
The world-space up direction used by the controller.
The current character velocity, in studs per second.
The character's walking speed, in studs per second.
Adds an instantaneous velocity change to the character controller.
Applies a named set of movement-controller settings.
Authorizes a server-controlled movement change.
Returns this instance if it is an ExecutionGroup.
Returns the named controller input value, or nil when unset.
Returns the names of the available controller presets.
Returns the named custom simulation-state value, or nil when unset.
Sets the requested movement direction.
Sets the named controller input value.
Sets a named custom simulation-state value.
Moves the controller to the supplied world-space CFrame.
Fires when the controller receives a movement correction.
Fires when the character motion state changes.
Properties
Acceleration
CharacterController.Acceleration: number = 500The acceleration applied to particles, in studs per second squared.
AirAcceleration
CharacterController.AirAcceleration: number = 143The acceleration used while the character is airborne.
AirJumps
CharacterController.AirJumps: number = 0The number of additional jumps permitted while airborne.
AutoJump
CharacterController.AutoJump: boolean = trueWhether the controller automatically requests jumps when appropriate.
AutoRotate
CharacterController.AutoRotate: boolean = trueWhether the controller turns the character toward its movement direction.
ClimbReach
CharacterController.ClimbReach: number = 0.75The distance used to detect climbable geometry.
ClimbSpeed
CharacterController.ClimbSpeed: number = 0.7The character's climbing speed, in studs per second.
CollisionType
CharacterController.CollisionType: Enum.HumanoidCollisionType = Enum.HumanoidCollisionType.OuterBoxThe collision-box configuration used by the character.
CoyoteTime
CharacterController.CoyoteTime: number = 0.125The interval after leaving the ground during which a jump remains permitted, in seconds.
Deceleration
CharacterController.Deceleration: number = 500The rate at which the controller reduces movement speed without directional input.
Enabled
CharacterController.Enabled: boolean = trueWhether this character controller is enabled.
FloorSnapDistance
CharacterController.FloorSnapDistance: number = 1.5The maximum distance over which the controller snaps to supporting ground, in studs.
GravityScale
CharacterController.GravityScale: number = 1Multiplier applied to the gravity acceleration affecting this body.
Grounded
CharacterController.Grounded: boolean = falseWhether the controller currently detects supporting ground.
HipHeight
CharacterController.HipHeight: number = 0The vertical offset used to position the character above its supporting surface, in studs.
HitboxSize
CharacterController.HitboxSize: Vector3 = Vector3.new(2, 5, 1)The dimensions of the character's collision body, in studs.
Jump
CharacterController.Jump: boolean = falseWhether the controller has a pending jump request.
JumpBufferTime
CharacterController.JumpBufferTime: number = 0How long an early jump request remains valid, in seconds.
JumpHeight
CharacterController.JumpHeight: number = 7.2The requested jump height, in studs.
MaxSlopeAngle
CharacterController.MaxSlopeAngle: number = 89The steepest ground angle treated as walkable, in degrees.
MoveDirection
CharacterController.MoveDirection: Vector3 = Vector3.new(0, 0, 0)The controller's requested movement direction.
MovementMode
CharacterController.MovementMode: Enum.MovementMode = Enum.MovementMode.WalkingThe active movement simulation mode.
Responsiveness
CharacterController.Responsiveness: number = 150The response strength used to approach the actuator's target.
RootPart
CharacterController.RootPart: BasePart? = nilThe BasePart used as the character's movement root, or nil when unavailable.
SimulationModule
CharacterController.SimulationModule: ModuleScript? = nilA ModuleScript returning Step(state, input, dt) or a function with that signature. The engine runs it after the movement motor on the owner, during prediction replay, and on the server. State includes Position, Velocity, Yaw, Up, Grounded, State, Replaying, and Custom. Input includes Direction, CameraRelative, CameraYaw, Jump, AutoJump, and Custom. dt is in seconds. Avoid unrelated side effects because replay can evaluate the same input again.
State
CharacterController.State: Enum.HumanoidStateType = Enum.HumanoidStateType.FreefallThe current character motion state.
StepHeight
CharacterController.StepHeight: number = 2.45The maximum ground step the controller can traverse, in studs.
SwimAcceleration
CharacterController.SwimAcceleration: number = 100The acceleration used while swimming.
SwimDepth
CharacterController.SwimDepth: number = 1The immersion depth used for swimming behavior.
SwimSpeed
CharacterController.SwimSpeed: number = 1The character's swimming speed, in studs per second.
TurnSpeed
CharacterController.TurnSpeed: number = 8The speed at which the controller changes facing direction.
UpDirection
CharacterController.UpDirection: Vector3 = Vector3.new(0, 0, 0)The world-space up direction used by the controller.
Velocity
CharacterController.Velocity: Vector3 = Vector3.new(0, 0, 0)The current character velocity, in studs per second.
WalkSpeed
CharacterController.WalkSpeed: number = 16The character's walking speed, in studs per second.
Methods
AddImpulse
CharacterController:AddImpulse(velocity: Vector3): ()Adds an instantaneous velocity change to the character controller.
ApplyPreset
CharacterController:ApplyPreset(name: string): ()Applies a named set of movement-controller settings.
AuthorizeMovement
CharacterController:AuthorizeMovement(options: MovementGrantOptions): booleanAuthorizes a server-controlled movement change. Options are Duration in seconds, optional MaxSpeed defaulting to walk speed, and Flight defaulting to false. Unknown options cause an error. Returns false when no associated character player exists. See MovementGrantOptions.
GetExecutionGroup
CharacterController:GetExecutionGroup(): ExecutionGroup?Returns this instance if it is an ExecutionGroup. Otherwise returns the nearest ancestor ExecutionGroup, or nil when no group contains the instance.
GetInput
CharacterController:GetInput(name: string): ControllerValue?Returns the named controller input value, or nil when unset.
GetPresets
CharacterController:GetPresets(): { string }Returns the names of the available controller presets.
GetState
CharacterController:GetState(name: string): ControllerValue?Returns the named custom simulation-state value, or nil when unset.
Move
CharacterController:Move(direction: Vector3, relativeToCamera: boolean?): ()Sets the requested movement direction. Set relativeToCamera to interpret the direction relative to the camera.
SetInput
CharacterController:SetInput(name: string, value: ControllerValue?): ()Sets the named controller input value. Passing nil removes it.
SetState
CharacterController:SetState(name: string, value: ControllerValue?): ()Sets a named custom simulation-state value. Pass nil to remove it.
Teleport
CharacterController:Teleport(cframe: CFrame): ()Moves the controller to the supplied world-space CFrame.
Events
Corrected
CharacterController.Corrected: RBXScriptSignalFires when the controller receives a movement correction.
StateChanged
CharacterController.StateChanged: RBXScriptSignalFires when the character motion state changes.
Inherited members
- Properties
- ArchivableClassNameNameParent
- Methods
- AddComponent()AddTag()ClearAllChildren()ClearTags()Clone()Destroy()FindFirstAncestor()FindFirstAncestorOfClass()FindFirstAncestorWhichIsA()FindFirstChild()FindFirstChildOfClass()FindFirstChildWhichIsA()FindFirstDescendant()GetAttribute()GetAttributeChangedSignal()GetAttributes()GetChildren()GetComponent()GetComponentChangedSignal()GetComponents()GetDebugId()GetDescendants()GetFullName()GetPropertyChangedSignal()GetReferencing()GetTags()HasComponent()HasTag()IsA()IsAncestorOf()IsDescendantOf()RemoveComponent()RemoveTag()SetAttribute()WaitForChild()
- Events
- AncestryChangedAttributeChangedChangedChildAddedChildRemovedDescendantAddedDescendantRemovingDestroying