b3dGetPhysicsBodyVelocityZ

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

This function retrieves Z velocity component. Return value: velocity in world units per second along Z-axis (positive = forward, negative = backward), reflects current physics simulation state (updated by Jolt each frame), includes effects of gravity, collisions, forces, friction, 0.0 on error (physics not initialized or invalid bodyHandle). Use cases: (1) Character control (read forward/backward speed to clamp or modify velocity), (2) Movement detection (check if body moving forward/backward for animation triggers), (3) Speed display (show forward velocity in UI or speedometer), (4) Conditional logic (if moving forward then apply boost), (5) Velocity modification (read current, modify, write back with b3dSetPhysicsBodyVelocity). Common patterns: clamp speed vz = b3dGetPhysicsBodyVelocityZ(body) then if Abs(vz) > maxSpeed then vz = Sgn(vz) * maxSpeed, check direction if b3dGetPhysicsBodyVelocityZ(car) > 0 then print "Moving forward", preserve vertical vy = b3dGetPhysicsBodyVelocityY(player) then b3dSetPhysicsBodyVelocity(player, newVX, vy, newVZ). Typical usage: read before modifying velocity to preserve components (maintain vertical while changing horizontal), use in character controller to implement speed limits, combine with b3dGetPhysicsBodyVelocityX/Y for full velocity vector. 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 vz component (use b3dGetPhysicsBodyVelocityX for vx, b3dGetPhysicsBodyVelocityY for vy), 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), Z-axis velocity independent of body rotation (world space not local space), positive vz always moves forward in world Z direction regardless of body facing. Velocity sources: velocity affected by many physics factors (gravity adds downward vy each frame but not vz, collisions reverse/reduce velocity components, friction opposes tangential velocity including vz, manually set velocity via b3dSetPhysicsBodyVelocity overrides), this function returns current result of all factors combined. Character controller integration: typical pattern read all three components (vx = b3dGetPhysicsBodyVelocityX(player), vy = b3dGetPhysicsBodyVelocityY(player), vz = b3dGetPhysicsBodyVelocityZ(player)), modify horizontal based on input (vx = inputX * walkSpeed, vz = inputZ * walkSpeed), preserve vertical for gravity/jumping (keep vy unchanged), write back (b3dSetPhysicsBodyVelocity(player, vx, vy, vz)). Speed limiting: max horizontal speed maxH = 10 then vx = b3dGetPhysicsBodyVelocityX(body) then vz = b3dGetPhysicsBodyVelocityZ(body) then hSpeed = Sqrt(vx*vx + vz*vz) then if hSpeed > maxH then scale = maxH / hSpeed then vx *= scale then vz *= scale then b3dSetPhysicsBodyVelocity(body, vx, vy, vz). 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), velocity queries on static bodies always return 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.GetZ() to extract Z 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), b3dGetPhysicsBodyVelocityY gets Y-axis velocity (vertical up/down movement), b3dSetPhysicsBodyVelocity sets linear velocity (write velocity components), b3dCreatePhysicsBody creates physics body (call this before querying velocity).