b3dSetPhysicsBodyVelocity

Sets physics body linear velocity in units/sec (vx/vy/vz movement speed, affects position over time). Takes bodyHandle (physics body from b3dCreatePhysicsBody), vx/vy/vz (velocity components in world units per second). Returns nothing. Sets Jolt linear velocity directly, affects body position in next physics update. Use for character movement, launching projectiles, or kinematic control.

This function sets movement velocity. Velocity components: vx (X-axis velocity in units/sec, positive = right, negative = left), vy (Y-axis velocity in units/sec, positive = up, negative = down), vz (Z-axis velocity in units/sec, positive = forward, negative = backward). Velocity behavior: velocity affects position each physics step (newPosition = oldPosition + velocity * deltaTime), gravity adds downward velocity each frame for dynamic bodies (vy decreases over time unless countered), friction opposes velocity tangent to contact surfaces (velocity reduced when sliding), air resistance not applied by default (bodies maintain velocity in air unless friction/damping configured). Use cases: (1) Character movement (set horizontal velocity for walking/running), (2) Jumping (set vertical velocity vy for jump impulse), (3) Projectiles (set initial velocity for bullets/grenades), (4) Kinematic control (override physics with scripted movement), (5) Reset momentum (set 0,0,0 to stop moving object). Common patterns: walk right b3dSetPhysicsBodyVelocity(player, 5, vy, 0), jump b3dSetPhysicsBodyVelocity(player, vx, 10, vz), shoot projectile b3dSetPhysicsBodyVelocity(bullet, dirX*20, dirY*20, dirZ*20), stop body b3dSetPhysicsBodyVelocity(body, 0, 0, 0). Typical usage: set velocity each frame for character control (overrides physics simulation), combine with b3dGetPhysicsBodyVelocity* to read and modify existing velocity (preserve vertical while changing horizontal), use with collision detection for responsive movement. Velocity vs impulse: b3dSetPhysicsBodyVelocity sets velocity directly (replaces current velocity, immediate effect, use for kinematic control), b3dApplyPhysicsImpulse adds to velocity (incremental change, use for forces like explosions), direct velocity set ignores mass (same velocity regardless of mass), impulse respects mass (heavier objects gain less velocity). Coordinate system: vx/vy/vz in BambooBasic Y-up world coordinates (same as position system), passed directly to Jolt Vec3 (no conversion needed), velocity in world space (not local to body rotation). Gravity interaction: gravity adds acceleration downward each frame (vy -= 9.81 * deltaTime for dynamic bodies), setting vy positive counters gravity (jumping, flying), setting vy = 0 each frame prevents falling (kinematic platform), static bodies (mass=0) unaffected by gravity (velocity ignored). Character controller pattern: read current velocity (vx = b3dGetPhysicsBodyVelocityX, vy = b3dGetPhysicsBodyVelocityY, vz = b3dGetPhysicsBodyVelocityZ), modify horizontal components based on input (vx = inputX * speed, vz = inputZ * speed), preserve vertical velocity (keep vy for gravity/jumping), set modified velocity (b3dSetPhysicsBodyVelocity(body, vx, vy, vz)). Velocity clamping: no automatic clamping (velocity can be arbitrarily high), manual clamp if desired (prevent super-speed exploits, cap falling speed for gameplay feel), high velocities may cause tunneling through thin geometry (continuous collision helps but not perfect). Performance: O(1) operation (simple Vec3 set via Jolt BodyInterface), velocity updated immediately (affects next physics step ~1/60 sec), no activation needed (velocity change doesn't require waking body). Collision response: velocity changes during collisions (normal component reversed for bounce, tangent component reduced by friction), manually set velocity overrides collision response (may cause objects to clip through geometry if set carelessly), use after collision to modify post-collision velocity (adjust bounce direction). Static body behavior: static bodies (mass=0) ignore velocity (immovable by definition), setting velocity on static body has no effect (position unchanged), convert to dynamic (mass>0) if velocity control needed. Validation: silently returns if g_physicsSystem not initialized, silently returns if bodyHandle not found in g_bodyHandleToBodyID, no value clamping (extreme velocities allowed). Related: b3dGetPhysicsBodyVelocityX/Y/Z reads current velocity (use to modify existing velocity), b3dSetPhysicsBodyAngularVelocity sets rotational velocity (spin rate), b3dApplyPhysicsImpulse adds impulse (alternative to direct velocity set), b3dSetPhysicsBodyPosition sets position (velocity causes position to change over time).