geometry-and-math

Phaser 4 — 几何与数学

Geom 类（Circle、Ellipse、Line、Polygon、Rectangle、Triangle）、相交检测，以及 Math 工具（Vector2、Vector3、Matrix4、角度、距离、插值、缓动、随机、对齐、钳制）。

相关技能：graphics-and-shapes.md、physics-arcade.md

---

快速开始

// 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

---

核心概念

几何对象是纯粹的数据容器，用于保存坐标和尺寸。它们不是游戏对象，不能添加到显示列表中。要渲染几何图形，请使用 Graphics 游戏对象或 Shape 游戏对象（参见 graphics-and-shapes.md）。

每个 geom 类都有一个 type 属性，其值为 Phaser.Geom 常量，用于快速类型检查。

所有 geom 类都遵循一套通用的实例方法模式：

• contains(x, y) —— 点在形状内的检测
• getPoint(position, output?) —— 周长上归一化位置（0-1）处的点
• getPoints(quantity, stepRate?, output?) —— 周长上等距分布的点
• getRandomPoint(output?) —— 形状内部的随机点
• setTo(...) —— 重置所有属性
• setEmpty() —— 将形状清零
• setPosition(x, y) —— 移动原点/中心

每种 geom 类型还有一个包含静态辅助函数的文件夹（例如 Phaser.Geom.Rectangle.Contains、Phaser.Geom.Circle.Area）。

---

几何类

类	命名空间	构造函数	关键属性
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（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 静态辅助函数

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 静态辅助函数

Phaser.Geom.Circle.*：Area、Circumference、CircumferencePoint、Clone、Contains、ContainsPoint、ContainsRect、CopyFrom、Equals、GetBounds、GetPoint、GetPoints、Offset、OffsetPoint、Random。

Line 静态辅助函数

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 静态辅助函数

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 输入格式

Polygon 构造函数接受多种格式的 points 参数：

• 空格分隔的字符串：'40 0 40 20 100 20 100 80'
• {x, y} 对象数组
• 扁平数字数组：[x1, y1, x2, y2, ...]
• [x, y] 子数组的数组

---

相交检测

全部位于 Phaser.Geom.Intersects 下。

布尔测试（返回 true/false）

函数	描述
CircleToCircle(circleA, circleB)	两个圆是否重叠
CircleToRectangle(circle, rect)	圆是否与矩形重叠
LineToCircle(line, circle)	线段是否与圆相交
LineToLine(line1, line2, out?)	两条线段是否交叉；将交点写入 out
LineToRectangle(line, rect)	线段是否与矩形相交
PointToLine(point, line, lineThickness?)	点是否位于直线上或附近
PointToLineSegment(point, line)	点是否位于有限线段上
RectangleToRectangle(rectA, rectB)	两个矩形是否重叠
RectangleToTriangle(rect, triangle)	矩形是否与三角形重叠
RectangleToValues(rect, left, right, top, bottom, tolerance?)	矩形是否与 LRTB 边界重叠
TriangleToCircle(triangle, circle)	三角形是否与圆重叠
TriangleToLine(triangle, line)	三角形是否与直线相交
TriangleToTriangle(triA, triB)	两个三角形是否重叠

获取交点（返回 Vector2[]）

函数	描述
GetCircleToCircle(circleA, circleB, out?)	两个圆的交点
GetCircleToRectangle(circle, rect, out?)	圆与矩形边的交点
GetLineToCircle(line, circle, out?)	直线与圆的交点
GetLineToLine(line1, line2, out?)	两条直线的单一交点
GetLineToPoints(line, points, out?)	与构成边的点序列的交点
GetLineToPolygon(line, polygon, out?)	与多边形边的最近交点
GetLineToRectangle(line, rect, out?)	直线与矩形的交点
GetRaysFromPointToPolygon(x, y, polygon)	从点向多边形边投射射线
GetRectangleIntersection(rectA, rectB, out?)	重叠的矩形区域
GetRectangleToRectangle(rectA, rectB, out?)	边的交点
GetRectangleToTriangle(rect, triangle, out?)	边的交点
GetTriangleToCircle(triangle, circle, out?)	边的交点
GetTriangleToLine(triangle, line, out?)	边的交点
GetTriangleToTriangle(triA, triB, out?)	边的交点

---

按类别划分的数学函数

除非另有说明，均位于 Phaser.Math 下。

常量

常量	值
Phaser.Math.TAU	PI * 2（v4 新增）
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	全局 RandomDataGenerator 实例（通过游戏配置 seed 设置种子）

角度函数（Phaser.Math.Angle.*）

