b3dCreateForceField

Creates force field handle (shapeType: 0=sphere 1=cone, falloffType: 0=constant 1=linear 2=inverse_square). Takes shapeType (0=SPHERE radial force all directions, 1=CONE directional force in cone), x/y/z (position in world space where force field is centered), radius (size of force field effect area in units, initial uniform scale), strength (force magnitude in units/sec^2, positive=repel negative=attract), falloffType (0=CONSTANT force uniform within radius, 1=LINEAR force decreases linearly with distance, 2=INVERSE_SQUARE force decreases by inverse square law). Returns force field handle (positive integer for created field, used with other force field functions). Use for repulsion fields, attraction points, wind tunnels, or directional force zones.

This function creates force field. Force field system: force fields affect characters within radius (characters in range experience force, outside range unaffected), applied during UpdatePhysicsSystem (force calculated and added to character velocity each physics frame), persistent effect (force field remains active until deleted, continuously affects characters). Shape types: shapeType 0 = SPHERE (radial force from center point, pushes/pulls in all directions equally, omnidirectional effect), shapeType 1 = CONE (directional force along rotation direction, cone-shaped area of effect, forward-facing force), default cone angle 45 degrees (half-angle, total 90 degrees cone, configurable via b3dSetForceFieldConeAngle). Position parameters: x/y/z define force field center (world space position, force originates from this point), radius defines effect area (spherical or conical volume around center, characters outside radius unaffected), position can be moved (use b3dPositionForceField to relocate field after creation). Strength parameter: positive strength = repulsion (push characters away from center, radial outward force), negative strength = attraction (pull characters toward center, radial inward force), magnitude determines force (higher absolute strength = stronger push/pull, units/sec^2 acceleration), typical range -50 to +50 units/sec^2. Falloff types: falloffType 0 = CONSTANT (force uniform throughout radius, same strength everywhere, no distance attenuation), falloffType 1 = LINEAR (force decreases linearly with distance, force = strength * (1 - distance/radius), smooth falloff), falloffType 2 = INVERSE_SQUARE (force decreases by distance squared, force = strength / (distance^2), realistic physics), clamped to 0-2 range (values outside clamped automatically). Use cases: (1) Repulsion fields (explosion forces, force barriers, keep-away zones), (2) Attraction points (black holes, vacuum zones, item collection), (3) Wind tunnels (cone-shaped directional wind, forward force channels), (4) Launch pads (strong upward force fields for jumps), (5) Environmental hazards (tornado vortex, magnetic fields, force shields). Common patterns: repulsion sphere b3dCreateForceField(0, x, y, z, 5.0, 20.0, 1), attraction point b3dCreateForceField(0, x, y, z, 10.0, -15.0, 2), wind tunnel b3dCreateForceField(1, x, y, z, 8.0, 12.0, 0), force barrier b3dCreateForceField(0, x, y, z, 3.0, 50.0, 0). Typical usage: create during level load (place force fields in environment), position at key locations (hazard zones, gameplay mechanics, environmental effects), delete when no longer needed (cleanup force fields on level unload).

