Movement
Move step
Following equation is used to calculate desired position delta for single move step:
Step Position Delta = (Dynamic Velocity + Kinematic Velocity) * Delta Time + External Delta
Dynamic Velocity
- Velocity that accumulates external forces
- Gravity, impulse from explosion, force field, jump pad
- Can push the KCC upwards on slopes
- Related API when using default
EnvironmentProcessor
:KCCData.DynamicVelocity
KCC.SetDynamicVelocity()
KCC.AddExternalForce()
KCC.AddExternalImpulse()
KCC.Jump()
Kinematic Velocity
- Unconstrained velocity calculated from user input actions
- Usually based on
KCCData.InputDirection
(entry point) - Only walkable surfaces push the KCC upwards to prevent artifacts on steep slopes (controlled by
KCCData.MaxGroundAngle
) - Related API when using default
EnvironmentProcessor
:KCCData.KinematicVelocity
KCC.SetInputDirection()
KCC.SetKinematicDirection()
KCC.SetKinematicSpeed()
KCC.SetKinematicVelocity()
External Delta
- Absolute position offset
- Useful for corrections on the end of move step (after depenetration)
- Related API:
KCCData.ExternalDelta
KCC.SetExternalDelta()
Movement algorithm
The KCC virtual capsule always moves by calculated position delta and then depenetrates from overlapping colliders.
- ✅ This approach gives natural sliding against geometry.
- ✅ Most of the time single capsule overlap is needed which makes KCC very performant.
- ❌ Sometimes it results in jitter when moving against multiple colliders (usually some corners), but this can be usually resolved by running more depenetration steps.
Continuous Collision Detection (CCD)
If the character moves too fast (position delta for single step is bigger than 75% or radius), the movement is divided into sub-steps to not pass through geometry.
- Movement is divided to smaller steps based on desired velocity.
- The maximum distance traveled in single step is 25-75% of radius and is controlled by
CCD Radius Multiplier
property inKCC Settings
asset. - 75% is good in most cases, lower this value only if you have problems with KCC running through geometry.
- Before lowering
CCD Radius Multiplier
try to increaseMax Penetration Steps
(improves quality of depenetration) inKCC Settings
asset.
![continuous collision detection](/docs/img/quantum/v3/addons/kcc/ccd-feature.jpg)
Collision filtering
- Primary filter is collision layer mask - controlled by
Collision Layer Mask
property inKCC Settings
asset. The Layer Collision Matrix from Physics Settings is not used by KCC. - It is possible to explicitly ignore a static collider or an entity with
KCC.SetIgnoreCollider()
. - Use
KCCContext.PrepareUserContext()
to setResolveCollision
delegate for application of additional filtering rules.