b3dCharacterClimbLedge

Initiates ledge climb animation (returns climb duration in seconds, interpolates to ledge position, requires b3dCharacterCanGrabLedge first). Takes characterHandle (character controller from b3dCreateCharacterController). Returns climb duration in seconds (time to complete climb from current position to ledge top, 0.0 if no ledge or error), climb duration if already climbing (same duration value, does not restart climb). Sets isClimbingLedge flag, stores start position, calculates duration based on distance and climb speed. Character automatically moves to ledge during physics update.

This function starts ledge climb. Climb initiation: requires data.hasLedge = true (b3dCharacterCanGrabLedge must be called first and found ledge), stores ledgeClimbStartPos = current character position (starting point for interpolation), sets isClimbingLedge = true flag (marks climbing in progress), sets ledgeClimbProgress = 0.0 (animation progress 0-1, 0=start 1=complete). Duration calculation: measures distance from current position to ledge position (delta = ledgePosition - currentPosition, vector from start to target), calculates duration = distance / ledgeClimbSpeed (time = space / velocity, typical 2-4 seconds for realistic climb), returns duration for animation synchronization (caller can trigger climb animation for this duration). Use cases: (1) Platformer ledge grab (auto-climb when ledge detected during jump), (2) Manual ledge climb (player presses climb button after detection), (3) AI climbing (NPC climbs ledges during pathfinding), (4) Parkour system (chain ledge climbs for vertical navigation). Common patterns: auto climb if b3dCharacterCanGrabLedge(char, 1.0) then duration = b3dCharacterClimbLedge(char) then PlayClimbAnim(duration), manual climb if climbButton and hasLedge then b3dCharacterClimbLedge(char), check progress if isClimbing and progress >= 1.0 then OnClimbComplete(). Typical usage: call after successful b3dCharacterCanGrabLedge (detection then climb), trigger climb animation for returned duration (sync animation with movement), disable player input during climb (prevent movement interference during animation). Already climbing behavior: if isClimbingLedge already true returns same duration (doesn't restart climb, preserves progress), allows multiple calls without restarting (idempotent after first call), duration value same as initial call (distance / climb speed unchanged). No ledge handling: if data.hasLedge = false returns 0.0 immediately (no ledge to climb, must call b3dCharacterCanGrabLedge first), does not start climb (isClimbingLedge remains false), silent failure (no error message, return value indicates no climb). Climb speed: uses data.ledgeClimbSpeed (default 3.0 units/sec, configurable via b3dCharacterSetLedgeClimbSpeed), affects duration calculation (faster speed = shorter duration, slower speed = longer duration), typical values 2.0 slow deliberate, 3.0 normal, 4.0 fast athletic. Ledge position target: data.ledgePosition set by b3dCharacterCanGrabLedge (standing position on ledge top, feet on surface), includes capsule offset (position.Y = ledgeTopY + halfHeight + radius, character standing not floating), interpolation target during climb (physics update moves character toward this position). Climb interpolation: handled in UpdatePhysicsSystem each frame (not in this function), progress incremented by deltaTime / duration each frame (0.0 to 1.0 over climb duration), position interpolated from startPos to ledgePosition (lerp based on progress), character velocity set to zero during climb (prevents gravity/movement interference). Progress tracking: ledgeClimbProgress goes from 0.0 (start) to 1.0 (complete) over duration (linear interpolation parameter), when progress >= 1.0 climb complete (character at ledge top, isClimbingLedge reset to false), physics update handles progress increment (called each frame ~60Hz). Climb state flags: isClimbingLedge = true during climb (prevents other movement like jumping, walking), hasLedge = true while ledge available (reset when climb starts or detection fails), ledgeClimbProgress tracks animation progress (0-1 interpolation parameter). Duration formula: duration = sqrt((dx^2 + dy^2 + dz^2)) / climbSpeed (Euclidean distance divided by speed), typical distances 2-5 units (depends on ledge height and forward offset), typical durations 1-3 seconds (comfortable climb animation timing). Multiple calls: first call initializes climb (stores start position, sets flags, calculates duration), subsequent calls while climbing return duration without reinitializing (doesn't reset progress or start position), call after completion returns 0.0 (hasLedge cleared after reaching ledge top). Animation synchronization: returned duration matches character movement interpolation (animation length should match climb time), trigger climb animation with this duration (sync visual animation with physics movement), animation completes when character reaches ledge (perfect sync if animation length = duration). Climb completion: when ledgeClimbProgress reaches 1.0 in UpdatePhysicsSystem (character at ledge top), isClimbingLedge set to false (climb finished, resume normal control), hasLedge set to false (ledge consumed, must detect new ledge for next climb), character positioned exactly at ledgePosition (feet on ledge surface). Input blocking during climb: game code should disable movement input while isClimbingLedge true (prevents interference with climb interpolation), disable jumping and other actions (character locked to climb animation), re-enable input when climb complete (check isClimbingLedge false). Performance: O(1) operation (simple flag setting and distance calculation, instant), climb interpolation cost in UpdatePhysicsSystem each frame (~0.01ms per climbing character), negligible overhead (single lerp operation per frame). Validation: returns 0.0 if g_physicsSystem not initialized (b3dInitPhysics not called), returns 0.0 if characterHandle not found in g_characters (invalid or freed character), returns 0.0 if hasLedge false (must call b3dCharacterCanGrabLedge first). Related: b3dCharacterCanGrabLedge detects ledge and stores position (must call before climbing), b3dCharacterSetLedgeClimbSpeed sets climb speed (affects duration calculation), b3dCreateCharacterController creates character controller (required before ledge climbing), b3dIsCharacterGrounded checks if landed after climb (verify climb success).