/godot-buff-system

name: godot-buff-system
description: Godot 4 Buff系统完整实现，支持状态效果管理、持续时间、循环效果、层叠机制等。使用Resource+Component架构。

Godot 4 Buff系统

完整的Buff/状态效果系统，支持增益和减益效果、持续时间、循环触发、层叠管理等。

何时使用此技能

• 实现游戏状态效果系统
• 玩家/敌人增益减益管理
• DOT/AOE持续伤害
• 护盾、回复、加速等效果

架构设计

Resource + Component 架构

Buff系统
├── Buff Resource（数据层）
│   ├── BuffData - Buff定义数据
│   └── BuffStack - 运行时Buff实例
├── BuffComponent（逻辑层）
│   ├── BuffStore - Buff注册中心
│   └── BuffTimer - 时间管理
└── BuffEffect（效果层）
    └── 各种效果实现

分层职责

• **BuffData**: 定义Buff的静态属性（名称、持续时间、效果类型等）
• **BuffStack**: 管理Buff实例的运行时状态（当前层数、剩余时间等）
• **BuffComponent**: 挂在目标身上，执行Buff逻辑

Buff数据结构

BuffData Buff定义资源

# buff_data.gd
class_name BuffData
extends Resource

## Buff唯一标识符
@export var id: StringName

## Buff显示名称
@export var buff_name: String

## Buff描述
@export_multiline var description: String

## Buff图标
@export var icon: Texture2D

## 持续时间（秒），0表示永久
@export var duration: float = 0.0

## 循环间隔（秒），0表示不循环
@export var tick_interval: float = 0.0

## 最大层数
@export var max_stack: int = 1

## 层叠方式
@export_enum("None", "Duration", "Intensity", "Both") var stack_type: int = 0

## 效果类型
@export_enum("Beneficial", "Harmful", "Neutral") var buff_type: int = 0

## 是否可以被驱散
@export var can_be_dispelled: bool = true

## 是否显示在UI上
@export var show_in_ui: bool = true

## 效果生效时调用
@export var effect_script: GDScript

## Buff优先级（高优先级先执行）
@export var priority: int = 0

BuffStack Buff实例

# buff_stack.gd
class_name BuffStack
extends RefCounted

## 所属的Buff数据
var buff_data: BuffData

## 当前层数
var current_stack: int = 1

## 剩余时间
var remaining_time: float

## 是否正在运行
var is_active: bool = false

## 父节点（BuffComponent持有者）
var owner_node: Node

## 内部计时器
var _tick_timer: float = 0.0

signal stack_changed(new_stack: int)
signal buff_ended(buff_id: StringName)
signal tick_elapsed

func _init(data: BuffData, owner: Node) -> void:
    buff_data = data
    owner_node = owner
    remaining_time = data.duration
    _tick_timer = data.tick_interval

func start() -> void:
    is_active = true
    _apply_effect()

func stop() -> void:
    is_active = false
    _remove_effect()
    buff_ended.emit(buff_data.id)

func update(delta: float) -> bool:
    if not is_active:
        return false
    
    # 更新剩余时间
    remaining_time -= delta
    
    # 循环效果
    if buff_data.tick_interval > 0:
        _tick_timer -= delta
        if _tick_timer <= 0:
            _tick_timer = buff_data.tick_interval
            _on_tick()
            tick_elapsed.emit()
    
    # 永久Buff
    if buff_data.duration <= 0:
        return true
    
    # 时间到则结束
    if remaining_time <= 0:
        stop()
        return false
    
    return true

func add_stack(amount: int = 1) -> void:
    var new_stack := mini(current_stack + amount, buff_data.max_stack)
    
    match buff_data.stack_type:
        1: # Duration - 刷新持续时间
            remaining_time = buff_data.duration
        2: # Intensity - 增加层数
            current_stack = new_stack
            _apply_effect()  # 重新应用效果
        3: # Both - 刷新时间并增加层数
            remaining_time = buff_data.duration
            current_stack = new_stack
            _apply_effect()
        _:
            current_stack = new_stack
    
    stack_changed.emit(current_stack)

func _apply_effect() -> void:
    if buff_data.effect_script:
        # 执行效果脚本
        pass

func _remove_effect() -> void:
    if buff_data.effect_script:
        # 移除效果脚本
        pass

func _on_tick() -> void:
    # 每次循环时调用
    pass

func get_time_percent() -> float:
    if buff_data.duration <= 0:
        return 1.0
    return remaining_time / buff_data.duration

效果执行机制

BuffStore 注册中心

# buff_store.gd
class_name BuffStore
extends Node

## 注册所有可用的Buff
@export var registered_buffs: Array[BuffData]

## 全局Buff字典
var _buff_registry: Dictionary = {}

func _ready() -> void:
    _register_all_buffs()

func _register_all_buffs() -> void:
    for buff in registered_buffs:
        _buff_registry[buff.id] = buff

func get_buff_data(buff_id: StringName) -> BuffData:
    return _buff_registry.get(buff_id)

func create_buff_stack(buff_id: StringName, owner: Node) -> BuffStack:
    var data := get_buff_data(buff_id)
    if data == null:
        push_error("Buff not found: ", buff_id)
        return null
    
    var stack := BuffStack.new(data, owner)
    return stack

BuffComponent Buff组件

# buff_component.gd
class_name BuffComponent
extends Node

## 信号：Buff被添加
signal buff_added(buff_id: StringName, stack: BuffStack)

## 信号：Buff被移除
signal buff_removed(buff_id: StringName)

## 信号：Buff层数变化
signal buff_stack_changed(buff_id: StringName, new_stack: int)

## 信号：Buff刷新
signal buff_refreshed(buff_id: StringName)

## 活跃的Buff字典
var active_buffs: Dictionary = {}

## 父节点引用
var _owner: Node

func _ready() -> void:
    _owner = get_parent()

func _process(delta: float) -> void:
    _update_buffs(delta)

func _update_buffs(delta: float) -> void:
    var to_remove: Array[StringName] = []
    
    for buff_id in active_buffs.keys():
        var stack: BuffStack = active_buffs[buff_id]
        if not stack.update(delta):
            to_remove.append(buff_id)
    
    for buff_id in to_remove:
        _remove_buff(buff_id)

## 添加Buff
func add_buff(buff_id: StringName, duration: float = -1) -> BuffStack:
    # 检查是否已存在
    if active_buffs.has(buff_id):
        var existing: BuffStack = active_buffs[buff_id]
        existing.add_stack(1)
        if duration > 0:
            existing.remaining_time = duration
        buff_refreshed.emit(buff_id)
        return existing
    
    # 创建新Buff
    var stack := BuffStore.create_buff_stack(buff_id, _owner)
    if stack == null:
        return null
    
    if duration > 0:
        stack.buff_data.duration = duration
    
    active_buffs[buff_id] = stack
    stack.start()
    
    buff_added.emit(buff_id, stack)
    return stack

## 移除Buff
func remove_buff(buff_id: StringName) -> bool:
    if not active_buffs.has(buff_id):
        return