This document is about: FUSION 2

SWITCH TO

FUSION 2 SHARED FUSION 1 FUSION 2

Simple KCC

Level

BEGINNER

概述

簡單KCC 是一個對使用者友善並且直觀的3D角色控制器附加元件。它設計為使用 Fusion 來為您的遊戲專案帶來簡便性及易於使用的角色。

建立一個平順的及有回應的角色控制器，是任何遊戲專案的一個關鍵。傳統角色控制器解決方案在整合方面可以是複雜的又充滿挑戰的，特別是對於尋求簡化及高效的工作流程的開發人員。這就是 簡單KCC 有用的地方 — 針對角色移動來提供一個簡化又有力的解決方案。

這個附加元件相容於客戶端／伺服器及共享模式。

功能

簡易整合及設置。
控制位置及查看旋轉（俯仰+偏擺）。
基於膠囊的物理查詢及取消穿透。
基於速度的移動。
支援重力。
支援跳躍。
基礎地面偵測。
開箱即用的持續碰撞偵測(CCD)。
針對碰撞器的分離的遊戲物件（在運行階段建立為下層遊戲物件）。
支援忽略下層碰撞器。
腳步偵測及地面貼齊。
平台獨立，對行動裝置友善。
網路及效能最佳化。
相容於輪詢。
完整評論的範例，附有測試遊樂場。

下載 - 範例

Version	Release Date	Download
2.1.1	9月 02, 2026	Fusion Simple KCC Sample 2.1.1
2.1.0	7月 17, 2026	Fusion Simple KCC Sample 2.1.0
2.0.18	11月 03, 2025	Fusion Simple KCC Sample 2.0.18

下載 - 附加元件

Version	Release Date	Download
2.1.1	9月 02, 2026	Fusion Simple KCC 2.1.1
2.1.0	7月 17, 2026	Fusion Simple KCC 2.1.0
2.0.15	5月 20, 2026	Fusion Simple KCC 2.0.15

需求

Unity 2021.3
Fusion應用程式帳號：為了運行範例，首先在Photon引擎儀表板中建立一個Fusion應用程式帳號，然後將它貼上到即時設定（可從Unity編輯器中的Fusion選單中到達）中的App Id Fusion欄位。繼續遵循第一步章節中的指引。

範例控制

使用W、S、A、D來移動，SPACE來跳躍，及Mouse來查看。
使用ENTER鍵在Unity編輯器中鎖定或放開您的游標。

開啟Assets/Scenes/Playground並且遊玩。場景可用於評估（角色及其參數的行為方式）或針對您的遊戲來做移動的原型。

第一步

開始 簡單KCC 的最好方式是下載範例專案，其是預先設置的，並且準備好以多重玩家來測試。

在以下的逐步指引中，我們將從零開始帶您走過整合 簡單KCC 附加元件到您的遊戲專案的流程。

匯入簡單KCC附加元件套件到您的Fusion 2.0專案中。

建立一個玩家預製件。

新增NetworkObject及SimpleKCC元件到根遊戲物件。在RigidBody元件上啟用Is Kinematic選項。

設置參數（半徑、高度、碰撞遮罩等等）。在設置章節中說明更多細節。
鏈接玩家預製件到您的生成管理器。

從程式碼的角色移動。在移動章節中說明更多細節。

設置

Simple KCC元件檢查器提供了一系列選項來微調行為。

參數為：

Shape - 定義角色物理行為。
- None - 跳過內部物理查詢，取消生成碰撞器。
- Capsule - 完整物理處理，生成膠囊碰撞器。
Is Trigger - 如果啟用，碰撞器為非阻擋。
Radius - 碰撞器半徑。
Height - 碰撞器高度。
Extent - 定義地面偵測及其他功能的額外的半徑範圍。建議範圍是半徑的1-2%。
Collider Layer - 碰撞器遊戲物件的圖層。
Collision Layer Mask - 角色碰撞到的圖層遮罩。
Teleport Threshold - 定義角色在一個刷新中必須移動的最小距離，以將移動視為即時（傳送）。
Anti Jitter Distance - 定義位置距離容差以平順化細微抖動。當切換移動方向時，更高的值可能帶來可見的延遲。
- X - 水平軸。
- Y - 垂直軸。
Step Height - 最大障礙物高度以踩在上面。
Step Depth - 腳步檢查的最大深度。
Step Speed - 未應用移動投射的乘數以往上邁出步伐。這有助於更快地穿越障礙物。
Snap Distance - 針對貼齊的最大地面檢查距離。
Snap Speed - 地面貼齊的秒速。

移動

初始化KCC屬性。

public override void Spawned()
{
    // Set custom gravity.
    _simpleKCC.SetGravity(Physics.gravity * 4.0f);
}

移動及查找角色。

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;
        Vector3 jumpImpulse  = default;

        if (input.Jump == true && _simpleKCC.IsGrounded == true)
        {
            // Set world space jump vector.
            jumpImpulse = Vector3.up * 10.0f;
        }

        _simpleKCC.Move(moveVelocity, jumpImpulse);
    }
}

