b3dApplyCharacterForce

Applies custom force vector to character (fx,fy,fz in units/sec^2, replaces previous force). Takes characterHandle (character controller from b3dCreateCharacterController), fx (force X component in units per second squared, east-west acceleration), fy (force Y component in units per second squared, vertical acceleration), fz (force Z component in units per second squared, north-south acceleration). Returns nothing. Sets data.customForce, applied during next physics update. Use for wind forces, explosions, conveyor belts, or custom character movement forces.

This function applies custom force. Custom force system: stores force vector in data.customForce (replaces any previous custom force, not additive), applied during UpdatePhysicsSystem (force added to velocity as acceleration, velocity += force * deltaTime), single-frame force (force applied once then cleared, or persistent if set every frame). Force parameters: fx = horizontal east-west force (positive = push east, negative = push west, units/sec^2 acceleration), fy = vertical up-down force (positive = push up, negative = push down, units/sec^2 acceleration), fz = horizontal north-south force (positive = push north, negative = push south, units/sec^2 acceleration), force vector (fx, fy, fz) form 3D acceleration. Use cases: (1) Wind forces (constant sideways push for wind zones), (2) Explosion knockback (radial force away from explosion center), (3) Conveyor belts (horizontal force moving character along belt), (4) Magnetic forces (attraction or repulsion from magnetic objects), (5) Launch pads (strong upward force for jump pads or trampolines). Common patterns: wind force b3dApplyCharacterForce(char, windX, 0, windZ) every frame, explosion knockback b3dApplyCharacterForce(char, dx * power, dy * power, dz * power) once, conveyor belt b3dApplyCharacterForce(char, beltSpeed, 0, 0) while on belt. Typical usage: call every frame for persistent forces (wind continues pushing while in zone), call once for impulse forces (explosion knockback applied single frame), clear force (call with 0, 0, 0 to remove force).

