b3dSetCharacterMovementState

Sets movement state 0=walk, 1=run, 2=crouch (selects speed from b3dSetCharacterMoveSpeed). Takes characterHandle (character controller from b3dCreateCharacterController), state (movement state 0=walk normal speed, 1=run fast speed, 2=crouch slow speed). Returns nothing. Sets data.movementState, determines which speed is used by b3dMoveCharacter. Use to switch between walk/run/crouch movement modes based on player input or gameplay context.

This function switches movement state. Movement state system: character has three predefined states (0=walk moderate, 1=run fast, 2=crouch slow), each state associated with speed from b3dSetCharacterMoveSpeed (walk uses walkSpeed, run uses runSpeed, crouch uses crouchSpeed), b3dMoveCharacter uses current state's speed to calculate velocity (actual movement = input * current speed). State parameter: state 0 = walk state (uses walkSpeed from b3dSetCharacterMoveSpeed, default 5.0 units/sec), state 1 = run state (uses runSpeed from b3dSetCharacterMoveSpeed, default 10.0 units/sec), state 2 = crouch state (uses crouchSpeed from b3dSetCharacterMoveSpeed, default 2.5 units/sec), clamped to 0-2 range (if state < 0 set to 0, if state > 2 set to 2). Use cases: (1) Player input control (shift key toggles walk/run, crouch key sets crouch state), (2) Automatic state switching (enter stealth area auto-crouch, combat mode auto-run), (3) Stamina system (out of stamina force walk state, disable run), (4) Context-sensitive movement (tight spaces force crouch, open areas allow run), (5) AI behavior (patrol uses walk, chase uses run, hiding uses crouch). Common patterns: toggle run If KeyDown(KEY_SHIFT) Then b3dSetCharacterMovementState(char, 1) Else b3dSetCharacterMovementState(char, 0), crouch toggle If KeyDown(KEY_CTRL) Then b3dSetCharacterMovementState(char, 2) Else b3dSetCharacterMovementState(char, 0), stamina check If stamina > 0 Then b3dSetCharacterMovementState(char, 1) Else b3dSetCharacterMovementState(char, 0). Typical usage: update every frame based on input (check run/crouch keys and set state accordingly), switch state based on gameplay events (enter stealth zone set crouch, exit set walk), AI state machines (patrol walk, alert run, hide crouch).

Walk state (0): uses walkSpeed for movement (default 5.0 units/sec moderate pace), typical for exploration and normal navigation (balanced speed and control), default state at character creation (initial movementState = 0 in b3dCreateCharacterController), common for non-action situations (calm exploration, casual movement). Run state (1): uses runSpeed for movement (default 10.0 units/sec fast pace), typical for combat and traversal (quick movement sacrifices stealth or stamina), player activates via sprint key (hold shift or toggle button), common for action situations (chase enemies, escape danger, fast travel). Crouch state (2): uses crouchSpeed for movement (default 2.5 units/sec slow pace), typical for stealth and precision (slow movement reduces detection or noise), player activates via crouch key (hold ctrl or toggle button), common for sneaking situations (avoid guards, careful approach, hide in cover). State clamping: if state < 0 clamped to 0 (negative values become walk state, prevents undefined behavior), if state > 2 clamped to 2 (large values become crouch state, prevents array out of bounds), valid range 0-2 only (three predefined states, no custom states). Speed selection: walk state reads data.walkSpeed (set by b3dSetCharacterMoveSpeed), run state reads data.runSpeed (set by b3dSetCharacterMoveSpeed), crouch state reads data.crouchSpeed (set by b3dSetCharacterMoveSpeed), speed determines maximum velocity (target speed for acceleration or instant speed if no acceleration). Input example: check shift key each frame (if KeyDown(KEY_SHIFT) running = True else running = False), check ctrl key each frame (if KeyDown(KEY_CTRL) crouching = True else crouching = False), priority crouching then running (if crouching state=2 else if running state=1 else state=0), call b3dSetCharacterMovementState with calculated state. Stamina example: track stamina value (stamina decreases when running, regenerates when walking), prevent running when stamina depleted (if stamina <= 0 force state=0 walk), allow running when stamina available (if stamina > 0 and player presses shift state=1 run), provides gameplay resource management (sprint sparingly, balance speed and stamina). AI state machine example: patrol state uses walk (b3dSetCharacterMovementState(npc, 0) slow patrol), alert state uses run (b3dSetCharacterMovementState(npc, 1) chase player), search state uses crouch (b3dSetCharacterMovementState(npc, 2) cautious search), smooth AI behavior transitions (change state when switching AI mode). State persistence: state remains until explicitly changed (doesn't reset automatically, persistent across frames), default state 0 at creation (b3dCreateCharacterController initializes movementState = 0 walk), change with b3dSetCharacterMovementState only (no other way to modify state). Animation synchronization: match animation to movement state (walk state plays walk anim, run state plays run anim, crouch state plays crouch anim), blend animations when state changes (smooth transition from walk to run animation), animation speed matches movement speed (walk anim slower than run anim). Movement state vs speed: state selects which speed to use (walk/run/crouch selector), speed defines velocity magnitude (how fast character moves in units/sec), both work together (state chooses speed, speed determines movement rate), separate systems (change state without changing speeds or vice versa). Performance: O(1) operation (simple integer assignment with clamping, instant), no validation overhead beyond clamping (clamps to 0-2 range automatically), safe to call every frame (typically called based on input each frame). Validation: silently returns if characterHandle not found in g_characters (invalid or freed character), clamps state to 0-2 range (ensures valid state, no error for out-of-range), no error messages (silent failure for performance). Related: b3dSetCharacterMoveSpeed sets speeds for each state (walk/run/crouch speed values), b3dMoveCharacter uses current state's speed for movement (applies speed to input velocity), b3dCreateCharacterController initializes state to 0 walk (default state), b3dSetCharacterAcceleration affects how fast state speed changes are applied (smooth transition between speeds).