b3dGetCharacterWallNormalY

Returns wall normal Y component (vertical tilt of wall, <0.5 guaranteed for walls). Takes characterHandle (character controller from b3dCreateCharacterController). Returns contact normal Y component (Y axis direction of wall surface normal, vertical component perpendicular to wall), returns 0.0 if no wall contact. Use for wall angle detection, sloped wall handling, or vertical wall mechanics.

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 Z components). Wall normal meaning: contact normal is perpendicular to surface (points away from wall toward character, unit vector length 1.0), Y component is vertical up-down direction (positive Y = wall tilts up/ceiling-like, negative Y = wall tilts down/floor-like, zero Y = perfectly vertical wall), combined with X and Z forms complete normal vector (3D direction perpendicular to wall). Use cases: (1) Wall angle detection (determine if wall is vertical or sloped), (2) Wall climbing validation (reject walls that are too steep or ceiling-like), (3) Wall sliding friction (steeper walls slide faster than vertical walls), (4) Animation selection (different animations for vertical vs sloped walls), (5) Gravity adjustment (modify gravity direction for wall running on slopes). Common patterns: wall normal vector ny = b3dGetCharacterWallNormalY(char) combined with X and Z, wall steepness check If Abs(ny) < 0.2 Then nearlyVertical = True, sloped wall If ny > 0.3 Then ceilingLike elseIf ny < -0.3 Then floorLike. Typical usage: query with X and Z components to get complete wall normal (all three form unit vector), check for vertical walls (Y near zero means vertical, Y > 0 means sloped upward), use for wall mechanic validation (too steep for wall running, ceiling-like surface).

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 Y component: Y axis vertical up-down (positive = wall leans back ceiling-like, negative = wall leans forward floor-like, zero = perfectly vertical wall), magnitude -0.5 to +0.5 for walls (wall detection requires abs(Y) < 0.5, excludes floors and ceilings), small Y values indicate vertical walls (Y near 0.0 means wall close to vertical, straight up surface). Wall detection guarantee: returned Y component always has abs(Y) < 0.5 (wall detection criteria, >60 degrees from horizontal), excludes floors (floor Y ~ 1.0, nearly horizontal surface pointing up), excludes ceilings (ceiling Y ~ -1.0, nearly horizontal surface pointing down). 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). Perfectly vertical wall: wall straight up has Y component near 0.0 (normal horizontal, no vertical component), wall perpendicular to ground plane (normal parallel to XZ plane, pure horizontal direction), typical for walls in buildings or cliffs. Sloped wall upward: wall leaning back has positive Y component (0.0 < Y < 0.5, ceiling-like slope), normal points upward somewhat (character below wall surface, wall overhangs), harder to climb (steeper than vertical, may require special mechanics). Sloped wall downward: wall leaning forward has negative Y component (-0.5 < Y < 0.0, floor-like slope), normal points downward somewhat (character above wall surface, wall recedes), easier to climb (gentler than vertical, nearly walkable slope). Wall angle calculation: angle from vertical = asin(normalY) (inverse sine of Y component gives tilt angle), 0 degrees = vertical wall (Y = 0.0, perfectly upright), +30 degrees = sloped back 30 degrees (Y ~ 0.5, leaning away from character), -30 degrees = sloped forward 30 degrees (Y ~ -0.5, leaning toward character). Wall climbing validation: check Y component for climbability (If Abs(ny) < 0.3 Then climbable = True else tooSteep = True), reject ceiling-like walls (If ny > 0.4 Then cannotClimb, too steep upward), reject floor-like walls (If ny < -0.4 Then cannotClimb, too steep downward), ensures reasonable climbing surfaces. Wall running mechanics: vertical walls best for wall running (Y ~ 0.0 allows horizontal running along wall), sloped walls affect running (positive Y gravity pulls character off wall, negative Y gravity presses into wall), adjust mechanics based on Y (modify friction or speed based on wall angle). 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 Y component -0.5 to +0.5 (guaranteed by wall detection criteria, mostly vertical). Coordinate system: Y axis vertical up-down (right-handed coordinate system, positive Y is up), X axis horizontal east-west (not queried by this function, see b3dGetCharacterWallNormalX), Z axis horizontal north-south (not queried by this function, see b3dGetCharacterWallNormalZ). Wall normal consistency: Y component remains consistent while touching wall (same wall same normal, stable angle), changes when wall changes (switching walls updates Y component, different slope different angle), updates every physics frame (CharacterVirtual contacts refreshed each frame). Multiple wall contacts: only first wall returned (searches contacts until wall found, returns immediately), Y component from same wall as X and Z (all three components describe same wall surface), doesn't average normals (single wall normal, not blend of multiple). Wall vs slope transition: wall has abs(Y) < 0.5 (>60 degrees from horizontal, mostly vertical), slope has abs(Y) >= 0.5 (<=60 degrees from horizontal, mostly horizontal), threshold creates distinction (walls for wall mechanics, slopes for ground mechanics). Gravity direction adjustment: sloped walls affect character differently (positive Y ceiling-like gravity pulls away, negative Y floor-like gravity presses in), modify gravity vector based on Y (adjust effective gravity for wall running physics), realistic wall interaction (steeper walls harder to stick to). Animation selection: vertical wall animation for Y ~ 0.0 (straight wall climb animation, no tilt), ceiling climb animation for Y > 0.3 (upward sloped wall, character hanging below), steep slope climb for Y < -0.3 (downward sloped wall, character climbing up incline), responsive animations (match character pose to wall angle). Wall friction calculation: wall steepness affects friction (more vertical = more friction, more sloped = less friction), friction = baseFriction * (1.0 - Abs(ny)) (reduce friction on sloped walls), character slides faster on sloped walls (gravity component along wall surface increases). Visual effects: character orientation matches wall angle (rotate character based on wall normal, align to wall surface), footprint decals angled correctly (project decals onto wall using normal), realistic wall interaction visuals. 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 Z 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), b3dGetCharacterWallNormalZ returns wall normal Z component (north-south component, completes normal vector), b3dGetCharacterWallContactY returns wall contact position Y (world position of collision point), b3dIsCharacterOnWall checks for wall contact (prerequisite for valid wall normal).