函数	描述
Between(x1, y1, x2, y2)	两点之间的弧度角
BetweenPoints(point1, point2)	同上，接受 {x,y} 对象
BetweenY(x1, y1, x2, y2)	相对于垂直轴的角度
BetweenPointsY(point1, point2)	同上，接受对象
CounterClockwise(angle)	转换为逆时针
GetClockwiseDistance(from, to)	顺时针角度距离
GetCounterClockwiseDistance(from, to)	逆时针角度距离
GetShortestDistance(from, to)	最短角度距离（带符号）
Normalize(angle)	归一化到 [0, 2PI)
Random()	随机弧度角
RandomDegrees()	随机角度（度）
Reverse(angle)	反向（加 PI）
RotateTo(currentAngle, targetAngle, lerp?)	逐步转向目标角度
ShortestBetween(angle1, angle2)	最短差值（度）
Wrap(angle)	环绕到 (-PI, PI]
WrapDegrees(angle)	环绕到 (-180, 180]

距离函数（Phaser.Math.Distance.*）

函数	描述
Between(x1, y1, x2, y2)	欧几里得距离
BetweenPoints(a, b)	同上，接收 {x,y} 对象
BetweenPointsSquared(a, b)	平方距离（避免开方）
Chebyshev(x1, y1, x2, y2)	切比雪夫（棋盘）距离
Power(x1, y1, x2, y2, pow)	自定义幂次的闵可夫斯基距离
Snake(x1, y1, x2, y2)	曼哈顿/出租车距离
Squared(x1, y1, x2, y2)	平方欧几里得距离

插值（Phaser.Math.Interpolation.*）

函数	描述
BezierInterpolation(v, k)	穿过控制点的贝塞尔曲线
CatmullRomInterpolation(v, k)	穿过各点的 Catmull-Rom 样条
CubicBezierInterpolation(t, p0, p1, p2, p3)	四个值之间的三次贝塞尔
LinearInterpolation(v, k)	在值数组上进行线性插值
QuadraticBezierInterpolation(t, p0, p1, p2)	二次贝塞尔
SmoothStepInterpolation(t, min, max)	Hermite 平滑步进
SmootherStepInterpolation(t, min, max)	Ken Perlin 的更平滑步进

对齐函数（Phaser.Math.Snap.*）

函数	描述
To(value, gap, start?, divide?)	对齐到最近的增量
Floor(value, gap, start?, divide?)	向下对齐到增量
Ceil(value, gap, start?, divide?)	向上对齐到增量

模糊比较（Phaser.Math.Fuzzy.*）

函数	描述
Equal(a, b, epsilon?)	a 近似等于 b
LessThan(a, b, epsilon?)	在 epsilon 范围内 a < b
GreaterThan(a, b, epsilon?)	在 epsilon 范围内 a > b
Ceil(value, epsilon?)	模糊向上取整
Floor(value, epsilon?)	模糊向下取整

缓动函数（Phaser.Math.Easing.*）

每种类型都有 .In、.Out、.InOut 变体。主要由补间动画使用（传入如 'Sine.easeOut' 这样的字符串名称）。

类型	字符串键
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（无变体）
Quadratic	Quad.easeIn、Quad.easeOut、Quad.easeInOut
Quartic	Quart.easeIn、Quart.easeOut、Quart.easeInOut
Quintic	Quint.easeIn、Quint.easeOut、Quint.easeInOut
Sine	Sine.easeIn、Sine.easeOut、Sine.easeInOut
Stepped	Stepped（无变体）

Power 别名：Power0 = Linear，Power1 = Quad.Out，Power2 = Cubic.Out，Power3 = Quart.Out，Power4 = Quint.Out。

简写名称同样可用：'Quad' = Quad.Out，'Sine' = Sine.Out，等等。

核心数学辅助方法（直接位于 Phaser.Math 上）

