Simple KCC

Overview

The Simple KCC is a user-friendly and intuitive 3D character controller addon. It is designed to bring simplicity and ease-to-use characters to your game projects using Fusion.

Creating a smooth and responsive character controller is a critical aspect of any game project. Traditional character controller solutions can be complex and challenging to integrate, especially for developers seeking a streamlined and efficient workflow. This is where Simple KCC shines — by offering a simplified yet powerful solution for character movement.

Features

• Easy integration and configuration.
• Control over position and look rotation (pitch + yaw).
• Capsule based physics query and depenetration.
• Velocity based movement.
• Support for Gravity.
• Support for Jump.
• Basic ground detection.
• Continuous collision detection (CCD) out of the box.
• Separate game object for collider (created at runtime as child game object).
• Support for ignoring child colliders.
• Step detection and ground snapping.
• Platform independent, mobile friendly.
• Network & performance optimized.
• Pooling compatible.
• Fully commented sample with testing playground.

Download - Sample

Download - Addon

Requirements

• Unity 2021.3 or newer (Addon)
• Unity 6000.3 or newer (Sample)
• Fusion AppId: To run the sample, first create a Fusion AppId in the PhotonEngine Dashboard and paste it into the App Id Fusion field in Real Time Settings (reachable from the Fusion menu in Unity editor). Continue with instructions in First Steps section.

Sample Controls

• Use W, S, A, D for movement, SPACE for jumping, and Mouse to look.
• Lock or release your cursor inside the Unity Editor using the ENTER key.

Open Assets/Scenes/Playground and play. The scene can be used for evaluation (how the character and its parameters behave) or to prototype movement for your game.

First Steps

The best way to start with Simple KCC is downloading sample project which is pre-configured and ready to be tested with multiple players.

In the following step-by-step guide, we'll walk you through the process of integrating Simple KCC addon into your game project from scratch.

1. Import Simple KCC addon package into your Fusion project.

2. Create a player prefab.

3. Add NetworkObject and SimpleKCC components to the root game object. Enable Is Kinematic option on RigidBody component.

4. Configure parameters (radius, height, collision mask, ...). More details in Configuration section.
5. Link the player prefab to your spawn manager.

6. Move with the character from code. More details in Movement section.

Configuration

The Simple KCC component inspector provides a set of options to fine-tune behavior.

The parameters are:

• Shape - Defines character physics behavior.
  • None - Skips internal physics query, collider is despawned.
  • Capsule - Full physics processing, Capsule collider spawned.
• Is Trigger - The collider is non-blocking if enabled.
• Radius - Collider radius.
• Height - Collider height.
• Extent - Defines additional radius extent for ground detection and other features. Recommended range is 10-20% of radius.
• Collider Layer - Layer of collider game object.
• Collision Layer Mask - Layer mask the character collides with.
• Proxy Interpolation Mode - Defines interpolation behavior of proxies.
  • Full - Interpolates all networked properties, synchronizes Transform and Rigidbody.
  • Transform - Interpolates only position and rotation. Use with caution!
• Max Penetration Steps - Penetration in single move step is corrected in multiple steps which results in higher overall depenetration quality.
• CCD Radius Multiplier - Controls maximum distance the character moves in a single CCD step. Valid range is 10% - 90% of the radius. Use lower values if the character passes through geometry. CCD Max Step Distance = Radius * CCD Radius Multiplier.
• Anti Jitter Distance - Defines position distance tolerance to smooth out jitter. Higher values may introduce noticeable delay when switching move direction.
  • X - Horizontal axis.
  • Y - Vertical axis.
• Compress Network Position - Reduces network traffic by synchronizing compressed position at the cost of precision.
• Force Predicted Look Rotation - Skips look rotation interpolation in render for local character, allowing mouse look updates at render rate.
• Step Height - Maximum obstacle height to step on it.
• Step Depth - Maximum depth of the step check.
• Step Speed - Multiplier of unapplied movement projected to step up. This helps traversing obstacles faster.
• Step Min Push Back - Minimum proportional penetration push-back distance to activate step-up.
• Step Ground Check Radius Scale - Radius multiplier used for last sphere-cast (ground surface detection).
• Step Require Ground Target - Step-up starts only if the target surface is walkable (angle <= MaxGroundAngle).
• Snap Distance - Maximum ground check distance for snapping.
• Snap Speed - Ground snapping speed per second.

