b3dGetPhysicsBodyVelocityY

Gets physics body Y-axis linear velocity in units/sec (vertical movement speed, affected by gravity). Takes bodyHandle (physics body from b3dCreatePhysicsBody). Returns Y-component of linear velocity in world units per second (positive = moving up, negative = falling down, 0.0 if physics not initialized or body not found). Queries Jolt BodyInterface.GetLinearVelocity, extracts Y component. Read-only state query.

This function retrieves Y velocity component. Return value: velocity in world units per second along Y-axis (positive = upward, negative = downward), reflects current physics simulation state (gravity adds downward acceleration each frame), includes effects of gravity, collisions, forces, friction, 0.0 on error (physics not initialized or invalid bodyHandle). Use cases: (1) Jump detection (check if player moving upward for jump animation), (2) Falling detection (check if negative for falling/landing logic), (3) Ground check (vy near 0 = on ground, vy < 0 = falling, vy > 0 = jumping), (4) Velocity preservation (read vy to preserve vertical while changing horizontal), (5) Terminal velocity limiting (clamp vy to prevent excessive falling speed). Common patterns: check grounded if Abs(b3dGetPhysicsBodyVelocityY(player)) < 0.1 then grounded = TRUE, limit fall speed vy = b3dGetPhysicsBodyVelocityY(body) then if vy < -maxFallSpeed then b3dSetPhysicsBodyVelocity(body, vx, -maxFallSpeed, vz), preserve vertical vx = b3dGetPhysicsBodyVelocityX(player) then vy = b3dGetPhysicsBodyVelocityY(player) then vz = b3dGetPhysicsBodyVelocityZ(player) then b3dSetPhysicsBodyVelocity(player, newVX, vy, newVZ). Typical usage: read every frame for jump/fall state detection, combine with position check for landing detection (vy < 0 and on platform = just landed), use in character controller to preserve gravity while controlling horizontal movement. Gravity effects: dynamic bodies (mass>0) have gravity applied each frame (vy decreases by ~9.81 units/sec^2 unless custom gravity), vy becomes increasingly negative when falling (accelerates downward), vy positive when jumping or moving upward (decreases due to gravity until apex then falls). Terminal velocity: vy can become very negative during long falls (no default limit), manual clamping recommended for gameplay feel (prevents instant death from high falls, reduces fall speed to safe range), air resistance not applied by default (damping can simulate). Velocity vector: full linear velocity = (vx, vy, vz) in world space (X-axis horizontal right, Y-axis vertical up, Z-axis depth forward), this function returns only vy component (use b3dGetPhysicsBodyVelocityX for vx, b3dGetPhysicsBodyVelocityZ for vz), combine all three for magnitude calculation (speed = Sqrt(vx*vx + vy*vy + vz*vz)). World space coordinates: velocity in BambooBasic Y-up world coordinates (same as position system), Y-axis velocity independent of body rotation (world space not local space), positive vy always moves up regardless of body orientation. Velocity sources: gravity constantly adds downward acceleration (vy -= gravity * deltaTime each frame, typically gravity = 9.81 or custom value), collisions with floors/ceilings reverse or zero vy component, jumping sets positive vy manually (b3dSetPhysicsBodyVelocity with positive vy), air friction/damping reduces vy over time if configured. Ground detection pattern: typical check vy = b3dGetPhysicsBodyVelocityY(player) then if vy > -0.1 and vy < 0.1 then onGround = TRUE (small epsilon handles floating point precision), combine with raycast downward for robust ground check (velocity alone insufficient, may be zero in air briefly). Jump/fall states: vy > 0.1 = jumping/ascending (moving upward), vy near 0 = apex or grounded (peak of jump or standing), vy < -0.1 = falling/descending (moving downward), state transitions trigger animations (jump anim when vy positive, fall anim when vy negative). Performance: O(1) operation (simple velocity component read via Jolt BodyInterface), safe to call every frame (no side effects, read-only query), instant (no physics simulation triggered). Static body behavior: static bodies (mass=0) always have velocity (0,0,0) since immovable (returns 0.0 for all components), not affected by gravity (infinite mass, vy always 0.0). Error handling: returns 0.0 if g_physicsSystem not initialized (b3dInitPhysics not called), returns 0.0 if bodyHandle not found in g_bodyHandleToBodyID (invalid or freed body), no error message printed (silent failure for performance). Jolt integration: calls g_physicsSystem->GetBodyInterface().GetLinearVelocity(bodyID) to get Vec3 velocity, calls velocity.GetY() to extract Y component as float, converts float to double for BambooBasic return. Validation: no validation needed (always returns valid number, 0.0 on error). Related: b3dGetPhysicsBodyVelocityX gets X-axis velocity (horizontal right/left movement), b3dGetPhysicsBodyVelocityZ gets Z-axis velocity (forward/backward movement), b3dSetPhysicsBodyVelocity sets linear velocity (write vy to jump or stop falling), b3dSetPhysicsGravity sets gravity acceleration (affects rate of vy change).