b3dGetCharacterWallContactZ

Returns wall contact position Z in world space (north-south position of wall touch, 0.0 if no wall). Takes characterHandle (character controller from b3dCreateCharacterController). Returns contact position Z coordinate (Z axis world space position where character touches wall), returns 0.0 if no wall contact. Use for spawning wall effects, placing wall decals, or calculating 3D wall contact 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 X/Y and normal components). Contact position meaning: position is world space coordinate (absolute position in 3D world, not relative to character or wall), Z component is north-south position (positive Z northward/forward, negative Z southward/backward in world coordinates), combined with X and Y forms complete 3D contact point (exact location where character capsule touches wall). Use cases: (1) Particle effects (spawn wall-touch particles at exact contact point), (2) Wall decals (place footprints or handprints on wall at precise position), (3) Sound positioning (3D audio at exact wall contact location), (4) Gameplay mechanics (grappling points, wall climb targets), (5) Visual feedback (highlight or mark exact wall contact point). Common patterns: contact position pz = b3dGetCharacterWallContactZ(char) combined with X and Y, complete position vector (px, py, pz) for 3D point, spawn effect SpawnParticles(px, py, pz) at exact contact. Typical usage: query with X and Y components to get complete 3D position (all three form world coordinate), use for visual or audio effects at contact point, combine all components for precise wall interaction location.

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: Z coordinate is absolute world position (not relative to character or wall, global north-south coordinate), matches entity position system (same coordinate space as b3dEntityZ, 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 complete contact position (px = b3dGetCharacterWallContactX(char), py = b3dGetCharacterWallContactY(char), pz = b3dGetCharacterWallContactZ(char)), spawn particles (SpawnWallDust(px, py, pz) at exact 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), precise decal placement (footprint or handprint at exact touch location). 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 exact contact location), realistic audio feedback (sound from precise contact point, accurate directional audio). Contact position relative to character: calculate offset from character (offsetZ = pz - b3dEntityZ(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 X/Y and 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: Z axis horizontal north-south (right-handed coordinate system, positive Z is north/forward), X axis horizontal east-west (not queried by this function, see b3dGetCharacterWallContactX), Y axis vertical up-down (not queried by this function, see b3dGetCharacterWallContactY). 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 placement: contact position for decal location (where to put decal on wall, X/Y/Z coordinates), wall 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 mechanics: contact position is attach point (where grappling hook connects to wall, anchor location in 3D), calculate rope vector (from character position to contact position, includes Z component), swing mechanics use contact as pivot (character swings around 3D contact point as center). 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 exact contact point (accurate 3D audio, sound from precise touch location), calculate distance attenuation (volume based on distance from camera to contact including Z), directional audio (sound intensity based on angle from listener to contact point). 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). Contact Z range: contact Z can be any world coordinate (any north-south position where wall exists, negative or positive Z), typical contact Z near character Z (within capsule radius of character, close to character position), extreme Z possible (walls at any world location, contact Z matches wall position). 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 X/Y and 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: b3dGetCharacterWallContactX returns wall contact position X (east-west coordinate, completes position vector), b3dGetCharacterWallContactY returns wall contact position Y (vertical coordinate, completes position vector), b3dGetCharacterWallNormalZ returns wall normal Z (direction wall faces north-south, complementary to position), b3dIsCharacterOnWall checks for wall contact (prerequisite for valid wall contact position).