Movement

1. Initialize KCC properties.

C#

public override void Spawned()
{
    // Set custom gravity acceleration (negative values point down).
    _simpleKCC.SetGravity(-25.0f);
}

2. Movement and look of the character.

C#

public override void FixedUpdateNetwork()
{
    if (Runner.TryGetInputForPlayer(Object.InputAuthority, out GameplayInput input) == true)
    {
        // Apply look rotation delta. This propagates to Transform component immediately.
        _simpleKCC.AddLookRotation(input.LookRotationDelta);

        // Set default world space velocity and jump impulse.
        Vector3 moveVelocity = _simpleKCC.TransformRotation * new Vector3(input.MoveDirection.x, 0.0f, input.MoveDirection.y) * 10.0f;
        float   jumpImpulse  = default;

        if (input.Jump == true && _simpleKCC.IsGrounded == true)
        {
            // Set upward jump impulse.
            jumpImpulse = 10.0f;
        }

        _simpleKCC.Move(moveVelocity, jumpImpulse);
    }
}

3. Camera synchronization.

C#

public void LateUpdate()
{
    // Only InputAuthority needs to update camera.
    if (Object == null || Object.HasInputAuthority == false)
        return;

    // Update camera pivot and transfer properties from camera handle to Main Camera.
    // LateUpdate() is called after all Render() calls - the character is already interpolated.

    Vector2 pitchRotation = _simpleKCC.GetLookRotation(true, false);
    _cameraPivot.localRotation = Quaternion.Euler(pitchRotation);

    Camera.main.transform.SetPositionAndRotation(_cameraHandle.position, _cameraHandle.rotation);
}

API Overview

Properties

• bool IsActive - Controls execution of the KCC.

• Transform Transform - Reference to cached Transform component.

• Rigidbody Rigidbody - Reference to attached Rigidbody component.

• CapsuleCollider Collider - Reference to KCC collider. Can be null if Shape is set to EKCCShape.None.

• KCCSettings Settings - Basic KCC settings.

• Vector3 Position - Calculated position which is propagated to Transform.

• Quaternion LookRotation - Combination of look Pitch and Yaw.

• Vector3 LookDirection - Look direction based on look rotation.

• Quaternion TransformRotation - Transform rotation based on Yaw look rotation.

• Vector3 TransformDirection - Transform direction based on transform rotation.

• float RealSpeed - Speed calculated from real position change.

• Vector3 RealVelocity - Velocity calculated from real position change.

• bool HasJumped - Flag that indicates KCC has jumped in current tick.

• bool HasTeleported - Flag that indicates KCC has teleported in current tick.

• bool IsGrounded - Flag that indicates KCC is touching a collider with normal angle lower than MaxGroundAngle.

• Vector3 GroundNormal - Combined normal of all touching colliders. Normals less distant from up direction have bigger impact on final normal.

• bool IsSteppingUp - Flag that indicates KCC is stepping up in current tick.

• bool WasSteppingUp - Flag that indicates KCC was stepping up in previous tick.

• bool IsSnappingToGround - Flag that indicates KCC lost grounded state and is snapping to ground in current tick.

• bool WasSnappingToGround - Flag that indicates KCC was snapping to ground in previous tick.

• bool IsPredictingLookRotation - Flag that indicates look rotation prediction is enabled for current fixed/render update.

• Func<KCC, Collider, bool> ResolveCollision - Custom collision resolver callback. Use this to apply extra filtering.

Methods

• void SetActive(bool isActive) - Controls execution of the KCC.

• void SetPosition(Vector3 position, bool teleport = true, bool allowAntiJitter = false) - Set position of the KCC and immediately synchronize Transform.

