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

// 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 containmentrect.contains(50, 50);    // truecircle.contains(410, 310); // true
// Intersection testPhaser.Geom.Intersects.CircleToRectangle(circle, rect); // boolean
// Math utilitiesconst v = new Phaser.Math.Vector2(3, 4);v.length();      // 5v.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

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)

Get Intersection Points (return Vector2[])

Math Functions by Category

All under Phaser.Math unless noted.

Constants

Angle Functions (Phaser.Math.Angle.*)

Distance Functions (Phaser.Math.Distance.*)

Interpolation (Phaser.Math.Interpolation.*)

Snap Functions (Phaser.Math.Snap.*)

Fuzzy Comparison (Phaser.Math.Fuzzy.*)

Easing Functions (Phaser.Math.Easing.*)

Each type has .In, .Out, .InOut variants. Used primarily by tweens (pass string names like 'Sine.easeOut').

Power aliases: Power0 = Linear, Power1 = Quad.Out, Power2 = Cubic.Out, Power3 = Quart.Out, Power4 = Quint.Out.

Short names also work: 'Quad' = Quad.Out, 'Sine' = Sine.Out, etc.

Core Math Helpers (directly on Phaser.Math)

Power-of-Two (Phaser.Math.Pow2.*)

Vector2 Quick Reference

Phaser.Math.Vector2 -- 2D vector used throughout Phaser for positions, velocities, directions.

Constructor: new Vector2(x?, y?) or new Vector2({x, y}). If only x given, y defaults to x.

Static: Vector2.ZERO, Vector2.RIGHT, Vector2.LEFT, Vector2.UP, Vector2.DOWN, Vector2.ONE.

Vector3 Quick Reference

Phaser.Math.Vector3 -- 3D vector for camera projections, lighting, 3D math.

Constructor: new Vector3(x?, y?, z?) or new Vector3({x, y, z}).

Key methods (same patterns as Vector2 plus): up(), min(v), max(v), addVectors(a, b), subVectors(a, b), crossVectors(a, b), cross(v), addScalar(s), addScale(v, scale), fromArray(array, offset?), setFromMatrixPosition(mat4), setFromMatrixColumn(mat4, index), applyMatrix3(mat), applyMatrix4(mat), transformCoordinates(mat), transformQuat(q), project(mat), projectViewMatrix(view, proj), unproject(viewport, invProjView).

Matrix4 Quick Reference

Phaser.Math.Matrix4 -- 4x4 matrix for 3D transforms, projection, and view matrices. Backed by Float32Array(16).

Constructor: new Matrix4(m?) -- copies from existing Matrix4, or defaults to identity.

Key methods: clone(), set(src), copy(src), identity(), transpose(), invert(), adjoint(), determinant(), multiply(src), multiplyLocal(src), translate(v), scale(v), rotate(angle, axis), rotateX(angle), rotateY(angle), rotateZ(angle), fromRotationTranslation(q, v), fromQuat(q), frustum(...), perspective(fovy, aspect, near, far), perspectiveLH(width, height, near, far), ortho(left, right, bottom, top, near, far), lookAt(eye, center, up), lookAtRH(eye, target, up), setWorldMatrix(rotation, position, scale, viewMatrix?, projectionMatrix?).

Also: Phaser.Math.Matrix3 -- 3x3 matrix for 2D transforms and normal matrices.

RandomDataGenerator

Phaser.Math.RandomDataGenerator -- seeded PRNG. Global instance at Phaser.Math.RND (seeded via game config seed property).

const rnd = Phaser.Math.RND; // or new Phaser.Math.RandomDataGenerator(['my-seed'])
rnd.integer();              // random integer in [0, 2^32]rnd.frac();                 // random float in [0, 1)rnd.between(1, 10);         // random integer in [1, 10]rnd.integerInRange(1, 10);  // alias for betweenrnd.realInRange(0.5, 1.5);  // random float in [0.5, 1.5]rnd.normal();               // normal distribution around 0rnd.angle();                // random angle in radians (-PI to PI)rnd.rotation();             // random rotation in radians (same range)rnd.pick(array);            // random element from arrayrnd.weightedPick(array);    // weighted toward end of arrayrnd.sign();                 // -1 or 1rnd.uuid();                 // RFC4122 v4 UUID stringrnd.shuffle(array);         // in-place Fisher-Yates shufflernd.state(state?);          // get/set serializable state for save/load

