Simple Brawler Tutorial Part 5: Improved Character Controller
This page accompanies the Simple Brawler - Video 5 - Improved Character Controller video and explains how to replace the floaty movement from Part 1 with phase-based gravity, acceleration, braking and a horizontal speed clamp in Photon Quantum 3.1, and how to add a short hit stun.
Use this page as a reference for the fifth entry in the Simple Brawler series. It continues from the Part 4 project, so complete Parts 1 to 4 (or use the equivalent project) first. You can download the sample project for this part.
Overview
Part 4 added the dash attack and props that can be shoved off the platform. Part 1 left one open item: the movement feels floaty. Part 5 fixes it and adds a short stun so a hit from a dash attack has a real effect.
The controller moves a PhysicsBody3D with forces and impulses, so props and knockback still interact through the physics engine. All logic runs in the deterministic Quantum simulation with fixed-point (FP) values, so every client computes the same movement from the same inputs. The values below are the ones used in the sample; tune them for your game. A PhysicsBody3D and Quantum's kinematic character controller (KCC) should not be combined on the same character, so pick one approach per character.
The video covers:
- phase-based gravity: a lower scale while rising and a higher one while falling;
- acceleration instead of a raw move force, and a jump impulse that only fires when grounded;
- braking when there is no movement input;
- a horizontal speed clamp;
- skipping normal movement while the dash attack is active;
- moving the ground check into a reusable
IsGroundedmethod; - hit stun with a
FrameTimeronPlayerState.
Prerequisites: completed Parts 1 to 4 of this series (or the equivalent project), Unity 6.3 LTS with URP, and Photon Quantum 3.1.
Video Timeline
| Time | Section |
|---|---|
| 00:00 | Introduction |
| 00:27 | Tightening up the gravity |
| 01:43 | Additional check for stopping the movement of the player |
| 02:01 | Movement, additional fields in Player Config |
| 03:08 | Braking |
| 03:49 | Clamping horizontal speed |
| 04:26 | Re-implementing isGrounded |
| 05:10 | Implementing Stun |
| 06:22 | Testing things out |
The Character Controller Design
Each simulation tick, PlayerMovementSystem runs these steps in order:
- Pick a gravity scale for the
PhysicsBody3Dfrom its vertical velocity. - Return early if the stun timer is running.
- Return early if the dash attack's activation or duration timer is running.
- With movement input, rotate toward the move direction and add a force scaled by
Acceleration. - Without movement input, reduce horizontal speed by
BrakingSpeed * DeltaTime. - Clamp horizontal speed to
MaxSpeed. - Update
IsGroundedand apply the jump impulse if jump was pressed while grounded.
Why the Movement Feels Floaty
Two things cause it. Gravity is the same on the way up and on the way down, so jumps hang in the air. Movement is a plain force with no limit and no braking, so the character keeps sliding after input stops. The sections below address both.
Gravity Settings in PlayerConfig
In PlayerConfig.cs, add a Gravity header with two fields:
C#
[Header("Gravity")]
public FP GravityScale = 12;
public FP FallGravityScale = 15;
| Field | Default | Purpose |
|---|---|---|
GravityScale |
12 | Gravity scale while the character is jumping. |
FallGravityScale |
15 | Gravity scale while the character is falling. |
HandleGravity: Picking a Gravity Scale From Vertical Velocity
In PlayerMovementSystem.cs, keep only the PlayerConfig retrieval at the top of Update, move the input retrieval next to the movement if statement, and call HandleGravity below the PlayerConfig assignment.
The method reads the Y velocity of the PhysicsBody3D:
- below -0.3 (slightly lower than zero), the character is falling and
FallGravityScaleapplies; - above 1, the character is jumping and
GravityScaleapplies; - otherwise, the gravity scale is 1.
C#
private static readonly FP FallVelocityThreshold = FP.FromString("-0.3");
private void HandleGravity(ref Filter filter, PlayerConfig playerConfig)
{
var velocityY = filter.PhysicsBody->Velocity.Y;
if (velocityY < FallVelocityThreshold)
{
filter.PhysicsBody->GravityScale = playerConfig.FallGravityScale;
}
else if (velocityY > 1)
{
filter.PhysicsBody->GravityScale = playerConfig.GravityScale;
}
else
{
filter.PhysicsBody->GravityScale = 1;
}
}
Using a threshold slightly below zero avoids switching phases on tiny velocity changes near the top of the jump.
Skipping Movement During the Dash Attack
Part 4 did not stop normal movement while the dash was running. Add AttackData to the filter and return early from Update while the attack's activation timer or duration timer is running.
C#
if (filter.AttackData->ActivationTimer.IsRunning(frame) ||
filter.AttackData->DurationTimer.IsRunning(frame))
{
return;
}
This keeps forces from the movement code from interfering with the dash impulse.
Acceleration, JumpImpulse, MaxSpeed and BrakingSpeed
In PlayerConfig, remove MoveForce and JumpForce, rename the Physics header to Movement, and add the following fields with tooltips for game designers:
| Field | Default | Purpose |
|---|---|---|
Acceleration |
75 | Replaces MoveForce; scales the force added from move input. |
JumpImpulse |
30 | Replaces JumpForce; linear impulse applied on jump. |
MaxSpeed |
8 | Upper limit for horizontal speed, mainly while dashing. |
BrakingSpeed |
50 | Horizontal speed removed per second when there is no input. |
In PlayerMovementSystem, call FaceMoveDirection and add the force inside the same if statement that checks for a non-zero move direction:
C#
if (moveDirection != FPVector3.Zero)
{
FaceMoveDirection(frame, ref filter, moveDirection, playerConfig);
filter.PhysicsBody->AddForce(moveDirection * playerConfig.Acceleration);
}
else
{
Brake(frame, ref filter, playerConfig);
}
Braking When There Is No Input
Brake slows the character on the XZ plane and leaves the Y velocity untouched.
- Read the XZ velocity and its magnitude.
- Return early if the magnitude is zero.
- Compute the new magnitude as
FPMath.Max(0, magnitude - BrakingSpeed * frame.DeltaTime)so it cannot go below zero. - Rescale the normalized direction to the new magnitude and write it back, keeping the Y velocity.
C#
private void Brake(Frame frame, ref Filter filter, PlayerConfig playerConfig)
{
var velocity = filter.PhysicsBody->Velocity.XZ;
var magnitude = velocity.Magnitude;
if (magnitude <= 0)
{
return;
}
var newMagnitude = FPMath.Max(0, magnitude - playerConfig.BrakingSpeed * frame.DeltaTime);
velocity = velocity.Normalized * newMagnitude;
filter.PhysicsBody->Velocity = new FPVector3(velocity.X, filter.PhysicsBody->Velocity.Y, velocity.Y);
}
Clamping Horizontal Speed
After the if/else in Update, call ClampHorizontalSpeed so the character cannot build up excessive speed, for example during a dash. It reads the same XZ velocity and magnitude as Brake:
- Return early if the magnitude is below
MaxSpeed. - Otherwise set the horizontal velocity to the normalized velocity times
MaxSpeed. - Write it back to the Y-preserving velocity as in
Brake.
C#
private void ClampHorizontalSpeed(ref Filter filter, PlayerConfig playerConfig)
{
var velocity = filter.PhysicsBody->Velocity.XZ;
var magnitude = velocity.Magnitude;
if (magnitude < playerConfig.MaxSpeed)
{
return;
}
var clamped = velocity.Normalized * playerConfig.MaxSpeed;
filter.PhysicsBody->Velocity = new FPVector3(clamped.X, filter.PhysicsBody->Velocity.Y, clamped.Y);
}
IsGrounded Method & Jump Impulse
The ground check and jump were removed in the refactor, so re-add them. Move the Part 3 raycast into an IsGrounded method that takes the frame, filter and PlayerConfig, and returns hit.HasValue:
C#
private bool IsGrounded(Frame frame, ref Filter filter, PlayerConfig playerConfig)
{
var hit = frame.Physics3D.Raycast(
filter.Transform->Position,
FPVector3.Down,
playerConfig.GroundCheckingDistance,
-1,
QueryOptions.HitStatics | QueryOptions.HitDynamics);
return hit.HasValue;
}
Set PlayerState.IsGrounded from it, then re-add the jump check below:
C#
filter.PlayerState->IsGrounded = IsGrounded(frame, ref filter, playerConfig);
if (input->Jump.WasPressed && filter.PlayerState->IsGrounded)
{
filter.PhysicsBody->AddLinearImpulse(new FPVector3(FP._0, playerConfig.JumpImpulse, FP._0));
}
Testing the New Controller
Run the game. Jumps are shorter and snappier, the character stops quickly when input is released, and dashing no longer builds up extra speed.
Hit Stun: StunSeconds and StunTimer
Most games stun a character briefly when it is hit. In PlayerConfig, add a Knockback header and a tooltip-documented field:
C#
[Header("Knockback")]
[Tooltip("Seconds the player cannot control the character after being hit.")]
public FP StunSeconds = FP.FromString("0.33");
| Field | Default | Purpose |
|---|---|---|
StunSeconds |
0.33 | Duration of the stun after a hit. |
In Player.qtn, add a FrameTimer to the PlayerState component:
component PlayerState
{
asset_ref<PlayerConfig> PlayerConfig;
bool IsGrounded;
FrameTimer StunTimer;
}
In PlayerMovementSystem, return early right after the gravity handling while the timer runs:
C#
if (filter.PlayerState->StunTimer.IsRunning(frame))
{
return;
}
Gravity still runs during the stun, so a stunned character keeps falling.
Starting the Stun From the AttackSystem
In the AttackSystem, in the overlap handling, below the line that adds the linear impulse to the hit entity:
- Check through the Unsafe API whether the hit entity has a
PlayerStatecomponent. - If it does, retrieve the
PlayerConfigfrom itsPlayerState. - Start the stun timer.
C#
if (frame.Unsafe.TryGetPointer<PlayerState>(hitEntity, out var playerState))
{
var hitPlayerConfig = frame.FindAsset(playerState->PlayerConfig);
playerState->StunTimer = FrameTimer.FromSeconds(frame, hitPlayerConfig.StunSeconds);
}
The timer lives in the simulation state, so the stun is deterministic and identical on every client.
Testing Hit Stun With Two Players
Start two players in a multiplayer session. When one player hits the other with the dash attack, the hit player cannot control the character for 0.33 seconds.
What's Next
The final part tracks game state, adds a life/death cycle, and puts a new prop in the middle of the map to finish the sample.
Key Concepts
| Concept | Description |
|---|---|
| Phase-based gravity | A different gravity scale for rising, falling and neutral vertical velocity. |
GravityScale |
PhysicsBody3D property that scales gravity for that body. |
Acceleration |
PlayerConfig value that scales the force added from movement input. |
JumpImpulse |
Linear impulse applied once when jump is pressed while grounded. |
MaxSpeed |
Horizontal speed limit enforced by ClampHorizontalSpeed. |
BrakingSpeed |
Horizontal speed removed per second when there is no input. |
FrameTimer |
Deterministic timer stored in simulation state and checked with IsRunning(frame). |
StunTimer |
FrameTimer on PlayerState that blocks movement while it runs. |
PhysicsBody3D vs. KCC |
Forces and impulses interact with props and knockback; Quantum advises against combining both on one character. |
Best Practices
Use this checklist when tuning a physics-based character controller in a Quantum project:
- Use a higher gravity scale while falling than while rising.
- Put a small negative threshold on the falling check to avoid flicker near the jump apex.
- Add force from acceleration instead of setting velocity directly, so physics interactions still work.
- Brake explicitly when there is no input, and keep the Y velocity untouched.
- Clamp horizontal speed after movement and braking.
- Skip normal movement while an attack that sets its own velocity is active.
- Gate the jump on
IsGrounded. - Keep tunable values in the
PlayerConfigData Asset and add tooltips for game designers. - Store timers such as the stun as
FrameTimerfields in components, not in systems. - Keep thresholds in systems as
static readonlyvalues, becauseFPcannot beconst.
Common Pitfalls
| Pitfall | Why It Is a Problem |
|---|---|
| Using one gravity scale for rising and falling | Jumps feel floaty because the character hangs in the air. |
| No braking when input stops | The character keeps sliding. |
| Writing the braked velocity without the original Y value | Vertical velocity is lost and jumps and falls break. |
| Skipping the horizontal clamp | Dash impulses and repeated forces can build up excessive speed. |
| Running normal movement during the dash attack | Movement forces interfere with the dash. |
| Forgetting to re-add the grounded jump check after the refactor | The character cannot jump, or can jump in the air. |
| Starting the stun timer without checking it in the movement system | The stun has no effect. |
Combining a PhysicsBody3D and a KCC on one character |
The Quantum docs advise against it; pick one per character. |
Summary
Part 5 replaces the Part 1 movement with a tighter controller. Gravity changes by phase, acceleration replaces the raw move force, braking removes horizontal speed when there is no input, and a clamp limits horizontal speed to MaxSpeed. The ground check lives in IsGrounded, and all tunable values sit in the PlayerConfig Data Asset.
The controller still moves a PhysicsBody3D with forces and impulses, so props and knockback behave as before. Because gravity scale, braking and clamping all use FP values and run in the simulation, every client computes the same result from the same inputs.
A StunTimer on PlayerState, started by the AttackSystem and checked by PlayerMovementSystem, adds hit stun. The timer is part of the simulation state, so the stun is identical on every client. The next part tracks game state, adds a life/death cycle, and adds a new prop in the middle of the map.
Last updated on
Back to top- Overview
- Video Timeline
- The Character Controller Design
- Why the Movement Feels Floaty
- Gravity Settings in PlayerConfig
- HandleGravity: Picking a Gravity Scale From Vertical Velocity
- Skipping Movement During the Dash Attack
- Acceleration, JumpImpulse, MaxSpeed and BrakingSpeed
- Braking When There Is No Input
- Clamping Horizontal Speed
- IsGrounded Method & Jump Impulse
- Testing the New Controller
- Hit Stun: StunSeconds and StunTimer
- Starting the Stun From the AttackSystem
- Testing Hit Stun With Two Players
- What's Next
- Key Concepts
- Best Practices
- Common Pitfalls
- Summary