This document is about: QUANTUM 3
SWITCH TO

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.

Simple Brawler - Video 5 - Improved Character Controller

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 IsGrounded method;
  • hit stun with a FrameTimer on PlayerState.

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:

  1. Pick a gravity scale for the PhysicsBody3D from its vertical velocity.
  2. Return early if the stun timer is running.
  3. Return early if the dash attack's activation or duration timer is running.
  4. With movement input, rotate toward the move direction and add a force scaled by Acceleration.
  5. Without movement input, reduce horizontal speed by BrakingSpeed * DeltaTime.
  6. Clamp horizontal speed to MaxSpeed.
  7. Update IsGrounded and 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 FallGravityScale applies;
  • above 1, the character is jumping and GravityScale applies;
  • 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.

  1. Read the XZ velocity and its magnitude.
  2. Return early if the magnitude is zero.
  3. Compute the new magnitude as FPMath.Max(0, magnitude - BrakingSpeed * frame.DeltaTime) so it cannot go below zero.
  4. 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:

  1. Return early if the magnitude is below MaxSpeed.
  2. Otherwise set the horizontal velocity to the normalized velocity times MaxSpeed.
  3. 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:

  1. Check through the Unsafe API whether the hit entity has a PlayerState component.
  2. If it does, retrieve the PlayerConfig from its PlayerState.
  3. 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 PlayerConfig Data Asset and add tooltips for game designers.
  • Store timers such as the stun as FrameTimer fields in components, not in systems.
  • Keep thresholds in systems as static readonly values, because FP cannot be const.

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