Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

godot-composition

/godot-composition

Ustala standardy architektury skalowalnych gier w Godot według wzorca kompozycji Entity-Component, dla kontrolerów graczy, NPC, wrogów, broni i systemów rozgrywki.

Repozytorium
dotfiles ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
14
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Ustala standardy architektury skalowalnych gier w Godot według wzorca kompozycji Entity-Component, dla kontrolerów graczy, NPC, wrogów, broni i systemów rozgrywki.

Wyzwalacze z opisu

Has-A\
Oryginalny opis (EN)

Expert architectural standards for building scalable Godot GAMES (RPGs, Platformers, Shooters) using the Composition pattern (Entity-Component). Use when designing player controllers, NPCs, enemies, weapons, or complex gameplay systems. Enforces \"Has-A\" relationships for game entities. Trigger keywords: Entity-Component, ECS, Gameplay, Actors, NPCs, Enemies, Weapons, Hitboxes, Game Loop, Level Design.

Jak działa

  1. Core Philosophy
  2. Available Scripts
  3. NEVER Do in Composition
  4. Implementation Standards
  5. Standard Components
  6. The Orchestrator (Putting it Together)
  7. Performance Note
  8. Reference
Sekcje z nagłówków SKILL.md, w oryginale · 209 linii, 954 słów
Podgląd SKILL.md
---
name: godot-composition
description: "Expert architectural standards for building scalable Godot GAMES (RPGs, Platformers, Shooters) using the Composition pattern (Entity-Component). Use when designing player controllers, NPCs, enemies, weapons, or complex gameplay systems. Enforces \"Has-A\" relationships for game entities. Trigger keywords: Entity-Component, ECS, Gameplay, Actors, NPCs, Enemies, Weapons, Hitboxes, Game Loop, Level Design."
---

# Godot Composition Architecture

## Core Philosophy
This skill enforces **Composition over Inheritance** ("Has-a" vs "Is-a").
In Godot, Nodes **are** components. A complex entity (Player) is simply an Orchestrator managing specialized Worker Nodes (Components).

### The Golden Rules
1.  **Single Responsibility**: One script = One job.
2.  **Encapsulation**: Components are "selfish." They handle their internal logic but don't know *who* owns them.
3.  **The Orchestrator**: The root script (e.g., `player.gd`) does **no logic**. It only manages state and passes data between components.
4.  **Decoupling**: Components communicate via **Signals** (up) and **Methods** (down).

---

## Available Scripts

### [health_component.gd](scripts/health_component.gd)
Specialized Node for managing lifespan, damage logic, and death signals across any entity.

### [hit_box_component.gd](scripts/hit_box_component.gd)
Area-based component for intercepting damage and delegating it to a HealthComponent.

### [hurt_box_component.gd](scripts/hurt_box_component.gd)
Area-based component for dealing damage specifically to HitBoxComponents.

### [velocity_component.gd](scripts/velocity_component.gd)
Encapsulated movement and acceleration logic for reuse across Players and Enemies.

### [interaction_component.gd](scripts/interaction_component.gd)
Decoupled interaction handler using injecting `Callable` logic for context-aware actions.

### [follower_component.gd](scripts/follower_component.gd)
Decoupled tracking logic using `NodePath` injection for smooth entity following.

### [state_component_vsm.gd](scripts/state_component_vsm.gd)
Component-based state machine pattern using child nodes as individual states.

### [status_effect_component.gd](scripts/status_effect_component.gd)
Managing temporary modifiers (buffs/debuffs) by stacking effect scenes as children.

### [visual_sync_component.gd](scripts/visual_sync_component.gd)
Separating logical state (velocity/direction) from visual representation (sprite flipping).

### [composition_root_init.gd](scripts/composition_root_init.gd)
The "Orchestrator" pattern for wiring and connecting components in a parent node.

## NEVER Do in Composition

- **NEVER use deep inheritance chains** (e.g., `Player > Entity > LivingThing > Node`) — Creates brittle "God Classes" that are hard to refactor [21].
- **NEVER use `get_node()` or `$` for components** — This breaks if the scene tree is rearranged. Always use `@export` or `%UniqueNames` [22].
- **NEVER let a component reference its parent script directly** — This makes the component impossible to reuse. Use signals or dependency injection [23].
- **NEVER mix Input, Physics, and Game Logic in one script** — This violates Single Responsibility. Split them into specialized components [24, 13].
- **NEVER create components that require a specific SceneTree structure** — A component should be "selfish" and only care about its own properties and direct children.
- **NEVER use inheritance to "add a feature"** — If you want an enemy to shoot, add a `ShootingComponent`, don't make it inherit from `ShooterEnemy`.
- **NEVER hardcode component dependencies** — If `CombatComponent` needs `HealthComponent`, look it up in `_ready()` or inject it via the parent [11].
- **NEVER treat Godot nodes as pure data** — Nodes provide lifecycle (`_process`) and signals. If you only need data, use a `Resource`.
- **NEVER ignore the Node lifecycle in components** — Use `_enter_tree()` and `_exit_tree()` for setup/cleanup that must happen regardless of the parent's state.
- **NEVER hide component points of access** — Expose `NodePath` or `Callable` properties so the parent can wire the component in the Inspector [13].

---

## Implementation Standards

### 1. Connection Strategy: Typed Exports
Do not rely on tree order. Use explicit dependency injection via `@export` with static typing.

**The "Godot Way" for strict godot-composition:**
```gdscript
# The Orchestrator (e.g., player.gd)
class_name Player extends CharacterBody3D

# Dependency Injection: Define the "slots" in the backpack
@export var health_component: HealthComponent
@export var movement_component: MovementComponent
@export var input_component: InputComponent

# Use Scene Unique Names (%) for auto-assignment in Editor
# or drag-and-drop in the Inspector.
```

