GFPriorityQueue

API Reference / Standard / 类索引

• 路径：addons/gf/standard/foundation/collections/gf_priority_queue.gd
• 模块：Standard
• 继承：RefCounted
• API：public
• 类别：值对象 (value_object)
• 首次版本：7.0.0

稳定优先队列。 用二叉堆保存带整数优先级的值，支持高优先级优先或低优先级优先， 并在相同优先级下保持稳定顺序。它只管理排序和弹出顺序，不解释任务、 通知、AI 行为或项目业务语义。

成员概览

类型	名称	签名
属性	high_priority_first	var high_priority_first: bool = true:
方法	_init	func _init(p_high_priority_first: bool = true) -> void:
方法	from_array	static func from_array( values: Array, priority: int = 0, p_high_priority_first: bool = true ) -> RefCounted:
方法	push	func push(value: Variant, priority: int = 0, front: bool = false) -> void:
方法	pop	func pop(default_value: Variant = null) -> Variant:
方法	peek	func peek(default_value: Variant = null) -> Variant:
方法	peek_priority	func peek_priority(default_value: int = 0) -> int:
方法	remove_value	func remove_value(value: Variant) -> bool:
方法	remove_all	func remove_all(value: Variant) -> int:
方法	has_value	func has_value(value: Variant) -> bool:
方法	set_priority	func set_priority(value: Variant, priority: int, front: bool = false) -> bool:
方法	clear	func clear() -> void:
方法	is_empty	func is_empty() -> bool:
方法	size	func size() -> int:
方法	to_array	func to_array(deep: bool = false) -> Array:
方法	to_entry_array	func to_entry_array(deep: bool = false) -> Array[Dictionary]:
方法	duplicate_priority_queue	func duplicate_priority_queue(deep: bool = false) -> RefCounted:
方法	get_debug_snapshot	func get_debug_snapshot() -> Dictionary:

属性

high_priority_first

• API：public
• 首次版本：7.0.0

var high_priority_first: bool = true:

是否优先弹出较大的 priority。设为 false 时较小的 priority 优先。

方法

_init

• API：public
• 首次版本：7.0.0

func _init(p_high_priority_first: bool = true) -> void:

构造函数。

参数：

名称	说明
p_high_priority_first	为 true 时 priority 数值越大越先弹出。

from_array

• API：public
• 首次版本：7.0.0

static func from_array( values: Array, priority: int = 0, p_high_priority_first: bool = true ) -> RefCounted:

从值数组创建优先队列。

参数：

名称	说明
values	初始值数组。
priority	所有初始值使用的优先级。
p_high_priority_first	为 true 时 priority 数值越大越先弹出。

返回：新优先队列。

结构：

• values: Array of queue values copied by reference.

push

• API：public
• 首次版本：7.0.0

func push(value: Variant, priority: int = 0, front: bool = false) -> void:

推入一个值。

参数：

名称	说明
value	要入队的值。
priority	整数优先级。
front	为 true 时会排在相同 priority 的既有元素之前。

结构：

• value: Variant queue value.

pop

• API：public
• 首次版本：7.0.0

func pop(default_value: Variant = null) -> Variant:

弹出当前最高优先级值。

参数：

名称	说明
default_value	队列为空时返回的值。

返回：队列值或 default_value。

结构：

• default_value: Variant fallback value.
• return: Variant queue value or fallback value.

peek

• API：public
• 首次版本：7.0.0

func peek(default_value: Variant = null) -> Variant:

读取当前最高优先级值但不移除。

参数：

名称	说明
default_value	队列为空时返回的值。

返回：队列值或 default_value。

结构：

• default_value: Variant fallback value.
• return: Variant queue value or fallback value.

peek_priority

• API：public
• 首次版本：7.0.0

func peek_priority(default_value: int = 0) -> int:

读取当前最高优先级。

参数：

名称	说明
default_value	队列为空时返回的值。

返回：当前最高优先级或 default_value。

remove_value

• API：public
• 首次版本：7.0.0

func remove_value(value: Variant) -> bool:

移除第一个等于 value 的队列值。

参数：

名称	说明
value	要移除的值。

返回：找到并移除时返回 true。

结构：

• value: Variant queue value.

remove_all

• API：public
• 首次版本：7.0.0

func remove_all(value: Variant) -> int:

移除所有等于 value 的队列值。

参数：

名称	说明
value	要移除的值。

返回：移除数量。

结构：

• value: Variant queue value.

has_value

• API：public
• 首次版本：7.0.0

func has_value(value: Variant) -> bool:

检查队列是否包含指定值。

参数：

名称	说明
value	要查找的值。

返回：包含时返回 true。

结构：

• value: Variant queue value.

set_priority

• API：public
• 首次版本：7.0.0

func set_priority(value: Variant, priority: int, front: bool = false) -> bool:

更新第一个等于 value 的队列值优先级。

参数：

名称	说明
value	要更新的值。
priority	新优先级。
front	为 true 时排到相同 priority 的既有元素之前。

返回：找到并更新时返回 true。

结构：

• value: Variant queue value.

clear

• API：public
• 首次版本：7.0.0

func clear() -> void:

清空队列。

is_empty

• API：public
• 首次版本：7.0.0

func is_empty() -> bool:

队列是否为空。

返回：为空返回 true。

size

• API：public
• 首次版本：7.0.0

func size() -> int:

获取元素数量。

返回：元素数量。

to_array

• API：public
• 首次版本：7.0.0

func to_array(deep: bool = false) -> Array:

按弹出顺序导出值数组，不修改当前队列。

参数：

名称	说明
deep	为 true 时深拷贝元素中的 Array、Dictionary、Object Resource 等可复制值。

返回：队列值数组。

结构：

• return: Array of queue values in pop order.

to_entry_array

• API：public
• 首次版本：7.0.0

func to_entry_array(deep: bool = false) -> Array[Dictionary]:

按弹出顺序导出队列条目，不修改当前队列。

参数：

名称	说明
deep	为 true 时深拷贝条目中的 value。

返回：条目数组。

结构：

• return: Array[Dictionary]，每项包含 value、priority 和 order。

duplicate_priority_queue

• API：public
• 首次版本：7.0.0

func duplicate_priority_queue(deep: bool = false) -> RefCounted:

复制优先队列。

参数：

名称	说明
deep	为 true 时深拷贝元素中的 Array、Dictionary、Object Resource 等可复制值。

返回：新优先队列；实际对象类型为 GFPriorityQueue。

结构：

• return: RefCounted GFPriorityQueue instance.

get_debug_snapshot

• API：public
• 首次版本：7.0.0

func get_debug_snapshot() -> Dictionary:

获取调试快照。

返回：调试信息字典。

结构：

• return: Dictionary with size, high_priority_first, and entries.