b3dGetCharacterWallContactY

Returns wall contact position Y in world space (height of wall touch, 0.0 if no wall). Takes characterHandle (character controller from b3dCreateCharacterController). Returns contact position Y coordinate (Y axis world space height where character touches wall), returns 0.0 if no wall contact. Use for spawning wall effects at correct height, IK hand placement, or wall contact height detection.

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/Z and normal components). Contact position meaning: position is world space coordinate (absolute position in 3D world, not relative to character or wall), Y component is vertical height (positive Y upward, world altitude of contact point), combined with X and Z forms complete 3D contact point (exact location where character capsule touches wall). Use cases: (1) IK hand placement (position character hands at correct height on wall for climbing), (2) Wall effect height (spawn particles or decals at actual touch height), (3) Sound positioning (3D audio at correct vertical position), (4) Foothold detection (check contact height for climbing ledges or footholds), (5) Visual feedback (highlight wall contact point at correct height). Common patterns: contact position py = b3dGetCharacterWallContactY(char) combined with X and Z, hand IK handY = py for climb animation, effect spawn SpawnEffect(px, py, pz) at contact height. Typical usage: query with X and Z components to get complete 3D position (all three form world coordinate), use for IK targets at wall contact height, spawn effects at actual touch height not approximate.

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 Y typically within character height range (between character bottom and top, depends on which part of capsule touches). 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: Y coordinate is absolute world height (not relative to character or wall, global altitude), matches entity position system (same coordinate space as b3dEntityY, b3dSetEntityPosition), can be used directly for entity placement (spawn effect entity at contact height). 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). IK hand placement example: get contact position for hand target (px = b3dGetCharacterWallContactX(char), py = b3dGetCharacterWallContactY(char), pz = b3dGetCharacterWallContactZ(char)), position hand at contact (handIK.SetTarget(px, py, pz) place hand on wall), realistic climbing animation (hands grab wall at actual contact points and heights). Wall climb foothold detection: get contact height (contactY = b3dGetCharacterWallContactY(char)), compare to character height (heightAboveGround = contactY - characterGroundY), check if reachable foothold (If heightAboveGround < reachHeight Then canStepUp = True), foothold height validation (ensure foothold not too high or low). Particle effect height: get contact position for effect (py = b3dGetCharacterWallContactY(char) along with X and Z), spawn particles at correct height (SpawnWallDust(px, py, pz) at actual touch point), particles appear at contact not character center (realistic visual feedback, effect at hand or body touch height). Contact height relative to character: contact Y within capsule range (character bottom Y <= contact Y <= character top Y, depends on contact point), contact higher when reaching up (hands touch wall above character center), contact lower when sliding (feet or lower body touch wall below center). Multiple contact heights: character may touch wall at multiple heights (hands high, feet low, multiple contact points), function returns first wall contact only (not necessarily highest or lowest, first in contact list), consider multiple queries for complex climbing (separate hand and foot contacts). Contact height for climbing: ascending wall contact Y increases (climbing up moves contact point higher), descending wall contact Y decreases (climbing down moves contact point lower), contact height tracks character climb progress (Y coordinate shows vertical climb position). Handhold positioning: left hand at contact position (leftHandY = py from current contact), right hand offset higher (rightHandY = py + handSpacing for alternating grip), IK targets from contact heights (realistic hand placement while climbing). Contact height stability: height changes as character moves vertically (climbing or falling updates contact Y), height stable while stationary horizontally (moving along wall at same height keeps contact Y constant), updates every physics frame (CharacterVirtual refreshes contacts each frame). 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 b3dGetCharacterWallContactX), Z axis horizontal north-south (not queried by this function, see b3dGetCharacterWallContactZ). Contact height vs wall normal: height is where contact occurs (vertical position in world space, Y coordinate), normal is direction perpendicular to wall (unit vector direction, not position), both describe same wall contact (height where, normal which way wall faces). Decal height placement: contact height for decal Y position (where to place decal vertically on wall), decal at actual touch height not character center (realistic wall marking at correct altitude), combine with X and Z for complete decal position. Grappling hook height: contact height is rope attach point Y (vertical position where hook connects to wall), calculate rope vector from character to contact height (includes vertical component for rope physics), swing mechanics use contact height (character swings with rope attached at specific wall height). Sound height positioning: position 3D audio at contact height (sound from actual touch point not character center), calculate distance from listener including height (accurate 3D audio with vertical position), directional audio with height (sound from above or below listener based on contact Y). Contact height range: contact Y can be any world height (any vertical position where wall exists, negative Y underground positive Y above ground), typical contact Y near character Y (within character capsule height, +/-height/2 from character center), extreme contact Y possible (very tall walls, character at bottom or top). Effect spawning at height: create effect entity at contact height (effectEntity = b3dCreateEntity(), b3dSetEntityPosition(effectEntity, px, py, pz)), effect at correct wall height not ground level (particles or sparks at actual touch point), height-appropriate effects (dust at feet, sparks at hands based on contact Y). Climbing ledge detection: check contact height vs target height (ledgeY = targetLedgeHeight, contactY = b3dGetCharacterWallContactY(char)), determine if character reached ledge (If Abs(contactY - ledgeY) < threshold Then atLedge = True), height-based climb progression (track vertical progress by contact Y). Contact height persistence: height valid only while wall contact exists (contact Y changes or disappears when character leaves wall), store height if needed (save py when leaving wall for delayed effects), height may jump between frames (if switching walls or climbing, contact Y can change rapidly). 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/Z 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), b3dGetCharacterWallContactZ returns wall contact position Z (north-south coordinate, completes position vector), b3dGetCharacterWallNormalY returns wall normal Y (vertical tilt of wall, complementary to position), b3dIsCharacterOnWall checks for wall contact (prerequisite for valid wall contact position).