GFDragSession

API Reference / Standard / 类索引

• 路径：addons/gf/standard/input/drag_drop/gf_drag_session.gd
• 模块：Standard
• 继承：RefCounted
• API：public
• 类别：运行时句柄 (runtime_handle)
• 首次版本：3.17.0

通用拖拽会话数据。 描述一次拖拽从开始到释放的稳定上下文，不绑定具体 UI、背包、棋盘、 关卡编辑器或任何业务对象。项目可把任意 payload 放入会话，再由落点规则解释。

成员概览

类型	名称	签名
属性	session_id	var session_id: int = -1
属性	drag_type	var drag_type: StringName = &""
属性	payload	var payload: Variant = null
属性	start_position	var start_position: Vector2 = Vector2.ZERO
属性	current_position	var current_position: Vector2 = Vector2.ZERO
属性	previous_position	var previous_position: Vector2 = Vector2.ZERO
属性	metadata	var metadata: Dictionary = {}
方法	setup	func setup( new_session_id: int, new_drag_type: StringName, new_payload: Variant, position: Vector2, source: Object = null, new_metadata: Dictionary = {} ) -> void:
方法	update_position	func update_position(position: Vector2) -> void:
方法	get_delta	func get_delta() -> Vector2:
方法	get_source	func get_source() -> Object:
方法	to_dictionary	func to_dictionary() -> Dictionary:

属性

session_id

• API：public

var session_id: int = -1

会话 ID，由 GFDragDropUtility 分配。

drag_type

• API：public

var drag_type: StringName = &""

拖拽类型。落点可用它做通用接收过滤。

payload

• API：public

var payload: Variant = null

项目自定义载荷。框架不解释该字段。

结构：

• payload: Variant，透传给 drop zone 的项目侧拖拽载荷。

start_position

• API：public

var start_position: Vector2 = Vector2.ZERO

起始位置，通常是屏幕或画布坐标。

current_position

• API：public

var current_position: Vector2 = Vector2.ZERO

当前指针位置。

previous_position

• API：public

var previous_position: Vector2 = Vector2.ZERO

上一次位置。

metadata

• API：public

var metadata: Dictionary = {}

项目自定义元数据。框架只负责复制和透传。

结构：

• metadata: Dictionary，复制到拖拽会话中的项目侧元数据。

方法

setup

• API：public

func setup( new_session_id: int, new_drag_type: StringName, new_payload: Variant, position: Vector2, source: Object = null, new_metadata: Dictionary = {} ) -> void:

初始化会话。

参数：

名称	说明
new_session_id	会话 ID。
new_drag_type	拖拽类型。
new_payload	项目自定义载荷。
position	起始位置。
source	可选来源对象。
new_metadata	项目自定义元数据。

结构：

• new_payload: Variant，透传给 drop zone 的项目侧拖拽载荷。
• new_metadata: Dictionary，复制到拖拽会话中的项目侧元数据。

update_position

• API：public

func update_position(position: Vector2) -> void:

更新当前拖拽位置。

参数：

名称	说明
position	新位置。

get_delta

• API：public

func get_delta() -> Vector2:

获取本次更新的位移。

返回：当前和上一次位置的差值。

get_source

• API：public

func get_source() -> Object:

获取来源对象。

返回：来源仍有效时返回对象，否则返回 null。

to_dictionary

• API：public

func to_dictionary() -> Dictionary:

转换为调试字典。

返回：会话快照。

结构：

• return: Dictionary，包含 session_id、drag_type、start_position、current_position、previous_position、delta、has_source 和 metadata。