b3dGetCharacterWallNormalX

Returns wall normal X component (direction wall faces, 0.0 if no wall contact). Takes characterHandle (character controller from b3dCreateCharacterController). Returns contact normal X component (X 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 sliding effects.

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, doesn't average multiple walls). Wall normal meaning: contact normal is perpendicular to surface (points away from wall toward character, unit vector length 1.0), X component is horizontal east-west direction (positive X = wall faces east/right, negative X = wall faces west/left), combined with Y and Z 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 climbing orientation (align character to face wall using normal), (4) Wall slide friction (apply friction opposite to normal), (5) Visual effects (spawn wall-touch particles in normal direction). Common patterns: wall normal vector nx = b3dGetCharacterWallNormalX(char) ny = b3dGetCharacterWallNormalY(char) nz = b3dGetCharacterWallNormalZ(char), wall jump push character away vx = nx * pushForce, wall run direction parallel to wall runDir perpendicular to normal. Typical usage: query when wall contact detected (check b3dIsCharacterOnWall or b3dGetCharacterState wall flag first), use for wall mechanics (wall jump, wall run, wall slide calculations), combine all components for full normal vector.

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 X component: X axis horizontal east-west (positive = wall faces east, negative = wall faces west), magnitude -1.0 to +1.0 (unit vector component range, combined with Y and Z), zero if wall perpendicular to X (north-south wall has X=0, only Z 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 right vector (perpendicular to normal and up, cross product for wall-parallel direction), move along wall (character velocity along right 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 surface). East-facing wall example: wall facing east has normal pointing east (positive X, nx ~ 1.0), character on west side of wall (touching wall from west, wall blocks eastward movement), wall jump pushes west (negative X velocity, away from wall). West-facing wall example: wall facing west has normal pointing west (negative X, nx ~ -1.0), character on east side of wall (touching wall from east, wall blocks westward movement), wall jump pushes east (positive X velocity, away from wall). North-south wall: wall aligned north-south has minimal X component (nx ~ 0.0, wall perpendicular to X axis), normal primarily in Z direction (nz ~ +/-1.0, wall faces north or south), X component near zero (wall parallel to X 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: 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 b3dGetCharacterWallNormalY), Z axis horizontal north-south (not queried by this function, see b3dGetCharacterWallNormalZ). Normal vs contact position: this returns normal direction (which way wall faces, perpendicular to surface), b3dGetCharacterWallContactX 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). Visual effects: spawn particles at contact point (use b3dGetCharacterWallContactX for position), emit particles in normal direction (particles move away from wall along normal), dust or sparks on wall touch (realistic contact effects). 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), negligible overhead (fast search, call every frame acceptable). 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: b3dGetCharacterWallNormalY returns wall normal Y component (vertical component, completes normal vector), b3dGetCharacterWallNormalZ returns wall normal Z component (north-south component, completes normal vector), b3dGetCharacterWallContactX returns wall contact position X (world position of collision point), b3dIsCharacterOnWall checks for wall contact (prerequisite for valid wall normal).