相機同步。

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概述

屬性

bool IsActive - 控制KCC的執行。
Transform Transform - 參照到已快取Transform元件。
Rigidbody Rigidbody - 參照到已附加Rigidbody元件。
CapsuleCollider Collider - 參照到KCC碰撞器。如果Shape被設定為EKCCShape.None的話，可以是空值。
KCCSettings Settings - 基礎KCC設定。
Vector3 Position - 被散佈到Transform的已計算位置。
Quaternion LookRotation - 查看Pitch及Yaw的組合。
Vector3 LookDirection - 基於查看旋轉的查看方向。
Quaternion TransformRotation - 基於Yaw查看旋轉的轉換旋轉。
Vector3 TransformDirection - 基於轉換旋轉的轉換方向。
float RealSpeed - 從真實位置改變計算的速度。
Vector3 RealVelocity - 從真實位置改變計算的速度。
bool HasJumped - 指出在目前刷新中KCC已經跳躍的旗標。
bool IsGrounded - 指出KCC正在以一個低於MaxGroundAngle的法線角度來觸碰一個碰撞器的旗標。
Vector3 GroundNormal - 所有觸碰碰撞器的組合法線。離上方向較近的法線對最終法線的影響較大。
Func<KCC, Collider, bool> ResolveCollision - 自訂碰撞解決器回調。使用這個以應用額外的篩選。

方法

void SetActive(bool isActive) - 控制KCC的執行。
void SetPosition(Vector3 position) - 設定KCC的位置並且立即同步Transform。
void SetGravity(Vector3 gravity) - 設定重力向量。
void SetHeight(float height) - 更新Settings中的Height並且立即與Collider同步。
void SetRadius(float radius) - 更新Settings中的Radius並且立即與Collider同步。
void SetShape(EKCCShape shape, float radius = 0.0f, float height = 0.0f) - 更新Settings中的Shape、Radius（選擇性）、Height（選擇性）並且立即與Collider同步。
void SetTrigger(bool isTrigger) - 更新Settings中的Is Trigger旗標並且立即與碰撞器同步。
void SetColliderLayer(int layer) - 更新Settings中的Collider Layer並且立即與碰撞器同步。
void SetCollisionLayerMask(LayerMask layerMask) - 更新Settings中的Collision Layer Mask。
void SetMaxGroundAngle(float maxGroundAngle) - 設定最大可行走地面角度（以度為單位）。
void RefreshChildColliders() - 重新整理下層碰撞器清單，用於碰撞篩選。完全忽略下層碰撞器，觸發被視為有效碰撞。
Vector2 GetLookRotation(bool pitch = true, bool yaw = true) - 傳回目前查看旋轉。
void SetLookRotation(float pitch, float yaw) - 設定俯仰及偏擺查看旋轉。值被包夾在 <-90, 90> （俯仰）及 <-180, 180> （偏擺）。
void SetLookRotation(Vector2 lookRotation) - 設定俯仰及偏擺查看旋轉。值被包夾在 <-90, 90> （俯仰）及 <-180, 180> （偏擺）。
void SetLookRotation(Quaternion lookRotation, bool preservePitch = false, bool preserveYaw = false) - 設定俯仰及偏擺查看旋轉。忽略滾動（不支援）。值被包夾在 <-90, 90> （俯仰）及 <-180, 180> （偏擺）。
void AddLookRotation(float pitchDelta, float yawDelta) - 新增俯仰及偏擺查看旋轉。結果值被包夾在 <-90, 90> （俯仰）及 <-180, 180> （偏擺）。
void AddLookRotation(float pitchDelta, float yawDelta, float minPitch, float maxPitch) - 新增俯仰及偏擺查看旋轉。結果值被包夾在 <minPitch, maxPitch> （俯仰）及 <-180, 180> （偏擺）。
void AddLookRotation(Vector2 lookRotationDelta) - 新增俯仰(x)及偏擺(y)查看旋轉。結果值被包夾在 <-90, 90> （俯仰）及 <-180, 180> （偏擺）。
void AddLookRotation(Vector2 lookRotationDelta, float minPitch, float maxPitch) - 新增俯仰(x)及偏擺(y)查看旋轉。結果值被包夾在 <minPitch, maxPitch> （俯仰）及 <-180, 180> （偏擺）。
void Move(Vector3 kinematicVelocity = default, Vector3 jumpImpulse = default) - 移動功能。KCC可以以零速度移動 - 從重疊的地理、重力等等取消穿透
void Log(params object[] messages) - 以幀／刷新中繼資料來記錄資訊訊息到主控台之中。

進階KCC

如果您已經享受了 簡單KCC 的簡便與易用，但您希望有更多功能性及自訂選項，請探索 進階KCC。 進階KCC 是 簡單KCC 的一個未受限版本，並且對於角色移動來提供精確的控制以及許多有力的功能。

💡 它也含有一些值得一看的一般性主題，像是輸入平順化及偵錯。

Last updated on 04/08/2026

概述
功能
下載 - 範例
下載 - 附加元件
需求
範例控制
第一步
設置
移動
API概述

進階KCC