Force vs velocity: force is acceleration (units/sec^2, rate of velocity change, not direct velocity), applied as acceleration (velocity += force * deltaTime, force integrated over time), force affects momentum (gradually changes velocity, not instant teleport). Force application: force applied during UpdatePhysicsSystem (integrated into velocity calculation each physics frame), force accumulates over time (persistent force builds velocity, longer application = faster movement), force cleared or replaced (each call replaces previous force, not additive). Single-frame force (impulse): call once with large force (b3dApplyCharacterForce(char, 100, 50, 0) for explosion), force applied one frame only (velocity increased once, then force cleared or replaced), simulates instant impact (explosion, launch pad, hit reaction). Persistent force (continuous): call every frame with constant force (If InWindZone Then b3dApplyCharacterForce(char, 5, 0, 0) wind push), force applied repeatedly (velocity continuously increased, character accelerates over time), simulates constant push (wind, conveyor, magnetic field). Force magnitude: small forces for gentle effects (force 1-5 units/sec^2 for subtle wind), medium forces for movement (force 10-20 units/sec^2 for conveyor belts), large forces for knockback (force 50-100+ units/sec^2 for explosions or launch pads), extreme forces for instant effects (force 500+ units/sec^2 for dramatic impacts). Wind zone example: detect wind zone (If InWindZone(char) Then applyWind = True), get wind force (windForce = GetZoneWind(charPos) vector from zone data), apply wind force (b3dApplyCharacterForce(char, windX, windY, windZ) each frame while in zone), clear on exit (b3dApplyCharacterForce(char, 0, 0, 0) when leaving zone). Explosion knockback example: detect explosion hit (If HitByExplosion(char) Then knockback = True), calculate knockback direction (dx = charX - explosionX, dy = charY - explosionY, dz = charZ - explosionZ, normalize), apply knockback force (b3dApplyCharacterForce(char, dx * 80, dy * 80 + 20, dz * 80) strong radial push), single-frame application (force applied once, character flung away). Conveyor belt example: detect belt contact (If OnConveyorBelt(char) Then onBelt = True), get belt direction (beltDir = GetBeltDirection(beltEntity) belt movement vector), apply belt force (b3dApplyCharacterForce(char, beltDir.X * 15, 0, beltDir.Z * 15) each frame on belt), character moves with belt (force pushes character along belt direction). Magnetic force example: detect magnetic field (If NearMagnet(char) Then inField = True), calculate attraction (toMagnet = magnetPos - charPos, normalize, magnetForce = strength / distance^2), apply magnetic force (b3dApplyCharacterForce(char, toMagnet.X * magnetForce, toMagnet.Y * magnetForce, toMagnet.Z * magnetForce) each frame), character pulled toward magnet (inverse square law attraction). Launch pad example: detect pad activation (If OnLaunchPad(char) And activated Then launch = True), get launch direction (launchDir = GetPadDirection(padEntity) upward and forward), apply launch force (b3dApplyCharacterForce(char, launchDir.X * 100, launchDir.Y * 150, launchDir.Z * 100) strong upward push), character launched into air (high velocity gained in single frame). Force replacement: each call replaces previous force (b3dApplyCharacterForce(char, 10, 0, 0) then b3dApplyCharacterForce(char, 0, 10, 0) results in only second force), not additive (forces don't accumulate, only most recent force used), clear force by setting zero (b3dApplyCharacterForce(char, 0, 0, 0) removes all custom force). Force vs gravity: custom force adds to gravity (both applied simultaneously, force + gravity = total acceleration), can counteract gravity (upward force offsets downward gravity, creates floating), independent systems (gravity from gravityScale, force from this function, both affect velocity). Force vs input movement: custom force adds to player input movement (both applied, force + input = total velocity), can override input (strong force overrides player control, forced movement), can augment input (wind assists or resists player movement). Force accumulation over time: force applied each frame builds velocity (velocity += force * deltaTime, repeated application accelerates character), longer force duration = higher velocity (persistent wind gradually speeds character up), force magnitude determines acceleration rate (higher force = faster velocity gain). Force direction: force vector points in acceleration direction (positive X east, positive Y up, positive Z north), force magnitude is vector length (magnitude = sqrt(fx^2 + fy^2 + fz^2), acceleration strength), normalize for constant magnitude (divide by length, then scale by desired force strength). Zero force: force (0, 0, 0) clears custom force (no acceleration applied, character moves normally), call to stop force effects (wind zone exit, conveyor belt off, explosion ended), character returns to normal movement (only gravity and input affect velocity). Negative force: negative components reverse direction (negative fx pushes west, negative fy pushes down, negative fz pushes south), useful for braking (negative force opposite to velocity slows character), repulsive forces (push away from object, negative of attraction vector). Force vs impulse comparison: this is force (acceleration, gradual velocity change), impulse would be velocity (instant velocity change, not available for character), force integrated over time (force * deltaTime = velocity change per frame), similar to physics body impulse but for character controller. Coordinate system: fx horizontal east-west (positive = east/right, negative = west/left), fy vertical up-down (positive = up, negative = down), fz horizontal north-south (positive = north/forward, negative = south/backward). Force magnitude recommendations: gentle effects 1-5 units/sec^2 (subtle wind, light push), moderate effects 10-30 units/sec^2 (conveyor belts, moderate wind), strong effects 50-100 units/sec^2 (explosion knockback, launch pads), extreme effects 200+ units/sec^2 (dramatic impacts, instant velocity change). Force duration: single-frame force applied once (explosion, launch pad, hit reaction), multi-frame force applied continuously (wind zone, conveyor belt, persistent push), duration determines total velocity gain (longer duration = more velocity accumulated). Character control: strong force overrides player input (character cannot resist explosion or launch pad), weak force modifies player input (wind assists or resists but player maintains control), balance force strength for gameplay (too strong removes control, too weak feels ineffective). Multiple force sources: only one custom force at a time (each call replaces previous), combine forces manually before applying (windForce + magnetForce = totalForce, then apply total), or apply forces in priority order (strongest force wins, apply most significant force only). Force clearing: force persists until replaced or character destroyed (doesn't auto-clear after one frame unless manually cleared), clear explicitly (b3dApplyCharacterForce(char, 0, 0, 0) when force no longer needed), or replace with new force (next zone or effect applies new force). Performance: O(1) operation (simple vector assignment, instant), no computation required (force stored for later application during physics), safe to call every frame (typical for wind zones, conveyor belts, persistent forces). Validation: silently returns if characterHandle not found (invalid or freed character), no force validation (any values allowed including zero or extreme), no error messages (silent failure for performance). Related: b3dSetPhysicsGravity sets global gravity force (applied to all dynamic bodies), b3dApplyPhysicsImpulse applies impulse to physics body (instant velocity change for rigid bodies), b3dMoveCharacter sets desired velocity (input movement, separate from force), b3dSetCharacterGravityScale scales gravity force (affects downward acceleration).