b3dCharacterSetLedgeClimbSpeed

Sets ledge climb speed in units/sec (affects b3dCharacterClimbLedge duration, default 3.0 units/sec). Takes characterHandle (character controller from b3dCreateCharacterController), speed (climb velocity in units per second, how fast character moves during ledge climb). Returns nothing. Sets data.ledgeClimbSpeed, affects future climb duration calculations. Use to customize climb speed per character or difficulty setting.

This function configures climb speed. Speed parameter: speed in units per second (rate at which character moves toward ledge during climb, higher speed = faster climb = shorter duration), typical values 2.0 slow/cautious, 3.0 normal/default, 4.0 fast/athletic, 5.0+ very fast/superhuman. Duration impact: climb duration = distance / speed (set by b3dCharacterClimbLedge), faster speed reduces duration (speed 6.0 = half duration of speed 3.0), slower speed increases duration (speed 1.5 = double duration of speed 3.0). Use cases: (1) Character differentiation (strong characters climb faster, weak characters slower), (2) Difficulty settings (easy mode faster climbs, hard mode slower), (3) Powerups (speed boost affects climbing), (4) Fatigue system (tired characters climb slower), (5) Animation matching (set speed to match animation length exactly). Common patterns: fast character b3dCharacterSetLedgeClimbSpeed(athlete, 4.5), slow character b3dCharacterSetLedgeClimbSpeed(weakling, 2.0), powerup b3dCharacterSetLedgeClimbSpeed(char, normalSpeed * 1.5), fatigue b3dCharacterSetLedgeClimbSpeed(char, normalSpeed * fatigueMultiplier). Typical usage: set once at character creation (configure character-specific climb speed), adjust dynamically for powerups or status effects (boost speed temporarily), reset after powerup expires (restore normal climb speed). Default value: ledgeClimbSpeed initialized to 3.0 in b3dCreateCharacterController (moderate realistic climb speed, not too fast or slow), remains until explicitly changed (persistent across climbs), typical for human-sized characters. Speed consistency: affects all future climbs (not just next climb, permanent until changed again), does not affect climbs in progress (ongoing climb uses duration calculated at start), call before b3dCharacterClimbLedge to affect next climb. Animation synchronization: match speed to animation length (if climb anim 2 seconds and distance 6 units set speed=3.0), allows perfect animation sync (visual climb matches physics movement), calculate as speed = distance / desiredDuration (solve for speed given desired animation length). Climb duration formula: duration = sqrt((dx^2 + dy^2 + dz^2)) / speed (distance / speed), example distance 6 units speed 3.0 gives 2 seconds, example distance 4 units speed 2.0 gives 2 seconds (same duration different speed/distance). Speed recommendations: minimum 1.0 for very slow climbs (below 1.0 feels broken, excessively slow), maximum 10.0 for instant climbs (above 10.0 may look teleport-like), sweet spot 2.0-4.0 for realistic human climbing (natural athletic movement). Performance: O(1) operation (simple float assignment, instant), no validation overhead (any speed allowed including zero or negative), safe to call every frame if needed (though typically set once). Zero or negative speed: speed 0.0 causes infinite duration (division by zero protection needed in game code), negative speed causes negative duration (may cause undefined climb behavior), avoid non-positive speeds (validate speed > 0 before calling). Climb speed vs movement speed: ledge climb speed independent of walk/run speed (separate systems, different movement types), walk speed affects horizontal movement, climb speed affects vertical ledge climbing, both can be different (fast runner may be slow climber or vice versa). Validation: silently returns if characterHandle not found in g_characters (invalid or freed character), no validation on speed value (any value allowed, user responsible for reasonable speed), no error messages (silent failure for performance). Related: b3dCharacterClimbLedge uses this speed for duration calculation (duration = distance / speed), b3dCreateCharacterController sets default speed 3.0 (initial value), b3dCharacterCanGrabLedge detects ledge (speed determines how fast climb completes).