b3dCanStepDown

Checks if ground exists within maxDistance below character feet (1=ground found 0=no ground, uses raycast). Takes characterHandle (character controller from b3dCreateCharacterController), maxDistance (maximum downward raycast distance in units to check for ground). Returns 1 if ground found within distance (solid surface below character), 0 if no ground (void, pit, or too far below), 0 on error (invalid character). Raycasts downward from character feet, detects ledges and drop-offs. Use for ledge detection, fall detection, AI pathfinding.

This function detects ground below character. Raycast parameters: rayStart at character feet position (bottomY = capsuleCenterY - halfHeight - radius, if moving checks ahead at capsule edge in movement direction), rayDirection straight down (Vec3(0,-1,0) vertical), rayLength = maxDistance (how far to check below feet). Ground detection: returns 1 if raycast hits any surface within maxDistance (solid floor, platform, slope), returns 0 if raycast misses (air below, pit, gap), distance measured from feet downward (not from capsule center). Use cases: (1) Ledge detection (check if ground ahead before walking, if not b3dCanStepDown(char, 2.0) then stop at ledge), (2) Fall detection (detect when character over void for fall animation), (3) AI pathfinding (check if path safe before moving forward, avoid pits), (4) Dynamic platforms (detect if platform below before jumping down), (5) Ladder transition (check if ground below ladder before dismounting). Common patterns: ledge check if not b3dCanStepDown(char, 1.0) then DontWalkForward(), safe to jump if b3dCanStepDown(char, 5.0) then AllowJumpDown(), pit detection if not b3dCanStepDown(char, 10.0) then OverVoid = TRUE. Typical usage: call before allowing AI to move forward (prevent walking off cliffs), check each frame for environmental awareness (character knows if over pit), combine with b3dIsCharacterGrounded for complete floor detection (grounded=on floor now, canStepDown=floor exists below). Raycast origin: starts at feet position (bottom of capsule, height = centerY - halfHeight - radius), if moving horizontally checks ahead (rayStart offset by capsule radius in movement direction), prevents late ledge detection (checks at capsule edge before center reaches ledge). Movement direction awareness: if inputVelocity length > 0.1 checks ahead in movement direction (rayStart = feet + moveDir * radius, detects ledge before stepping off), if stationary or moving slowly checks straight down from center (no lookahead, detects ground directly below). Feet position calculation: capsule center at character position (CharacterVirtual.GetPosition), feet at bottom of capsule (feetY = centerY - halfHeight - radius for capsule shape), horizontal position same as capsule center (feetX = centerX, feetZ = centerZ). Ledge lookahead: when moving forward offset rayStart horizontally by radius (checks at leading edge of capsule), detects ledge early (before capsule center reaches edge), allows character to stop before falling off. Raycast collision: uses Jolt narrow-phase CastRay (precise raycast against geometry), checks against all static and dynamic objects (Layers::MOVING broadphase filter), stops at first hit (ClosestHitCollector with ForceEarlyOut). Collector implementation: ClosestHitCollector custom class (inherits CastRayCollector), AddHit sets mHit=true and calls ForceEarlyOut (early termination after first surface), returns mHit flag (true if any surface hit, false if ray misses). Max distance recommendations: 0.5-1.0 for ledge detection at walk speed (short range, stop before edge), 2.0-5.0 for fall detection (medium range, detect significant drops), 10.0+ for pit detection (long range, detect bottomless voids), too large distance may hit distant floors below actual pits. False positives: thin geometry may not block raycast if moving too fast (raycast misses thin floor), diagonal slopes may give misleading results (raycast hits slope side not floor), steep overhangs may hit overhang instead of ground below. False negatives: raycast length too short misses ground (ground exists but beyond maxDistance), raycast starts inside geometry returns miss (clipping through floor edge), moving platform moved after raycast returns stale result. Performance: O(1) raycast operation (Jolt narrow-phase query, fast), typical cost 0.01-0.05ms per call (depends on scene complexity), safe to call frequently (designed for per-frame ledge checking). AI pathfinding integration: check before each move (if canStepDown then safe to move else find alternate path), build navigation mesh using this function (grid of stepDown checks marks safe areas), dynamic obstacle avoidance (recalculate safe zones as platforms move). Ledge stopping: typical pattern vel = GetInput() then if vel.length > 0 and not b3dCanStepDown(char, 1.0) then vel = 0 (stop movement if ledge ahead), combine with animation (play stop animation at ledge), add buffer distance (check slightly ahead of capsule edge for smooth stopping). Platform detection: check if platform below before jumping down (safe descent height check), verify landing zone before scripted jumps (cutscene safety), detect elevator platforms (check if floor moving). Validation: returns 0 if g_physicsSystem not initialized (b3dInitPhysics not called), returns 0 if characterHandle not found in g_characters (invalid or freed character), no error messages (silent failure for performance). Related: b3dIsCharacterGrounded checks if currently on ground (on floor now vs ground exists below), b3dCharacterCanGrabLedge checks for grabbable ledge ahead (more complex ledge detection with grab point), b3dCreateCharacterController creates character controller (required before ground checking), b3dMoveCharacter sets movement (combine with canStepDown for safe movement).