Sphere force field (shapeType 0): radial force from center (pushes/pulls in all directions equally, omnidirectional), affects characters within radius (spherical volume around center point), force direction away from center for repulsion (radial outward, positive strength), force direction toward center for attraction (radial inward, negative strength), typical for explosions or black holes. Cone force field (shapeType 1): directional force along rotation axis (forward direction based on pitch/yaw/roll), cone-shaped area of effect (characters within cone angle affected, outside cone unaffected), default forward direction +Z axis (north/forward in world space, before rotation), rotation applied via b3dRotateForceField (orient cone direction after creation), typical for wind tunnels or directional beams. Force field handle: returned handle is positive integer (unique identifier for this force field, starting from 1), use with other force field functions (b3dPositionForceField, b3dRotateForceField, b3dDeleteForceField), handle remains valid until force field deleted (persistent identifier, doesn't change). Radius meaning: for sphere radius is effect distance from center (spherical volume, force stops at radius boundary), for cone radius is length along cone axis (how far forward cone extends, plus cone angle determines volume), characters outside radius unaffected (zero force, out of range). Strength magnitude: small strength 1-10 units/sec^2 (subtle force, gentle push or pull), medium strength 10-30 units/sec^2 (moderate force, noticeable effect on movement), large strength 30-100+ units/sec^2 (strong force, significant impact on character trajectory), extreme strength 200+ units/sec^2 (overwhelming force, dramatic fling or suction). Falloff type 0 constant: force uniform within radius (same strength at center and edge, no attenuation), force drops to zero at radius boundary (sharp cutoff, immediate transition), simple behavior (easy to predict, consistent force everywhere), useful for barriers or uniform zones. Falloff type 1 linear: force strongest at center (full strength, maximum effect), force decreases linearly to radius (gradual reduction, smooth falloff), force zero at radius boundary (reaches zero at edge, gentle transition), formula force = strength * (1 - distance/radius), realistic for many effects. Falloff type 2 inverse square: force strongest at center (approaches infinity near center, very strong), force decreases rapidly with distance (inverse square law, physical gravity/magnetism), force weak at radius edge (minimal effect far from center), formula force = strength / max(distance^2, minDistance^2), prevents division by zero at center. Repulsion field example: explosion force field (repulsion = b3dCreateForceField(0, explosionX, explosionY, explosionZ, 10.0, 80.0, 1)), radial push from explosion center (characters flung outward), linear falloff (stronger near center, weaker at edges), temporary or permanent (can delete after short duration for impulse, or keep for barrier). Attraction point example: black hole force field (blackHole = b3dCreateForceField(0, holeX, holeY, holeZ, 15.0, -30.0, 2)), radial pull toward center (characters sucked inward), inverse square falloff (realistic gravitational attraction, very strong near center), permanent hazard (force field remains active, continuous danger). Wind tunnel example: tunnel force field (tunnel = b3dCreateForceField(1, tunnelX, tunnelY, tunnelZ, 20.0, 15.0, 0)), rotate to forward direction (b3dRotateForceField(tunnel, 0, tunnelYaw, 0) orient cone), constant forward push (uniform force along tunnel length), directional movement (characters pushed forward through tunnel). Force barrier example: barrier force field (barrier = b3dCreateForceField(0, barrierX, barrierY, barrierZ, 5.0, 100.0, 0)), strong repulsion (very high strength, hard to penetrate), constant falloff (uniform force, consistent barrier everywhere), access control (blocks character movement, force field as wall). Launch pad example: upward force field (launcher = b3dCreateForceField(0, padX, padY, padZ, 3.0, 50.0, 1)), position at ground level (y = floor height, force field at pad location), strong upward force (flings characters into air when they step on pad), linear falloff (strongest at center, weaker at edges for gradual launch). Default properties: cone angle 45 degrees (half-angle, set at creation, modify with b3dSetForceFieldConeAngle), resistance 0.0 (no opposing force, set at creation, modify with b3dSetForceFieldResistance), rotation (0, 0, 0) (no rotation, default forward +Z, modify with b3dRotateForceField), uniform scale (radius, radius, radius) (same size all axes, modify with b3dScaleForceField). Multiple force fields: create multiple fields independently (each with unique handle, separate positioning and properties), fields combine additively (character in multiple fields experiences sum of forces, forces add together), unlimited fields (no hard limit, create as many as needed for level). Force field lifetime: fields persist until deleted (b3dDeleteForceField(handle) removes field), remains active across frames (continuously affects characters until removed), cleanup on level unload (delete all force fields when changing levels or exiting). Coordinate system: x horizontal east-west (positive east, negative west), y vertical up-down (positive up, negative down), z horizontal north-south (positive north/forward, negative south/backward), position in world space (absolute coordinates, same as entity positions). Performance: O(1) creation (simple struct initialization, instant), force application cost per frame (O(N*M) where N=characters M=fields, calculated during UpdatePhysicsSystem), typical performance (few fields and characters, negligible cost < 0.1ms). Validation: no validation on parameters (any values allowed, user responsible for reasonable values), falloffType clamped to 0-2 (ensures valid type, prevents undefined behavior), returns valid handle (always succeeds, handle from sequential counter). Related: b3dPositionForceField moves force field (change position after creation), b3dRotateForceField orients force field (set cone direction for cone type), b3dDeleteForceField removes force field (cleanup when no longer needed), b3dScaleForceField resizes force field (change radius after creation).