跳转至

GFHitBox3D

API Reference / Combat / 类索引

  • 路径：addons/gf/extensions/combat/hit_detection/gf_hit_box_3d.gd
  • 模块：Combat
  • 继承：Area3D
  • API：public
  • 类别：运行时句柄 (runtime_handle)
  • 首次版本：3.17.0

3D 通用命中发送区域。 节点负责构建 GFCombatHitContext 并发送给具备 receive_hit() 的接收对象， 不规定伤害、阵营、冷却、命中特效或生命值规则。

成员概览

类型 名称 签名
信号 hit_sent signal hit_sent(context: GFCombatHitContext, receiver: Object, report: Dictionary)
信号 hit_accepted signal hit_accepted(context: GFCombatHitContext, receiver: Object, report: Dictionary)
信号 hit_rejected signal hit_rejected(context: GFCombatHitContext, receiver: Object, report: Dictionary)
信号 enabled_changed signal enabled_changed(enabled: bool)
属性 enabled var enabled: bool = true:
属性 hit_id var hit_id: StringName = &""
属性 payload var payload: Dictionary = {}
属性 magnitude var magnitude: float = 0.0
属性 tags var tags: Array[StringName] = []
属性 metadata var metadata: Dictionary = {}
属性 sender_path var sender_path: NodePath = NodePath("")
属性 collision_shape_config var collision_shape_config: GFHitCollisionShapeConfig3D = null:
属性 collision_shape_configs var collision_shape_configs: Array[GFHitCollisionShapeConfig3D] = []:
属性 auto_apply_collision_shape_config var auto_apply_collision_shape_config: bool = true
方法 apply_collision_shape_config func apply_collision_shape_config(config: GFHitCollisionShapeConfig3D = null) -> CollisionShape3D:
方法 apply_collision_shape_configs func apply_collision_shape_configs(configs: Array[GFHitCollisionShapeConfig3D] = []) -> Array[CollisionShape3D]:
方法 get_generated_collision_shape func get_generated_collision_shape() -> CollisionShape3D:
方法 get_generated_collision_shapes func get_generated_collision_shapes() -> Array[CollisionShape3D]:
方法 clear_generated_collision_shape func clear_generated_collision_shape() -> void:
方法 clear_generated_collision_shapes func clear_generated_collision_shapes() -> void:
方法 build_hit_context func build_hit_context( target: Object = null, payload_override: Variant = null, hit_id_override: StringName = &"" ) -> GFCombatHitContext:
方法 send_to func send_to( receiver: Object, payload_override: Variant = null, hit_id_override: StringName = &"" ) -> Dictionary:
方法 send_to_path func send_to_path( receiver_path: NodePath, payload_override: Variant = null, hit_id_override: StringName = &"" ) -> Dictionary:
方法 broadcast_overlaps func broadcast_overlaps( max_count: int = 0, payload_override: Variant = null, hit_id_override: StringName = &"" ) -> Array[Dictionary]:

信号

hit_sent

  • API：public
signal hit_sent(context: GFCombatHitContext, receiver: Object, report: Dictionary)

命中已发送。

参数：

名称 说明
context 命中上下文。
receiver 接收对象。
report 结果报告。

结构：

  • report: Dictionary，统一命中发送结果，包含 ok、hit_id、receiver、reason、message 和 metadata。

hit_accepted

  • API：public
signal hit_accepted(context: GFCombatHitContext, receiver: Object, report: Dictionary)

命中被接收对象接受。

参数：

名称 说明
context 命中上下文。
receiver 接收对象。
report 结果报告。

结构：

  • report: Dictionary，统一命中发送结果，包含 ok、hit_id、receiver、reason、message 和 metadata。

hit_rejected

  • API：public
signal hit_rejected(context: GFCombatHitContext, receiver: Object, report: Dictionary)

命中被接收对象拒绝或发送失败。

参数：

名称 说明
context 命中上下文。
receiver 接收对象。
report 结果报告。

结构：

  • report: Dictionary，统一命中发送结果，包含 ok、hit_id、receiver、reason、message 和 metadata。

enabled_changed

  • API：public
signal enabled_changed(enabled: bool)

启用状态变化时发出。

参数：

名称 说明
enabled 当前是否允许发送命中。

属性

enabled

  • API：public
var enabled: bool = true:

是否允许发送命中。

hit_id

  • API：public
var hit_id: StringName = &""

默认命中 ID。

payload

  • API：public
var payload: Dictionary = {}

默认 payload；发送时会深拷贝。

结构：

  • payload: Dictionary，默认命中载荷；框架只复制并透传。

magnitude

  • API：public
var magnitude: float = 0.0

通用强度值。框架不解释该字段。

tags

  • API：public
var tags: Array[StringName] = []

命中标签。框架不解释该字段。

metadata

  • API：public
var metadata: Dictionary = {}

发送器自定义元数据。框架不解释该字段。

结构：

  • metadata: Dictionary，发送器自定义命中元数据；会进入命中上下文和结果报告。

