geometry-and-math

# 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 toward target angle | | `ShortestBetween(angle1, angle2)` | Shortest difference in degrees | | `Wrap(angle)` | Wrap to (-PI, PI] | | `WrapDegrees(angle)` | Wrap to (-180, 180] | ### Distance Functions (`Phaser.Math.Distance.*`) | Function | Description | |---|---| | `Between(x1, y1, x2, y2)` | Euclidean distance | | `BetweenPoints(a, b)` | Same, taking `{x,y}` objects | | `BetweenPointsSquared(a, b)` | Squared distance (avoids sqrt) | | `Chebyshev(x1, y1, x2, y2)` | Chebyshev (chessboard) distance | | `Power(x1, y1, x2, y2, pow)` | Minkowski distance with custom power | | `Snake(x1, y1, x2, y2)` | Manhattan/taxicab distance | | `Squared(x1, y1, x2, y2)` | Squared Euclidean distance | ### Interpolation (`Phaser.Math.Interpolation.*`) | Function | Description | |---|---| | `BezierInterpolation(v, k)` | Bezier curve through control points | | `CatmullRomInterpolation(v, k)` | Catmull-Rom spline through points | | `CubicBezierInterpolation(t, p0, p1, p2, p3)` | Cubic Bezier between four values | | `LinearInterpolation(v, k)` | Linear through array of values | | `QuadraticBezierInterpolation(t, p0, p1, p2)` | Quadratic Bezier | | `SmoothStepInterpolation(t, min, max)` | Hermite smooth step | | `SmootherStepInterpolation(t, min, max)` | Ken Perlin's smoother step | ### Snap Functions (`Phaser.Math.Snap.*`) | Function | Description | |---|---| | `To(value, gap, start?, divide?)` | Snap to nearest increment | | `Floor(value, gap, start?, divide?)` | Snap down to increment | | `Ceil(value, gap, start?, divide?)` | Snap up to increment | ### Fuzzy Comparison (`Phaser.Math.Fuzzy.*`) | Function | Description | |---|---| | `Equal(a, b, epsilon?)` | a approximately equals b | | `LessThan(a, b, epsilon?)` | a < b within epsilon | | `GreaterThan(a, b, epsilon?)` | a > b within epsilon | | `Ceil(value, epsilon?)` | Fuzzy ceiling | | `Floor(value, epsilon?)` | Fuzzy floor | ### Easing Functions (`Phaser.Math.Easing.*`) Each type has `.In`, `.Out`, `.InOut` variants. Used primarily by tweens (pass string names like `'Sine.easeOut'`). | Type | String Keys | |---|---| | Back | `Back.easeIn`, `Back.easeOut`, `Back.easeInOut` | | Bounce | `Bounce.easeIn`, `Bounce.easeOut`, `Bounce.easeInOut` | | Circular | `Circ.easeIn`, `Circ.easeOut`, `Circ.easeInOut` | | Cubic | `Cubic.easeIn`, `Cubic.easeOut`, `Cubic.easeInOut` | | Elastic | `Elastic.easeIn`, `Elastic.easeOut`, `Elastic.easeInOut` | | Expo | `Expo.easeIn`, `Expo.easeOut`, `Expo.easeInOut` | | Linear | `Linear` (no variants) | | Quadratic | `Quad.easeIn`, `Quad.easeOut`, `Quad.easeInOut` | | Quartic | `Quart.easeIn`, `Quart.easeOut`, `Quart.easeInOut` |