Huck,Clemens

How Companions Move

CPS movement is driver-aware. A companion is a GC2 Character, and GC2 Characters move through a swappable driver. Which driver a companion uses decides how it handles obstacles:

Character Controller / Rigidbody driver

Moves in a straight line toward the target. Fine in open space, but it walks into walls — CPS falls back to a lightweight raycast steering that can nudge around a single obstacle, but cannot route around a whole building or find a doorway.

NavMesh Agent driver Recommended

Uses Unity's NavMesh pathfinding with high-quality local avoidance, agent-to-agent separation, and automatic repathing. Companions route correctly around walls, through doorways, and never clump together — at no extra cost to you.

CPS detects the driver automatically. If a companion already uses the NavMesh Agent driver, native pathfinding is used and the raycast fallback is skipped entirely. With Prefer NavMesh (the default), CPS also upgrades companions to the NavMesh driver at spawn when a baked mesh is present.

NavMesh Pathfinding

Enabling NavMesh navigation for companions takes three steps:

Step 1: Bake a NavMesh

Open Window → AI → Navigation (or use Unity's NavMeshSurface component) and bake a NavMesh over your walkable geometry. Companions can only pathfind where the mesh exists — the same requirement your enemy AI already has.

Step 2: Set the Obstacle Avoidance mode

Open Window → Companion System → Settings and set Navigation → Obstacle Avoidance to Prefer NavMesh (the default). This upgrades each companion's GC2 Character to the NavMesh Agent driver at spawn when a baked mesh is present.

Step 3: Press Play

Select a companion and check the Companion Motor inspector. It should read GC2 Driver: Navmesh Agent and Active Mode: NavMesh Pathfinding. Companions now route around walls instead of pressing into them.

Graceful fallback

NavMesh is the recommended default, not a hard requirement. If a scene has no baked NavMesh, companions keep their existing driver and use the raycast steering fallback — nothing breaks, you simply don't get full pathfinding until a mesh is baked.

Unreachable slots

If a companion's target is genuinely unreachable (an off-mesh gap, a dynamic blocker) the NavMesh path returns Partial. After a few seconds of no progress CPS performs a fade-teleport back to the owner as a last resort — never the jittery raycast steering.

Obstacle Avoidance Modes

Set project-wide in CompanionSettings → Navigation → Obstacle Avoidance.

Mode	Behavior
Auto	Use native NavMesh pathfinding when the companion already runs the NavMesh Agent driver; otherwise fall back to raycast steering. Non-invasive — never changes the driver.
Prefer NavMesh Default	Same as Auto, but also upgrades the companion's Character to the NavMesh Agent driver at spawn when a baked NavMesh is present. Zero-config "it just works".
Raycast Only	Always use the legacy raycast steering, even on a NavMesh driver. A back-compat escape hatch.

Climb & Vault Links

A NavMesh naturally leaves gaps at low walls and boxes — surfaces the player can hop but the mesh won't connect. Rather than detour or teleport, drop a CompanionNavMeshLink across the gap and companions will climb or vault over it with a scripted arc and an optional animation.

Step 1: Create the link object

Add an empty GameObject at the obstacle and attach Companion System → Companion NavMesh Link.

Step 2: Position the endpoints

Drag the two orange handles in the Scene view so each endpoint sits on the baked NavMesh on either side of the wall/box. The gizmo previews the crossing arc.

Step 3: Tune the crossing

Set Traverse Duration (quick vault vs. slow climb), Arc Height (≈ the obstacle height), and optionally assign a Climb Gesture animation clip. Match the link's Agent Type ID to your companion's (0 = Unity's default Humanoid).

CompanionNavMeshLink MonoBehaviour

Property	Description
Start / End Offset	The two link endpoints (local space). Draggable via Scene handles.
Width	Crossing width — wider links accept a broader approach angle.
Bidirectional	Allow crossing in both directions.
Area / Agent Type ID	NavMesh area and agent type the link belongs to (0 = default Humanoid).
Traverse Duration	Seconds to cross — short for a vault, longer for a climb.
Arc Height	Peak height of the crossing arc above the straight line (≈ obstacle height).
Climb Gesture	Optional animation clip played while crossing (root motion ignored — the arc drives movement).
Face Traverse Direction	Rotate the companion to face the crossing while traversing.

Links are generic NavMesh links — they work for any GC2 NavMesh-driven Character, not only companions. While a companion is traversing a link, stuck detection is suspended so the climb is never mistaken for being stuck.

If a crossing slides instead of climbs

Set Auto Traverse Off Mesh Link = off on the companion's NavMesh Agent driver so CPS drives the crossing itself.

Breadcrumb Trail Following

Pathing straight to a slot beside the player is a problem around corners: the computed route can differ from the one you actually walked, sometimes ending in a pocket beyond another wall. CPS solves this by recording a breadcrumb trail of where the owner actually walked and having companions follow a point back along that trail — so they retrace your exact route through the same doorway, around the same corner.

Hybrid behavior

While the owner moves: companions follow single-file along the breadcrumb trail, staggered so multiple companions form a natural follow-the-leader line.
While the owner is at rest: companions fan out into their configured formation (Line / V / Circle) around the owner.

The trail is recorded by the CompanionOwnerAdapter on your player. Tune it there:

Setting	Description
Record Trail	Enable breadcrumb recording (on by default).
Trail Sample Distance	Distance the owner must travel before a new breadcrumb is recorded (default 0.35 m).
Trail Max Points	Maximum breadcrumbs kept. Trail length ≈ points × sample distance.
Trail Discontinuity	If the owner jumps farther than this between samples (teleport/warp), the trail is cleared so companions never path along a bogus segment.

Trail following is automatic when the owner implements the trail interface (the built-in CompanionOwnerAdapter does). A custom owner without it simply falls back to formation-slot following. When the trail is too short (e.g. you just started moving), companions also fall back to the formation slot until enough breadcrumb exists.

With the hybrid model, V and Circle formations apply while the owner is standing still. In motion, companions travel single-file along your trail. This is intentional — it's what keeps the party retracing your route around corners.

Debugging Movement

Two tools show exactly what a companion is doing in Play Mode.

Companion Motor inspector

A live Navigation section shows the active Obstacle Avoidance setting, the current GC2 driver, and the Active Mode (NavMesh Pathfinding / Raycast — Local Avoidance / Raycast — Direct). On the NavMesh driver it also surfaces the agent's path status (Complete / Partial / Invalid), remaining distance, velocity, and an On Link indicator while climbing.

Companion Path Visualizer

Add CompanionPathVisualizer to a companion (or toggle it from the Brain's Behavior Analyzer). The new Follow Trail toggle draws the owner's breadcrumb polyline and the companion's follow target — orange when retracing the trail, cyan when heading to its formation slot. The Brain inspector also shows a live Following Via: Breadcrumb Trail / Formation Slot readout.

Turn on Debug Logging in CompanionSettings to log driver upgrades, link traversal, and fallback teleports to the console.