函数	描述
Between(min, max)	[min, max] 范围内的随机整数
FloatBetween(min, max)	[min, max] 范围内的随机浮点数
Clamp(value, min, max)	将值限制在范围内
Wrap(value, min, max)	将值环绕在范围内
Within(a, b, tolerance)	检查 a 是否在 b 的容差范围内
Percent(value, min, max, upperMax?)	值占范围百分比
FromPercent(percent, min, max)	根据范围百分比获取值
DegToRad(degrees)	将角度转换为弧度
RadToDeg(radians)	将弧度转换为角度
Linear(p0, p1, t)	两个值之间的线性插值
LinearXY(v1, v2, t, out?)	两个 Vector2Like 对象之间的线性插值
SmoothStep(x, min, max)	Hermite 平滑步进
SmootherStep(x, min, max)	Perlin 更平滑步进
Average(values)	数字数组的平均值
Median(values)	数字数组的中位数
CeilTo(value, place?, base?)	向上取整到指定小数位
FloorTo(value, place?, base?)	向下取整到指定小数位
RoundTo(value, place?, base?)	四舍五入到指定小数位
RoundAwayFromZero(value)	远离零方向四舍五入
MaxAdd(value, amount, max)	相加并限制在最大值
MinSub(value, amount, min)	相减并限制在最小值
Difference(a, b)	绝对差值
IsEven(value)	整数是否为偶数
IsEvenStrict(value)	严格偶数（不为零）
Factorial(value)	阶乘
Rotate(point, angle)	围绕原点旋转点
RotateAround(point, cx, cy, angle)	围绕自定义中心旋转点
RotateAroundDistance(point, cx, cy, angle, dist)	以固定距离旋转
TransformXY(x, y, posX, posY, rotation, scaleX, scaleY, output?)	完整 2D 变换
GetSpeed(distance, time)	根据距离和时间获取速度
RandomXY(vector, scale?)	将向量设置为随机单位方向

2 的幂（Phaser.Math.Pow2.*）

函数	描述
GetPowerOfTwo(value)	大于等于 value 的下一个 2 的幂
IsValuePowerOfTwo(value)	检查 value 是否为 2 的幂
IsSizePowerOfTwo(width, height)	检查宽高是否均为 2 的幂

---

Vector2 快速参考

Phaser.Math.Vector2 -- Phaser 中广泛使用的 2D 向量，用于表示位置、速度和方向。

构造函数：new Vector2(x?, y?) 或 new Vector2({x, y})。如果只传入 x，则 y 默认为 x。

方法	返回值	描述
set(x, y) / setTo(x, y)	this	设置分量
setToPolar(angle, length?)	this	根据角度和长度设置
copy(src) / setFromObject(obj)	this	从 Vector2Like 复制
clone()	Vector2	创建新副本
add(src) / subtract(src)	this	按分量相加/相减
multiply(src) / divide(src)	this	按分量相乘/相除
scale(value)	this	将两个分量乘以标量
negate()	this	翻转两个分量的符号
normalize()	this	将长度设为 1
normalizeRightHand()	this	垂直向量（右手定则）
normalizeLeftHand()	this	垂直向量（左手定则）
limit(max)	this	将长度限制为 max
setLength(length)	this	缩放至精确长度
length()	number	模长
lengthSq()	number	模长的平方（不进行开方）
distance(src)	number	到另一个向量的距离
distanceSq(src)	number	距离的平方
dot(src)	number	点积
cross(src)	number	2D 叉积（标量）
angle()	number	相对正 x 轴的角度（弧度）
setAngle(angle)	this	旋转到指定角度，保持长度不变
rotate(delta)	this	旋转 delta 弧度
lerp(src, t)	this	向 src 进行线性插值
reflect(normal)	this	根据表面法线进行反射
mirror(axis)	this	沿轴向量进行镜像
project(src)	this	投影到另一个向量上
equals(v)	boolean	精确相等
fuzzyEquals(v, epsilon?)	boolean	近似相等
ceil() / floor() / invert()	this	分量变换
reset()	this	设为 (0, 0)
transformMat3(mat)	this	使用 Matrix3 变换
transformMat4(mat)	this	使用 Matrix4 变换

静态属性：Vector2.ZERO、Vector2.RIGHT、Vector2.LEFT、Vector2.UP、Vector2.DOWN、Vector2.ONE。

---

Vector3 快速参考

Phaser.Math.Vector3 -- 用于相机投影、光照、3D 数学的 3D 向量。

构造函数：new Vector3(x?, y?, z?) 或 new Vector3({x, y, z})。

关键方法（与 Vector2 模式相同，另加）：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 快速参考

Phaser.Math.Matrix4 -- 用于 3D 变换、投影和视图矩阵的 4x4 矩阵。底层由 Float32Array(16) 支持。

构造函数：new Matrix4(m?) -- 从现有 Matrix4 复制，或默认为单位矩阵。

关键方法：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?)。

另外：Phaser.Math.Matrix3 -- 用于 2D 变换和法线矩阵的 3x3 矩阵。

---

RandomDataGenerator

Phaser.Math.RandomDataGenerator -- 带种子的伪随机数生成器。全局实例位于 Phaser.Math.RND（通过游戏配置的 seed 属性设置种子）。

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 between
rnd.realInRange(0.5, 1.5);  // random float in [0.5, 1.5]
rnd.normal();               // normal distribution around 0
rnd.angle();                // random angle in radians (-PI to PI)
rnd.rotation();             // random rotation in radians (same range)
rnd.pick(array);            // random element from array
rnd.weightedPick(array);    // weighted toward end of array
rnd.sign();                 // -1 or 1
rnd.uuid();                 // RFC4122 v4 UUID string
rnd.shuffle(array);         // in-place Fisher-Yates shuffle
rnd.state(state?);          // get/set serializable state for save/load

