b3dRotateEntity

Sets entity rotation in degrees (modifies transform, routes to physics if body attached). Takes entity (entity handle), pitch (rotation around X-axis in degrees), yaw (rotation around Y-axis in degrees), roll (rotation around Z-axis in degrees). Returns nothing. Validates entity exists, if physicsBodyHandle!=0 routes to b3dSetPhysicsBodyRotation for physics-driven rotation, otherwise sets entity.rotation=XMFLOAT3(pitch, yaw, roll), marks worldMatrixDirty=true to trigger matrix recalculation. Modifies entity transform (doesn't change geometry).

This function sets entity orientation via Euler angles. Transform vs geometry: RotateEntity modifies entity's transform matrix (affects rendering orientation), doesn't change mesh vertices (geometry unchanged), entity visually rotates but mesh data identical. Contrast with b3dRotateMesh which rotates vertices/normals/tangents directly (permanent geometry change). Euler angles: rotation specified as pitch/yaw/roll (degrees), pitch rotates around X-axis (look up/down), yaw rotates around Y-axis (turn left/right), roll rotates around Z-axis (tilt sideways). Order of rotation: pitch->yaw->roll (intrinsic rotations), converted to quaternion for matrix calculation (avoids gimbal lock internally). Gimbal lock: Euler angles suffer gimbal lock at pitch=+/-90 degrees (loss of degree of freedom), for complex rotations prefer quaternion-based rotation (b3dSetEntityQuaternion if available). Physics integration: checks entity.physicsBodyHandle!=0 (non-zero means physics body attached), if physics body present, routes to b3dSetPhysicsBodyRotation instead of setting rotation directly, physics system owns orientation (rotation updates propagate to entity during physics step), prevents physics-visual desynchronization. If no physics body, standard rotation applies. WorldMatrix dirty flag: setting rotation marks worldMatrixDirty=true, triggers UpdateEntityWorldMatrix() during next render pass, recalculates matrix: WorldMatrix = Scale * Rotation * Translation, parent matrices multiply with child matrices (hierarchy propagation). Use cases: (1) Orient objects (face direction, aim weapons, point cameras), (2) Animate rotation (spinning objects, turret tracking, vehicle wheels), (3) Align to surfaces (place objects on slopes), (4) Procedural generation (random orientations), (5) Camera control (first-person look, orbit camera). Common pattern: b3dRotateEntity(entity, pitch, yaw, roll) for absolute orientation, or b3dTurnEntity for relative rotation. Coordinate system: right-handed coordinate system (X=right, Y=up, Z=forward), rotations follow right-hand rule (positive rotation counterclockwise when looking down axis). World vs local rotation: RotateEntity sets world space rotation (ignores parent orientation), for local rotation use b3dSetEntityLocalRotation or apply relative to parent. Parent-child relationships: rotated entity rotates children with it (children inherit parent rotation), children's local rotations combine with parent rotation for final world orientation. Performance: rotation setting is O(1) operation (no immediate recalculation), matrix recalculation deferred until render (lazy evaluation), setting multiple properties (position, rotation, scale) before render efficient (single matrix update). Typical usage: set rotation at creation for initial orientation, update rotation in game loop for animated rotation, route through physics for physically-simulated rotation (ragdolls, tumbling objects). Validation: invalid entity handles silently ignored. Angle range: no clamping applied (360+ degrees valid, normalized during matrix calculation). Related: b3dRotateMesh modifies vertices/normals directly (permanent geometry change), b3dTurnEntity for relative rotation, b3dSetPhysicsBodyRotation for physics body rotation, b3dGetEntityPitch/Yaw/Roll for querying rotation, UpdateEntityWorldMatrix recalculates world matrix.