Climbing

NavMeshLink Climbing System

The climbing system enables EnemyCrowd agents to climb walls, ladders, and other vertical surfaces using Unity's native NavMeshLink system. This provides seamless pathfinding integration where agents automatically find and use climbing routes as part of their navigation.

---

Overview

The NavMeshLink-based climbing system provides robust, pathfinding-integrated climbing:

Feature	Description
Native Pathfinding	Agents automatically discover climbing routes via NavMesh
No State Hacking	No need to disable/enable NavMeshAgent during climbs
Direction Detection	Climb direction (up/down) determined by link traversal
Horde Mode	Multiple agents can climb simultaneously (World War Z style)
GPU Animation	Full GPU Instancer Pro Crowd Animations support

Components

Component	Purpose	Count
NavMeshLinkClimbable	Defines a climbable surface (wall, ladder, etc.)	One per climbable surface
NavMeshLinkTraversalHandler	Central controller for all climbing	One per scene
NavMeshLinkCrowdAnimationHandler	GPU animation integration (optional)	One per scene

---

Quick Start

Step 1: Create a Climbable Surface

1. Select your wall/ladder GameObject

2. Add Component → Enemy Masses → Climbing → NavMesh Link Climbable

3. Right-click the component header → Auto-Detect Dimensions from Collider/Renderer

4. Press Play to generate NavMeshLinks

Your Wall GameObject
├── MeshRenderer / Collider
└── NavMeshLinkClimbable ← Add this

Step 2: Add the Central Controller

1. Create an empty GameObject named ClimbingSystem

2. Add Component → Enemy Masses → Climbing → NavMesh Link Traversal Handler

3. (Optional) Add Component → Enemy Masses → Climbing → NavMesh Link Crowd Animation Handler

ClimbingSystem (Empty GameObject)
├── NavMeshLinkTraversalHandler    ← Required
└── NavMeshLinkCrowdAnimationHandler ← For GPU animations

Step 3: Configure Climbing Animations (Optional)

1. Open your EnemyCrowd ScriptableObject

2. Go to the Animations tab

3. Expand Climbing Animations

4. Assign climb up/down animation clips

Step 4: Bake NavMesh

1. Open Window → AI → Navigation

2. Ensure your surfaces are marked as Navigation Static

3. Click Bake

4. Play the scene - agents will now automatically climb when their path requires it!

---

NavMeshLinkClimbable Component

This component creates NavMeshLinks on a climbable surface. Links connect the ground at the wall's base to the ground at the wall's top.

Climb Surface Dimensions

Setting	Description
Width	Width of the climbable surface (X axis)
Height	Height of the climbable surface (Y axis)
Base Y Offset	Vertical offset from pivot to wall base. For center-pivoted objects (Unity cubes), set to -height/2
Wall Surface Z Offset	Forward offset from pivot to wall's front surface. For center-pivoted objects, set to -depth/2

Tip: Right-click the component and select Auto-Detect Dimensions from Collider/Renderer to automatically calculate these values.

NavMesh Links Settings

Setting	Description
Double Sided	Create links on both sides of the wall (for walls climbable from either side)
Auto Link Count	Automatically calculate number of links based on width and spacing
Link Spacing	Maximum distance between links (smaller = more links, more agents can climb)
Link Count	Manual number of links (when Auto Link Count is disabled)
Link Width	Width of each link (affects agent queuing)
Agent Type ID	Must match your NavMeshAgent's agent type (0 = Humanoid)
NavMesh Area Type	Area type for cost calculation
Bidirectional	Allow both climbing up AND down
Cost Modifier	Higher values make climbing less preferred than walking

Climb Points

Setting	Description
Bottom Offset	Offset from wall base for bottom link points
Top Offset	Offset from wall top for top link points
NavMesh Snap Radius	Search radius for finding NavMesh surface near offset points
Preserve Height Offset	Keep Y offset after NavMesh snap (for consistent climb height)

Traversal Settings

Setting	Description
Use Height-Based Duration	Calculate climb time from height ÷ speed (recommended)
Climb Speed	Units per second when using height-based duration
Traversal Time	Fixed climb duration (when height-based is disabled)

Animation Speed

Setting	Description
Sync Animation To Climb	Auto-match animation speed to climb duration
Animation Speed Override	Manual animation speed (when sync is disabled)
Climb Curve	Animation curve for vertical movement (ease-in-out recommended)

Climb Style

Controls how agents move during climbing:

Style	Description	Best For
Machine	Smooth, constant velocity like an elevator	Robots, mechanical units
Human	Rhythmic stepping with arm pulls	Humanoid units, zombies
Custom	Only uses the Climb Curve	Special effects

Human Style Settings:

Setting	Description
Climb Steps	Number of "pulls" during the climb (2-20)
Step Pause Strength	Pause duration between steps (0 = none, 0.8 = long)
Randomize Rhythm	Add variation for natural movement
Rhythm Variation	Amount of randomization

Horde Mode (Multi-Agent Climbing)

Enable massive simultaneous climbing like World War Z:

Setting	Description
Links Per Position	Overlapping links at each spot (1 = single-file, 10 = horde)
Climb Position Spread	Horizontal spread for climbers (prevents overlap)
Climb Depth Spread	Forward/backward position variation
Climb Speed Variation	Random speed differences (0 = uniform, 1 = chaotic)

---

NavMeshLinkTraversalHandler Component

Central controller that manages all climbing agents. Only one needed per scene.