通过提供种子创建可重现的序列：new RandomDataGenerator(['level-42'])。

---

颜色工具

颜色类（Phaser.Display.Color）

一种可变的 RGBA 颜色表示，可自动转换为 WebGL 浮点数、HSV、CSS 字符串和打包整数。

// Construction
const 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 object
const 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 }

// Properties
color.r; color.g; color.b; color.a;   // 0-255 integers
color.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)

颜色操作

// Adjustment methods (amount is typically 0-100, returns the Color instance)
color.brighten(25);      // increase brightness
color.saturate(50);      // increase saturation
color.desaturate(30);    // decrease saturation
color.lighten(20);       // increase lightness
color.darken(10);        // decrease lightness

// Utility methods
color.random();          // set to random RGB values (optional min/max range)
color.gray(128);         // set to grayscale shade (0-255)

// Setting values
color.setTo(255, 128, 0, 255);           // RGBA
color.setFromRGB({ r: 255, g: 128, b: 0, a: 255 });
color.setFromHSV(0.1, 0.8, 1.0);        // HSV (0-1 range)

颜色插值（Phaser.Display.Color.Interpolate）

在给定长度上对颜色进行插值。返回 { r, g, b, a, color }。

// Between raw RGB values
const 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 objects
const mid = Phaser.Display.Color.Interpolate.ColorWithColor(color1, color2, 100, 50);

// HSV interpolation (v4): smooth hue transition
const hsvResult = Phaser.Display.Color.Interpolate.HSVWithHSV(0, 1, 1, 0.5, 1, 1, 100, 50);

---

注意事项

1. 几何对象不是游戏对象。 它们没有 scene，没有来自显示列表的 setPosition，也没有纹理。请使用 Graphics 或 Shape 游戏对象来渲染它们。

2. Point 类已在 v4 中移除。 请改用 Phaser.Math.Vector2 或普通的 {x, y} 对象。GEOM_CONST.POINT（3）仍然存在，但 Point 类不存在。

3. 整个数学 API 中的角度均以弧度为单位。 请使用 Phaser.Math.DegToRad() 和 RadToDeg() 进行转换。Phaser.Math.TAU 常量（2 * PI）是 v4 中新增的。

4. Vector2 方法会原地修改并返回 this 以支持链式调用。如果需要保留原始值，请先调用 .clone()：const result = v.clone().add(other)。

5. 平方距离比欧几里得距离更快（避免了 Math.sqrt）。在不需要实际距离值的比较中，请使用 Distance.Squared 或 vec.distanceSq()。

6. Intersection Get 函数会分配数组。* 请传入一个可复用的 out 数组，以避免在热点循环中产生垃圾回收压力。

7. EaseMap 短名称默认使用 .Out 变体。'Quad' 表示 Quadratic.Out，而不是 Quadratic.In。对于其他变体，请使用完整的字符串键，如 'Quad.easeIn'。

8. RandomDataGenerator 状态是可序列化的。 调用 rnd.state() 获取可存储的字符串，调用 rnd.state(savedString) 恢复它以进行确定性重放。

9. Polygon.contains 使用射线投射（奇偶规则）。复杂的自相交多边形可能会给出意外结果。

10. Matrix4.val 是一个 Float32Array。 请使用列主序（OpenGL 约定）通过 mat.val[index] 直接访问元素。

---

源文件映射

领域	路径
几何类	src/geom/{circle,ellipse,line,polygon,rectangle,triangle}/
几何常量	src/geom/const.js
相交测试	src/geom/intersects/
Vector2	src/math/Vector2.js
Vector3	src/math/Vector3.js
Vector4	src/math/Vector4.js
Matrix3	src/math/Matrix3.js
Matrix4	src/math/Matrix4.js
四元数	src/math/Quaternion.js
欧拉角	src/math/Euler.js
角度函数	src/math/angle/
距离函数	src/math/distance/
缓动函数	src/math/easing/（以及用于字符串键的 EaseMap.js）
模糊比较	src/math/fuzzy/
插值	src/math/interpolation/
吸附函数	src/math/snap/
二的幂	src/math/pow2/
RandomDataGenerator	src/math/random-data-generator/RandomDataGenerator.js
数学常量	src/math/const.js
颜色类	src/display/color/Color.js
颜色工具	src/display/color/（ValueToColor、HexStringToColor、RGBStringToColor、HSVToRGB、Interpolate）
核心数学辅助函数	src/math/（Clamp.js、Between.js、Wrap.js、Linear.js 等）