b3dGetCharacterVelocityX

Returns actual horizontal velocity X in units/sec (velocity after acceleration applied). Takes characterHandle (character controller from b3dCreateCharacterController). Returns actualVelocity.X component (horizontal velocity along X axis in world space units per second), reflects current movement speed after acceleration/deceleration and physics updates. Use to query character movement speed for gameplay logic, animation blending, or visual effects.

This function queries velocity. Velocity components: character has 3D velocity vector (actualVelocity with X, Y, Z components), X component is horizontal velocity along X axis (east-west in world space, positive X is east/right), returned value is current actual velocity (not desired or target, actual velocity after physics). Actual velocity meaning: actualVelocity is velocity after all modifications (acceleration/deceleration smoothing applied, slope sliding added, physics constraints enforced), reflects true character movement (how fast character is actually moving this frame), updated every physics frame in UpdatePhysicsSystem (velocity calculated then applied to character position). Use cases: (1) Animation blending (blend walk/run animations based on actual speed), (2) Movement audio (footstep frequency based on velocity magnitude), (3) Speedometer UI (display current speed to player), (4) Gameplay logic (damage on impact based on velocity), (5) Particle effects (dust trail intensity based on movement speed). Common patterns: speed check speed = Sqrt(vx*vx + vz*vz) where vx = b3dGetCharacterVelocityX(char) (horizontal speed magnitude), animation blend animSpeed = speed / maxSpeed (normalize to 0-1 for animation blending), movement sound If speed > 0.5 Then PlayFootstep (play sound only if moving significantly). Typical usage: query each frame for animation systems (blend animations based on current speed), check for gameplay events (detect landing impact, check if moving for stamina regen), display to UI (show speedometer or velocity indicator).

Velocity vs speed: velocity is vector (has direction and magnitude, separate X/Y/Z components), speed is scalar magnitude (Sqrt(vx^2 + vy^2 + vz^2), single value no direction), this function returns X component only (one axis of velocity vector, combine with Y and Z for full velocity). Horizontal velocity calculation: actualVelocity.X updated in UpdatePhysicsSystem (smoothed from desired velocity using acceleration/deceleration), desired velocity from b3dMoveCharacter input (player input direction * current movement speed), acceleration applied (velocity gradually approaches desired based on accel/decel settings), final velocity after physics (CharacterVirtual collision resolution may modify velocity). Coordinate system: X axis is horizontal east-west (positive X is east/right, negative X is west/left in world space), Y axis is vertical up-down (not returned by this function, see b3dGetCharacterVelocityY), Z axis is horizontal north-south (not returned by this function, see b3dGetCharacterVelocityZ), right-handed Y-up coordinate system (standard 3D orientation). Return value range: can be any value positive or negative (positive = moving east/right, negative = moving west/left, zero = no X movement), magnitude limited by movement speed and air control (typically -15 to +15 units/sec for normal character with default speeds), extreme values possible on slopes or with physics forces (sliding or pushed by external forces). Animation blending example: get all velocity components (vx = b3dGetCharacterVelocityX(char), vz = b3dGetCharacterVelocityZ(char)), calculate horizontal speed (horizontalSpeed = Sqrt(vx*vx + vz*vz), ignore vertical for ground movement), normalize to animation range (animBlend = horizontalSpeed / runSpeed, 0.0=idle 1.0=full run), blend animations (blend between idle and run based on animBlend factor). Speedometer example: get velocity (vx = b3dGetCharacterVelocityX(char), vz = b3dGetCharacterVelocityZ(char)), calculate speed magnitude (speed = Sqrt(vx*vx + vz*vz) units per second), display to UI (speedText = "Speed: " + Int(speed) + " units/sec"), update each frame (real-time speedometer). Movement detection: check if character is moving (vx = b3dGetCharacterVelocityX(char), vz = b3dGetCharacterVelocityZ(char)), calculate horizontal motion (moving = (Abs(vx) > 0.1) Or (Abs(vz) > 0.1), threshold prevents jitter), use for gameplay (if not moving regenerate stamina, if moving play footsteps), helps detect idle vs active state. Impact damage example: get velocity at landing (vy = b3dGetCharacterVelocityY(char) on ground contact event), calculate fall speed (fallSpeed = Abs(vy) if vy negative), apply damage based on speed (damage = Max(0, fallSpeed - 10) * 5, damage if fall faster than 10 units/sec), realistic fall damage (harder landings hurt more). Velocity components vs CharacterVirtual: actualVelocity is BambooBasic computed velocity (smoothed with acceleration, includes desired movement), CharacterVirtual.GetLinearVelocity is Jolt physics velocity (actual physics simulation result), actualVelocity is desired velocity after smoothing (what we want character to move), CharacterVirtual velocity is result (what character actually moved after collisions). Acceleration smoothing: if acceleration > 0 actualVelocity smoothly approaches desired (gradual speed change, actualVelocity lags behind input), if acceleration = 0 actualVelocity equals desired instantly (no smoothing, immediate response), returned velocity reflects smoothing (shows gradual ramp-up or ramp-down if acceleration enabled). Slope sliding: when character on slope actualVelocity includes slide component (sliding down slope adds to velocity), returned X velocity includes slide (if sliding northeast X velocity increased by slide), combine input movement and slope sliding (total velocity is player input plus environmental forces). Air control effect: when airborne actualVelocity affected by air control (horizontal components scaled by air control factor), returned X velocity reduced if in air (30% air control means 30% of ground velocity), shows limited air steering (lower velocity when jumping than when grounded with same input). Stopped character: if character not moving actualVelocity.X = 0.0 (zero velocity when idle), if just stopped may be near-zero (small residual from deceleration rounding ~0.001), threshold check recommended (if Abs(vx) < 0.1 consider stopped, avoids floating point noise). Moving character: if character moving east actualVelocity.X positive (positive value, magnitude based on movement speed and state), if moving west actualVelocity.X negative (negative value, same magnitude opposite direction), if moving north/south actualVelocity.X near zero (primarily Z velocity, minimal X component). Performance: O(1) operation (simple float value return from data.actualVelocity.X, instant), no computation required (value already calculated during physics update), safe to call every frame multiple times (negligible cost, direct memory access). 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 actualVelocity is valid (set during UpdatePhysicsSystem). Related: b3dGetCharacterVelocityY returns vertical velocity Y (up/down component, complementary function), b3dGetCharacterVelocityZ returns horizontal velocity Z (north/south component, complementary function), b3dMoveCharacter sets desired velocity (actualVelocity smoothed toward this), b3dSetCharacterAcceleration affects how actualVelocity changes (smoothing rate).