b3dGetCharacterWallContactX

Returns wall contact position X in world space (where character touches wall, 0.0 if no wall). Takes characterHandle (character controller from b3dCreateCharacterController). Returns contact position X coordinate (X axis world space position where character touches wall), returns 0.0 if no wall contact. Use for spawning wall contact effects, placing wall decals, or calculating wall interaction points.

This function queries wall contact position. Wall detection: searches CharacterVirtual active contacts (all current collision points from physics update), identifies wall contacts (contact normal Y component < 0.5 means >60 degrees from horizontal, mostly vertical surface), returns first wall contact position found (stops at first wall contact, same wall as normal components). Contact position meaning: position is world space coordinate (absolute position in 3D world, not relative to character or wall), X component is east-west position (positive X eastward, negative X westward in world coordinates), combined with Y and Z forms complete 3D contact point (exact location where character capsule touches wall). Use cases: (1) Particle effects (spawn wall-touch particles at contact point), (2) Decals (place footprints or handprints on wall at contact position), (3) Sound positioning (play wall-touch sound at contact location for 3D audio), (4) Gameplay mechanics (grappling hook attach point, wall climb hand position), (5) Visual feedback (highlight or mark wall contact point for player). Common patterns: contact position px = b3dGetCharacterWallContactX(char) py = b3dGetCharacterWallContactY(char) pz = b3dGetCharacterWallContactZ(char), spawn effect SpawnParticles(px, py, pz), place decal PlaceDecal(px, py, pz, wallNormal). Typical usage: query when wall contact detected (check b3dIsCharacterOnWall first), combine all components for 3D position (all three X/Y/Z form world coordinate), use for visual or audio effects at contact point.

Contact position vs character position: contact position is where collision occurs (surface point on wall where character touches), character position is center of capsule (mid-height of character controller), contact position typically near character (within capsule radius + padding distance from character center). Contact position accuracy: position from Jolt CharacterVirtual contact (exact collision point calculated by physics engine), updated every physics frame (ContactList refreshed during UpdatePhysicsSystem), accurate to physics precision (~0.001 units, sub-millimeter accuracy). World space coordinates: X coordinate is absolute world position (not relative to character or wall, global coordinate system), matches entity position system (same coordinate space as b3dEntityX, b3dSetEntityPosition), can be used directly for entity placement (spawn effect entity at contact position). Return zero cases: no wall contact (character not touching any vertical surfaces, airborne or on ground only), invalid character handle (characterHandle not found in g_characters map), only non-wall contacts (all contacts are floors or ceilings, no vertical surfaces). Wall contact position determination: Jolt calculates contact position during collision (intersection point of character capsule and wall geometry), position is on wall surface (exact point on wall mesh or collision shape), may be slightly offset from wall (collision detection tolerance, minimal penetration). Particle effect example: detect wall contact (If b3dIsCharacterOnWall(char) Then onWall = True), get contact position (px = b3dGetCharacterWallContactX(char), py = b3dGetCharacterWallContactY(char), pz = b3dGetCharacterWallContactZ(char)), spawn particles (SpawnDustParticles(px, py, pz) at contact point), get wall normal for direction (emit particles away from wall using normal). Wall decal example: get contact position for decal placement (px, py, pz from contact functions), get wall normal for decal orientation (nx, ny, nz from normal functions), place decal on wall (CreateDecal(px, py, pz, nx, ny, nz) aligned to wall surface), footprint or handprint on wall (visual indication of wall contact). Sound positioning example: get contact position for 3D audio (px, py, pz from contact functions), play positioned sound (Play3DSound("wall_touch.wav", px, py, pz) at contact location), realistic audio feedback (sound comes from exact contact point, directional audio). Wall climb hand position: get contact position for IK target (handX = px, handY = py, handZ = pz), position character hand at contact (IK solver places hand at wall touch point), realistic climbing animation (hands grab wall at actual contact positions). Contact position relative to character: calculate offset from character (offsetX = px - b3dEntityX(characterEntity)), offset is contact direction (vector from character to wall contact point), typically within capsule radius (contact near character surface, distance = radius + padding). Multiple wall contacts: only first wall returned (searches contacts until wall found, returns immediately), position from same wall as normal (X/Y/Z position and X/Y/Z normal describe same wall contact), doesn't average positions (single contact point, not blend of multiple). Contact position stability: position changes as character moves along wall (contact point slides along wall surface, follows character movement), position stable while stationary on wall (consistent contact point while not moving), updates every physics frame (CharacterVirtual refreshes contacts each frame). Coordinate system: X axis horizontal east-west (right-handed coordinate system, positive X is east/right), Y axis vertical up-down (not queried by this function, see b3dGetCharacterWallContactY), Z axis horizontal north-south (not queried by this function, see b3dGetCharacterWallContactZ). Contact position vs wall normal: position is where contact occurs (location in world space, 3D coordinate), normal is direction perpendicular to wall (unit vector direction, not position), both describe same wall contact (position where, normal which way wall faces). Decal orientation: position for decal placement (where to put decal on wall, X/Y/Z coordinates), normal for decal rotation (how to orient decal on wall surface, perpendicular to wall), combine both (decal at position aligned to normal, realistic wall marking). Grappling hook mechanics: contact position is attach point (where grappling hook connects to wall, anchor location), calculate rope length (distance from character to contact position), swing mechanics use contact as pivot (character swings around contact point as center). Wall climb hand placement: alternate hands at different contact heights (left hand at contact position, right hand offset up and sideways), IK targets from contact position (place hands realistically on wall), smooth transition as climbing (update contact position as character ascends wall). Contact height relative to character: contact Y typically near character Y (within capsule height/2 of character center), contact can be higher or lower (depending on which part of capsule touches wall), contact Y useful for animation (hand placement height based on contact Y position). Effect spawning: create effect entity at contact (effectEntity = b3dCreateEntity(), b3dSetEntityPosition(effectEntity, px, py, pz)), orient effect to wall (use wall normal to rotate effect entity, particles emit correctly), timed effect removal (delete effect after duration, temporary visual feedback). 3D audio positioning: position sound at contact point (accurate 3D audio, sound from exact touch location), calculate distance attenuation (volume based on distance from camera to contact), directional audio (sound intensity based on angle from listener to contact). Contact position persistence: position valid only while wall contact exists (contact point changes or disappears when character leaves wall), store position if needed (save px, py, pz when leaving wall for delayed effects), position may jump between frames (if switching between walls, contact position teleports to new wall). Wall surface mapping: contact position on wall mesh (exact surface point on wall geometry), can be used for texture mapping (UV coordinates for decal placement), precise wall interaction (contact exactly where character touches, not approximate). Performance: O(N) operation where N is active contacts (searches contact list for wall, typically 1-4 contacts), returns immediately when wall found (short-circuits on first wall, no further iteration), same search as normal components (position and normal from same wall detection, call together efficient). Validation: returns 0.0 if characterHandle not found (invalid or freed character, safe default), returns 0.0 if no wall contact (no vertical surface touching, position undefined), no error messages (silent failure, returns reasonable fallback). Related: b3dGetCharacterWallContactY returns wall contact position Y (vertical coordinate, completes position vector), b3dGetCharacterWallContactZ returns wall contact position Z (north-south coordinate, completes position vector), b3dGetCharacterWallNormalX returns wall normal X (direction wall faces, complementary to position), b3dIsCharacterOnWall checks for wall contact (prerequisite for valid wall contact position).