跳转至

GFHapticUtility

API Reference / Feedback / 类索引

  • 路径：addons/gf/extensions/feedback/runtime/gf_haptic_utility.gd
  • 模块：Feedback
  • 继承：GFUtility
  • API：public
  • 类别：运行时服务 (runtime_service)
  • 首次版本：7.0.0

通用手柄震动播放工具。 管理命名 channel 上的 GFHapticPreset 播放状态，并把合成后的弱/强马达强度 路由到玩家席位或手柄设备。项目仍然决定何时播放、如何分组以及玩法语义。

成员概览

类型 名称 签名
信号 haptic_started signal haptic_started(haptic_id: int, channel: StringName, target_type: int, target_id: int)
信号 haptic_finished signal haptic_finished(haptic_id: int, channel: StringName, target_type: int, target_id: int)
信号 haptic_stopped signal haptic_stopped(haptic_id: int, channel: StringName, target_type: int, target_id: int)
枚举 TargetType enum TargetType
枚举 OverflowPolicy enum OverflowPolicy
属性 default_channel var default_channel: StringName = &"default"
属性 default_player_index var default_player_index: int = 0
属性 master_strength var master_strength: float = 1.0:
属性 max_active_haptics var max_active_haptics: int = 64
属性 overflow_policy var overflow_policy: OverflowPolicy = OverflowPolicy.STOP_OLDEST
属性 auto_apply_on_tick var auto_apply_on_tick: bool = true
属性 output_refresh_seconds var output_refresh_seconds: float = 0.05:
属性 input_device_utility var input_device_utility: GFInputDeviceUtility = null
属性 output_handler var output_handler: Callable = Callable()
属性 stop_handler var stop_handler: Callable = Callable()
方法 init func init() -> void:
方法 ready func ready() -> void:
方法 dispose func dispose() -> void:
方法 tick func tick(delta: float) -> void:
方法 play_haptic func play_haptic( channel: StringName, preset: GFHapticPreset, player_index: int = -1, strength: float = 1.0, metadata: Dictionary = {} ) -> int:
方法 play_haptic_for_device func play_haptic_for_device( channel: StringName, preset: GFHapticPreset, device_id: int, strength: float = 1.0, metadata: Dictionary = {} ) -> int:
方法 stop_haptic func stop_haptic(haptic_id: int, emit_stopped: bool = true) -> bool:
方法 stop_channel func stop_channel(channel: StringName) -> int:
方法 stop_player func stop_player(player_index: int) -> int:
方法 stop_device func stop_device(device_id: int) -> int:
方法 clear func clear() -> void:
方法 is_haptic_active func is_haptic_active(haptic_id: int) -> bool:
方法 get_active_haptic_count func get_active_haptic_count(channel: StringName = &"") -> int:
方法 set_channel_strength func set_channel_strength(channel: StringName, strength: float) -> void:
方法 get_channel_strength func get_channel_strength(channel: StringName) -> float:
方法 clear_channel_strengths func clear_channel_strengths() -> void:
方法 sample_player func sample_player(player_index: int, channel: StringName = &"") -> Dictionary:
方法 sample_device func sample_device(device_id: int, channel: StringName = &"") -> Dictionary:
方法 apply_current_outputs func apply_current_outputs(duration_seconds: float = -1.0) -> Dictionary:
方法 get_haptic_info func get_haptic_info(haptic_id: int) -> Dictionary:
方法 get_debug_snapshot func get_debug_snapshot() -> Dictionary:

信号

haptic_started

  • API：public
  • 首次版本：7.0.0
signal haptic_started(haptic_id: int, channel: StringName, target_type: int, target_id: int)

震动播放开始时发出。

参数：

名称 说明
haptic_id 播放实例 ID。
channel 震动 channel。
target_type 目标类型，见 TargetType。
target_id 玩家索引或设备 ID。

haptic_finished

  • API：public
  • 首次版本：7.0.0
signal haptic_finished(haptic_id: int, channel: StringName, target_type: int, target_id: int)

震动播放结束时发出。

参数：

名称 说明
haptic_id 播放实例 ID。
channel 震动 channel。
target_type 目标类型，见 TargetType。
target_id 玩家索引或设备 ID。

haptic_stopped

  • API：public
  • 首次版本：7.0.0
signal haptic_stopped(haptic_id: int, channel: StringName, target_type: int, target_id: int)

震动播放被停止时发出。

参数：

