b3dCharacterGroundY

Returns ground Y position if grounded, else character center Y (use to get floor height). Takes characterHandle (character controller from b3dCreateCharacterController). Returns ground surface Y coordinate if character is grounded (contact with floor below), returns character center Y position if airborne (no ground contact). Use to get accurate floor height for character positioning, ledge detection, or visual effects.

This function queries ground position. Grounded check: first calls b3dIsCharacterGrounded to check floor contact (uses CharacterVirtual ground state from physics update), if grounded returns groundPosition.Y (exact Y coordinate of ground surface from last physics collision), if not grounded returns character position Y (center of capsule, not bottom). Return value meaning: if grounded value is floor surface height (actual terrain/platform Y coordinate at character location), if airborne value is character center (mid-height of capsule, not useful for floor height but prevents error). Use cases: (1) Visual grounding (position foot IK targets at ground height for animation), (2) Ledge height calculation (determine if ledge is climbable height above ground), (3) Platform detection (get current platform Y for relative positioning), (4) Jump landing prediction (check landing height for animation prep), (5) Effect spawning (spawn footstep particles at exact ground Y). Common patterns: foot IK b3dCharacterGroundY(char) for foot target Y, ledge check ledgeY = b3dCharacterCanGrabLedge() then groundY = b3dCharacterGroundY(char) (calculate ledge height difference), platform Y platformY = b3dCharacterGroundY(char) (get platform height). Typical usage: call when character is grounded to get accurate floor height (not useful when airborne unless checking fallback to center Y), update foot IK every frame with ground Y (smooth foot placement on uneven terrain), use for gameplay logic requiring floor height (spawn point calculation, relative positioning).

Ground position accuracy: groundPosition stored during UpdatePhysicsSystem collision resolution (set when character contacts floor, updated every physics frame), reflects actual collision point (exact surface Y where character stands), accurate to physics simulation precision (matches Jolt collision detection ~0.001 units). Grounded vs airborne behavior: if b3dIsCharacterGrounded returns true guarantees groundPosition.Y is valid (accurate floor height from recent collision), if returns false groundPosition.Y may be stale (last known ground from before leaving floor), function returns character center Y when airborne (safe fallback, prevents using stale ground data). Character center Y calculation: center Y = character position Y (mid-height of capsule shape, position set by b3dMoveCharacter or physics), not character bottom Y (bottom would be center Y - height/2 for capsule), useful to know character is airborne but not useful for ground height. Foot placement example: get ground Y each frame (floorY = b3dCharacterGroundY(char)), calculate foot target Y (footTargetY = floorY, place foot exactly on ground), apply to foot bone IK (smooth foot placement on slopes and stairs), prevents foot floating or penetrating ground. Ledge height calculation: detect ledge with b3dCharacterCanGrabLedge (stores ledge position), get ground Y (currentGroundY = b3dCharacterGroundY(char)), calculate height difference (ledgeHeight = ledgeY - currentGroundY), verify climbable range (must be 0.5-2.5 units above ground for grabbable ledge). Platform following: character on moving platform (platform entity with physics body), get platform Y (platformY = b3dCharacterGroundY(char) gives platform surface Y), track platform movement (compare platformY each frame for platform velocity), adjust character Y to follow platform (maintain relative height on moving platform). Ground detection limitations: only accurate when grounded (airborne returns character center not ground), no ground detection when falling (must land to update groundPosition), no lookahead (can't predict ground Y ahead of character, only current position). Coordinate system: Y-up coordinate system (positive Y is up, ground typically Y=0 for flat terrain), ground Y can be any value (platforms at Y=10, valleys at Y=-5, variable terrain height), return value matches world space Y (consistent with b3dSetPhysicsBodyPosition and entity positions). Performance: O(1) operation (simple grounded check and value return, no raycasting or collision detection), ground position already computed during physics update (UpdatePhysicsSystem stores groundPosition, no extra cost), negligible overhead (safe to call every frame multiple times). Validation: returns character center Y if characterHandle not found (invalid or freed character, safe fallback to position.Y), no error messages (silent failure, returns reasonable value), assumes character position is valid. Related: b3dIsCharacterGrounded checks if character has floor contact (prerequisite for accurate ground Y), b3dMoveCharacter updates character position (affects center Y fallback when airborne), b3dCanStepDown checks for floor ahead (complementary ground detection for step prediction), b3dCharacterCanGrabLedge uses ground height for ledge climb validation.