b3dCharacterCanGrabLedge

Detects grabbable ledge ahead (1=ledge found 0=no ledge, requires movement, checks wall+top surface 0.5-2.5 units above). Takes characterHandle (character controller from b3dCreateCharacterController), lookAheadDist (forward raycast distance to check for wall/ledge). Returns 1 if grabbable ledge found (wall + top surface within grab range 0.5-2.5 units above character center), 0 if no ledge (no wall, no top surface, or out of range), 0 on error. Three-step detection: forward ray at chest height finds wall, forward offset past wall, downward ray finds ledge top. Stores ledge position in character data for climbing.

This function detects climbable ledges. Ledge detection requirements: character must be moving (inputVelocity length > 0.1, stationary character returns 0 immediately), wall ahead within lookAheadDist (chest-height raycast hits geometry forward), ledge top surface beyond wall (downward raycast from above wall hits platform), ledge height 0.5-2.5 units above character center (grabbable range, not too low or too high). Use cases: (1) Platformer ledge grab (detect ledge while jumping toward wall, auto-grab when near), (2) Climbing system (find next ledge to climb during wall climb), (3) Parkour mechanics (detect vaultable ledges for parkour movement), (4) AI navigation (find climbable ledges for advanced pathfinding). Common patterns: ledge grab if b3dCharacterCanGrabLedge(char, 1.0) and jumpPressed then b3dCharacterClimbLedge(char), auto grab if falling and b3dCharacterCanGrabLedge(char, 0.5) then b3dCharacterClimbLedge(char), ledge check if not b3dIsCharacterGrounded(char) then check ledge. Typical usage: call while airborne approaching wall (detect ledge during jump), check each frame when near walls (responsive ledge detection), combine with b3dCharacterClimbLedge to initiate climb (detection + climb initiation). Detection algorithm step 1 (find wall): raycast forward from chest height (70% up capsule, chestY = centerY + halfHeight*0.7), ray direction horizontal (movement direction with Y=0, forwardDir normalized), ray length = lookAheadDist (user-specified distance, typical 0.5-2.0 units), hit detects wall (any geometry ahead in movement direction). Detection algorithm step 2 (position beyond wall): calculate wall hit position (chestPos + forwardDir * wallDist, wallDist from raycast fraction), offset forward past wall (beyondWall = wallHitPos + forwardDir * (radius + 0.3), past capsule radius + safety margin), prevents hitting wall face during downward raycast (checks past wall for ledge top). Detection algorithm step 3 (find ledge top): raycast downward from above (start at beyondWall XZ, Y = characterY + 2.5 max height), ray direction straight down (Vec3(0,-1,0) vertical), ray length covers grabbable range (from maxHeight 2.5 to minHeight 0.5 above character), hit detects ledge top surface (platform or floor at ledge). Ledge height validation: ledgeRelativeHeight = ledgeY - characterCenterY (height of ledge above character), must be within 0.5-2.5 units (minLedgeHeight to maxLedgeHeight), too low (<0.5) not grabbable (can just walk up), too high (>2.5) out of reach (can't grab that high). Ledge position storage: if ledge found calculates standing position on ledge (standingY = ledgeTopY + halfHeight + radius, feet on surface), stores in data.ledgePosition (target position for climb, used by b3dCharacterClimbLedge), sets data.hasLedge = true flag (ledge available for climbing). Movement direction requirement: uses inputVelocity as facing direction (character must be moving toward wall, stationary returns 0), normalizes movement direction (moveDir / moveSpeed, unit vector forward), horizontal only (moveDir.Y set to 0, only XZ components). Chest height raycast: 70% up capsule (chestHeight = halfHeight * 0.7, just below top), typical chest position for human-shaped character (appropriate height to detect climbable walls), avoids hitting floor or ceiling (mid-body raycast). Forward offset calculation: radius + 0.3 units past wall (clears capsule diameter + safety, typically 0.7-1.0 units total), ensures downward raycast starts beyond wall face (avoids hitting wall instead of ledge top), positions check on ledge platform (where character will stand after climb). Downward raycast range: starts at character center + 2.5 units (maxLedgeHeight above, high enough for any grabbable ledge), ends at character center + 0.5 units (minLedgeHeight above, low enough to not miss ledges), covers 2.0 unit range (2.5 - 0.5, all grabbable heights). Ledge validation: ledge must exist (both wall raycast and downward raycast hit geometry), ledge must be in range (height between min and max), ledge must be ahead (in movement direction, not behind or to side). Reset on check: sets data.hasLedge = false at start (clears previous ledge detection), only sets true if valid ledge found (prevents stale ledge data), ensures ledge data current (reflects latest detection). Raycast collectors: WallHitCollector custom class (stores hit flag and fraction), AddHit sets mHit=true and ForceEarlyOut (early termination after first surface), separate collectors for wall and ledge checks (independent hit detection). Performance: O(1) two raycasts operation (wall forward + ledge downward, Jolt narrow-phase queries), typical cost 0.02-0.1ms per call (depends on scene complexity), safe to call every frame (designed for continuous ledge monitoring). False positives: thin ledges may be detected but too small to stand on (geometry exists but impractical), sloped ledges may detect top but climbing unsafe (downward ray hits sloped surface), moving platforms may move after detection (ledge position becomes stale). False negatives: lookAheadDist too short misses distant ledges (wall beyond range), character not moving returns 0 (must have inputVelocity to detect), ledge height outside 0.5-2.5 range missed (too low or too high to grab). Ledge grab workflow: detect ledge b3dCharacterCanGrabLedge returns 1, initiate climb b3dCharacterClimbLedge starts climb animation/movement, climb completes character positioned on ledge top (data.ledgePosition), character standing on ledge platform ready to move. Integration with climbing: this function finds ledge (detection phase), b3dCharacterClimbLedge initiates climb (execution phase), combine both for complete ledge grab system (detect then climb), check b3dIsCharacterGrounded after climb (verify landed on ledge). Validation: returns 0 if g_physicsSystem not initialized (b3dInitPhysics not called), returns 0 if characterHandle not found in g_characters (invalid or freed character), returns 0 if not moving (inputVelocity length < 0.1, stationary check). Related: b3dCharacterClimbLedge initiates ledge climb (uses ledge position from this detection), b3dCanStepDown checks ground below (complementary detection for drops vs ledges), b3dIsCharacterOnWall checks wall contact (alternative wall detection), b3dCreateCharacterController creates character controller (required before ledge detection).