Core.Extensions

This documentation provides an overview of the core extension methods found in the Meatcorps.Engine.Core.Extensions namespace. These methods are designed to simplify common mathematical operations, string manipulations, and geometric calculations within the engine.

---

1. String Extensions (StringExtensions)

Provides utility methods for string manipulation.

• ToCapitalize(): Converts the first character of a string to uppercase.
  • Use Case: Formatting UI labels or names.
  • Example:

string name = "player";
      string capitalized = name.ToCapitalize(); // "Player"

---

2. Integer Extensions (IntExtensions)

• Wrap(int size): Wraps a value within the range [0, size - 1]. Unlike the standard modulo operator, this correctly handles negative numbers for toroidal (wrap-around) logic.
  • Use Case: Indexing in a circular array or wrapping tile coordinates.
  • Example:

int index = -1;
      int wrapped = index.Wrap(10); // 9

---

3. Enum Extensions (EnumExtensions)

• HasFlagFast<T>(T flag): A high-performance version of Enum.HasFlag using unsafe bitwise operations.
  • Use Case: Checking state flags in performance-critical loops (e.g., input handling or physics).
  • Example:

if (myFlags.HasFlagFast(EntityFlags.Active)) { ... }

---

4. Floating Point Extensions (FloatExtensions)

Provides safe comparisons and range utilities for float.

• EqualsSafe / Approximately: Checks if two floats are equal within a small epsilon.
• Between / Between01: Checks if a value is within a specific range.
• Saturate(): Clamps a value between 0.0f and 1.0f.
• Wrap(float size): Wraps a float value (toroidal).
  • Example:

float healthNormalized = currentHealth / maxHealth;
      if (healthNormalized.Between01()) { ... }
      float angle = 370f;
      float wrappedAngle = angle.Wrap(360f); // 10.0f

---

5. Vector2 Extensions (Vector2Extensions)

Extends System.Numerics.Vector2 with common game development math.

• Lerp / LerpClamped: Linear interpolation between two vectors.
• NormalizedCopy / NormalizedSafe: Returns a normalized version of the vector. Safe handles zero-length vectors without returning NaN.
• Rotate(float radians): Rotates the vector by a given angle.
• ProjectOn / RejectFrom: Vector projection and rejection (perpendicular component).
• LimitMagnitude(float max): Truncates the vector length if it exceeds max.
• ReflectVelocity(LineF line): Reflects a velocity vector against a 2D line.
  • Example (Steering Behaviors):

Vector2 velocity = new Vector2(10, 5);
      velocity = velocity.LimitMagnitude(maxSpeed);

---

6. PointInt Extensions (PointIntExtensions)

Utilities for integer-based coordinates.

• Warp(int width, int height): Wraps integer coordinates within a bounding box.
  • Use Case: Moving an entity on a grid-based map where the edges wrap around.
  • Example:

PointInt pos = new PointInt(-1, 5);
      PointInt wrappedPos = pos.Warp(100, 100); // (99, 5)

---

7. Matrix3x2 Extensions (Matrix3x2Extensions)

• Transform(Vector2 v): Applies the matrix transformation to a point.
• TransformRectangle: Transforms the center and extents of an Axis-Aligned Bounding Box (AABB), resulting in a new AABB that encloses the transformed area.
• TransformOrientedRectangle: Updates the center and orientation matrix of an Oriented Bounding Box (OBB).

---

8. RectangleF Extensions (RectangleFExtensions)

Extends RectF (and RectangleF) with layout and collision utilities.

• Intersects(RectangleF other): Standard AABB collision check.
• ClampPoint / WrapPoint: Constrains a point to be inside the rectangle or wraps it around the edges.
• GetSegments: Divides a rectangle into a grid of smaller rectangles.
  • Use Case: Creating UI grids, inventory slots, or splitting a sprite sheet.
• Align(RectF inner, Vector2 uv): Positions an inner rectangle within an outer one based on UV coordinates (e.g., (0.5, 0.5) for center alignment).
• NextPosition: Calculates the position for the "next" element in a layout sequence.
  • Example (Grid Layout):

RectF screen = new RectF(0, 0, 800, 600);
      // Get a 4x4 grid of segments with a 5px gap
      var slots = screen.GetSegments(4, 4, gap: 5f);