Create reproducible sequences by providing seeds: new RandomDataGenerator(['level-42']).

Color Utilities

Color Class (Phaser.Display.Color)

A mutable RGBA color representation with automatic conversion to WebGL floats, HSV, CSS strings, and packed integers.

// Constructionconst color = new Phaser.Display.Color(255, 0, 0, 255);     // RGBA (0-255)
// Creation helpers (return Color instances)const c1 = Phaser.Display.Color.ValueToColor('#ff0000');     // hex string, integer, or objectconst c2 = Phaser.Display.Color.HexStringToColor('#ff0000');const c3 = Phaser.Display.Color.RGBStringToColor('rgb(255,0,0)');const c4 = Phaser.Display.Color.HSVToRGB(0.5, 1, 1);        // returns { r, g, b, color }
// Propertiescolor.r; color.g; color.b; color.a;   // 0-255 integerscolor.redGL; color.greenGL; color.blueGL; color.alphaGL;  // 0-1 floats (WebGL)color.color;    // packed 24-bit integer (0xRRGGBB)color.color32;  // packed 32-bit integer (0xAARRGGBB)color.rgba;     // CSS string 'rgba(r,g,b,a)'color.h; color.s; color.v;  // HSV representation (read-only, auto-updated)

Color Manipulation

// Adjustment methods (amount is typically 0-100, returns the Color instance)color.brighten(25);      // increase brightnesscolor.saturate(50);      // increase saturationcolor.desaturate(30);    // decrease saturationcolor.lighten(20);       // increase lightnesscolor.darken(10);        // decrease lightness
// Utility methodscolor.random();          // set to random RGB values (optional min/max range)color.gray(128);         // set to grayscale shade (0-255)
// Setting valuescolor.setTo(255, 128, 0, 255);           // RGBAcolor.setFromRGB({ r: 255, g: 128, b: 0, a: 255 });color.setFromHSV(0.1, 0.8, 1.0);        // HSV (0-1 range)

Color Interpolation (Phaser.Display.Color.Interpolate)

Interpolate between colors over a given length. Returns { r, g, b, a, color }.

// Between raw RGB valuesconst result = Phaser.Display.Color.Interpolate.RGBWithRGB(    255, 0, 0,    // start color (r, g, b)    0, 0, 255,    // end color (r, g, b)    100,          // length (number of steps)    50            // index (current step));  // returns midpoint purple { r, g, b, a, color }
// Between two Color objectsconst mid = Phaser.Display.Color.Interpolate.ColorWithColor(color1, color2, 100, 50);
// HSV interpolation (v4): smooth hue transitionconst hsvResult = Phaser.Display.Color.Interpolate.HSVWithHSV(0, 1, 1, 0.5, 1, 1, 100, 50);

Gotchas

1. Geom objects are not game objects. They have no scene, no setPosition from the display list, no texture. Use Graphics or Shape game objects to render them.

2. Point class removed in v4. Use Phaser.Math.Vector2 or plain {x, y} objects instead. The GEOM_CONST.POINT (3) exists but the Point class does not.

3. Angles are in radians throughout the math API. Use Phaser.Math.DegToRad() and RadToDeg() for conversion. The Phaser.Math.TAU constant (2 * PI) is new in v4.

4. Vector2 methods mutate in place and return this for chaining. Call .clone() first if you need to preserve the original: const result = v.clone().add(other).

5. Squared distance is faster than Euclidean distance (avoids Math.sqrt). Use Distance.Squared or vec.distanceSq() for comparisons where the actual distance value is not needed.

6. Intersection Get functions allocate arrays.* Pass a reusable out array to avoid garbage collection pressure in hot loops.

7. EaseMap short names default to the .Out variant. 'Quad' means Quadratic.Out, not Quadratic.In. Use full string keys like 'Quad.easeIn' for other variants.

8. RandomDataGenerator state is serializable. Call rnd.state() to get a string you can store, and rnd.state(savedString) to restore it for deterministic replay.

9. Polygon.contains uses ray-casting (even/odd rule). Complex self-intersecting polygons may give unexpected results.

10. Matrix4.val is a Float32Array. Access elements directly via mat.val[index] using column-major order (OpenGL convention).

Source File Map