b3dMoveCharacter

Sets character horizontal movement velocity (velocityX/Z normalized input, scaled by movement state speed). Takes characterHandle (character controller from b3dCreateCharacterController), velocityX (horizontal X-axis input typically -1 to 1), velocityZ (horizontal Z-axis input typically -1 to 1). Returns nothing. Stores input velocity scaled by current movement state (walk/run/crouch speed), combined with physics in UpdatePhysicsSystem. Call every frame with player input for character movement.

This function sets horizontal input. Input parameters: velocityX (X-axis movement input, typically -1=left, 0=none, 1=right from input device), velocityZ (Z-axis movement input, typically -1=backward, 0=none, 1=forward from input device), values should be normalized (length <= 1, prevents diagonal speed exploit). Movement state speed: movementState=0 (walk mode, multiplies input by walkSpeed default 5.0 units/sec), movementState=1 (run mode, multiplies input by runSpeed default 10.0 units/sec), movementState=2 (crouch mode, multiplies input by crouchSpeed default 2.5 units/sec). Speed application: inputVelocity.X = velocityX * speedMultiplier (final horizontal velocity in units/sec), inputVelocity.Z = velocityZ * speedMultiplier (final depth velocity in units/sec), inputVelocity.Y = 0 (vertical velocity separate, controlled by gravity and jumping). Use cases: (1) Player movement (call each frame with WASD or joystick input for walking/running), (2) AI character movement (call with pathfinding direction vector for NPC movement), (3) Scripted movement (call with predetermined velocities for cutscenes), (4) Vehicle control (use for simple vehicle movement without full physics). Common patterns: WASD input vx = (KeyD() - KeyA()) then vz = (KeyW() - KeyS()) then b3dMoveCharacter(char, vx, vz), joystick input b3dMoveCharacter(char, JoyX(), JoyY()), stop movement b3dMoveCharacter(char, 0, 0), normalize diagonal inputLen = Sqrt(vx*vx + vz*vz) then if inputLen > 1 then vx /= inputLen then vz /= inputLen. Typical usage: call every frame in main loop with player input (read input device, normalize, pass to this function), combine with run button to set movementState before calling (if running then movementState=1 else movementState=0), use with b3dCharacterJump for full character control (horizontal movement + jumping). Movement state configuration: walkSpeed set via separate function (default 5.0, typical range 3-7), runSpeed set via separate function (default 10.0, typical range 8-15), crouchSpeed set via separate function (default 2.5, typical range 1-4), movementState set via separate function (0=walk, 1=run, 2=crouch). Input velocity storage: stores in data.inputVelocity (CharacterData member, Vec3 with Y=0), not applied immediately (actual movement happens in UpdatePhysicsSystem each physics step), allows multiple calls per frame (last call before physics update wins). Physics integration: UpdatePhysicsSystem reads data.inputVelocity (called by b3dRenderWorld each frame ~60Hz), combines inputVelocity with sliding forces and gravity (sliding down slopes adds to horizontal velocity), applies air control factor when airborne (reduces input effectiveness mid-air), performs collision detection and resolution (Jolt CharacterVirtual handles wall sliding, step climbing). Air control: when character airborne (not grounded) input scaled by airControl factor (default 0.3 = 30% control), prevents unrealistic mid-air maneuvering (realistic physics, can't change direction as easily in air), allows some air control for gameplay feel (100% grounded control too restrictive). Slope interaction: on slopes input velocity combined with sliding forces (steep slopes add downward sliding velocity), friction affects effective speed (lower friction = faster sliding, input less effective), character can walk up climbable slopes (angle < maxSlopeAngle 45 degrees by default), character slides down steep slopes (angle > maxSlopeAngle, input opposes sliding). Velocity normalization: function does not normalize input (user responsible for normalization), unnormalized diagonal input causes faster movement (vx=1, vz=1 gives length=sqrt(2)=1.414, 41% faster diagonal), normalized input ensures consistent speed (if len > 1 then vx/=len, vz/=len, all directions same speed). World space vs local space: velocityX/Z in world space (not relative to character facing direction), positive vx always moves right in world, positive vz always moves forward in world, for character-relative movement rotate input by character yaw before passing (localToWorld transformation). Movement combination: if multiple movement sources active (player input + sliding + wind) all combined in UpdatePhysicsSystem (input + sliding + wind + impulses = final velocity), this function sets only player input component (other components separate). Performance: O(1) operation (simple velocity storage, three float assignments), no physics simulation triggered (actual movement in UpdatePhysicsSystem), safe to call every frame (designed for per-frame input). Stationary character: to stop character movement call with (0, 0) input (data.inputVelocity becomes zero), gravity still applied (character falls if airborne or slides on steep slopes), does not freeze character (velocity from other sources still active like sliding or wind). Validation: silently returns if g_physicsSystem not initialized (b3dInitPhysics not called), silently returns if characterHandle not found in g_characters (invalid or freed character), no clamping on input values (extreme values allowed, user responsible for reasonable input). Related: b3dCharacterJump sets vertical velocity for jumping (complements horizontal movement), b3dIsCharacterGrounded checks if on ground (use to disable run or change animation), b3dCreateCharacterController creates character controller (call this before movement), b3dSetCharacterHeight changes height (affects movement speed on slopes via collision).