SuperAPI AI 工具集

groups-and-containers

编程与开发

查看项目

更新于 10-15 15:25

技能介绍

Groups and Containers 是 Phaser 4 中用于组织游戏对象的技能文档,介绍了三种分组机制:逻辑分组(Group)、带变换继承的可视化分组(Container)以及渲染层分组(Layer),并说明对象池与各自的适用场景。相关源码路径为 src/gameobjects/group/、src/gameobjects/container/、src/gameobjects/layer/,关联技能包括 ../sprites-and-images/SKILL.md 与 ../physics-arcade/SKILL.md。

一、三者区别

Group:用于同类对象的逻辑集合与对象池,可进行物理分组碰撞;不在显示列表上,没有位置、旋转、缩放;子对象存储于 children(Set),无索引访问;子对象可同时属于多个 Group。工厂方法为 this.add.group()。

Container:带变换继承的可视化父级,子对象继承位置、旋转、缩放、alpha;在显示列表上并渲染子对象;子对象存储于 list(Array);默认排他,一个子对象只能属于一个 Container(可用 setExclusive(false) 覆盖);支持遮罩;可嵌套 Container。工厂方法为 this.add.container(x, y)。

Layer:用于控制对象批次的渲染顺序,可应用共享 alpha/blend/mask;没有位置、缩放、旋转;不能放入 Container,但 Container 可加入 Layer。工厂方法为 this.add.layer()。

二、Group 常用模式

创建与填充:可用 this.add.group() 创建空组后 add/addMultiple 添加已有对象,或用配置(classType、key、quantity、setXY、setScale 等)自动创建子对象。可指定自定义 classType(须接受 scene, x, y, key, frame 参数)、maxSize、defaultKey、runChildUpdate。

对象池:核心模式是不销毁对象而是将其停用后复用。bullets.get(x, y) 查找首个非活跃成员或新建;killAndHide 将 active 与 visible 设为 false。相关方法包括 getFirst、getFirstAlive、getFirstDead、getLast、kill、countActive、getTotalUsed、getTotalFree、isFull。

物理分组:this.physics.add.group() 使每个成员获得动态刚体,staticGroup 用于不可移动刚体,可用 collider/overlap 检测碰撞。

三、Container 常用模式

嵌套变换:bundle 多个子对象作为整体移动、缩放、旋转;setScrollFactor 可固定于相机(HUD)。示例中 HUD 容器设 setScrollFactor(0),子对象随容器移动;还可用嵌套 Container 构建背包槽位。关键方法包括 add/addAt、remove、getAt/getIndex、getByName/getFirst、getAll/count、sort/swap/moveTo、each/iterate、setScrollFactor(x, y, updateChildren)、getBounds、pointToContainer、setExclusive、replace、setSize;length 为只读子对象数量。

四、Layer 渲染排序

创建多个 Layer 并按顺序添加对象,对象按 Layer 顺序渲染,再按 Layer 内 depth 排序;Layer 本身可设 depth;可对整个 Layer 统一设置 alpha、visible、blendMode。

五、批量创建与批操作

createMultiple 接受 GroupCreateConfig 或数组,支持 key、quantity、setXY、setScale、setRotation(带 step)、setAlpha、setOrigin、setDepth、gridAlign 等,可一次创建多组。Group 还支持 setXY、incX、setVisible、propertyValueSet、playAnimation 等批量操作,以及 setX(100, 50) 这类递增步进赋值。

六、注意事项

Group 不在显示列表上,移动 Group 不会产生视觉效果;Container 有性能开销,深层嵌套更明显,不需要变换时优先用 Group 或 Layer;Container 原点固定为 0,0;Container 子对象的 depth 只在其内部排序;Container 与物理结合有问题,容器不在 (0,0) 时子对象刚体会偏移;Canvas 渲染下子对象无法单独遮罩;Group.get() 是 getFirst(false, true, ...) 的简写并会自动创建;Layer 不能放进 Container;Group 的 children 是无序 Set;killAndHide 不会从组中移除对象;Container.setScrollFactor 不会自动传播到子对象,需传第三个参数 true;group.add() 默认不加入显示列表;Container 需要 setSize() 才能启用输入。

文档还提供了源码文件对照表,如 src/gameobjects/group/Group.js、GroupFactory.js、typedefs/GroupConfig.js、typedefs/GroupCreateConfig.js、src/gameobjects/container/Container.js 等。