• void SetGravity(float gravity) - Set gravity acceleration along up axis (negative values point down).

• void SetHeight(float height) - Update Height in Settings and immediately synchronize with Collider.

• void SetRadius(float radius) - Update Radius in Settings and immediately synchronize with Collider.

• void SetShape(EKCCShape shape, float radius = 0.0f, float height = 0.0f) - Update Shape, Radius (optional), Height (optional) in Settings and immediately synchronize with Collider.

• void SetTrigger(bool isTrigger) - Update Is Trigger flag in Settings and immediately synchronize with Collider.

• void SetColliderLayer(int layer) - Update Collider Layer in Settings and immediately synchronize with Collider.

• void SetCollisionLayerMask(LayerMask layerMask) - Update Collision Layer Mask in Settings.

• void SetMaxGroundAngle(float maxGroundAngle) - Set maximum walkable ground angle (in degrees).

• void RefreshChildColliders() - Refresh child colliders list, used for collision filtering. Child colliders are ignored completely, triggers are treated as valid collision.

• void InvokeOnSpawn(Action<KCC> callback) - Invoke the callback when the KCC is spawned (immediately if already spawned).

• Vector2 GetLookRotation(bool pitch = true, bool yaw = true) - Returns current look rotation.

• void SetLookRotation(float pitch, float yaw) - Set pitch and yaw look rotation. Values are clamped to <-90, 90> (pitch) and <-180, 180> (yaw).

• void SetLookRotation(float pitch, float yaw, float minPitch, float maxPitch) - Set pitch and yaw look rotation. Values are clamped to <minPitch, maxPitch> (pitch) and <-180, 180> (yaw).

• void SetLookRotation(Vector2 lookRotation) - Set pitch and yaw look rotation. Values are clamped to <-90, 90> (pitch) and <-180, 180> (yaw).

• void SetLookRotation(Vector2 lookRotation, float minPitch, float maxPitch) - Set pitch and yaw look rotation. Values are clamped to <minPitch, maxPitch> (pitch) and <-180, 180> (yaw).

• void SetLookRotation(Quaternion lookRotation, bool preservePitch = false, bool preserveYaw = false) - Set pitch and yaw look rotation. Roll is ignored (not supported). Values are clamped to <-90, 90> (pitch) and <-180, 180> (yaw).

• void AddLookRotation(float pitchDelta, float yawDelta) - Add pitch and yaw look rotation. Resulting values are clamped to <-90, 90> (pitch) and <-180, 180> (yaw).

• void AddLookRotation(float pitchDelta, float yawDelta, float minPitch, float maxPitch) - Add pitch and yaw look rotation. Resulting values are clamped to <minPitch, maxPitch> (pitch) and <-180, 180> (yaw).

• void AddLookRotation(Vector2 lookRotationDelta) - Add pitch (x) and yaw (y) look rotation. Resulting values are clamped to <-90, 90> (pitch) and <-180, 180> (yaw).

• void AddLookRotation(Vector2 lookRotationDelta, float minPitch, float maxPitch) - Add pitch (x) and yaw (y) look rotation. Resulting values are clamped to <minPitch, maxPitch> (pitch) and <-180, 180> (yaw).

• void Move(Vector3 kinematicVelocity = default, float jumpImpulse = default) - Move function. The KCC can move with zero velocity - depenetration from overlapping geometry, gravity, ...

• void ResetVelocity() - Reset current velocity.

• bool ProjectOnGround(Vector3 vector, out Vector3 projectedVector) - Project a vector on ground plane.

• void Log(params object[] messages) - Logs info message into console with frame/tick metadata.

Advanced KCC

If you've enjoyed the simplicity and ease-of-use of Simple KCC but find yourself yearning for more functionalities and customization options, feel free to explore Advanced KCC.
The Advanced KCC is an unconstrained version of Simple KCC and provides precise control over the character movement and many powerful features.

💡 It also contains some general topics worth checking, for example Input Smoothing and Debugging.