### 2. Component Mindset
Components must define `class_name` to be recognized as types.

**Standard Component Boilerplate:**
```gdscript
class_name MyComponent extends Node 
# Use Node for logic, Node3D/2D if it needs position

@export var stats: Resource # Components can hold their own data
signal happened_something(value)

func do_logic(delta: float) -> void:
    # Perform specific task
    pass
```

---

## Standard Components

### The Input Component (The Senses)
**Responsibility**: Read hardware state. Store it. Do NOT act on it.
*State*: `move_dir`, `jump_pressed`, `attack_just_pressed`.

```gdscript
class_name InputComponent extends Node

var move_dir: Vector2
var jump_pressed: bool

func update() -> void:
    # Called by Orchestrator every frame
    move_dir = Input.get_vector("left", "right", "up", "down")
    jump_pressed = Input.is_action_just_pressed("jump")
```

### The Movement Component (The Legs)
**Responsibility**: Manipulate physics body. Handle velocity/gravity.
**Constraint**: Requires a reference to the physics body it moves.

```gdscript
class_name MovementComponent extends Node

@export var body: CharacterBody3D # The thing we move
@export var speed: float = 8.0
@export var jump_velocity: float = 12.0

func tick(delta: float, direction: Vector2, wants_jump: bool) -> void:
    if not body: return
    
    # Handle Gravity
    if not body.is_on_floor():
        body.velocity.y -= 9.8 * delta
        
    # Handle Movement
    if direction:
        body.velocity.x = direction.x * speed
        body.velocity.z = direction.y * speed # 3D conversion
    else:
        body.velocity.x = move_toward(body.velocity.x, 0, speed)
        body.velocity.z = move_toward(body.velocity.z, 0, speed)
        
    # Handle Jump
    if wants_jump and body.is_on_floor():
        body.velocity.y = jump_velocity
        
    body.move_and_slide()
```

### The Health Component (The Life)
**Responsibility**: Manage HP, Clamp values, Signal changes.
**Context Agnostic**: Can be put on a Player, Enemy, or a Wooden Crate.

```gdscript
class_name HealthComponent extends Node

signal died
signal health_changed(current, max)

@export var max_health: float = 100.0
var current_health: float

func _ready():
    current_health = max_health

func damage(amount: float):
    current_health = clamp(current_health - amount, 0, max_health)
    health_changed.emit(current_health, max_health)
    if current_health == 0:
        died.emit()
```

---

## The Orchestrator (Putting it Together)

The Orchestrator (`player.gd`) binds the components in the `_physics_process`. It acts as the bridge.

```gdscript
class_name Player extends CharacterBody3D

@onready var input: InputComponent = %InputComponent
@onready var move: MovementComponent = %MovementComponent
@onready var health: HealthComponent = %HealthComponent

func _ready():
    # Connect signals (The ears)
    health.died.connect(_on_death)

func _physics_process(delta):
    # 1. Update Senses
    input.update()
    
    # 2. Pass Data to Workers (State Management)
    # The Player script decides that "Input Direction" maps to "Movement Direction"
    move.tick(delta, input.move_dir, input.jump_pressed)

func _on_death():
    queue_free()
```

## Performance Note
Nodes are lightweight. Do not fear adding 10-20 nodes per entity. The organizational benefit of Composition vastly outweighs the negligible memory cost of `Node` instances.


## Reference
- Master Skill: [godot-master](../godot-master/SKILL.md)
Pliki w paczce (14)
  • QA_REPORT.md 1 KB
  • SKILL.md 8 KB
  • resources/health_component.gd 1 KB
  • resources/hitbox_component.gd 1 KB
  • scripts/composition_root_init.gd 1 KB
  • scripts/follower_component.gd 1 KB
  • scripts/health_component.gd 1 KB
  • scripts/hit_box_component.gd 1 KB
  • scripts/hurt_box_component.gd 1 KB
  • scripts/interaction_component.gd 1 KB
  • scripts/state_component_vsm.gd 1 KB
  • scripts/status_effect_component.gd 1 KB
  • scripts/velocity_component.gd 1 KB
  • scripts/visual_sync_component.gd 1 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · ahmet-cetinkaya/dotfiles100MIT
thedivergentai/game-dev-agentic-skills100LGPL

Migawka bazy z 13.11.2026 · wersja paczki 44487775e642 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 1 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100godot-composition-apps
    Ustala standardy architektury skalowalnych aplikacji i gier w Godot według wzorca kompozycji, przydatne przy projektowaniu drzew węzłów i dzieleniu monolitycznych skryptów.
  • 100godot-composition-apps
    Ustala standardy architektury skalowalnych aplikacji, narzędzi, wtyczek EditorPlugin i interfejsów Control w Godot według kompozycji z orkiestratorem i komponentami.
  • 100gecs
    Opisuje API frameworka ECS gecs dla Godot 4.x: Entity, Component, System, World, QueryBuilder, Relationship, Observer, CommandBuffer i SystemTimer oraz zapytania po składzie komponentów.
  • 95godot-master
    Doradza w architekturze gier i aplikacji w Godot 4.7+: układ projektu, systemy encji, wydajność, fizykę i wybór 2D lub 3D.
  • 91godot
    Buduje gry w Godot z GDScript, natywnymi asercjami rozgrywki i bezpiecznymi eksportami do przeglądarki.
  • 100godot-master
    Zbiera bibliotekę ekspercką do zawodowego tworzenia gier i aplikacji w Godot 4.x: 94 plany, przepływy architektoniczne, katalogi antywzorców, budżety wydajności i wzorce Server API.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.