b3dIsCharacterOnWall

Checks if character touching wall (1=wall contact 0=no wall, vertical surface normalY<0.5 = >60deg). Takes characterHandle (character controller from b3dCreateCharacterController). Returns 1 if character touching vertical surface (wall detected, normal mostly horizontal), 0 if no wall contact or only touching floors/ceilings, 0 on error (invalid character). Iterates active contacts from CharacterVirtual, checks contact normals for verticality. Read-only wall detection query.

This function checks wall contact. Return values: 1 (TRUE, character touching wall, at least one contact with normalY < 0.5), 0 (FALSE, no wall contact, all contacts horizontal or no contacts). Wall definition: wall surface has normal mostly horizontal (normal.Y component < 0.5 absolute value), means surface more vertical than 60 degrees from horizontal (acos(0.5) = 60 degrees), steep enough to be unclimbable by normal walking. Contact normal interpretation: normal points from surface toward character (away from wall into character), normal.Y near 0 means purely vertical wall (exactly 90 degrees), normal.Y = 0.5 means 60 degree slope (threshold between wall and walkable surface), normal.Y > 0.5 means walkable surface (floor or gentle slope). Use cases: (1) Wall jump detection (if b3dIsCharacterOnWall(char) then allow wall jump), (2) Wall run mechanics (enable wall running when touching wall), (3) Animation control (play wall slide animation if on wall while airborne), (4) Ledge grab detection (check wall contact before raycast for ledge), (5) Climbing system (detect climbable walls). Common patterns: wall jump check if b3dIsCharacterOnWall(char) and Key(KEY_SPACE) then b3dCharacterWallJump(char, 10, 5), wall slide if b3dIsCharacterOnWall(char) and not b3dIsCharacterGrounded(char) then vy = Max(vy, -wallSlideSpeed), wall run if b3dIsCharacterOnWall(char) and running then EnableWallRun(). Typical usage: check before allowing wall jump (require wall contact + jump input), query each frame for wall slide effect (reduce fall speed when sliding down wall), combine with b3dIsCharacterGrounded for state machine (grounded, airborne, on wall states). Active contacts: Jolt CharacterVirtual maintains active contacts list (all surfaces currently touching character), contacts updated each physics step (added when collision starts, removed when collision ends), includes walls, floors, ceilings, any geometry in contact. Normal verticality check: for each contact calculate normalY = abs(normal.GetY()) (absolute value of Y component), check if normalY < 0.5 (mostly vertical surface, <60 degrees from vertical), return 1 immediately if any contact matches (early exit optimization, only need one wall). Wall angle threshold: normalY < 0.5 corresponds to surface >60 degrees from horizontal (slope too steep to walk on normally), includes vertical walls (normalY ~ 0), includes overhanging walls (normalY negative, ceiling-like but vertical), excludes walkable slopes (normalY >= 0.5, <60 degrees, character can walk up). Multiple walls: if character in corner touching multiple walls returns 1 (only need one wall detected), does not return wall count (binary yes/no, not how many walls), first wall contact triggers return 1 (early exit, doesn't check remaining contacts). Contact validity: checks contact.mBodyB not invalid (valid body ID, actual geometry not empty contact), skips invalid contacts (deleted bodies or placeholder contacts), ensures returned wall is real geometry. Performance: O(N) operation where N = active contact count (typically 1-4 contacts for character), early exit when wall found (best case O(1) if first contact is wall), contacts list small (Jolt optimizes contact count), safe to call every frame (designed for frequent queries). Wall detection delay: wall contacts updated during physics step (CharacterVirtual::Update ~60Hz), wall contact may be one frame delayed from actual collision (negligible delay at 60 FPS), fast-moving character may miss brief wall contact (contact exists for <1 frame). False positives: character brushing past wall corner may trigger wall detection (brief contact counts), character jumping against wall from below may detect wall (upward collision with wall normal pointing down), typically desired behavior (any wall touch = wall detected for responsive gameplay). False negatives: character on exactly 60 degree slope (normalY = 0.5 boundary) returns 0 (threshold exclusive not inclusive), very thin walls may not generate contacts (character passes through if moving too fast), character separated from wall by tiny gap returns 0 (no contact, no detection). Wall normal direction: normal points away from wall surface toward character (collision normal convention), for vertical wall normal horizontal (X and Z components non-zero, Y near 0), normal magnitude always 1.0 (normalized unit vector from Jolt). Ceiling vs wall: ceiling has normalY near -1 (points downward from ceiling), this function treats ceiling as wall (normalY absolute value < 0.5 if ceiling angle <60 degrees from vertical), typically ceilings horizontal so normalY = -1 (excluded by normalY < 0.5 check). Wall direction: function doesn't return wall normal direction (only binary wall yes/no), use b3dCharacterWallJump or custom code to get wall normal (iterate contacts, find wall contact, use normal for push direction). Validation: returns 0 if characterHandle not found in g_characters (invalid or freed character, treated as no wall contact), no error message (silent failure for performance in query function). Related: b3dCharacterWallJump performs wall jump (uses same wall detection internally to find push direction), b3dIsCharacterGrounded checks floor contact (complementary surface detection), b3dCreateCharacterController creates character controller (wall detection automatic after creation), b3dMoveCharacter sets movement (works with or without wall contact).