b3dCharacterJump

Makes character jump with upward velocity (jumpSpeed in units/sec, uses coyote time 0.15sec after leaving ground). Takes characterHandle (character controller from b3dCreateCharacterController), jumpSpeed (initial upward velocity in units/sec, typical values 7-12 for realistic jump). Returns nothing. Sets vertical velocity to jumpSpeed if grounded or within coyote time, resets coyote timer to prevent double jumping. Use for player jumping, NPC jumps, platformer mechanics.

This function initiates jump. Jump parameters: jumpSpeed (upward velocity in units/sec, affects jump height, higher speed = higher jump, typical values: 7=low jump, 10=medium jump, 12=high jump, 15=very high jump). Jump height calculation: approximate max height = jumpSpeed^2 / (2*gravity) (physics formula for vertical motion, gravity default -9.81 units/sec^2), jumpSpeed=10 gives height ~ 100/(2*9.81) ~ 5.1 units, jumpSpeed=7 gives height ~ 49/(2*9.81) ~ 2.5 units. Coyote time: allows jumping shortly after leaving ground (grace period COYOTE_TIME=0.15 seconds), prevents frustrating missed jumps (player presses jump just after walking off edge), feels responsive (player intention recognized even if slightly late). Coyote time implementation: timeSinceGrounded tracks time since last grounded (incremented each frame while airborne, reset to 0 when grounded), canJump = (timeSinceGrounded <= 0.15) allows jump if grounded recently, timeSinceGrounded set to >0.15 after jump (prevents double jumping during grace period). Use cases: (1) Player jump (bind to spacebar or button for player jumping), (2) Platformer mechanics (precise jump control for platform games), (3) AI jumping (NPC jumps over obstacles or to reach targets), (4) Double jump (call twice with different speeds for double jump powerup). Common patterns: simple jump if Key(KEY_SPACE) and b3dIsCharacterGrounded(char) then b3dCharacterJump(char, 10), coyote jump if Key(KEY_SPACE) then b3dCharacterJump(char, 10) (relies on coyote time internally), variable jump if Key(KEY_SPACE) then if crouching then b3dCharacterJump(char, 7) else b3dCharacterJump(char, 10). Typical usage: call once when jump button pressed (not every frame), check b3dIsCharacterGrounded first if strict grounded-only jumping desired (bypasses coyote time), combine with jump animation trigger (play jump anim when function called). Vertical velocity: sets data.velocity.Y = jumpSpeed directly (replaces current vertical velocity, stops falling or previous jump), horizontal velocity unaffected (preserves horizontal movement during jump), velocity decreased by gravity each frame (UpdatePhysicsSystem applies gravity, vy -= 9.81 * dt). Jump height control: jumpSpeed determines peak height (higher speed = higher peak), gravity determines fall rate (lower gravity = floatier jump, higher gravity = snappier jump), air control affects horizontal control (default 30% control mid-air). Grounded check: function checks timeSinceGrounded internally (does not call b3dIsCharacterGrounded), coyote time allows jump if timeSinceGrounded <= 0.15 even if not currently grounded, prevents jump if airborne too long (realistic, can't jump while falling). Double jump prevention: timeSinceGrounded set to >0.15 after jump (prevents immediate second jump from coyote time), only one jump allowed per grounded period (unless double jump explicitly implemented separately), respects realistic physics (can't jump again until landing). Coyote timer reset: timeSinceGrounded reset to 0 when character becomes grounded (tracked in UpdatePhysicsSystem), timeSinceGrounded incremented by deltaTime each frame when airborne (accumulates air time), allows coyote time window after leaving ground (walk off ledge, have 0.15sec to jump). Jump timing: typical usage check grounded then jump immediately (player presses jump while standing), coyote time allows late jump (player presses jump within 0.15sec of leaving edge), early jump queuing not built-in (would require separate input buffering system). Gravity interaction: after jump gravity applies each frame (vy decreases by ~9.81 units/sec^2), character rises until vy becomes negative (peak of jump when vy=0), character falls with increasing downward velocity (vy becomes more negative). Jump arc: typical arc with jumpSpeed=10 (frame 0: vy=10, rising at 10 units/sec, frame ~0.5sec: vy~5, still rising but slower, frame ~1sec: vy=0, at peak height ~5 units, frame ~1.5sec: vy~-5, falling, frame ~2sec: vy~-10, falling at original jump speed, lands shortly after), realistic parabolic trajectory. Performance: O(1) operation (simple velocity set, two float assignments and comparison), no physics simulation triggered (actual movement in UpdatePhysicsSystem), safe to call every frame (designed for input-driven calls). Jump buffering: not built into function (would need external input buffer, store jump press, execute when grounded), coyote time handles late jumps (pressed after leaving ground), combine both for very forgiving jump controls (buffer early press + coyote time late press). Validation: silently returns if g_physicsSystem not initialized (b3dInitPhysics not called), silently returns if characterHandle not found in g_characters (invalid or freed character), no clamping on jumpSpeed (any value allowed, negative speed makes character fall faster). Related: b3dIsCharacterGrounded checks if on ground (use to determine if jump allowed), b3dMoveCharacter sets horizontal velocity (combine with jumping for full control), b3dCreateCharacterController creates character controller (required before jumping), b3dCharacterWallJump performs wall jump (alternative jump type with push-away).