跳转至

GFBudgetLedger

API Reference / Standard / 类索引

  • 路径：addons/gf/standard/foundation/budget/gf_budget_ledger.gd
  • 模块：Standard
  • 继承：RefCounted
  • API：public
  • 类别：运行时服务 (runtime_service)
  • 首次版本：3.17.0

通用资源预算账本。 用于记录一组抽象资源的容量、可用量和消耗结果。 资源含义由项目决定，框架只提供预算检查、消费、释放和快照。

成员概览

类型 名称 签名
信号 budget_changed signal budget_changed(budget_id: StringName, available: float, capacity: float)
信号 budget_consumed signal budget_consumed(budget_id: StringName, amount: float)
信号 budget_rejected signal budget_rejected(budget_id: StringName, amount: float, reason: String)
方法 set_capacity func set_capacity(budget_id: StringName, capacity: float, reset_available: bool = true) -> void:
方法 set_available func set_available(budget_id: StringName, available: float) -> void:
方法 get_capacity func get_capacity(budget_id: StringName) -> float:
方法 get_available func get_available(budget_id: StringName) -> float:
方法 can_consume func can_consume(budget_id: StringName, amount: float) -> bool:
方法 consume func consume(budget_id: StringName, amount: float, metadata: Dictionary = {}) -> Dictionary:
方法 release func release(budget_id: StringName, amount: float) -> void:
方法 reset func reset(budget_id: StringName = &"") -> void:
方法 clear func clear() -> void:
方法 get_snapshot func get_snapshot() -> Dictionary:

信号

budget_changed

  • API：public
signal budget_changed(budget_id: StringName, available: float, capacity: float)

资源预算变化后发出。

参数：

名称 说明
budget_id 预算标识。
available 当前可用量。
capacity 当前容量。

budget_consumed

  • API：public
signal budget_consumed(budget_id: StringName, amount: float)

资源消费成功后发出。

参数：

名称 说明
budget_id 预算标识。
amount 消费数量。

budget_rejected

  • API：public
signal budget_rejected(budget_id: StringName, amount: float, reason: String)

资源消费被拒绝后发出。

参数：

名称 说明
budget_id 预算标识。
amount 请求数量。
reason 拒绝原因。

方法

set_capacity

  • API：public
func set_capacity(budget_id: StringName, capacity: float, reset_available: bool = true) -> void:

设置预算容量，并可选重置可用量。

参数：

名称 说明
budget_id 预算标识。
capacity 容量。
reset_available 是否把可用量重置为容量。

set_available

  • API：public
func set_available(budget_id: StringName, available: float) -> void:

设置当前可用量。

参数：

名称 说明
budget_id 预算标识。
available 可用量。

get_capacity

  • API：public
func get_capacity(budget_id: StringName) -> float:

获取容量。

参数：

名称 说明
budget_id 预算标识。

返回：容量；不存在时返回 0。

get_available

  • API：public
func get_available(budget_id: StringName) -> float:

获取可用量。

参数：

名称 说明
budget_id 预算标识。

返回：可用量；不存在时返回 0。

can_consume

  • API：public
func can_consume(budget_id: StringName, amount: float) -> bool:

是否有足够预算。

参数：

名称 说明
budget_id 预算标识。
amount 请求数量。

返回：预算足够时返回 true。

consume

  • API：public
func consume(budget_id: StringName, amount: float, metadata: Dictionary = {}) -> Dictionary:

尝试消费预算。

参数：

名称 说明
budget_id 预算标识。
amount 消费数量。
metadata 调用方附加信息。

返回：消费结果字典。

结构：

  • metadata: Dictionary copied into the consume result.
  • return: Dictionary with ok, budget_id, amount, reason, available, capacity, and metadata.

release

  • API：public
func release(budget_id: StringName, amount: float) -> void:

释放预算，可用量不会超过容量。

参数：

名称 说明
budget_id 预算标识。
amount 释放数量。

reset

  • API：public
func reset(budget_id: StringName = &"") -> void:

将一个或全部预算重置为容量。

参数：

名称 说明
budget_id 预算标识；为空时重置全部。

clear

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

清空所有预算。

get_snapshot

  • API：public
func get_snapshot() -> Dictionary:

获取预算快照。

返回：预算字典副本。

结构：

  • return: Dictionary from budget id to capacity and available values.