b3dPointEntity

Orients entity to face target position (look-at, supports smooth interpolation and parenting). Takes entity (entity handle), targetX/Y/Z (target world position - Y positive up), transition (interpolation factor 0.0-1.0, 0.0=no change, 1.0=instant). Returns nothing. Validates entity exists, negates targetY for internal coords, handles parenting (transforms target to parent's local space if parent exists, ensures parent matrix updated), calculates direction vector to target, normalizes direction, calculates pitch/yaw from direction, interpolates rotation with angle wrapping for yaw, sets roll=0.0, marks worldMatrixDirty=true. Orientation toward target with optional smooth interpolation.

This function implements look-at behavior. Target position: specified in world space (user coordinates, +Y=up), function negates Y: targetInternalY = -targetY for internal coordinate system. Parent handling: if entity has parent (entity.parent!=nullptr), transforms target from world space to parent's local space: ensures parent worldMatrix updated (UpdateEntityWorldMatrix if worldMatrixDirty), calculates parentWorldInv = inverse(parent.worldMatrix), transforms target: localTarget = XMVector3TransformCoord(worldTarget, parentWorldInv), uses localTarget for direction calculation (entity orients toward target in parent's local space). If no parent: uses world coordinates directly (targetLocal = targetInternal). Direction calculation: calculates direction vector: dir = targetLocal - entityPosition, normalizes: dir /= length(dir), if length < 0.0001 (target at entity position or nearly so), function returns without changing rotation (zero-length direction undefined). Pitch/yaw calculation: calculates pitch (up/down rotation): targetPitch = asin(dirY) * 180/PI (angle from horizontal plane), calculates yaw (left/right rotation): targetYaw = atan2(dirX, dirZ) * 180/PI (angle around Y-axis). Roll handling: sets entity.rotation.z = 0.0 (no roll, upright orientation), use b3dPointEntityAt for roll control. Interpolation: transition parameter controls blend between current and target rotation (clamped to 0.0-1.0), transition=0.0: no rotation change (function calculates but doesn't apply, early return), transition=1.0: instant rotation to target (sets rotation = target), 0.0<transition<1.0: lerps between current and target: newPitch = currentPitch + (targetPitch - currentPitch) * transition, newYaw = currentYaw + yawDiff * transition. Angle wrapping for yaw: handles 360-degree wrapping for shortest path: yawDiff = targetYaw - currentYaw, while yawDiff > 180: yawDiff -= 360, while yawDiff < -180: yawDiff += 360, ensures rotation takes shortest path (e.g., 350 to 10 degrees rotates +20, not -340). Use cases: (1) Enemy tracking (turrets, enemies face player), (2) Camera look-at (orbit camera faces target), (3) Billboard sprites (face camera), (4) Animated transitions (smooth turn toward target), (5) Character head tracking (look at points of interest). Common pattern: b3dPointEntity(turret, playerX, playerY, playerZ, 1.0) instant aim at player, b3dPointEntity(camera, targetX, targetY, targetZ, 0.1) smooth camera transition (call every frame). Transition usage: transition=1.0 for instant orientation, 0.0<transition<1.0 for smooth blending (call every frame for animated tracking), transition=0.0 for no change (calculate without applying, debugging). Typical usage: call every frame with low transition for smooth tracking, or call once with transition=1.0 for instant orientation, combine with distance checks for targeting. Performance: parent matrix update if dirty (UpdateEntityWorldMatrix, relatively fast), direction/angle calculations use math functions (asin, atan2, moderate cost), interpolation is simple lerp (fast). Related: b3dPointEntityAt orients toward target entity (instead of position, supports roll), b3dAlignToVector aligns axis to direction vector, b3dRotateEntity sets absolute rotation, b3dTurnEntity applies relative rotation.