Collider

ctx.collider 提供当前 GameObject 的碰撞查询能力。

只有挂载了 Collider 组件的对象才应该使用这些 API。目标对象如果也参与碰撞，也应该配置 Collider 组件。

前置条件

当前脚本所在 GameObject 需要有 Collider 组件：

{
  "type": "Collider",
  "enabled": true,
  "shape": "box",
  "offsetX": 0,
  "offsetY": 0,
  "width": 48,
  "height": 48,
  "isTrigger": true
}

ctx.collider.bounds()

作用

获取当前对象 Collider 的世界包围盒。

签名

ctx.collider.bounds(): {
  x: number
  y: number
  width: number
  height: number
}

示例

export default {
  update(ctx) {
    const box = ctx.collider.bounds()
    if (box.y > ctx.project.height) {
      ctx.node.destroy()
    }
  }
}

限制

• 只表示当前对象 Collider 的范围。
• 当前对象必须有 Collider 组件。
• 这是编辑器碰撞体范围，不等同于 Phaser sprite 的显示范围。

ctx.collider.overlaps(target)

作用

检查当前对象 Collider 是否与一个目标对象发生重叠。

签名

ctx.collider.overlaps(target: string | SceneObject): boolean

参数

参数	类型	说明
target	string | SceneObject	目标对象名称、对象 id，或对象数据

返回值

boolean

发生碰撞返回 true，否则返回 false。

示例

export default {
  update(ctx) {
    if (ctx.collider.overlaps('Ground')) {
      ctx.state.gameOver = true
    }
  }
}

限制

• 当前对象必须有 Collider。
• 目标对象应该有 Collider。
• 字符串目标必须真实存在。
• 不推荐用于大量重复 Prefab 实例，因为重复对象名可能造成歧义。

ctx.collider.overlapsAll(names)

作用

检查当前对象 Collider 是否与一组命名对象发生重叠。

签名

ctx.collider.overlapsAll(names: string[]): SceneObject[]

参数

参数	类型	说明
names	string[]	目标对象名称或 id 列表

返回值

SceneObject[]

返回所有发生重叠的目标对象。没有碰撞时返回空数组。

示例

export default {
  update(ctx) {
    const hits = ctx.collider.overlapsAll(['TopPipe', 'BottomPipe'])
    if (hits.length > 0) {
      ctx.state.dead = true
    }
  }
}

限制

• 适合少量固定对象。
• 不适合大量重复生成的 Prefab。
• 列表里的名字必须存在，否则项目 lint 会报错。
• 返回数组，判断时应该使用 .length > 0。

ctx.collider.overlapsGroup(tag)

作用

检查当前对象 Collider 是否与带指定 tag 的对象发生重叠。

这适合管道、敌人、子弹等重复生成对象。

签名

ctx.collider.overlapsGroup(tag: string): SceneObject[]

参数

参数	类型	说明
tag	string	目标对象 tag，例如 'pipe'

返回值

SceneObject[]

返回所有发生重叠的对象。没有碰撞时返回空数组。

示例

export default {
  update(ctx) {
    const hits = ctx.collider.overlapsGroup('pipe')
    if (hits.length > 0) {
      ctx.state.dead = true
    }
  }
}

Prefab 示例

创建管道 Prefab 时，应给需要参与碰撞的子对象加 tag：

{
  "name": "TopPipe",
  "tags": ["pipe"],
  "components": [
    { "type": "ImageRenderer", "assetName": "pipe_up.png" },
    { "type": "Collider", "enabled": true, "shape": "box", "width": 52, "height": 320, "isTrigger": true }
  ]
}

限制

• 目标对象必须带有对应 tag。
• 如果项目中没有任何对象或 Prefab 子对象带该 tag，lint 会报错。
• 返回数组，判断时应该使用 .length > 0。
• 不要写成：

if (ctx.collider.overlapsGroup('pipe')) {
  // 错误：空数组也是真值
}

应该写成：

if (ctx.collider.overlapsGroup('pipe').length > 0) {
  ctx.state.dead = true
}

常见错误

使用不存在的 tag

ctx.collider.overlapsGroup('pipe')

但项目中没有任何对象带：

"tags": ["pipe"]

结果：项目 lint 报错。

解决：给目标对象或 Prefab 子对象添加 tag，或者改用真实存在的对象名。

把数组当 boolean 用

错误：

if (ctx.collider.overlapsGroup('enemy')) {}

正确：

if (ctx.collider.overlapsGroup('enemy').length > 0) {}

对重复 Prefab 使用固定名称

不推荐：

ctx.collider.overlaps('TopPipe')

如果场景里有多个管道实例，固定名称可能不稳定。

推荐：

ctx.collider.overlapsGroup('pipe').length > 0

AI 使用规则

AI 生成脚本时必须遵守：

• 使用 overlapsGroup(tag) 前，必须确保对象或 Prefab 子对象已有对应 tag。
• overlapsAll(names) 里的每个 name 必须存在。
• overlapsGroup 和 overlapsAll 返回数组，判断时必须用 .length > 0。
• 不要猜测不存在的 tag、对象名或 Collider API。
• 如果需要的碰撞能力不存在，应该报告工具能力缺失，而不是写 fallback 并静默忽略。