Agent Avoidance

Quantum 實現了一種稱為 混合互惠速度障礙（HRVO） 的碰撞避障技術變體。

設置避障Agent

NavMeshAvoidanceAgent組件要求實體已具備NavMeshPathfinder 和 NavMeshSteeringAgent組件。

模擬配置

避障需要位於SimulationConfig中Navigation部分的以下全局參數。

禁用EnableAvoidance可完全消除避障系統的任何開銷。

AvoidanceRange對避障系統的質量和性能成本至關重要。它定義了 Agent 開始相互影響的範圍。該範圍是在兩個 Agent 的半徑之間測量的。（A）是個體 Agent 的避障半徑，（B）是 Agent 的避障半徑加上全局AvoidanceRange。

inRange = Distance(positionAgentA, positionAgentB) - radiusAgentA - radiusAgentB < AvoidanceRange

MaxAvoidanceCandidates定義每個 Agent 使用的最大避障候選數量。候選數量越多，需要的內存和 CPU 就越多，但也會提高質量。AvoidanceQuality越高且相互影響的 Agent 越多，這個數值就需要越大。

VelocityObstacleTruncationFactor定義了非移動障礙物的速度障礙（VO）被截斷的程度。

NavMeshAgentConfig - 避障

AvoidanceType	設置 Agent 的活動避障模式。 `None` = Agent 不會避開其他 Agent，但其他 Agent 會避開它 `Internal` = Agent 將使用內部避障系統主動避開其他 Agent
AvoidanceQuality	設置 Agent 的活動避障模式。 `None` = Agent 不會避開其他 Agent，但其他 Agent 會避開它 `Internal` = Agent 將使用內部避障系統主動避開其他 Agent
Priority	Agent 的`Priority`與 Unity 中的作用相同。默認值 = `50` 最重要 = `0` 最不重要 = `99` 由於避障系統依賴互惠性，避障工作（誰避開誰以及避開多少）總是在 Agent 之間分配。優先級較高的 Agent 只承擔`25%` 的工作，而相同優先級的 Agent 則平均分配工作`50`/`50`。
AvoidanceRadius	此 Agent 的避障半徑應大致匹配可見角色的大小。它與 `SimulationConfig` 中的避障半徑一起，在創建相互影響的 Agent 對的避障廣域階段使用。
AvoidanceLayer	設置此 Agent 的避障層。 Unity 層用於`AvoidanceLayer` 和 `AvoidanceMask`以過濾 Agent。
AvoidanceMask	設置此 Agent 的避障遮罩。`AvoidanceLayer`不在遮罩中的 Agent 將被忽略。
MaxAvoidanceCandidates	設置此 Agent 類型的最大避障候選數量。全局最大值在 `SimulationConfig`中設置。
ReduceAvoidanceAtWaypoints	在試圖遵循路點繞過拐角或穿過狹窄通道時解決避障問題是很困難的。為了緩解這個問題，並且為了避免 Agent 相互阻塞而接受可見的重疊，可以切換 `ReduceAvoidanceAtWaypoints`。
ReduceAvoidanceFactor	當 Agent 接近路點時，所應用的避障會減少。`ReduceAvoidanceFactor`值與 Agent 半徑相乘，然後表示避障影響按二次方減少的距離。
AvoidanceCanReduceSpeed	此選項允許速度候選減小 Agent 的速度，使避障動作看起來更自然。
ShowDebugAvoidance	定義在運行時是否將速度障礙和候選項繪製為 gizmos。

設置避障障礙物

Avoidance Obstacles是靜態或移動的實體，它們會影響導航網格 Agent 的避障行為，但本身並不是 Agent。它們不會影響路徑尋找器，並且不應用於阻塞遊戲關卡的部分區域。

NavMeshAvoidanceObstacle組件需要Transform2D或Transform3D組件才能正常工作。

如果具有NavMeshAvoidanceObstacle組件的實體正在移動，其他 Agent 需要其速度信息來預測其未來位置，並且必須手動設置NavMeshAvoidanceObstacle.Velocity。

在Unity中的 Quantum 實體原型上添加NavMeshAvoidanceObstacle。

或者在代碼中添加它。

var c = f.Create();
f.Set(c, new Transform2D { Position = new FPVector2(8,-2) });
var obstacle = new NavMeshAvoidanceObstacle();
obstacle.AvoidanceLayer = 0;
obstacle.Radius = FP._0_50;
obstacle.Velocity = FPVector2.Zero;
f.Set(c, obstacle);

抖動的 Agent

由於避障計算的性質以及定點數學，Agent 的移動，特別是它們的移動方向，可能不穩定。這會導致 Agent 出現明顯的抖動。

為了緩解這一問題，可以降低 Agent 的Angular Speed，或者添加視圖平滑。這可以通過重寫QuantumEntityView類並在應用變換時添加旋轉混合來實現。

namespace Quantum {
  using UnityEngine;

  public class SmoothRotationEntityView : QuantumEntityView {
    public float Blending = 15;

    private Quaternion rotation;

    protected override void ApplyTransform(ref UpdatePositionParameter param) {
      // Override this in subclass to change how the new position is applied to the transform.
      transform.position = param.NewPosition + param.ErrorVisualVector;

      // Unity's quaternion multiplication is equivalent to applying rhs then lhs (despite their doc saying the opposite)
      rotation = param.ErrorVisualQuaternion * param.NewRotation;
      transform.rotation = Quaternion.Lerp(transform.rotation, rotation, Time.deltaTime * Blending);
    }
  }
}

Last updated on 11/06/2026

設置避障Agent

模擬配置
NavMeshAgentConfig - 避障

設置避障障礙物
抖動的 Agent