b3dGetPhysicsBodyVelocityX

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

This function retrieves X velocity component. Return value: velocity in world units per second along X-axis (positive = right, negative = left), 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 horizontal speed to clamp or modify velocity), (2) Movement detection (check if body moving left/right for animation triggers), (3) Speed display (show horizontal velocity in UI or debug overlay), (4) Conditional logic (if moving right then apply different physics), (5) Velocity modification (read current, modify, write back with b3dSetPhysicsBodyVelocity). Common patterns: clamp speed vx = b3dGetPhysicsBodyVelocityX(body) then if Abs(vx) > maxSpeed then vx = Sgn(vx) * maxSpeed, check direction if b3dGetPhysicsBodyVelocityX(player) > 0 then print "Moving right", 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 b3dGetPhysicsBodyVelocityY/Z 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 vx component (use b3dGetPhysicsBodyVelocityY for vy, 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), X-axis velocity independent of body rotation (world space not local space), positive vx always moves right regardless of body facing direction. Velocity sources: velocity affected by many physics factors (gravity adds downward vy each frame, collisions reverse/reduce velocity components, friction opposes tangential velocity, 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.GetX() to extract X component as float, converts float to double for BambooBasic return. Validation: no validation needed (always returns valid number, 0.0 on error). Related: b3dGetPhysicsBodyVelocityY gets Y-axis velocity (vertical movement speed), b3dGetPhysicsBodyVelocityZ gets Z-axis velocity (forward/backward movement speed), b3dSetPhysicsBodyVelocity sets linear velocity (write velocity components), b3dCreatePhysicsBody creates physics body (call this before querying velocity).