b3dCharacterWallJump

Performs wall jump (jumps up at jumpSpeed, pushes away from wall at pushAwaySpeed horizontally). Takes characterHandle (character controller from b3dCreateCharacterController), jumpSpeed (upward velocity in units/sec for jump), pushAwaySpeed (horizontal push velocity away from wall in units/sec). Returns nothing. Finds wall contact, calculates push direction perpendicular to wall, sets vertical velocity to jumpSpeed, adds horizontal impulse away from wall. Use for wall jump mechanics in platformers.

This function performs wall jump. Wall jump parameters: jumpSpeed (upward velocity component, affects jump height, typical values 7-12 for realistic wall jump, same as normal jump), pushAwaySpeed (horizontal push component away from wall, affects distance from wall, typical values 3-8, less than jump speed for realistic arc). Wall jump mechanics: sets vertical velocity = jumpSpeed (upward component, same as normal jump), applies horizontal impulse = pushDirection * pushAwaySpeed (pushes character away from wall, preserves momentum via impulse system), combines to create diagonal trajectory (up and away from wall). Use cases: (1) Wall jump platforming (jump between parallel walls to climb vertical shaft), (2) Wall escape (jump away from wall to reach distant platform), (3) Advanced movement (chain wall jumps for fast vertical climbing), (4) Parkour mechanics (realistic wall interaction for freerunning gameplay). Common patterns: simple wall jump if b3dIsCharacterOnWall(char) and Key(KEY_SPACE) then b3dCharacterWallJump(char, 10, 5), variable wall jump if crouching then b3dCharacterWallJump(char, 7, 3) else b3dCharacterWallJump(char, 10, 6), wall jump chain if b3dIsCharacterOnWall(char) and not b3dIsCharacterGrounded(char) then allow wall jump. Typical usage: call when wall jump input detected (check b3dIsCharacterOnWall + jump button), combine with wall slide for complete wall mechanics (slide down wall at reduced speed, wall jump to escape), trigger wall jump animation when called (play push-off animation). Wall contact detection: iterates CharacterVirtual active contacts (same as b3dIsCharacterOnWall), finds first contact with normalY < 0.5 (vertical surface >60 degrees from horizontal), uses contact normal as push direction (normal points away from wall toward character). Push direction calculation: contact normal points from wall toward character (away from wall), sets normal.Y = 0 to get horizontal component only (zeros vertical, keeps X and Z), normalizes horizontal direction (divides by length if length > 0.001, ensures unit vector), prevents upward/downward push (only horizontal push perpendicular to wall). Velocity application: vertical component set directly (velocity.Y = jumpSpeed, replaces current vertical velocity, stops falling), horizontal component applied as impulse (impulseVelocity += pushDirection * pushAwaySpeed, preserves momentum, combined with input in UpdatePhysicsSystem). Impulse vs direct velocity: vertical uses direct velocity set (immediate upward velocity, overrides falling), horizontal uses impulse (adds to existing momentum, doesn't replace horizontal velocity completely), allows player to influence direction mid-jump (air control applies to impulse velocity). Wall normal interpretation: normal for vertical wall has X and Z components (horizontal direction perpendicular to wall), normal.Y near 0 for vertical wall (purely horizontal push direction), normalizing ensures consistent push speed (pushAwaySpeed independent of wall angle). Multiple walls handling: uses first wall found in contacts (early exit after first normalY < 0.5), if character in corner touching multiple walls uses arbitrary wall (whichever comes first in contacts list), typically doesn't matter (any wall push direction works, player in corner). No wall handling: if no wall contact found (no contacts or all contacts floors/ceilings) function returns early (no jump executed), silently fails (no error message, no velocity change), check b3dIsCharacterOnWall before calling to ensure wall exists. Debug logging: writes to C:\Users\denat\walljump_debug.txt (developer debug file, logs wall jump attempts), logs current velocity and pendingImpulse before jump (useful for debugging trajectory issues), logs contact normals and wall detection (helps verify wall contact working), logs push direction and speeds (confirms correct wall normal calculation). Velocity preservation: horizontal push added to impulseVelocity (doesn't replace existing horizontal velocity, combines with player input and sliding forces), allows player to influence jump arc (move joystick while wall jumping affects trajectory), creates responsive wall jump feel (not pure physics, some player control). Wall jump trajectory: typical arc with jumpSpeed=10, pushAwaySpeed=5 (frame 0: vy=10 up, horizontal impulse=5 away, character leaves wall diagonally, frame ~0.5sec: vy~5 up, horizontal maintained by impulse, character moving up and away, frame ~1sec: vy=0 peak, horizontal still active, character at apex away from wall, frame ~1.5sec: vy~-5 down, horizontal decaying, character falling in arc, lands away from wall). Air control interaction: after wall jump player has 30% air control (default airControl = 0.3), allows subtle trajectory adjustment (can move back toward wall or further away), prevents full directional change (can't reverse horizontal completely mid-air). Wall jump chaining: player can wall jump repeatedly (jump to opposite wall, wall jump again, repeat to climb), each wall jump pushes away from current wall (alternates direction in vertical shaft), requires timing and positioning (must be touching wall to wall jump). Performance: O(N) operation where N = active contact count (iterates contacts to find wall, typically 1-4 contacts), early exit when wall found (best case O(1) if first contact is wall), safe to call every frame if desired (designed for input-driven calls). Validation: silently returns if characterHandle not found in g_characters (invalid or freed character), silently returns if no wall contact found (no vertical surfaces in contacts), no validation on speeds (any values allowed, negative speeds reverse direction). Related: b3dIsCharacterOnWall checks wall contact (use before wall jump to verify wall exists), b3dCharacterJump performs normal jump (alternative jump type without push-away), b3dMoveCharacter sets horizontal movement (combines with wall jump impulse), b3dCreateCharacterController creates character controller (required before wall jumping).