b3dGetCharacterState

Returns character state bitflags (1=grounded, 2=jumping, 4=falling, 8=in_air, 16=wall_contact). Takes characterHandle (character controller from b3dCreateCharacterController). Returns state as bitfield integer (combination of state flags using bitwise OR, multiple states can be active simultaneously), reflects current character physics state from Jolt CharacterVirtual. Use to query character state for animation, gameplay logic, or input handling.

This function queries character state. State bitflags: state is bitfield (each bit represents different state flag, combine flags with bitwise OR), multiple states possible (character can be grounded AND on wall, or jumping AND on wall simultaneously), query individual flags with bitwise AND (If (state And 1) Then grounded = True). State flag values: 1 (bit 0) = CHAR_STATE_GROUNDED (character on ground, CharacterVirtual.GetGroundState() == OnGround), 2 (bit 1) = CHAR_STATE_JUMPING (character rising rapidly, velocity.Y > 2.0 units/sec), 4 (bit 2) = CHAR_STATE_FALLING (character descending rapidly, velocity.Y < -2.0 units/sec), 8 (bit 3) = CHAR_STATE_IN_AIR (character airborne with minimal vertical velocity, -2.0 <= velocity.Y <= 2.0), 16 (bit 4) = CHAR_STATE_WALL_CONTACT (character touching vertical surface, wall normal Y < 0.5). Use cases: (1) Animation state machine (select jump/fall/idle animations based on state), (2) Input handling (allow wall jump only if wall_contact flag set), (3) Gameplay logic (disable stamina regen while jumping or falling), (4) Visual effects (spawn landing particles when grounded flag activates), (5) Sound triggers (play landing sound on grounded transition). Common patterns: grounded check If (state And 1) Then onGround = True, jumping check If (state And 2) Then playJumpAnim(), wall contact If (state And 16) Then allowWallJump(), combined check If (state And 16) And Not (state And 1) Then onWallInAir = True. Typical usage: query each frame for animation system (blend animations based on state flags), check for input conditions (wall jump requires wall_contact flag), detect state transitions (grounded flag changes trigger landing events).

