b3dIsCharacterGrounded

Checks if character is on ground (1=grounded 0=airborne, uses Jolt EGroundState). Takes characterHandle (character controller from b3dCreateCharacterController). Returns 1 if character on ground (standing on solid surface), 0 if airborne (falling, jumping, or no floor contact), 0 on error (invalid character). Queries Jolt CharacterVirtual.GetGroundState, returns EGroundState::OnGround status. Read-only ground detection query.

This function checks ground contact. Return values: 1 (TRUE, character on ground, EGroundState::OnGround, standing on walkable surface), 0 (FALSE, character airborne, EGroundState::InAir or EGroundState::NotSupported, no ground contact or on too-steep surface). Ground state types: OnGround (character supported by walkable surface, floor angle <= maxSlopeAngle, weight distributed on ground), InAir (character not touching any surface, falling or jumping, no contacts below), NotSupported (touching surface but too steep to stand on, angle > maxSlopeAngle, sliding down). Use cases: (1) Jump control (only allow jump if grounded, if b3dIsCharacterGrounded(char) then b3dCharacterJump(char, 10)), (2) Animation control (switch to fall animation if not grounded, if not b3dIsCharacterGrounded(char) then PlayAnim(fallAnim)), (3) Sound effects (play landing sound when transitioning airborne to grounded), (4) Double jump prevention (track air jumps, reset count when grounded). Common patterns: jump check if b3dIsCharacterGrounded(char) and Key(KEY_SPACE) then b3dCharacterJump(char, 10), fall detection if not b3dIsCharacterGrounded(char) then PlayAnim("falling"), landing detection wasAirborne and b3dIsCharacterGrounded(char) then PlaySound("land"), coyote time alternative use b3dIsCharacterGrounded(char) for strict grounded check (bypasses internal coyote time). Typical usage: call before allowing jump to prevent air jumping (unless double jump intended), check each frame for animation state machine transitions (idle/walk on ground, jump/fall in air), detect landing for particle effects or sound (transition from airborne to grounded). Ground detection: Jolt CharacterVirtual performs ground detection automatically (raycast or shape cast downward from character), checks if surface angle walkable (normal.Y > cos(maxSlopeAngle), typical maxSlopeAngle=45 degrees), updates ground state each physics step (OnGround, InAir, or NotSupported). MaxSlopeAngle interaction: character on surface with angle < 45 degrees returns OnGround (walkable floor, grounded), character on surface with angle > 45 degrees returns NotSupported (too steep, treated as airborne for jumping), this function returns 0 for NotSupported (can't jump on steep slopes, realistic). Step-down distance: character remains OnGround while descending gentle slopes or stairs (within stepDown distance default 0.5 units), stepping off edge transitions to InAir once beyond stepDown (slight delay before airborne, allows walking down stairs smoothly). Grounded vs coyote time: b3dIsCharacterGrounded returns instant grounded state (no grace period), b3dCharacterJump uses internal coyote time (0.15sec grace period after leaving ground), for strict jumping check both (if b3dIsCharacterGrounded(char) and Key(SPACE) then jump), for forgiving jumping rely on coyote time (call b3dCharacterJump directly). Animation state machine: typical state machine idle/walk (if b3dIsCharacterGrounded and inputVelocity > 0 then walk else idle), jump (if b3dIsCharacterGrounded and jump pressed then jump), fall (if not b3dIsCharacterGrounded and vy < 0 then fall), land (transition from fall to idle when b3dIsCharacterGrounded). Landing detection pattern: store previous grounded state wasGrounded then current grounded state isGrounded = b3dIsCharacterGrounded(char) then if not wasGrounded and isGrounded then OnLand() (detects airborne to grounded transition), execute landing logic in OnLand (play sound, spawn dust particles, trigger camera shake). Performance: O(1) operation (simple EGroundState enum check via Jolt CharacterVirtual.GetGroundState), no physics simulation triggered (ground state already calculated by Jolt), safe to call every frame (designed for frequent queries). Ground state update: ground state updated during CharacterVirtual::Update in UpdatePhysicsSystem (called each physics step ~60Hz via b3dRenderWorld), state current as of last physics step (may be one frame delayed from actual collision), typically negligible delay (60Hz update fast enough for responsive gameplay). False negatives: character on very steep slope returns 0 (NotSupported treated as airborne even though touching surface), character in rapid vertical motion may miss brief ground contact (moving too fast, passes through detection threshold), typically not issue with reasonable jump heights and physics step rate. Edge cases: character on moving platform may flicker grounded/airborne (if platform moves down faster than step-down tracking), character on thin geometry may pass through if moving too fast (use continuous collision detection or thicker floors), character on ledge exactly at maxSlopeAngle may jitter between OnGround and NotSupported. Validation: returns 0 if characterHandle not found in g_characters (invalid or freed character, treated as airborne), no error message (silent failure for performance in query function). Related: b3dCharacterJump uses coyote time for forgiving jumps (internal grounded check with grace period), b3dMoveCharacter sets movement (works whether grounded or airborne), b3dIsCharacterOnWall checks wall contact (complementary surface detection), b3dCreateCharacterController creates character controller (ground detection automatic after creation).