名称 说明
haptic_id 播放实例 ID。
channel 震动 channel。
target_type 目标类型，见 TargetType。
target_id 玩家索引或设备 ID。

枚举

TargetType

  • API：public
  • 首次版本：7.0.0
enum TargetType {
    ## 目标是本地玩家索引，通过 GFInputDeviceUtility 解析到手柄设备。
    PLAYER,
    ## 目标是 Godot 手柄设备 ID。
    DEVICE,
}

震动输出目标类型。

OverflowPolicy

  • API：public
  • 首次版本：7.0.0
enum OverflowPolicy {
    ## 跳过新的播放请求。
    SKIP_NEW,
    ## 停止最早的播放实例。
    STOP_OLDEST,
}

活跃震动达到上限时的处理方式。

属性

default_channel

  • API：public
  • 首次版本：7.0.0
var default_channel: StringName = &"default"

默认 channel。

default_player_index

  • API：public
  • 首次版本：7.0.0
var default_player_index: int = 0

默认玩家索引。play_haptic() 传入负数时使用该值。

master_strength

  • API：public
  • 首次版本：7.0.0
var master_strength: float = 1.0:

全局震动强度倍率。

max_active_haptics

  • API：public
  • 首次版本：7.0.0
var max_active_haptics: int = 64

最大活跃震动数量；小于等于 0 表示不限制。

overflow_policy

  • API：public
  • 首次版本：7.0.0
var overflow_policy: OverflowPolicy = OverflowPolicy.STOP_OLDEST

达到上限时的处理方式。

auto_apply_on_tick

  • API：public
  • 首次版本：7.0.0
var auto_apply_on_tick: bool = true

tick() 后是否自动把当前采样输出到设备。

output_refresh_seconds

  • API：public
  • 首次版本：7.0.0
var output_refresh_seconds: float = 0.05:

每次输出请求的刷新持续时间，单位秒。

input_device_utility

  • API：public
  • 首次版本：7.0.0
var input_device_utility: GFInputDeviceUtility = null

可选输入设备工具。为空时 ready() 会尝试从架构中获取。

output_handler

  • API：public
  • 首次版本：7.0.0
var output_handler: Callable = Callable()

可选输出回调。有效时替代默认 Input/GFInputDeviceUtility 路由。

结构：

  • output_handler: Callable(target_type: int, target_id: int, weak_magnitude: float, strong_magnitude: float, duration_seconds: float, metadata: Dictionary) -> bool。

stop_handler

  • API：public
  • 首次版本：7.0.0
var stop_handler: Callable = Callable()

可选停止回调。有效时替代默认停止路由。

结构：

  • stop_handler: Callable(target_type: int, target_id: int, metadata: Dictionary) -> bool。

方法

init

  • API：public
  • 首次版本：7.0.0
func init() -> void:

初始化震动运行时状态。

ready

  • API：public
  • 首次版本：7.0.0
func ready() -> void:

在架构 ready 后补全输入设备工具引用。

dispose

  • API：public
  • 首次版本：7.0.0
func dispose() -> void:

停止全部震动并释放状态。

tick

  • API：public
  • 首次版本：7.0.0
func tick(delta: float) -> void:

推进震动播放状态。

参数：

名称 说明
delta 本帧时间增量。

play_haptic

  • API：public
  • 首次版本：7.0.0
func play_haptic( channel: StringName, preset: GFHapticPreset, player_index: int = -1, strength: float = 1.0, metadata: Dictionary = {} ) -> int:

播放一个玩家震动预设。

参数：

名称 说明
channel 震动 channel；为空时使用 default_channel。
preset 震动预设。
player_index 玩家索引；小于 0 时使用 default_player_index。
strength 播放强度倍率。
metadata 项目自定义元数据。

返回：播放实例 ID；无法播放时返回 -1。

结构：

  • metadata: Dictionary，播放实例自定义元数据，会在 get_haptic_info() 快照中复制返回。

play_haptic_for_device

  • API：public
  • 首次版本：7.0.0
func play_haptic_for_device( channel: StringName, preset: GFHapticPreset, device_id: int, strength: float = 1.0, metadata: Dictionary = {} ) -> int:

播放一个设备震动预设。

参数：

名称 说明
channel 震动 channel；为空时使用 default_channel。
preset 震动预设。
device_id Godot 手柄设备 ID。
strength 播放强度倍率。
metadata 项目自定义元数据。

返回：播放实例 ID；无法播放时返回 -1。

结构：

  • metadata: Dictionary，播放实例自定义元数据，会在 get_haptic_info() 快照中复制返回。

