Phaser 4 的 Actions 与工具函数主要用途是对游戏对象数组进行批量处理。Phaser.Actions 命名空间提供一次性批量操作,Phaser.Utils.Array、Phaser.Utils.Objects、Phaser.Utils.String 则提供数组、对象与字符串层面的辅助函数。
核心概念方面,每个 Action 都遵循统一模式:第一个参数始终是游戏对象数组(或任何具备所需公共属性如 x、y、alpha 的对象);返回同一个数组,支持链式调用或传递;通过传入 group.getChildren() 可与 Group 配合使用;Action 本身不保存状态,属于一次性批量操作。大多数 Set/Inc 类 Action 内部委托给两个核心函数:PropertyValueSet(将 items[i][key] 设为 value + istep)和 PropertyValueInc(在 items[i][key] 上累加 value + istep)。step 参数为每个元素添加递增偏移,index 和 direction 控制迭代起点与方向(1 为正向,-1 为反向)。基于几何图形的摆放类 Action 接受 Phaser.Geom 几何对象(如 Phaser.Geom.Circle、Phaser.Geom.Line),而非游戏对象形状;若使用 Phaser.GameObjects.Circle,需传入其 .geom 属性。
主要能力涵盖以下类别。属性设置器包括 SetX、SetY、SetXY、SetAlpha、SetBlendMode、SetDepth、SetHitArea、SetOrigin、SetRotation、SetScale、SetScaleX、SetScaleY、SetScrollFactor 系列、SetTint、SetVisible 以及通用的 PropertyValueSet。属性递增器包括 IncX、IncXY、IncY、IncAlpha、Angle、Rotate、ScaleX、ScaleXY、ScaleY 以及通用的 PropertyValueInc。几何摆放包括 PlaceOnCircle、PlaceOnEllipse、PlaceOnLine、PlaceOnRectangle、PlaceOnTriangle 以及 RandomCircle、RandomEllipse、RandomLine、RandomRectangle、RandomTriangle。布局与对齐包括 GridAlign(按 config 中的 width、height、cellWidth、cellHeight、position、x、y 排列)、AlignTo(按 Phaser.Display.Align 常量将每个元素对齐到前一个元素旁)、FitToRegion(v4.0.0+,按 scaleMode 0 拉伸、-1 内适应、1 外覆盖将对象缩放定位以填充矩形)。分布与插值包括 Spread(在 min 与 max 之间线性分布属性)、SmoothStep(Hermite smoothstep 插值)、SmootherStep(Ken Perlin smootherstep)。旋转与移动包括 RotateAround、RotateAroundDistance、ShiftPosition(蛇形移动,头部移至 x/y,每个元素占据前一个的位置)、WrapInRectangle(将 x/y 限制在矩形边界内循环)。查询与迭代包括 GetFirst、GetLast、Call、Shuffle、ToggleVisible、PlayAnimation。效果(v4.0.0+)包括 AddEffectBloom、AddEffectShine、AddMaskShape(支持圆形、方形、矩形、椭圆遮罩并可附加模糊),它们返回所创建效果的数组。
Phaser.Utils.Array 提供数组操作函数,如 Add、AddAt、BringToTop、CountAllMatching、Each、EachInRange、FindClosestInSorted、Flatten、GetAll、GetFirst、GetRandom、MoveAbove、MoveBelow、MoveDown、MoveTo、MoveUp、NumberArray、NumberArrayStep、QuickSelect、Range、Remove、RemoveAt、RemoveBetween、RemoveRandomElement、Replace、RotateLeft、RotateRight、SafeRange、SendToBack、SetAll、Shuffle、SortByDigits、SpliceOne、StableSort、Swap,以及用于二维矩阵运算的 Phaser.Utils.Array.Matrix 子命名空间。Phaser.Utils.Objects 提供对象操作函数:Clone、DeepCopy、Extend、GetAdvancedValue、GetFastValue、GetMinMaxValue、GetValue(支持点路径如 'render.screen.width')、HasAll、HasAny、HasValue、IsPlainObject、Merge、MergeRight、Pick、SetValue。Phaser.Utils.String 提供字符串函数:Format(替换 %1、%2 等标记)、Pad、RemoveAt、Reverse、UppercaseFirst、UUID。
使用方式上,典型流程是先创建或获取对象数组(例如创建精灵后放入数组,或从 Group 调用 getChildren()),再调用相应 Action。例如用 GridAlign 将精灵排成网格,用 Spread 从 0 到 1 分布 alpha,用 IncX 按步长偏移 x。也可对 Group 的 getChildren() 结果直接调用。
适用场景包括:批量布置关卡元素(网格、圆形、直线、矩形周边的均匀或随机分布)、批量设置或叠加属性(透明度渐变、缩放渐变、旋转渐变)、蛇形移动、边界循环、批量播放动画、批量查询与随机重排,以及在配置解析中安全读取深层属性。
已知限制与注意事项:Action 直接作用于普通数组而非 Group,需调用 group.getChildren();PlaceOn/Random 几何类 Action 需要 Phaser.Geom 对象,传入 Phaser.GameObjects.Circle 时应使用 circle.geom;SetXY 在 y 为 undefined 或 null 时默认 y 等于 x,如需 y=0 应显式传入 0;Spread 仅一个元素时该元素位于中点 (min + max) / 2 而非 min;step 按迭代索引相乘而非累加,第 0 个元素得到 value + 0step,第 1 个得到 value + 1step;StableSort 在引擎支持稳定排序时使用原生 Array.sort,仅在需要时回退到归并排序;Shuffle(Actions 与 Utils.Array)会原地修改数组并返回它;GetFastValue 仅支持顶层键、无点路径解析,在热点循环中比 GetValue 更快;AddEffectBloom、AddEffectShine、AddMaskShape 为 v4 专属的滤镜效果,返回所创建效果的数组而非输入。