b3dGetCharacterWallNormalZ

Returns wall normal Z component (direction wall faces north-south, 0.0 if no wall contact). Takes characterHandle (character controller from b3dCreateCharacterController). Returns contact normal Z component (Z axis direction of wall surface normal, perpendicular to wall pointing away from wall), returns 0.0 if no wall contact. Use for wall running mechanics, wall jump direction, or wall alignment calculations.

This function queries wall normal. 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 normal found (stops at first wall contact, same wall as X and Y components). Wall normal meaning: contact normal is perpendicular to surface (points away from wall toward character, unit vector length 1.0), Z component is horizontal north-south direction (positive Z = wall faces north/forward, negative Z = wall faces south/backward), combined with X and Y forms complete normal vector (3D direction perpendicular to wall). Use cases: (1) Wall running direction (calculate movement direction parallel to wall), (2) Wall jump pushoff (push character away from wall using normal), (3) Wall alignment (orient character to face wall using normal), (4) Wall slide direction (calculate slide vector along wall surface), (5) Visual effects (spawn wall particles in normal direction). Common patterns: wall normal vector nz = b3dGetCharacterWallNormalZ(char) combined with X and Y, wall jump push character away vz = nz * pushForce, wall run direction parallel to wall runDir perpendicular to normal. Typical usage: query with X and Y components to get complete wall normal (all three form unit vector), use for wall mechanics (wall jump, wall run, wall slide calculations), combine all components for 3D wall direction.

Wall normal vector: normal is unit vector (length 1.0, normalized direction), perpendicular to wall surface (90 degrees angle from wall plane, points away from wall), points toward character (collision normal direction, outward from wall into character space). Normal Z component: Z axis horizontal north-south (positive = wall faces north/forward, negative = wall faces south/backward), magnitude -1.0 to +1.0 (unit vector component range, combined with X and Y), zero if wall perpendicular to Z (east-west wall has Z=0, only X component non-zero). Wall detection criteria: contact normal Y < 0.5 threshold (abs(normalY) < 0.5 means mostly horizontal normal, >60 degrees from horizontal = wall), excludes floors and ceilings (floor Y~1.0, ceiling Y~-1.0, both > 0.5 threshold), first wall found returned (doesn't average or prioritize, simply first in contact list). 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 jump example: detect wall contact (If b3dIsCharacterOnWall(char) Then hasWall = True), get wall normal (nx = b3dGetCharacterWallNormalX(char), ny = b3dGetCharacterWallNormalY(char), nz = b3dGetCharacterWallNormalZ(char)), push away from wall (vx = nx * pushSpeed, vy = jumpSpeed, vz = nz * pushSpeed), character bounces off wall realistically. Wall running example: get wall normal (nx, ny, nz from wall normal functions), calculate tangent vector (perpendicular to normal and up, cross product for wall-parallel direction), move along wall (character velocity along tangent vector, runs parallel to wall surface), maintains wall contact (stay close to wall while running along it). Wall orientation: normal points away from wall (toward character, direction character pushed when colliding), negative normal points into wall (opposite direction, toward wall interior), perpendicular to wall tangent (tangent is along wall surface, normal is across). Normal magnitude: components squared sum to 1.0 (nx^2 + ny^2 + nz^2 = 1.0, unit vector property), individual components -1.0 to +1.0 range (can be negative or positive depending on direction), wall normal Y component < 0.5 (guaranteed by wall detection, mostly horizontal normal vector). North-facing wall example: wall facing north has normal pointing north (positive Z, nz ~ 1.0), character on south side of wall (touching wall from south, wall blocks northward movement), wall jump pushes south (negative Z velocity, away from wall). South-facing wall example: wall facing south has normal pointing south (negative Z, nz ~ -1.0), character on north side of wall (touching wall from north, wall blocks southward movement), wall jump pushes north (positive Z velocity, away from wall). East-west wall: wall aligned east-west has minimal Z component (nz ~ 0.0, wall perpendicular to Z axis), normal primarily in X direction (nx ~ +/-1.0, wall faces east or west), Z component near zero (wall parallel to Z axis, normal perpendicular). Corner contacts: character in corner may contact multiple walls (two walls at different angles), function returns first wall found (not necessarily closest or most significant), consider checking all components for corner handling. Multiple wall contacts: only first wall returned (searches contacts until wall found, returns immediately), doesn't average normals (single wall normal, not blend of multiple), doesn't prioritize by angle (simply first in contact list order). Wall normal consistency: normal remains consistent while touching wall (same wall same normal, stable direction), changes when wall changes (switching walls updates normal, different surface different direction), updates every physics frame (CharacterVirtual contacts refreshed 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 b3dGetCharacterWallNormalX), Y axis vertical up-down (not queried by this function, see b3dGetCharacterWallNormalY). Normal vs contact position: this returns normal direction (which way wall faces, perpendicular to surface), b3dGetCharacterWallContactZ returns contact position (where collision occurred in world space), both describe same wall contact (different information about same collision point). Wall slide calculation: get wall normal (nx, ny, nz from functions), calculate velocity parallel to wall (project velocity onto wall plane, remove normal component), apply gravity and friction (slide down wall with friction resistance), realistic wall sliding (character slides along wall not into it). Wall tangent calculation: get wall normal (nx, ny, nz), calculate up vector (0, 1, 0 world up), cross product tangent = normal x up (perpendicular to both, along wall surface), wall run direction is tangent or -tangent (choose direction based on input or momentum). Visual effects: spawn particles at contact point (use b3dGetCharacterWallContactZ for position), emit particles in normal direction (particles move away from wall along normal), dust or sparks on wall touch (realistic contact effects), orient effect to normal (align particle spray perpendicular to wall). Character alignment: face character toward wall (rotate character to face opposite of normal, look at wall surface), align character to wall surface (use normal to rotate character parallel to wall, wall running pose), smooth rotation to wall (interpolate character orientation to wall normal over time). Wall jump direction: calculate pushoff direction from normal (push character away from wall nx, ny, nz scaled by push force), add upward component (combine normal push with upward velocity for jump arc), diagonal jump away from wall (realistic wall jump trajectory, away and up). Wall running parallel direction: calculate right vector for wall running (cross product of normal and up vector), run left or right along wall (move character in right or -right direction), perpendicular to normal (movement along wall surface, doesn't push into or away from wall). 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 and Y components (all three use 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, normal direction undefined), no error messages (silent failure, returns reasonable fallback). Related: b3dGetCharacterWallNormalX returns wall normal X component (east-west component, completes normal vector), b3dGetCharacterWallNormalY returns wall normal Y component (vertical component, completes normal vector), b3dGetCharacterWallContactZ returns wall contact position Z (world position of collision point), b3dIsCharacterOnWall checks for wall contact (prerequisite for valid wall normal).