跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

component-system

Use when building reusable node components — composition patterns, component communication, and interface design

jame581 · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add jame581/GodotPrompter --skill component-system

技能说明


name: component-system description: Use when building reusable node components — composition patterns, component communication, and interface design

Component System in Godot 4.3+

Build behavior through composition. Attach small, focused components to any entity rather than climbing an inheritance chain. All examples target Godot 4.3+ with no deprecated APIs.

Related skills: scene-organization for scene tree composition, event-bus for decoupled component communication, resource-pattern for data-driven component configuration, physics-system for Area2D/3D overlap detection and collision shapes, ability-system for an AbilityComponent example built on this pattern.


1. Why Components

Problem with inheritanceHow components solve it
Deep chains are brittle — change one class, break manyEach component is an isolated scene with a single job
Sharing behavior across unrelated entities requires awkward base classesDrop a component onto any entity that needs that behavior
Adding a new combination means a new subclassMix and match components freely at the scene level

Key benefits:

  • Reuse across entities — a HealthComponent works on a player, an enemy, a destructible crate, or a boss with no code changes.
  • Separation of concerns — damage detection, health tracking, and state animation are each their own file. Debugging is local.
  • Mix-and-match behaviors — give an enemy a HitboxComponent and a PatrolComponent independently. Removing one does not affect the other.

2. Component Design Rules

  1. One responsibility per component. If you find yourself naming it HealthAndShieldAndRegenComponent, split it.
  2. Communicate via signals, not direct sibling access. A component must not call get_parent().get_node("SiblingComponent"). Emit a signal instead.
  3. Stateless where possible. Prefer deriving state from inputs and @export configuration over storing mutable state. When state is necessary, keep it private.
  4. Use @export for all configuration. Damage amount, cooldown duration, and layer masks belong in the Inspector, not hardcoded constants.

3. Common Components

ComponentPurposeKey Signals
HealthComponentTracks current and max HP, applies damage and healinghealth_changed(current, maximum), died
HitboxComponentDetects overlapping hurtboxes and triggers damagehit(target_hurtbox)
HurtboxComponentReceives hits, routes damage to HealthComponenthurt(damage_amount)
InteractableComponentMarks an entity as interactable and fires on player overlapinteracted(interactor)
StateMachineComponentDelegates _process and _physics_process to child state nodesstate_changed(from, to)

4. HitboxComponent

Attach to any entity that deals damage. Configure damage in the Inspector.

GDScript (hitbox_component.gd)

class_name HitboxComponent
extends Area2D

## Damage dealt to the target hurtbox on contact.
@export var damage: int = 10

## Minimum seconds between successive hits (0 = no cooldown).
@export var cooldown_duration: float = 0.5

signal hit(target_hurtbox: HurtboxComponent)

var _on_cooldown: bool = false

@onready var _cooldown_timer: Timer = _build_timer()


func _ready() -> void:
	area_entered.connect(_on_area_entered)


func _on_area_entered(area: Area2D) -> void:
	if _on_cooldown:
		return
	if area is not HurtboxComponent:
		return
	hit.emit(area)
	area.receive_hit(damage)
	if cooldown_duration > 0.0:
		_on_cooldown = true
		_cooldown_timer.start(cooldown_duration)


func _on_cooldown_timeout() -> void:
	_on_cooldown = false


func _build_timer() -> Timer:
	var t := Timer.new()
	t.one_shot = true
	t.timeout.connect(_on_cooldown_timeout)
	add_child(t)
	return t

C# (HitboxComponent.cs)

using Godot;

public partial class HitboxComponent : Area2D
{
    /// <summary>Damage dealt to the target hurtbox on contact.</summary>
    [Export] public int Damage { get; set; } = 10;

    /// <summary>Minimum seconds between successive hits (0 = no cooldown).</summary>
    [Export] public float CooldownDuration { get; set; } = 0.5f;

    [Signal] public delegate void HitEventHandler(HurtboxComponent targetHurtbox);

    private bool _onCooldown;
    private Timer _cooldownTimer;

    public override void _Ready()
    {
        _cooldownTimer = new Timer { OneShot = true };
        _cooldownTimer.Timeout += OnCooldownTimeout;
        AddChild(_cooldownTimer);

        AreaEntered += OnAreaEntered;
    }

    private void OnAreaEntered(Area2D area)
    {
        if (_onCooldown) return;
        if (area is not HurtboxComponent hurtbox) return;

        EmitSignal(SignalName.Hit, hurtbox);
        hurtbox.ReceiveHit(Damage);

        if (CooldownDuration > 0f)
        {
            _onCooldown = true;
            _cooldownTimer.Start(CooldownDuration);
        }
    }

    private void OnCooldownTimeout() => _onCooldown = false;
}

5. HurtboxComponent

Attach to any entity that can take damage. Wire it to a sibling HealthComponent via @export.

GDScript (hurtbox_component.gd)

class_name HurtboxComponent
extends Area2D

## Reference to the HealthComponent on the same entity.
@export var health_component: HealthComponent

## Invincibility frame duration in seconds (0 = none).
@export var invincibility_duration: float = 0.0

signal hurt(damage_amount: int)

var _invincible: bool = false

@onready var _iframes_timer: Timer = _build_timer()


func receive_hit(damage: int) -> void:
	if _invincible:
		return
	hurt.emit(damage)
	if health_component:
		health_component.take_damage(damage)
	if invincibility_duration > 0.0:
		_invincible = true
		_iframes_timer.start(invincibility_duration)


func _on_iframes_timeout() -> void:
	_invincible = false


func _build_timer() -> 
阅读完整来源 ↗