omgkit 2.12.0 → 2.15.0

package/plugin/skills/game/godot-patterns/SKILL.md

@@ -0,0 +1,413 @@
+# Godot Patterns
+
+Godot 4 architecture patterns including node composition, signals, resources, and GDScript/C# best practices.
+
+## Overview
+
+Godot's scene/node architecture enables composition-based game design with powerful signal systems and resource management.
+
+## Core Concepts
+
+### Node Hierarchy
+- **Node**: Base class for everything
+- **Scene**: Reusable node tree
+- **Resource**: Shareable data objects
+- **Autoload**: Global singletons
+
+### Design Philosophy
+- Composition over inheritance
+- Scenes as prefabs
+- Signals for decoupling
+- Resources for data
+
+## Scene Architecture
+
+### Component Pattern
+```gdscript
+# health_component.gd
+class_name HealthComponent
+extends Node
+
+signal health_changed(current: float, maximum: float)
+signal died
+
+@export var max_health: float = 100.0
+var current_health: float:
+    set(value):
+        var old_health = current_health
+        current_health = clampf(value, 0.0, max_health)
+        health_changed.emit(current_health, max_health)
+        if current_health <= 0 and old_health > 0:
+            died.emit()
+
+func _ready() -> void:
+    current_health = max_health
+
+func take_damage(amount: float) -> void:
+    current_health -= amount
+
+func heal(amount: float) -> void:
+    current_health += amount
+
+func is_alive() -> bool:
+    return current_health > 0
+```
+
+```gdscript
+# hitbox_component.gd
+class_name HitboxComponent
+extends Area3D
+
+signal hit(damage: float, source: Node)
+
+@export var damage: float = 10.0
+@export var knockback_force: float = 500.0
+
+func _on_area_entered(area: Area3D) -> void:
+    if area is HurtboxComponent:
+        area.receive_hit(damage, knockback_force, owner)
+        hit.emit(damage, area.owner)
+```
+
+```gdscript
+# hurtbox_component.gd
+class_name HurtboxComponent
+extends Area3D
+
+signal damage_received(amount: float, source: Node)
+
+@export var health_component: HealthComponent
+
+func receive_hit(damage: float, knockback: float, source: Node) -> void:
+    if health_component:
+        health_component.take_damage(damage)
+    damage_received.emit(damage, source)
+```
+
+### Entity Composition
+```gdscript
+# player.gd
+extends CharacterBody3D
+
+@onready var health: HealthComponent = $HealthComponent
+@onready var hurtbox: HurtboxComponent = $HurtboxComponent
+@onready var state_machine: StateMachine = $StateMachine
+@onready var animation_player: AnimationPlayer = $AnimationPlayer
+
+func _ready() -> void:
+    health.died.connect(_on_death)
+    hurtbox.damage_received.connect(_on_damage_received)
+
+func _physics_process(delta: float) -> void:
+    state_machine.process_physics(delta)
+
+func _on_death() -> void:
+    state_machine.transition_to("Dead")
+
+func _on_damage_received(amount: float, source: Node) -> void:
+    animation_player.play("hit")
+```
+
+## Signal Patterns
+
+### Event Bus (Autoload)
+```gdscript
+# events.gd (Autoload)
+extends Node
+
+# Game events
+signal game_started
+signal game_paused(is_paused: bool)
+signal game_over(won: bool)
+
+# Player events
+signal player_spawned(player: Node)
+signal player_died(player: Node)
+signal player_scored(points: int)
+
+# UI events
+signal show_dialog(text: String)
+signal update_health(current: float, max: float)
+signal update_score(score: int)
+
+# Combat events
+signal enemy_killed(enemy: Node, killer: Node)
+signal damage_dealt(amount: float, target: Node, source: Node)
+```
+
+```gdscript
+# Usage in player
+func _ready() -> void:
+    Events.player_spawned.emit(self)
+
+func die() -> void:
+    Events.player_died.emit(self)
+```
+
+```gdscript
+# Usage in UI
+extends Control
+
+func _ready() -> void:
+    Events.update_health.connect(_on_health_updated)
+    Events.update_score.connect(_on_score_updated)
+    Events.game_over.connect(_on_game_over)
+
+func _on_health_updated(current: float, max: float) -> void:
+    $HealthBar.value = current / max * 100
+```
+
+## Resource System
+
+### Custom Resources
+```gdscript
+# weapon_resource.gd
+class_name WeaponResource
+extends Resource
+
+@export var weapon_name: String
+@export var icon: Texture2D
+@export var damage: float
+@export var attack_speed: float
+@export var range: float
+@export_enum("Melee", "Ranged", "Magic") var weapon_type: int
+@export var attack_animation: String
+@export var attack_sound: AudioStream
+
+func get_dps() -> float:
+    return damage * attack_speed
+```
+
+```gdscript
+# character_stats.gd
+class_name CharacterStats
+extends Resource
+
+@export var character_name: String
+@export var max_health: float = 100.0
+@export var move_speed: float = 300.0
+@export var jump_force: float = 400.0
+@export var starting_weapon: WeaponResource
+@export_multiline var description: String
+
+func apply_to(character: CharacterBody2D) -> void:
+    character.max_health = max_health
+    character.move_speed = move_speed
+    character.jump_force = jump_force
+```
+
+### Inventory System
+```gdscript
+# inventory.gd
+class_name Inventory
+extends Resource
+
+signal item_added(item: ItemResource, slot: int)
+signal item_removed(item: ItemResource, slot: int)
+signal inventory_changed
+
+@export var slots: Array[ItemResource] = []
+@export var max_slots: int = 20
+
+func _init() -> void:
+    slots.resize(max_slots)
+
+func add_item(item: ItemResource) -> bool:
+    # Try to stack first
+    for i in range(slots.size()):
+        if slots[i] and slots[i].can_stack_with(item):
+            slots[i].quantity += item.quantity
+            inventory_changed.emit()
+            return true
+
+    # Find empty slot
+    for i in range(slots.size()):
+        if slots[i] == null:
+            slots[i] = item.duplicate()
+            item_added.emit(item, i)
+            inventory_changed.emit()
+            return true
+
+    return false
+
+func remove_item(slot: int) -> ItemResource:
+    if slot < 0 or slot >= slots.size():
+        return null
+
+    var item = slots[slot]
+    slots[slot] = null
+    if item:
+        item_removed.emit(item, slot)
+        inventory_changed.emit()
+    return item
+```
+
+## State Machine
+
+### GDScript State Machine
+```gdscript
+# state_machine.gd
+class_name StateMachine
+extends Node
+
+signal state_changed(old_state: State, new_state: State)
+
+@export var initial_state: State
+var current_state: State
+var states: Dictionary = {}
+
+func _ready() -> void:
+    for child in get_children():
+        if child is State:
+            states[child.name.to_lower()] = child
+            child.state_machine = self
+
+    if initial_state:
+        current_state = initial_state
+        current_state.enter()
+
+func process_input(event: InputEvent) -> void:
+    if current_state:
+        current_state.handle_input(event)
+
+func process_frame(delta: float) -> void:
+    if current_state:
+        current_state.update(delta)
+
+func process_physics(delta: float) -> void:
+    if current_state:
+        current_state.physics_update(delta)
+
+func transition_to(state_name: String, params: Dictionary = {}) -> void:
+    var new_state = states.get(state_name.to_lower())
+    if new_state == null:
+        push_error("State not found: " + state_name)
+        return
+
+    if current_state:
+        current_state.exit()
+
+    var old_state = current_state
+    current_state = new_state
+    current_state.enter(params)
+
+    state_changed.emit(old_state, new_state)
+```
+
+```gdscript
+# state.gd
+class_name State
+extends Node
+
+var state_machine: StateMachine
+
+func enter(params: Dictionary = {}) -> void:
+    pass
+
+func exit() -> void:
+    pass
+
+func handle_input(event: InputEvent) -> void:
+    pass
+
+func update(delta: float) -> void:
+    pass
+
+func physics_update(delta: float) -> void:
+    pass
+```
+
+```gdscript
+# player_idle_state.gd
+extends State
+
+@onready var player: CharacterBody2D = owner
+
+func enter(params: Dictionary = {}) -> void:
+    player.animation_player.play("idle")
+
+func physics_update(delta: float) -> void:
+    var input_dir = Input.get_vector("move_left", "move_right", "move_up", "move_down")
+
+    if input_dir.length() > 0.1:
+        state_machine.transition_to("Move")
+
+    if Input.is_action_just_pressed("jump") and player.is_on_floor():
+        state_machine.transition_to("Jump")
+
+    if Input.is_action_just_pressed("attack"):
+        state_machine.transition_to("Attack")
+```
+
+## C# Patterns
+
+### Component in C#
+```csharp
+using Godot;
+
+public partial class HealthComponent : Node
+{
+    [Signal]
+    public delegate void HealthChangedEventHandler(float current, float max);
+
+    [Signal]
+    public delegate void DiedEventHandler();
+
+    [Export]
+    public float MaxHealth { get; set; } = 100f;
+
+    private float _currentHealth;
+    public float CurrentHealth
+    {
+        get => _currentHealth;
+        set
+        {
+            float oldHealth = _currentHealth;
+            _currentHealth = Mathf.Clamp(value, 0f, MaxHealth);
+            EmitSignal(SignalName.HealthChanged, _currentHealth, MaxHealth);
+
+            if (_currentHealth <= 0 && oldHealth > 0)
+                EmitSignal(SignalName.Died);
+        }
+    }
+
+    public override void _Ready()
+    {
+        CurrentHealth = MaxHealth;
+    }
+
+    public void TakeDamage(float amount) => CurrentHealth -= amount;
+    public void Heal(float amount) => CurrentHealth += amount;
+    public bool IsAlive() => CurrentHealth > 0;
+}
+```
+
+## Best Practices
+
+1. **Use Composition**: Build entities from components
+2. **Leverage Signals**: Decouple systems
+3. **Resources for Data**: Share data between scenes
+4. **Autoloads Sparingly**: Only for truly global systems
+5. **Type Hints**: Use static typing in GDScript
+
+## Anti-Patterns
+
+- Deep inheritance hierarchies
+- Direct node references across scenes
+- Business logic in UI nodes
+- Hardcoded paths
+- Overusing autoloads
+
+## When to Use
+
+- Godot game projects
+- 2D and 3D games
+- Rapid prototyping
+- Open-source game development
+- Cross-platform games
+
+## When NOT to Use
+
+- AAA-scale projects (consider Unity/Unreal)
+- Specialized engines exist (racing, sports)
+- Team heavily invested in other engines