sender_path

  • API：public
var sender_path: NodePath = NodePath("")

可选发送者路径；为空时使用当前节点。

collision_shape_config

  • API：public
var collision_shape_config: GFHitCollisionShapeConfig3D = null:

可选碰撞形状配置。设置后可自动生成或更新 CollisionShape3D 子节点。

collision_shape_configs

  • API：public
var collision_shape_configs: Array[GFHitCollisionShapeConfig3D] = []:

可选碰撞形状配置列表。非空时可自动生成或更新多个 CollisionShape3D 子节点。

auto_apply_collision_shape_config

  • API：public
var auto_apply_collision_shape_config: bool = true

是否在进入场景树或配置变化时自动应用碰撞形状配置。

方法

apply_collision_shape_config

  • API：public
func apply_collision_shape_config(config: GFHitCollisionShapeConfig3D = null) -> CollisionShape3D:

应用碰撞形状配置，创建或更新框架管理的 CollisionShape3D 子节点。

参数：

名称 说明
config 可选配置；为空时使用 collision_shape_config。

返回：创建或更新的 CollisionShape3D；配置无效时返回 null。

apply_collision_shape_configs

  • API：public
func apply_collision_shape_configs(configs: Array[GFHitCollisionShapeConfig3D] = []) -> Array[CollisionShape3D]:

应用碰撞形状配置列表，创建或更新框架管理的多个 CollisionShape3D 子节点。

参数：

名称 说明
configs 可选配置列表；为空时使用 collision_shape_configs。

返回：创建或更新的 CollisionShape3D 列表。

get_generated_collision_shape

  • API：public
func get_generated_collision_shape() -> CollisionShape3D:

获取框架管理的 CollisionShape3D 子节点。

返回：存在则返回 CollisionShape3D，否则返回 null。

get_generated_collision_shapes

  • API：public
func get_generated_collision_shapes() -> Array[CollisionShape3D]:

获取框架管理的 CollisionShape3D 子节点列表。

返回：已生成的 CollisionShape3D 列表。

clear_generated_collision_shape

  • API：public
func clear_generated_collision_shape() -> void:

移除框架管理的 CollisionShape3D 子节点。

clear_generated_collision_shapes

  • API：public
func clear_generated_collision_shapes() -> void:

移除框架管理的全部 CollisionShape3D 子节点。

build_hit_context

  • API：public
func build_hit_context( target: Object = null, payload_override: Variant = null, hit_id_override: StringName = &"" ) -> GFCombatHitContext:

构建命中上下文。

参数：

名称 说明
target 命中目标。
payload_override 覆盖 payload；为 null 时使用节点默认 payload。
hit_id_override 覆盖命中 ID；为空时使用节点默认命中 ID。

返回：命中上下文。

结构：

  • payload_override: Variant，可为 null、Dictionary 或项目自定义命中载荷；为 null 时使用节点默认 payload。

send_to

  • API：public
func send_to( receiver: Object, payload_override: Variant = null, hit_id_override: StringName = &"" ) -> Dictionary:

向指定接收对象发送命中。

参数：

名称 说明
receiver 接收对象。
payload_override 覆盖 payload；为 null 时使用节点默认 payload。
hit_id_override 覆盖命中 ID；为空时使用节点默认命中 ID。

返回：统一结果报告。

结构：

  • payload_override: Variant，可为 null、Dictionary 或项目自定义命中载荷；为 null 时使用节点默认 payload。
  • return: Dictionary，统一命中发送结果，包含 ok、hit_id、receiver、reason、message 和 metadata。

send_to_path

  • API：public
func send_to_path( receiver_path: NodePath, payload_override: Variant = null, hit_id_override: StringName = &"" ) -> Dictionary:

向指定节点路径发送命中。

参数：

名称 说明
receiver_path 接收节点路径。
payload_override 覆盖 payload；为 null 时使用节点默认 payload。
hit_id_override 覆盖命中 ID；为空时使用节点默认命中 ID。

返回：统一结果报告。

结构：

  • payload_override: Variant，可为 null、Dictionary 或项目自定义命中载荷；为 null 时使用节点默认 payload。
  • return: Dictionary，统一命中发送结果，包含 ok、hit_id、receiver、reason、message 和 metadata。

broadcast_overlaps

  • API：public
func broadcast_overlaps( max_count: int = 0, payload_override: Variant = null, hit_id_override: StringName = &"" ) -> Array[Dictionary]:

向当前重叠对象中的命中接收器批量发送命中。

参数：

名称 说明
max_count 最多发送数量；小于等于 0 表示不限制。
payload_override 覆盖 payload；为 null 时使用节点默认 payload。
hit_id_override 覆盖命中 ID；为空时使用节点默认命中 ID。

返回：结果报告列表。

结构：

  • payload_override: Variant，可为 null、Dictionary 或项目自定义命中载荷；为 null 时使用节点默认 payload。
  • return: Array[Dictionary]，每项为统一命中发送结果，包含 ok、hit_id、receiver、reason、message 和 metadata。