Core.Utilities.MathHelper

The MathHelper class in the Meatcorps.Engine.Core.Utilities namespace provides a set of static utility methods designed to simplify common mathematical operations, particularly those used in game development and 2D physics.

Here is an explanation of each helper method along with usage examples:

1. Angle Conversions

These methods allow you to switch between radians (used by most mathematical functions) and degrees (more intuitive for human input).

• ToDegrees(float radians): Converts radians to degrees by multiplying by $180 / \pi$.
• ToRadians(float degrees): Converts degrees to radians by multiplying by $\pi / 180$.

Example:

float angleInDegrees = 90f;
float angleInRadians = MathHelper.ToRadians(angleInDegrees); // Results in approximately 1.5708 (PI/2)

float backToDegrees = MathHelper.ToDegrees(angleInRadians); // Results in 90.0

2. Randomization Helpers

These methods facilitate generating random values specifically for movement and positioning.

• RandomizedPhase(): Returns a random float between $0$ and $2\pi$ (Tau). This is useful for starting a sine wave or rotation at a random point in its cycle.
• RandomUnitVector(System.Random rng): Returns a Vector2 with a length (magnitude) of exactly $1$, pointing in a random direction.
• RandomInsideUnitCircle(System.Random rng): Uses "rejection sampling" to find a random point inside a circle with a radius of $1$.

Example:

var rng = new Random();

// Get a random direction for a projectile
Vector2 direction = MathHelper.RandomUnitVector(rng);

// Get a random spawn point within 5 units of the center
Vector2 spawnOffset = MathHelper.RandomInsideUnitCircle(rng) * 5f;

3. Safety and Clamping

These methods provide robust ways to handle values that might go out of expected ranges.

• Clamp(float value, float min, float max): Ensures a value stays within the specified boundaries.
• SafeAcos(float x): A wrapper for MathF.Acos. It prevents "NaN" (Not a Number) errors by clamping the input to the valid range of $[-1, 1]$ before calculating the inverse cosine. This is vital because floating-point precision errors can occasionally result in values like 1.0000001, which would crash standard math functions.

Example:

// Clamp health between 0 and 100
float currentHealth = 120f;
float safeHealth = MathHelper.Clamp(currentHealth, 0f, 100f); // Returns 100.0

// Safe arc-cosine
float dotProduct = 1.000001f; // Slightly out of range due to float math
float angle = MathHelper.SafeAcos(dotProduct); // Returns 0 instead of NaN

4. Vector Operations

These methods perform complex geometric calculations on Vector2 objects.

• AngleBetweenRad(Vector2 a, Vector2 b): Calculates the angle between two vectors in radians. It includes a safety check to return 0 if either vector is too small (nearly zero length) to avoid division by zero.
• MoveTowards(Vector2 current, Vector2 target, float maxDistanceDelta): Moves a point from current toward target, but never moves further than maxDistanceDelta. This is the standard way to implement constant-speed movement.

Example:

Vector2 playerPos = new Vector2(0, 0);
Vector2 enemyPos = new Vector2(10, 10);

// Calculate the angle the enemy is relative to the player
float angle = MathHelper.AngleBetweenRad(Vector2.UnitX, enemyPos - playerPos);

// Move the player toward the enemy by 0.5 units (e.g., in one frame)
float speed = 0.5f;
playerPos = MathHelper.MoveTowards(playerPos, enemyPos, speed);