b3dSetPhysicsGravity

Sets global physics gravity vector in units/sec^2 (default 0,-9.81,0 for Earth gravity). Takes x/y/z (gravity acceleration components in world units per second squared). Returns nothing. Sets Jolt PhysicsSystem gravity, affects all dynamic bodies (mass>0) globally. Use for planetary gravity, zero-gravity, or directional gravity effects.

This function sets global gravity. Gravity components: x (horizontal gravity in units/sec^2, typically 0 for normal Earth gravity, non-zero for sideways gravity like falling room), y (vertical gravity in units/sec^2, -9.81 for Earth downward, 0 for zero-gravity, positive for upward gravity), z (depth gravity in units/sec^2, typically 0 for normal gravity, non-zero for directional pull). Gravity physics: gravity is constant acceleration applied to all dynamic bodies each frame (velocity += gravity * deltaTime), affects only bodies with mass>0 (static bodies immovable, infinite mass), applied globally (all dynamic bodies experience same gravity vector). Default gravity: Earth gravity is (0, -9.81, 0) in Y-up coordinates (-9.81 units/sec^2 downward = 9.81 m/s^2 in metric, typical starting value), if not set explicitly Jolt default may be (0, 0, 0) zero-gravity (must call this function to enable gravity). Use cases: (1) Earth gravity (set 0,-9.81,0 for realistic falling and jumping), (2) Low gravity (set 0,-3.0,0 for moon-like physics, slower falling), (3) High gravity (set 0,-20.0,0 for heavy planet, faster falling), (4) Zero gravity (set 0,0,0 for space simulation, no automatic falling), (5) Directional gravity (set non-zero x/z for tilted world, falling sideways). Common patterns: Earth gravity b3dSetPhysicsGravity(0, -9.81, 0), moon gravity b3dSetPhysicsGravity(0, -1.62, 0), zero gravity b3dSetPhysicsGravity(0, 0, 0), sideways gravity b3dSetPhysicsGravity(-9.81, 0, 0), custom gravity b3dSetPhysicsGravity(0, -customG, 0). Typical usage: call once at start to set global gravity (b3dInitPhysics then b3dSetPhysicsGravity), change dynamically for gameplay (enter zero-G zone, gravity = 0, exit zone, gravity = -9.81), create gravity wells by adjusting gravity based on proximity to massive objects. Gravity application: Jolt adds gravity * deltaTime to velocity each physics step (for 60 Hz physics, deltaTime = 1/60 sec), gravity accumulates each frame (velocity becomes increasingly negative downward with Earth gravity), terminal velocity not automatic (velocity increases indefinitely unless damping or manual clamping applied). Dynamic body effect: dynamic bodies (mass>0) accelerate according to gravity (vy -= 9.81 * deltaTime each frame for Earth gravity), bodies fall until hitting ground (collision stops downward motion), jumping requires upward velocity or impulse to counter gravity (vy = jumpSpeed or b3dApplyPhysicsImpulse with positive iy). Static body behavior: static bodies (mass=0) unaffected by gravity (immovable, infinite mass, gravity/mass = 0 acceleration), remain fixed in place regardless of gravity direction or magnitude. Coordinate system: x/y/z in BambooBasic Y-up world coordinates (Y-axis vertical, positive up, negative down), passed directly to Jolt Vec3 (Jolt also uses Y-up), typical Earth gravity has negative y component (pulls downward). Gravity magnitude: Earth gravity magnitude = 9.81 units/sec^2 (if 1 unit = 1 meter, exactly Earth gravity 9.81 m/s^2), moon gravity = 1.62 units/sec^2 (1/6 Earth), Jupiter gravity = 24.79 units/sec^2 (2.5x Earth), adjust magnitude for gameplay feel (lower gravity = floaty jumps, higher gravity = quick falls). Gravity direction: non-axis-aligned gravity possible (set x and z non-zero for diagonal pull, like gravity toward planet center in spherical world), creates unusual gameplay (walls become floors when gravity rotates), magnitude = sqrt(x^2 + y^2 + z^2) for arbitrary direction. Zero-gravity zones: disable gravity in specific areas by setting (0,0,0) when entering zone, re-enable with Earth gravity when exiting zone, allows space simulation or floating puzzles, bodies retain velocity (drift until damping or collision stops them). Gravity transitions: smoothly interpolate gravity for zone transitions (lerp from oldGravity to newGravity over time), prevents abrupt velocity changes (falling object doesn't instantly stop when entering low-gravity zone), creates smooth gameplay feel. Performance: O(1) operation (simple Vec3 set via Jolt PhysicsSystem), gravity applied to all dynamic bodies during physics step (integrated into velocity update, minimal overhead), instant gravity change (affects next physics frame immediately). Gravity and terminal velocity: gravity alone causes indefinite acceleration (velocity increases without limit), realistic terminal velocity requires damping or manual clamping (set linearDamping > 0 or clamp vy each frame), air resistance balances gravity at terminal velocity (damping opposes velocity, equilibrium when damping = gravity acceleration). Custom gravity effects: attract toward point (calculate direction from body to attractor, set gravity = direction * magnitude dynamically), repel from point (reverse direction for anti-gravity), orbit simulation (gravity toward center for circular motion). Validation: silently returns if g_physicsSystem not initialized (b3dInitPhysics not called), no validation on gravity values (negative y typical, but positive y or extreme values allowed), no clamping (any magnitude permitted, even extreme values). Jolt integration: calls g_physicsSystem->SetGravity(Vec3((float)x, (float)y, (float)z)), Jolt stores gravity vector globally (affects all bodies in physics world), gravity applied during PhysicsSystem::Update (adds gravity * deltaTime to each dynamic body's velocity). Units: gravity in units per second squared (acceleration), if 1 unit = 1 meter then Earth gravity = 9.81 units/sec^2 = 9.81 m/s^2 exactly, scale gravity proportionally if units differ (1 unit = 2 meters then Earth gravity = 4.905 units/sec^2). Related: b3dCreatePhysicsBody creates dynamic bodies (mass>0 affected by gravity), b3dSetPhysicsBodyVelocity sets velocity (gravity continuously changes velocity over time), b3dSetPhysicsBodyDamping sets damping (damping can balance gravity for terminal velocity), b3dGetPhysicsBodyVelocityY reads vertical velocity (gravity causes vy to decrease over time).