Grounded flag (1): set when CharacterVirtual.GetGroundState() == OnGround (Jolt physics detects floor contact, character supported by ground), cleared when airborne (character leaves ground via jump or fall off edge), mutually exclusive with jumping/falling/in_air (either grounded or one of the airborne states, not both). Jumping flag (2): set when airborne AND velocity.Y > 2.0 units/sec (character rising rapidly, recently jumped or launched upward), cleared when velocity.Y <= 2.0 (reaching jump apex or descending, transitions to in_air or falling), indicates upward motion (character actively ascending, jump or launch effect). Falling flag (4): set when airborne AND velocity.Y < -2.0 units/sec (character descending rapidly, falling or dropped from height), cleared when velocity.Y >= -2.0 (slowing descent or landing, transitions to in_air or grounded), indicates downward motion (character actively descending, gravity pulling down). In_air flag (8): set when airborne AND -2.0 <= velocity.Y <= 2.0 units/sec (character airborne with minimal vertical movement, at jump apex or gentle fall), cleared when leaving this velocity range (accelerating up to jumping or down to falling), indicates neutral vertical motion (peak of jump, gentle descent, transitional state). Wall_contact flag (16): set when character has active contact with vertical surface (CharacterVirtual contact list contains contact with normal.Y < 0.5), can combine with other flags (wall_contact AND jumping for wall-jump setup), persistent while touching wall (remains set as long as wall contact exists, cleared when leaving wall). State transitions: grounded to jumping (character jumps, state changes from 1 to 2), jumping to in_air (velocity slows at apex, state changes from 2 to 8), in_air to falling (velocity becomes negative, state changes from 8 to 4), falling to grounded (character lands, state changes from 4 to 1), smooth transitions (state updates every physics frame based on current physics state). Velocity thresholds: jumping threshold > 2.0 units/sec (rapid ascent, clearly jumping upward), falling threshold < -2.0 units/sec (rapid descent, clearly falling downward), in_air range -2.0 to 2.0 units/sec (minimal vertical movement, near apex or gentle fall), thresholds prevent jitter (hysteresis between states, avoids rapid flickering). Wall normal calculation: gets active contacts from CharacterVirtual (all current collision points), checks contact normal for each (contact.mContactNormal direction vector), vertical surface if normal.Y < 0.5 (Y component small means mostly horizontal normal, >60 degrees from horizontal = wall), wall_contact flag set if any wall found (only needs one wall contact to set flag). Animation state machine example: get state (state = b3dGetCharacterState(char)), check flags (If (state And 1) playIdleAnim() ElseIf (state And 2) playJumpAnim() ElseIf (state And 4) playFallAnim()), blend animations (crossfade between states when flags change), responsive animation (immediate state changes reflected in animation). Wall jump input example: get state (state = b3dGetCharacterState(char)), check wall contact (wallContact = (state And 16) > 0), allow wall jump if on wall (If wallContact And jumpPressed Then b3dCharacterWallJump(char, 8.0, 5.0)), contextual input (jump button does different things based on state flags). Combined state checks: on wall while jumping (If (state And 2) And (state And 16) Then wallJumpingUp = True), on wall while falling (If (state And 4) And (state And 16) Then wallSliding = True), multiple flags active (wall_contact can combine with vertical movement states for advanced mechanics). State transitions detection: store previous state (lastState = currentState before update), get current state (currentState = b3dGetCharacterState(char)), detect changes (If (lastState And 1) = 0 And (currentState And 1) > 0 Then justLanded = True), trigger events on transitions (landing event plays sound, spawns particles). Grounded transition: from airborne to grounded (any of 2/4/8 to 1, character lands on ground), trigger landing effects (play landing sound, spawn dust particles, screen shake), apply fall damage (check velocity just before landing, damage if too fast), reset jump count (allow jump again after landing). Jump transition: from grounded to jumping (1 to 2, character initiates jump), trigger jump effects (play jump sound, spawn jump dust from ground), start jump animation (blend from idle/walk to jump animation), disable ground mechanics (no footsteps while airborne). Default state: if character invalid returns 8 CHAR_STATE_IN_AIR (safe default state, assumes airborne with neutral velocity), in_air is safest fallback (doesn't imply ground contact or extreme velocity, neutral state). Bitwise operations: check flag with AND (If (state And CHAR_STATE_GROUNDED) Then grounded = True), combine flags with OR (state = CHAR_STATE_GROUNDED Or CHAR_STATE_WALL_CONTACT for grounded on wall), toggle flag with XOR (state = state Xor CHAR_STATE_JUMPING removes jumping flag), bitwise logic for flag manipulation. State flag constants: define constants for readability (Const CHAR_STATE_GROUNDED = 1, Const CHAR_STATE_JUMPING = 2, etc.), use in checks (If (state And CHAR_STATE_GROUNDED) clearer than If (state And 1)), improves code clarity (self-documenting state checks). Wall sliding mechanic: check wall contact while falling (If (state And 4) And (state And 16) Then wallSliding = True), reduce fall velocity during slide (modify velocity.Y to slow descent), transition to wall jump state (press jump while sliding triggers wall jump), classic platformer mechanic. Jump apex detection: check in_air flag (If (state And 8) And previousFlag was JUMPING Then atApex = True), trigger apex effects (play apex animation, enable glide, activate special abilities), precise apex timing (in_air flag indicates transitional state at top of jump). State consistency: grounded is mutually exclusive with jumping/falling/in_air (either on ground or in one airborne state, never both), wall_contact can combine with any other state (can be grounded on wall, jumping on wall, falling on wall), logical state combinations (states represent real physics situations). Performance: O(N) operation where N is active contacts (checks contact normals for wall detection, typically 1-4 contacts), fast ground state query (CharacterVirtual.GetGroundState() is O(1)), negligible overhead (call every frame acceptable, typical cost <0.01ms). Validation: returns 8 (CHAR_STATE_IN_AIR) if characterHandle not found (invalid or freed character, safe neutral default), no error messages (silent failure, returns reasonable fallback), assumes CharacterVirtual is valid (crash if character data corrupted). Related: b3dIsCharacterGrounded returns simple grounded boolean (simplified version of grounded flag), b3dIsCharacterOnWall returns simple wall contact boolean (simplified version of wall_contact flag), b3dGetCharacterVelocityY velocity determines jumping/falling/in_air flags (Y velocity threshold checks), b3dCharacterWallJump uses wall_contact state (requires flag 16 to be set for wall jump).