b3dSetCharacterGravityScale

Sets gravity scale multiplier (1.0=normal, 0.5=half gravity, 2.0=double gravity, default 1.0). Takes characterHandle (character controller from b3dCreateCharacterController), scale (gravity multiplier 0.0-infinity, scales global gravity for this character). Returns nothing. Sets data.gravityScale, affects character gravity during physics update. Use for low gravity areas, powerups, or special movement states like gliding.

This function configures gravity scaling. Gravity scale system: global gravity is default (set by b3dSetPhysicsGravity, typically -9.81 units/sec^2 downward), character gravity = global gravity * gravityScale (per-character multiplier applied to global gravity), allows per-character gravity customization (different characters different gravity, independent of global setting). Scale parameter: scale = 1.0 normal gravity (default, full global gravity applied to character), scale = 0.5 half gravity (character falls slower, floaty jumps), scale = 2.0 double gravity (character falls faster, heavy feel), scale = 0.0 zero gravity (character doesn't fall, floats in air indefinitely). Use cases: (1) Low gravity zones (moon level or space area, reduced gravity for all characters in zone), (2) Gliding powerup (reduce gravity while gliding, slower fall for extended air time), (3) Heavy character (larger characters higher gravity scale, fall faster than normal), (4) Water physics (underwater reduce gravity, buoyancy effect), (5) Slow-motion effects (reduce gravity during slow-mo, exaggerated jump arcs). Common patterns: low gravity b3dSetCharacterGravityScale(char, 0.3), heavy character b3dSetCharacterGravityScale(tank, 1.5), gliding If gliding Then b3dSetCharacterGravityScale(char, 0.4), zero gravity b3dSetCharacterGravityScale(char, 0.0). Typical usage: set once for character type (heavy vs light characters have different scales), adjust dynamically for powerups or zones (enter low gravity area reduce scale), reset when effect ends (restore scale to 1.0 when leaving zone).

Default value: gravityScale = 1.0 (normal gravity, set in b3dCreateCharacterController), remains until explicitly changed (persistent across frames), full global gravity applied (no scaling, standard physics). Gravity calculation: effective gravity = global gravity * gravityScale (e.g. -9.81 * 0.5 = -4.905 units/sec^2), applied during UpdatePhysicsSystem (velocity.Y += effectiveGravity * deltaTime each frame), affects falling speed and jump arcs (lower scale = slower fall, higher scale = faster fall). Scale = 1.0 normal gravity: character falls at normal rate (default physics, standard game feel), jump arcs are standard (typical jump height and duration), feels realistic (matches normal earth-like gravity). Scale < 1.0 reduced gravity: character falls slower (lower gravity, floaty physics), jump higher and longer (reduced downward acceleration, extended air time), feels light or moon-like (low gravity environment), scale 0.0 = zero gravity (character doesn't fall at all, floats indefinitely). Scale > 1.0 increased gravity: character falls faster (higher gravity, heavy physics), jump lower and shorter (increased downward acceleration, reduced air time), feels heavy or high-gravity (character pulled down strongly), scale 2.0 = double gravity (falls twice as fast as normal). Low gravity zone example: detect zone entry (If InLowGravityZone(char) Then inZone = True), reduce gravity scale (b3dSetCharacterGravityScale(char, 0.3) for moon-like feel), restore on exit (b3dSetCharacterGravityScale(char, 1.0) when leaving zone), creates low-gravity gameplay area. Gliding powerup example: activate gliding (If glideButton And airborne Then gliding = True), reduce gravity while gliding (b3dSetCharacterGravityScale(char, 0.4) slow fall), restore on landing or deactivate (b3dSetCharacterGravityScale(char, 1.0) when grounded or glide ends), extended air time for traversal. Heavy character example: set at character creation (b3dSetCharacterGravityScale(heavyCharacter, 1.4) falls faster than normal), persistent heavy feel (character always falls faster, inherent property), differentiated character types (light agile characters scale 0.8, heavy tanks scale 1.5). Underwater physics: enter water volume (If InWater(char) Then underwater = True), reduce gravity for buoyancy (b3dSetCharacterGravityScale(char, 0.1) near-weightless underwater), restore above water (b3dSetCharacterGravityScale(char, 1.0) when surfacing), realistic water physics (slow sinking, floaty movement). Zero gravity example: set zero scale (b3dSetCharacterGravityScale(char, 0.0) no gravity), character floats in place (no falling, remains at current height unless forces applied), space environment (zero-G gameplay, thrust-based movement only), restore gravity when needed (b3dSetCharacterGravityScale(char, 1.0) exit space area). Gravity scale vs global gravity: global gravity affects all characters (b3dSetPhysicsGravity sets world gravity, typically -9.81), per-character scale customizes individual character (this function, multiply global by scale), independent systems (can change global gravity or per-character scale separately). Jump interaction: reduced gravity increases jump height (same jump velocity but slower fall, character travels higher before gravity stops ascent), increased gravity decreases jump height (faster fall, character peak height lower), scale affects entire jump arc (ascent and descent both scaled). Fall speed calculation: terminal velocity affected by scale (character reaches different max fall speeds based on scale), lower scale = slower terminal velocity (reduced gravity less acceleration), higher scale = faster terminal velocity (increased gravity more acceleration). Negative gravity scale: negative scale reverses gravity (e.g. -1.0 makes character fall upward, inverted gravity), unconventional but possible (gravity pulls character up instead of down), useful for ceiling walking (character adheres to ceiling with negative gravity). Scale clamping: no clamping applied (any value allowed including zero, negative, or extreme values), user responsible for reasonable scales (typical range 0.0-2.0 for normal gameplay), extreme scales possible (scale 10.0 super heavy, scale 0.01 near-weightless). Slow-motion effect: reduce gravity during slow-mo (b3dSetCharacterGravityScale(char, 0.5) exaggerated bullet-time jumps), matches time dilation (slower fall matches slower time, realistic slow-mo physics), restore normal speed (b3dSetCharacterGravityScale(char, 1.0) when slow-mo ends). Dynamic gravity zones: check character position each frame (zone = GetGravityZone(charPos)), set scale based on zone (If zone = lowGrav Then scale = 0.3 Else scale = 1.0), dynamic scaling (gravity changes as character moves between zones), seamless transitions (smooth gravity change when crossing zone boundaries). Character differentiation: light characters scale 0.8 (fall slightly slower, more floaty jumps), normal characters scale 1.0 (standard physics, typical game feel), heavy characters scale 1.3 (fall faster, shorter jumps), creates gameplay variety (different movement feel per character type). Gravity scale animation: when scale changes fade animation speed (animSpeed = scale for realistic animation, faster animation when falling faster), blend animation states (transition from normal to floaty animations based on scale), visual feedback (animations match physics feel). Performance: O(1) operation (simple float assignment, instant), no validation overhead (any value allowed, no clamping), safe to call every frame if needed (though typically set infrequently). Validation: silently returns if characterHandle not found (invalid or freed character), no scale validation (any value allowed including zero or negative), no error messages (silent failure for performance). Related: b3dSetPhysicsGravity sets global gravity (world-wide gravity affecting all characters), b3dCreateCharacterController initializes scale to 1.0 (default normal gravity), b3dCharacterJump affected by gravity scale (jump height and arc shaped by gravity), b3dGetCharacterVelocityY reflects gravity scale effect (falling velocity influenced by scaled gravity).