geometry-and-math

What this skill does

# Phaser 4 — Geometry and Math

> Geom classes (Circle, Ellipse, Line, Polygon, Rectangle, Triangle), intersection tests, and Math utilities (Vector2, Vector3, Matrix4, angles, distances, interpolation, easing, random, snap, clamp).

Related skills: graphics-and-shapes.md, physics-arcade.md

---

## Quick Start

```js
// Create geometry objects (these are data only, not renderable)
const rect = new Phaser.Geom.Rectangle(10, 20, 200, 100);
const circle = new Phaser.Geom.Circle(400, 300, 50);
const line = new Phaser.Geom.Line(0, 0, 100, 100);

// Point containment
rect.contains(50, 50);    // true
circle.contains(410, 310); // true

// Intersection test
Phaser.Geom.Intersects.CircleToRectangle(circle, rect); // boolean

// Math utilities
const v = new Phaser.Math.Vector2(3, 4);
v.length();      // 5
v.normalize();   // {x: 0.6, y: 0.8}

const dist = Phaser.Math.Distance.Between(0, 0, 100, 100);
const angle = Phaser.Math.Angle.Between(0, 0, 100, 100);
const clamped = Phaser.Math.Clamp(150, 0, 100); // 100
```

---

## Core Concepts

Geometry objects are pure data containers holding coordinates and dimensions. They are NOT game objects and cannot be added to the display list. To render geometry, use the Graphics game object or Shape game objects (see graphics-and-shapes.md).

Every geom class has a `type` property set to a `Phaser.Geom` constant for fast type checks.

All geom classes share a common instance method pattern:
- `contains(x, y)` -- point-in-shape test
- `getPoint(position, output?)` -- point at normalized position (0-1) on perimeter
- `getPoints(quantity, stepRate?, output?)` -- evenly spaced points on perimeter
- `getRandomPoint(output?)` -- random point inside the shape
- `setTo(...)` -- reset all properties
- `setEmpty()` -- zero out the shape
- `setPosition(x, y)` -- move origin/center

Each geom type also has a folder of static helper functions (e.g., `Phaser.Geom.Rectangle.Contains`, `Phaser.Geom.Circle.Area`).

---

## Geometry Classes

| Class | Namespace | Constructor | Key Properties |
|---|---|---|---|
| **Circle** | `Phaser.Geom.Circle` | `(x, y, radius)` | `x`, `y`, `radius`, `diameter`, `left`, `right`, `top`, `bottom` |
| **Ellipse** | `Phaser.Geom.Ellipse` | `(x, y, width, height)` | `x`, `y`, `width`, `height`, `left`, `right`, `top`, `bottom` |
| **Line** | `Phaser.Geom.Line` | `(x1, y1, x2, y2)` | `x1`, `y1`, `x2`, `y2`, `left`, `right`, `top`, `bottom` |
| **Polygon** | `Phaser.Geom.Polygon` | `(points)` | `area`, `points` (array of Vector2Like) |
| **Rectangle** | `Phaser.Geom.Rectangle` | `(x, y, width, height)` | `x`, `y`, `width`, `height`, `left`, `right`, `top`, `bottom`, `centerX`, `centerY` |
| **Triangle** | `Phaser.Geom.Triangle` | `(x1, y1, x2, y2, x3, y3)` | `x1`, `y1`, `x2`, `y2`, `x3`, `y3` |

### Rectangle Static Helpers

`Phaser.Geom.Rectangle.*`: Area, Ceil, CeilAll, CenterOn, Clone, Contains, ContainsPoint, ContainsRect, CopyFrom, Decompose, Equals, FitInside, FitOutside, Floor, FloorAll, FromPoints, FromXY, GetAspectRatio, GetCenter, GetPoint, GetPoints, GetSize, Inflate, Intersection, MarchingAnts, MergePoints, MergeRect, MergeXY, Offset, OffsetPoint, Overlaps, Perimeter, PerimeterPoint, Random, RandomOutside, SameDimensions, Scale, Union.

### Circle Static Helpers

`Phaser.Geom.Circle.*`: Area, Circumference, CircumferencePoint, Clone, Contains, ContainsPoint, ContainsRect, CopyFrom, Equals, GetBounds, GetPoint, GetPoints, Offset, OffsetPoint, Random.

### Line Static Helpers

`Phaser.Geom.Line.*`: Angle, BresenhamPoints, CenterOn, Clone, CopyFrom, Equals, Extend, GetEasedPoints, GetMidPoint, GetNearestPoint, GetNormal, GetPoint, GetPoints, GetShortestDistance, Height, Length, NormalAngle, NormalX, NormalY, Offset, PerpSlope, Random, ReflectAngle, Rotate, RotateAroundPoint, RotateAroundXY, SetToAngle, Slope, Width.

### Triangle Static Helpers