stop_haptic

  • API：public
  • 首次版本：7.0.0
func stop_haptic(haptic_id: int, emit_stopped: bool = true) -> bool:

停止指定震动实例。

参数：

名称 说明
haptic_id 播放实例 ID。
emit_stopped 是否发出停止信号。

返回：成功停止返回 true。

stop_channel

  • API：public
  • 首次版本：7.0.0
func stop_channel(channel: StringName) -> int:

停止指定 channel 上的全部震动实例。

参数：

名称 说明
channel 震动 channel；为空时使用 default_channel。

返回：停止数量。

stop_player

  • API：public
  • 首次版本：7.0.0
func stop_player(player_index: int) -> int:

停止指定玩家的全部震动实例。

参数：

名称 说明
player_index 玩家索引。

返回：停止数量。

stop_device

  • API：public
  • 首次版本：7.0.0
func stop_device(device_id: int) -> int:

停止指定设备的全部震动实例。

参数：

名称 说明
device_id Godot 手柄设备 ID。

返回：停止数量。

clear

  • API：public
  • 首次版本：7.0.0
func clear() -> void:

清空全部震动实例并停止上次输出过的目标。

is_haptic_active

  • API：public
  • 首次版本：7.0.0
func is_haptic_active(haptic_id: int) -> bool:

检查震动实例是否仍在播放。

参数：

名称 说明
haptic_id 播放实例 ID。

返回：正在播放返回 true。

get_active_haptic_count

  • API：public
  • 首次版本：7.0.0
func get_active_haptic_count(channel: StringName = &"") -> int:

获取活跃震动数量。

参数：

名称 说明
channel 可选 channel；为空时统计全部。

返回：活跃震动数量。

set_channel_strength

  • API：public
  • 首次版本：7.0.0
func set_channel_strength(channel: StringName, strength: float) -> void:

设置 channel 强度倍率。

参数：

名称 说明
channel 震动 channel；为空时使用 default_channel。
strength 强度倍率；小于 0 时按 0 处理。

get_channel_strength

  • API：public
  • 首次版本：7.0.0
func get_channel_strength(channel: StringName) -> float:

获取 channel 强度倍率。

参数：

名称 说明
channel 震动 channel；为空时使用 default_channel。

返回：强度倍率。

clear_channel_strengths

  • API：public
  • 首次版本：7.0.0
func clear_channel_strengths() -> void:

清空全部 channel 强度覆盖。

sample_player

  • API：public
  • 首次版本：7.0.0
func sample_player(player_index: int, channel: StringName = &"") -> Dictionary:

采样指定玩家当前的合成震动。

参数：

名称 说明
player_index 玩家索引。
channel 可选 channel；为空时合成该玩家全部 channel。

返回：合成震动采样。

结构：

  • return: Dictionary，包含 weak_magnitude、strong_magnitude、intensity 与 progress。

sample_device

  • API：public
  • 首次版本：7.0.0
func sample_device(device_id: int, channel: StringName = &"") -> Dictionary:

采样指定设备当前的合成震动。

参数：

名称 说明
device_id Godot 手柄设备 ID。
channel 可选 channel；为空时合成该设备全部 channel。

返回：合成震动采样。

结构：

  • return: Dictionary，包含 weak_magnitude、strong_magnitude、intensity 与 progress。

apply_current_outputs

  • API：public
  • 首次版本：7.0.0
func apply_current_outputs(duration_seconds: float = -1.0) -> Dictionary:

把当前采样输出到所有活跃目标。

参数：

名称 说明
duration_seconds 输出请求持续时间；小于 0 时使用 output_refresh_seconds。

返回：输出报告。

结构：

  • return: Dictionary，包含 applied_count、stopped_count、applied 与 stopped。

get_haptic_info

  • API：public
  • 首次版本：7.0.0
func get_haptic_info(haptic_id: int) -> Dictionary:

获取指定震动实例的只读快照。

参数：

名称 说明
haptic_id 播放实例 ID。

返回：播放实例快照。

结构：

  • return: Dictionary，包含 id、channel、target_type、target_id、elapsed_seconds、duration_seconds、strength 与 metadata；实例不存在时为空。

get_debug_snapshot

  • API：public
  • 首次版本：7.0.0
func get_debug_snapshot() -> Dictionary:

获取震动系统调试快照。

返回：调试快照。

结构：

  • return: Dictionary，包含 active_count、max_active_haptics、channels、targets 与 play_order。