Settings

Setting	Description
Crowd Controller	Reference to EnemyMassesCrowdController (auto-found if empty)
Auto Complete Traversal	Automatically finish link traversal (recommended: true)
Speed Multiplier	Global speed modifier for all climbing

Horde Mode (Proximity Detection)

Setting	Description
Use Proximity Detection	Bypass Unity's link occupancy for true simultaneous climbing
Proximity Detection Radius	Distance from link start to trigger climbing
Proximity Check Interval	How often to check (lower = faster response, higher CPU)
Climb Cooldown	Delay before agent can climb again (prevents yo-yo)

Mecanim Fallback

Setting	Description
Use Mecanim Fallback	Enable Mecanim animator for non-GPU agents

Public API

// Check if an agent is currently climbing
bool IsAgentClimbing(int agentIndex);

// Check climb direction
bool IsAgentAscending(int agentIndex);

// Get climb progress (0-1)
float GetAgentClimbProgress(int agentIndex);

// Force start climbing (for manual control)
void StartClimbing(CrowdAgent agent, NavMeshLinkClimbable climbable, bool ascending);

---

NavMeshLinkCrowdAnimationHandler Component

Integrates climbing with GPU Instancer Pro Crowd Animations. Requires NavMeshLinkTraversalHandler on the same GameObject.

Settings

Setting	Description
Transition Speed	Crossfade speed for animation transitions
Animation Speed Multiplier	Global animation speed modifier

Animation Source

Animations are sourced from each agent's EnemyCrowd.climbingAnimationConfig, allowing different factions to have different climbing animations.

---

Climbing Animation Config

Configure animations per-faction in the EnemyCrowd ScriptableObject:

Animation Clips

Clip	Usage
Climb Up Clip	Looping climb animation (going up)
Climb Down Clip	Descending animation
Mount Clip	Ground-to-climb transition (optional)
Dismount Clip	Climb-to-ground transition (optional)
Climb Idle Clip	Holding position (optional)
Fall Clip	Edge fall animation (optional)

Mecanim Parameters

Parameter	Type	Usage
Climbing Bool Parameter	Bool	True while climbing
Climb Speed Parameter	Float	Animation playback speed
Mount Trigger Parameter	Trigger	Start mount animation
Dismount Trigger Parameter	Trigger	Start dismount animation

Timing

Setting	Description
Mount Duration	Transition time from ground to climbing
Dismount Duration	Transition time from climbing to ground

---

Scene Setup Examples

Basic Wall

Castle Wall
├── MeshFilter + MeshRenderer
├── Box Collider
└── NavMeshLinkClimbable
    ├── Width: 10
    ├── Height: 8
    ├── Double Sided: true
    ├── Auto Link Count: true
    └── Link Spacing: 3

Siege Ladder (Single File)

Siege Ladder
├── MeshFilter + MeshRenderer
├── Capsule Collider
└── NavMeshLinkClimbable
    ├── Width: 1
    ├── Height: 12
    ├── Double Sided: false
    ├── Link Count: 1
    ├── Links Per Position: 1
    └── Climb Style: Human

Zombie Horde Wall (World War Z)

Horde Wall
├── MeshFilter + MeshRenderer  
├── Box Collider
└── NavMeshLinkClimbable
    ├── Width: 20
    ├── Height: 15
    ├── Double Sided: false
    ├── Auto Link Count: true
    ├── Link Spacing: 2
    ├── Links Per Position: 5       ← Multiple agents per spot
    ├── Climb Position Spread: 1.0  ← Visual spread
    ├── Climb Speed Variation: 0.5  ← Chaotic speeds
    └── Climb Style: Human

---

Troubleshooting

Agents Don't Climb

1. Check NavMesh bake - Ensure surfaces at top and bottom are walkable

2. Check NavMesh snap radius - Increase if links can't find NavMesh

3. Verify Agent Type ID - Must match NavMeshAgent settings

4. Check cost modifier - Very high values may make climbing never preferred

Agents Get Stuck at Link Start

1. Enable Proximity Detection - In NavMeshLinkTraversalHandler

2. Increase Link Width - Allow more agents to use each link

3. Add more Links Per Position - For horde mode

Animation Not Playing

1. Check ClimbingAnimationConfig - Ensure clips are assigned in EnemyCrowd

2. Add NavMeshLinkCrowdAnimationHandler - Required for GPU animations

3. Verify GPU Instancer Pro - Agents need GPUICrowdAnimator

Agents Climbing Through Each Other

1. Increase Climb Position Spread - Spreads agents horizontally

2. Increase Climb Depth Spread - Adds forward/back variation

3. Reduce Links Per Position - For more orderly climbing

Jerky/Stuttering Climb Movement

1. Adjust Climb Curve - Use smooth ease-in-out

2. Check Step Pause Strength - Lower values for smoother motion

3. Verify Speed Multiplier - Very high values may cause issues

---

Performance Considerations

Link Count

• RTS/Strategy: 1 link per 3-5 meters of wall width

• Horde/Swarm: 1 link per 1-2 meters + high Links Per Position

Proximity Detection

Agent Count	Proximity Check Interval
< 100	0.05s
100-500	0.1s
500-1000	0.2s
1000+	0.3s+

Animation

• GPU Instancer Pro handles thousands of climbing agents efficiently

• Mecanim fallback has higher CPU cost - use only for non-batched agents

---

Related Documentation

• Public API Reference

• Networking Overview