`Phaser.Geom.Triangle.*`: Area, BuildEquilateral, BuildFromPolygon, BuildRight, CenterOn, Centroid, CircumCenter, CircumCircle, Clone, Contains, ContainsArray, ContainsPoint, CopyFrom, Decompose, Equals, GetPoint, GetPoints, InCenter, Offset, Perimeter, Random, Rotate, RotateAroundPoint, RotateAroundXY.

### Polygon Input Formats

The Polygon constructor accepts multiple formats for the `points` argument:
- Space-separated string: `'40 0 40 20 100 20 100 80'`
- Array of `{x, y}` objects
- Flat number array: `[x1, y1, x2, y2, ...]`
- Array of `[x, y]` sub-arrays

---

## Intersection Tests

All under `Phaser.Geom.Intersects`.

### Boolean Tests (return `true`/`false`)

| Function | Description |
|---|---|
| `CircleToCircle(circleA, circleB)` | Two circles overlap |
| `CircleToRectangle(circle, rect)` | Circle overlaps rectangle |
| `LineToCircle(line, circle)` | Line segment intersects circle |
| `LineToLine(line1, line2, out?)` | Two line segments cross; writes point to `out` |
| `LineToRectangle(line, rect)` | Line segment intersects rectangle |
| `PointToLine(point, line, lineThickness?)` | Point lies on/near line |
| `PointToLineSegment(point, line)` | Point lies on finite line segment |
| `RectangleToRectangle(rectA, rectB)` | Two rectangles overlap |
| `RectangleToTriangle(rect, triangle)` | Rectangle overlaps triangle |
| `RectangleToValues(rect, left, right, top, bottom, tolerance?)` | Rectangle overlaps LRTB bounds |
| `TriangleToCircle(triangle, circle)` | Triangle overlaps circle |
| `TriangleToLine(triangle, line)` | Triangle intersects line |
| `TriangleToTriangle(triA, triB)` | Two triangles overlap |

### Get Intersection Points (return `Vector2[]`)

| Function | Description |
|---|---|
| `GetCircleToCircle(circleA, circleB, out?)` | Intersection points of two circles |
| `GetCircleToRectangle(circle, rect, out?)` | Points where circle meets rectangle edges |
| `GetLineToCircle(line, circle, out?)` | Points where line crosses circle |
| `GetLineToLine(line1, line2, out?)` | Single intersection point of two lines |
| `GetLineToPoints(line, points, out?)` | Intersection with a series of points forming edges |
| `GetLineToPolygon(line, polygon, out?)` | Closest intersection with polygon edges |
| `GetLineToRectangle(line, rect, out?)` | Points where line crosses rectangle |
| `GetRaysFromPointToPolygon(x, y, polygon)` | Ray-cast from point to polygon edges |
| `GetRectangleIntersection(rectA, rectB, out?)` | Overlapping rectangle region |
| `GetRectangleToRectangle(rectA, rectB, out?)` | Edge intersection points |
| `GetRectangleToTriangle(rect, triangle, out?)` | Edge intersection points |
| `GetTriangleToCircle(triangle, circle, out?)` | Edge intersection points |
| `GetTriangleToLine(triangle, line, out?)` | Edge intersection points |
| `GetTriangleToTriangle(triA, triB, out?)` | Edge intersection points |

---

## Math Functions by Category

All under `Phaser.Math` unless noted.

### Constants

| Constant | Value |
|---|---|
| `Phaser.Math.TAU` | PI * 2 (v4 addition) |
| `Phaser.Math.PI_OVER_2` | PI / 2 |
| `Phaser.Math.EPSILON` | 1.0e-6 |
| `Phaser.Math.DEG_TO_RAD` | PI / 180 |
| `Phaser.Math.RAD_TO_DEG` | 180 / PI |
| `Phaser.Math.RND` | Global `RandomDataGenerator` instance (seeded via game config `seed`) |

### Angle Functions (`Phaser.Math.Angle.*`)

| Function | Description |
|---|---|
| `Between(x1, y1, x2, y2)` | Angle in radians between two points |
| `BetweenPoints(point1, point2)` | Same, taking `{x,y}` objects |
| `BetweenY(x1, y1, x2, y2)` | Angle from vertical axis |
| `BetweenPointsY(point1, point2)` | Same, taking objects |
| `CounterClockwise(angle)` | Convert to counter-clockwise |
| `GetClockwiseDistance(from, to)` | Clockwise angular distance |
| `GetCounterClockwiseDistance(from, to)` | Counter-clockwise angular distance |
| `GetShortestDistance(from, to)` | Shortest angular distance (signed) |
| `Normalize(angle)` | Normalize to [0, 2PI) |
| `Random()` | Random angle in radians |
| `RandomDegrees()` | Random angle in degrees |
| `Reverse(angle)` | Reverse (add PI) |
| `RotateTo(currentAngle, targetAngle, lerp?)` | Step