b3dGetCharacterVelocityY

Returns vertical velocity Y in units/sec (positive=rising, negative=falling). Takes characterHandle (character controller from b3dCreateCharacterController). Returns velocity.Y component (vertical velocity along Y axis in world space units per second), reflects gravity, jumping, and falling. Use to detect jump state, calculate fall damage, or trigger landing effects.

This function queries vertical velocity. Velocity.Y meaning: vertical component of velocity vector (up/down movement speed), positive values = rising/jumping (moving upward against gravity), negative values = falling (moving downward with gravity), zero or near-zero = peak of jump or grounded. Returns velocity.Y (raw vertical velocity from Jolt physics, not actualVelocity), updated by gravity and jump forces (gravity pulls down, jump pushes up), reflects true vertical motion (physics-driven vertical movement). Use cases: (1) Fall damage calculation (check impact velocity when landing), (2) Jump detection (positive velocity means character is jumping), (3) Fall detection (negative velocity means character is falling), (4) Peak detection (velocity near zero at top of jump arc), (5) Animation state (blend jump/fall animations based on Y velocity). Common patterns: fall damage If vy < -10.0 Then damage = Abs(vy) - 10 where vy = b3dGetCharacterVelocityY(char), jump check If b3dGetCharacterVelocityY(char) > 1.0 Then jumping = True, fall check If b3dGetCharacterVelocityY(char) < -1.0 Then falling = True. Typical usage: query each frame for animation (blend jump/fall animations based on vertical velocity), check on ground contact event (calculate fall damage from landing velocity), detect jump apex (velocity crosses zero at peak).

Vertical velocity states: positive velocity > 2.0 units/sec (jumping state, character rising rapidly), positive velocity 0.0-2.0 (gentle rise or jump peak, nearly at apex), zero velocity ~0.0 (at jump peak or grounded, transitioning between rise and fall), negative velocity -2.0-0.0 (gentle fall or just leaving ground), negative velocity < -2.0 (falling state, character descending rapidly). Gravity effect: gravity constantly adds negative velocity (default -9.81 units/sec^2, pulls character down), velocity.Y decreases each frame when airborne (gets more negative over time, accelerating downward), terminal velocity may be clamped (maximum fall speed to prevent infinite acceleration). Jump effect: b3dCharacterJump sets positive velocity.Y (instant upward velocity, jump speed like 8.0 units/sec), gravity gradually reduces velocity (slows rise until velocity reaches zero at peak), then gravity makes velocity negative (character starts falling after peak). Grounded vs airborne: when grounded velocity.Y typically zero or very small (standing on floor, no vertical movement), when airborne velocity.Y non-zero (jumping up or falling down, affected by gravity), velocity.Y transitions smoothly (gradual change from positive to negative through jump arc). Fall damage example: store velocity on ground event (vy = b3dGetCharacterVelocityY(char) when character lands), calculate impact speed (fallSpeed = Abs(vy) take absolute value), apply damage based on speed (If fallSpeed > 15.0 Then damage = (fallSpeed - 15.0) * 2), threshold prevents low-fall damage (only fast falls cause injury). Jump detection example: check velocity sign each frame (vy = b3dGetCharacterVelocityY(char)), rising If vy > 1.0 Then playJumpAnimation (positive velocity means jumping up), falling If vy < -1.0 Then playFallAnimation (negative velocity means falling down), peak If Abs(vy) < 1.0 And not grounded Then playApexAnimation (near-zero velocity means at top of jump). Animation blending: get vertical velocity (vy = b3dGetCharacterVelocityY(char)), map to animation state (if vy > 2.0 jump anim, if vy < -2.0 fall anim, else in-air idle), blend based on velocity (animBlend = vy / maxJumpSpeed normalize to -1.0 to 1.0), smooth transitions (crossfade between jump and fall animations at peak). Landing impact effects: detect landing event (character transitions from airborne to grounded), sample velocity just before landing (landingVelocity = b3dGetCharacterVelocityY(char) when groundContact), play effect based on impact (loud thud and dust if landingVelocity < -10.0, soft step if > -5.0), realistic landing feedback (harder landings have more dramatic effects). Jump apex detection: track velocity over time (vy = b3dGetCharacterVelocityY(char) each frame), detect zero crossing (if previousVy > 0 And vy <= 0 Then atApex = True), trigger apex event (play apex animation, start fall sound, activate special ability), useful for air control timing (double-jump at apex, glide activation at peak). Velocity vs actualVelocity: velocity.Y is raw vertical physics velocity (Jolt CharacterVirtual linear velocity Y, affected by gravity and jumps), actualVelocity.Y would be smoothed horizontal equivalent (but Y is not smoothed, uses raw physics), this function returns raw physics velocity (not affected by acceleration smoothing). Coordinate system: Y-up coordinate system (positive Y is up, negative Y is down), velocity.Y positive means moving upward (rising, jumping, ascending), velocity.Y negative means moving downward (falling, descending), matches gravity direction (gravity is negative Y, -9.81 default). Velocity range: typical jump velocity +5.0 to +10.0 units/sec (initial upward velocity from jump), peak velocity near 0.0 (zero at top of jump arc, transitioning from rise to fall), typical fall velocity -5.0 to -20.0 units/sec (terminal velocity may limit max fall speed), extreme values possible with powerful jumps or long falls. Zero velocity interpretation: when grounded velocity.Y ~0.0 (standing still on floor, no vertical movement), at jump apex velocity.Y ~0.0 (peak of jump, moment of transition from rise to fall), requires context to distinguish (use b3dIsCharacterGrounded to determine if grounded or at apex). Performance: O(1) operation (simple float value return from data.velocity.Y, instant), no computation required (value updated during physics simulation, direct memory access), safe to call every frame multiple times (negligible cost). Validation: returns 0.0 if characterHandle not found in g_characters (invalid or freed character, safe default), no error messages (silent failure, returns reasonable fallback), assumes velocity is valid (set during UpdatePhysicsSystem). Related: b3dGetCharacterVelocityX returns horizontal velocity X (east/west component, complementary function), b3dGetCharacterVelocityZ returns horizontal velocity Z (north/south component, complementary function), b3dCharacterJump sets positive velocity.Y (initiates upward movement), b3dIsCharacterGrounded checks if vertical movement possible (grounded vs airborne affects Y velocity interpretation).