GFBuff¶
API Reference / Combat / 类索引
- 路径：
addons/gf/extensions/combat/attributes/gf_buff.gd - 模块：
Combat - 继承：
RefCounted - API：
public - 类别：协议与扩展点 (
protocol) - 首次版本：
3.17.0
状态效果基类。 管理 Buff 的生命周期、层数以及对属性/标签的影响。 在 GFCombatSystem 的 tick 中驱动 update。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 枚举 | StackMode |
enum StackMode |
| 枚举 | DurationRefreshPolicy |
enum DurationRefreshPolicy |
| 常量 | REMOVAL_REASON_EXPIRED |
const REMOVAL_REASON_EXPIRED: StringName = &"expired" |
| 常量 | REMOVAL_REASON_REMOVED |
const REMOVAL_REASON_REMOVED: StringName = &"removed" |
| 常量 | REMOVAL_REASON_CLEARED |
const REMOVAL_REASON_CLEARED: StringName = &"cleared" |
| 常量 | REMOVAL_REASON_ENTITY_UNREGISTERED |
const REMOVAL_REASON_ENTITY_UNREGISTERED: StringName = &"entity_unregistered" |
| 常量 | REMOVAL_REASON_DISPOSED |
const REMOVAL_REASON_DISPOSED: StringName = &"disposed" |
| 属性 | id |
var id: StringName = &"" |
| 属性 | duration |
var duration: float = 0.0 |
| 属性 | time_left |
var time_left: float = 0.0 |
| 属性 | stacks |
var stacks: int = 1 |
| 属性 | max_stacks |
var max_stacks: int = 1 |
| 属性 | stack_mode |
var stack_mode: StackMode = StackMode.ADD_STACK |
| 属性 | duration_refresh_policy |
var duration_refresh_policy: DurationRefreshPolicy = DurationRefreshPolicy.RESET_TO_NEW_DURATION |
| 属性 | tick_interval_seconds |
var tick_interval_seconds: float = 0.0 |
| 属性 | max_periodic_ticks_per_update |
var max_periodic_ticks_per_update: int = 8 |
| 属性 | remove_on_expire |
var remove_on_expire: bool = true |
| 属性 | modifiers |
var modifiers: Array[GFModifier] = [] |
| 属性 | tags |
var tags: Array[StringName] = [] |
| 属性 | owner |
var owner: Object = null |
| 属性 | checks |
var checks: Array[GFBuffCheck] = [] |
| 属性 | effects |
var effects: Array[GFBuffEffect] = [] |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 属性 | removal_reason |
var removal_reason: StringName = &"" |
| 方法 | setup |
func setup(p_id: StringName, p_duration: float, p_owner: Object) -> void: |
| 方法 | get_apply_report |
func get_apply_report(context: Dictionary = {}) -> Dictionary: |
| 方法 | on_apply |
func on_apply() -> Dictionary: |
| 方法 | on_remove |
func on_remove() -> Dictionary: |
| 方法 | on_refresh |
func on_refresh(p_new_duration: float) -> Dictionary: |
| 方法 | refresh_from |
func refresh_from(source_buff: GFBuff) -> Dictionary: |
| 方法 | on_tick |
func on_tick(_p_delta: float) -> void: |
| 方法 | update |
func update(p_delta: float) -> bool: |
| 方法 | mark_removed |
func mark_removed(reason: StringName = REMOVAL_REASON_REMOVED) -> void: |
| 方法 | get_state_snapshot |
func get_state_snapshot() -> Dictionary: |
| 方法 | restore_state_snapshot |
func restore_state_snapshot(snapshot: Dictionary, owner_override: Object = null) -> void: |
枚举¶
StackMode¶
- API：
public
enum StackMode {
## 只刷新持续时间，不改变层数。
REFRESH_ONLY,
## 刷新持续时间，并在 max_stacks 允许时增加层数。
ADD_STACK,
## 忽略重复添加，不刷新持续时间或层数。
IGNORE,
}
重复添加同 ID Buff 时的层数策略。
DurationRefreshPolicy¶
- API：
public
enum DurationRefreshPolicy {
## 保持当前剩余时间。
KEEP_CURRENT,
## 使用新的持续时间重置剩余时间。
RESET_TO_NEW_DURATION,
## 将新的持续时间追加到当前剩余时间。
EXTEND_BY_NEW_DURATION,
## 保留当前剩余时间与新持续时间中较长者。
KEEP_LONGER_REMAINING,
}
重复添加同 ID Buff 时的持续时间刷新策略。
常量¶
REMOVAL_REASON_EXPIRED¶
- API：
public - 首次版本：
6.0.0
Buff 因持续时间耗尽而移除。
REMOVAL_REASON_REMOVED¶
- API：
public - 首次版本：
6.0.0
Buff 被显式移除。
REMOVAL_REASON_CLEARED¶
- API：
public - 首次版本：
6.0.0
Buff 被批量清理。
REMOVAL_REASON_ENTITY_UNREGISTERED¶
- API：
public - 首次版本：
6.0.0
Buff 随实体注销而移除。
REMOVAL_REASON_DISPOSED¶
- API：
public - 首次版本：
6.0.0
Buff 随系统释放而移除。
属性¶
id¶
- API：
public
Buff 的唯一标识名（通常用于排斥逻辑）。
duration¶
- API：
public
Buff 的总持续时间（秒）。如果为 -1 则视为永久 Buff。
time_left¶
- API：
public
当前剩余剩余时间。
stacks¶
- API：
public
当前层数。
max_stacks¶
- API：
public
最大层数。
stack_mode¶
- API：
public
重复添加同 ID Buff 时的层数策略。
duration_refresh_policy¶
- API：
public
重复添加同 ID Buff 时的持续时间刷新策略。
tick_interval_seconds¶
- API：
public
周期 Tick 间隔。小于等于 0 时保持每帧调用 on_tick() 的旧行为。
max_periodic_ticks_per_update¶
- API：
public
单次 update 允许补偿触发的最大周期 Tick 次数。小于等于 0 时不限制。
remove_on_expire¶
- API：
public
持续时间耗尽时是否由 CombatSystem 移除。
modifiers¶
- API：
public
Buff 携带的属性修饰器列表。应用时会自动挂载到宿主的 Attribute 上。
tags¶
- API：
public
Buff 携带的标签列表。应用时会自动挂载到宿主的 TagComponent 上。
owner¶
- API：
public
Buff 的拥有者（通常是一个持有 Combat 数据的 Object）。
checks¶
- API：
public - 首次版本：
6.0.0
Buff 应用前检查列表。全部通过后才会应用。
effects¶
- API：
public - 首次版本：
6.0.0
Buff 生命周期效果列表。
metadata¶
- API：
public - 首次版本：
6.0.0
项目自定义元数据。GF 不解释该字段。
结构：
metadata: Dictionary project-defined buff metadata.
removal_reason¶
- API：
public - 首次版本：
6.0.0
最近一次移除原因。
方法¶
setup¶
- API：
public
初始化 Buff，由系统或工厂调用。
参数：
| 名称 | 说明 |
|---|---|
p_id |
Buff 标识。 |
p_duration |
Buff 持续时间（秒）。 |
p_owner |
Buff 所属对象。 |
get_apply_report¶
- API：
public - 首次版本：
6.0.0
获取应用检查报告。
参数：
| 名称 | 说明 |
|---|---|
context |
可选应用上下文。 |
返回：检查报告。
结构：
context: Dictionary merged into the default buff apply context.return: Dictionary with ok, reason, buff_id, failed_check_id, metadata, and issues.
on_apply¶
- API：
public - 首次版本：
8.0.0
当 Buff 首次应用时触发。
返回：生命周期报告；ok=false 时表示应用失败且内置效果已回滚。
结构：
return: Dictionary with ok, reason, event, buff_id, changed, failed_effect_id, metadata, and effect_reports.
on_remove¶
- API：
public - 首次版本：
8.0.0
当 Buff 被移除时触发。
返回：生命周期报告；移除会尽力清理内置效果，即使自定义效果报告失败。
结构：
return: Dictionary with ok, reason, event, buff_id, changed, failed_effect_id, metadata, and effect_reports.
on_refresh¶
- API：
public - 首次版本：
8.0.0
当 Buff 层数增加时触发（通常用于刷新持续时间）。
参数：
| 名称 | 说明 |
|---|---|
p_new_duration |
刷新后的持续时间（秒）。 |
返回：生命周期报告；changed=false 表示本次刷新未改变运行状态。
结构：
return: Dictionary with ok, reason, event, buff_id, changed, failed_effect_id, metadata, and effect_reports.
refresh_from¶
- API：
public - 首次版本：
8.0.0
使用同 ID 的新 Buff 刷新当前运行中实例。
参数：
| 名称 | 说明 |
|---|---|
source_buff |
本次尝试添加的新 Buff。 |
返回：生命周期报告；changed=false 表示本次刷新被策略忽略。
结构：
return: Dictionary with ok, reason, event, buff_id, changed, failed_effect_id, metadata, and effect_reports.
on_tick¶
- API：
public
周期性触发逻辑。
参数：
| 名称 | 说明 |
|---|---|
_p_delta |
帧间隔。 |
update¶
- API：
public
内部状态更新流程。
参数：
| 名称 | 说明 |
|---|---|
p_delta |
帧间隔。 |
返回：如果 Buff 已耗尽生命周期需要被移除，则返回 true。
mark_removed¶
- API：
public - 首次版本：
6.0.0
标记移除原因。
参数：
| 名称 | 说明 |
|---|---|
reason |
移除原因。 |
get_state_snapshot¶
- API：
public - 首次版本：
6.0.0
获取运行时状态快照。
返回：状态快照。
结构：
return: Dictionary with generic buff runtime state, modifiers, tags, metadata, and effect_states.
restore_state_snapshot¶
- API：
public - 首次版本：
6.0.0
恢复运行时状态快照。
参数：
| 名称 | 说明 |
|---|---|
snapshot |
状态快照。 |
owner_override |
可选 owner 覆盖；为空时保留当前 owner。 |
结构：
snapshot: Dictionary returned by get_state_snapshot().