b3dRotateForceField

Rotates force field (pitch,yaw,roll in degrees, sets cone direction for cone type fields). Takes handle (force field handle from b3dCreateForceField), pitch (rotation around X axis in degrees, up/down tilt), yaw (rotation around Y axis in degrees, left/right turn), roll (rotation around Z axis in degrees, barrel roll). Returns nothing. Sets ff.rotation, orients force field for next physics update. Use to aim cone force fields, rotate directional forces, or orient field directions.

This function rotates force field. Force field rotation: sphere fields (shapeType 0) rotation has no effect (radial force same in all directions, rotation irrelevant), cone fields (shapeType 1) rotation determines cone direction (forward axis based on pitch/yaw/roll, cone points in rotated direction), rotation defines orientation (default forward +Z axis, rotation transforms to desired direction). Rotation parameters: pitch = rotation around X axis (positive = tilt up, negative = tilt down, degrees), yaw = rotation around Y axis (positive = turn right, negative = turn left, degrees), roll = rotation around Z axis (positive = clockwise roll, negative = counter-clockwise, degrees), Euler angles (applied in pitch/yaw/roll order, standard rotation convention). Use cases: (1) Wind tunnel aiming (orient cone to blow in specific direction), (2) Directional hazards (cone force field pointing at player or path), (3) Rotating beams (cone that spins or sweeps area), (4) Angled launchers (aim force field up and forward for arc trajectory), (5) Dynamic targeting (rotate cone to track moving character). Common patterns: aim forward b3dRotateForceField(field, 0, 0, 0) default +Z direction, aim up b3dRotateForceField(field, -90, 0, 0) vertical upward, aim right b3dRotateForceField(field, 0, 90, 0) eastward, track target b3dRotateForceField(field, pitchToTarget, yawToTarget, 0) aim at character. Typical usage: set once at creation (orient cone to desired initial direction), call every frame for rotating fields (spin or sweep cone over time), call for dynamic aiming (point cone at moving target).

Default rotation: (0, 0, 0) at creation (no rotation, default forward +Z axis, north/forward direction), remains until explicitly changed (persistent rotation, doesn't reset), applied to cone forward axis (transforms cone direction from default to rotated). Cone direction: default forward +Z axis (north/forward in world space, before rotation), pitch rotates around X (tilts cone up or down, changes vertical angle), yaw rotates around Y (turns cone left or right, changes horizontal angle), roll rotates around Z (spins cone around forward axis, usually not needed for aiming). Sphere field rotation: sphere fields unaffected by rotation (radial force same in all directions, rotation does nothing), can still call function (no error, silently ignored for sphere type), only cone fields use rotation (directional force requires orientation). Wind tunnel example: create cone wind tunnel (tunnel = b3dCreateForceField(1, x, y, z, 20, 15, 0)), orient tunnel forward (b3dRotateForceField(tunnel, 0, yaw, 0) set horizontal direction), adjust for slope (b3dRotateForceField(tunnel, pitch, yaw, 0) tilt up or down if needed), forward push in rotated direction. Rotating beam example: cone beam rotates continuously (angle increments each frame, angle += rotationSpeed * deltaTime), rotate beam (b3dRotateForceField(rotatingBeam, 0, angle, 0) spin around Y axis), sweeping hazard (beam rotates 360 degrees, sweeps area repeatedly). Upward launcher example: cone points upward and forward (launch arc trajectory), set pitch for angle (b3dRotateForceField(launcher, -60, 0, 0) aim 60 degrees above horizontal), combined with forward component (upward and forward force for arc), launches characters into air. Track target example: calculate aim angles (dx = targetX - fieldX, dz = targetZ - fieldZ, dy = targetY - fieldY), calculate yaw (yaw = atan2(dx, dz) aim horizontally toward target), calculate pitch (dist = sqrt(dx^2 + dz^2), pitch = atan2(dy, dist) aim vertically toward target), rotate to target (b3dRotateForceField(trackingField, pitch, yaw, 0) aim at target position). Coordinate system: X axis east-west (pitch rotates around, tilts forward axis up/down), Y axis up-down (yaw rotates around, turns forward axis left/right), Z axis north-south (roll rotates around, spins forward axis), right-handed Y-up (standard 3D coordinate system). Rotation order: rotations applied in pitch/yaw/roll order (standard Euler angle convention), pitch applied first (tilts forward axis up/down), yaw applied second (turns tilted axis left/right), roll applied last (spins final axis around itself, rarely needed). Pitch range: -90 degrees aims down (cone points vertically downward, negative pitch), 0 degrees aims horizontal (cone points forward horizontally, no vertical tilt), +90 degrees aims up (cone points vertically upward, positive pitch), typical range -90 degrees to +90 degrees for up/down aiming. Yaw range: 0 degrees aims forward/north (default +Z direction, no horizontal turn), 90 degrees aims right/east (turns 90 degrees right, points eastward), 180 degrees aims backward/south (turns 180 degrees, points southward), -90 degrees aims left/west (turns 90 degrees left, points westward), full 360 degrees rotation (any angle valid, wraps around). Roll range: 0 degrees no roll (cone upright, standard orientation), 90 degrees rolled 90 degrees clockwise (cone rotated around forward axis), useful for asymmetric cones (if cone not radially symmetric, roll affects orientation), typically 0 degrees (roll rarely needed for symmetric cones). Rotation vs position: rotation sets direction only (where cone points, orientation of force), position sets location only (where cone originates, center point of force), independent properties (can change rotation without affecting position, vice versa). Rotation animation: interpolate between rotations (currentRot = Slerp(startRot, endRot, t) for smooth rotation), update field rotation (b3dRotateForceField(animField, currentRot.Pitch, currentRot.Yaw, currentRot.Roll)), smooth turning (cone smoothly rotates from start to end direction). Spinning field: increment yaw each frame (yaw += spinSpeed * deltaTime, continuous rotation), rotate field (b3dRotateForceField(spinningField, 0, yaw, 0) rotate around Y axis), spinning cone (rotates continuously, sweeps 360 degrees repeatedly). Target tracking: calculate target direction each frame (aimPitch, aimYaw from character position to target), rotate to aim (b3dRotateForceField(trackingField, aimPitch, aimYaw, 0) point at target), dynamic targeting (cone follows moving target continuously). Rotation persistence: rotation change immediate (takes effect next physics update, no delay), rotation remains until changed again (persistent, doesn't reset automatically), force field oriented at new rotation until explicitly rotated or deleted. Real-time rotation: safe to call every frame (O(1) operation, simple assignment), typical for rotating hazards or tracking fields (dynamic orientation, continuous updates), smooth rotation (small angle changes each frame create continuous motion). Performance: O(1) operation (simple vector assignment, instant), no computation required (rotation stored for later use during physics), safe to call every frame for rotating fields (negligible cost). Validation: silently returns if handle not found (invalid or deleted force field, no error), no rotation validation (any angles allowed, user responsible for reasonable rotations), no error messages (silent failure for performance). Related: b3dCreateForceField creates force field (returns handle, default rotation 0,0,0 at creation), b3dPositionForceField moves force field (sets center point, complementary to rotation), b3dSetForceFieldConeAngle sets cone spread (half-angle of cone, affects cone width), b3dScaleForceField resizes force field (changes radius, complementary to rotation).