Przejdź do treści
Biblioteka skilli
Programowanie · Nauka i wyjaśnianie

gecs

/gecs

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.

Repozytorium
godotmaker ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
23.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
11
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

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.

Oryginalny opis (EN)

gecs ECS framework API reference — the Entity-Component-System addon for Godot 4.x used by this project. Covers Entity, Component, System, World, QueryBuilder, Relationship, Observer, CommandBuffer, SystemTimer. Use when the task involves ECS architecture: creating entities with components, defining component data classes (C_ prefix), writing game logic systems, querying entities by component composition, entity relationships or links, reactive observers for component changes, safe structural changes during iteration, system tick rates, ECS world setup, debugging ECS queries or cache, or defer

Jak działa

  1. Core Concept Mapping
  2. Quick Start
  3. Naming Conventions
  4. Common Operations
  5. Reference Files
  6. MANDATORY: Read gotchas.md Before Writing ECS Code
  7. Critical Gotchas (summary)
Sekcje z nagłówków SKILL.md, w oryginale · 227 linii, 1 195 słów
Podgląd SKILL.md
---
name: gecs
description: |
  gecs ECS framework API reference — the Entity-Component-System addon for
  Godot 4.x used by this project. Covers Entity, Component, System, World,
  QueryBuilder, Relationship, Observer, CommandBuffer, SystemTimer.
  Use when the task involves ECS architecture: creating entities with components,
  defining component data classes (C_ prefix), writing game logic systems,
  querying entities by component composition, entity relationships or links,
  reactive observers for component changes, safe structural changes during
  iteration, system tick rates, ECS world setup, debugging ECS queries or cache,
  or deferred entity destruction. Also trigger on gecs API calls: q.with_all(),
  ECS.world, ECS.process(), define_components(), cmd.add_component(). gecs has
  zero LLM training data — without this skill all ECS API calls will be
  fabricated. NOT relevant for standard Godot subsystems (physics, animation,
  UI, tilemap, shader, particles, navigation, signals, audio) unless explicitly
  connected to ECS.
---

# gecs — ECS Framework for Godot 4.x

$ARGUMENTS

gecs is the ECS backend for GodotMaker. It has **zero LLM training data coverage** —
all API knowledge must come from this skill.

## Core Concept Mapping

| gecs Class | Godot Base | Key Insight |
|------------|-----------|-------------|
| `Entity` | `extends Node` | Entity IS a Node — lives in scene tree, can have child nodes |
| `Component` | `extends Resource` | Pure data, `@export` properties with defaults, no logic |
| `System` | `extends Node` | Contains game logic, queries entities, placed in scene tree |
| `World` | `extends Node` | Manages all entities/systems, archetype storage, query engine |
| `QueryBuilder` | `extends RefCounted` | Chain API: `with_all`/`with_any`/`with_none`, auto-cached |
| `Relationship` | `extends Resource` | Pair (relation_component, target), archetype-level indexing |
| `Observer` | `extends Node` | Reactive: fires on component add/remove/change events |
| `CommandBuffer` | `extends RefCounted` | Safe structural changes during iteration via `cmd` |
| `ECS` | Autoload singleton | Global access: `ECS.world`, `ECS.process(delta, group)` |

## Quick Start

```gdscript
# --- Component (pure data, extends Resource) ---
class_name C_Health extends Component
@export var current: float = 100.0
@export var maximum: float = 100.0

class_name C_Velocity extends Component
@export var direction: Vector3 = Vector3.ZERO
@export var speed: float = 100.0

# --- Entity (extends Node, define default components) ---
class_name Player extends Entity
func define_components() -> Array:
    return [C_Health.new(), C_Velocity.new()]

func on_ready():
    add_to_group("player")

# --- System (game logic, extends Node) ---
class_name MovementSystem extends System
func query() -> QueryBuilder:
    return q.with_all([C_Velocity])

func process(entities: Array[Entity], components: Array, delta: float) -> void:
    for entity in entities:
        var vel = entity.get_component(C_Velocity)
        var pos = entity.get_component(C_Position)
        pos.value += vel.direction * vel.speed * delta  # Entity is Node, not Node2D!

# --- Main scene processing ---
# main.gd
func _process(delta):
    ECS.process(delta, "input")
    ECS.process(delta, "gameplay")

func _physics_process(delta):
    ECS.process(delta, "physics")
    ECS.process(delta, "run-last")
```

## Naming Conventions

| Type | Class Name | File Name | Example |
|------|-----------|-----------|---------|
| Component | `C_Name` | `c_name.gd` | `C_Health` / `c_health.gd` |
| System | `NameSystem` | `s_name.gd` | `MovementSystem` / `s_movement.gd` |
| Entity | `Name` | `e_name.gd` | `Player` / `e_player.gd` |
| Observer | `NameObserver` | `o_name.gd` | `HealthUIObserver` / `o_health_ui.gd` |
| Relationship component | `R_Action` | `r_action.gd` | `R_ChildOf` / `r_child_of.gd` |

## Common Operations

### Entity

```gdscript
# Create programmatically
var entity = Player.new()
ECS.world.add_entity(entity)

# Instantiate from scene prefab (.tscn with Entity root)
var entity = preload("res://entities/e_player.tscn").instantiate()
get_tree().current_scene.add_child(entity)
ECS.world.add_entity(entity)

# Component operations (pass CLASS to get/has, INSTANCE to add/remove)
entity.add_component(C_Health.new(100))
var health = entity.get_component(C_Health)      # returns instance or null
var has = entity.has_component(C_Health)           # bool check
entity.remove_component(health)                    # pass the instance

# Enable/disable
entity.enabled = false     # excluded from queries
ECS.world.disable_entity(entity)
ECS.world.enable_entity(entity)

# Destroy (calls on_destroy, queue_free, cleans up relationships)
ECS.world.remove_entity(entity)
```

### Query

```gdscript
# In a System — use q shorthand
func query() -> QueryBuilder:
    return q.with_all([C_Health, C_Velocity])   # must have ALL
             .with_any([C_Player, C_Enemy])     # must have at least ONE
             .with_none([C_Dead])                # must NOT have
             .enabled()                           # only enabled entities

# Batch component access (faster — avoids per-entity get_component):
func query() -> QueryBuilder:
    return q.with_all([C_Velocity]).iterate([C_Velocity])

func process(entities: Array[Entity], components: Array, delta: float):
    var velocities = components[0]   # Array of C_Velocity, same order as entities
    for i in entities.size():
        var pos = entities[i].get_component(C_Position)
        pos.value += velocities[i].direction * delta  # Entity is Node, not Node2D!

# Standalone query (outside a System):
var enemies = ECS.world.query.with_all([C_Health, C_Enemy]).execute()
var player = ECS.world.query.with_all([C_Player]).execute_one()
```

### CommandBuffer (safe structural changes during iteration)

```gdscript
class_name LifetimeSystem extends System

func query():
    return q.with_all([C_Lifetime])

func process(entities: Array[Entity], components: Array, delta: float):
    for entity in entities:          # safe forward iteration
        var lt = entity.get_component(C_Lifetime)
        lt.time -= delta
        if lt.time <= 0:
            cmd.remove_entity(entity)                     # queued
        if should_upgrade(entity):
            cmd.remove_component(entity, C_OldState)      # queued
            cmd.add_component(entity, C_NewState.new())   # queued
    # auto-executes after system completes (FlushMode.PER_SYSTEM default)
```

### Relationships

```gdscript
# Add a relationship
entity.add_relationship(Relationship.new(R_ChildOf.new(), parent_entity))

# Query entities with a relationship
var children = ECS.world.query.with_relationship([
    Relationship.new(R_ChildOf.new(), parent_entity)
]).execute()

# Wildcard query (any target)
var has_allies = entity.has_relationship(Relationship.new(R_AllyTo.new(), null))

# Remove with limit
entity.remove_relationship(Relationship.new(R_Buff.new(), null), 1)   # remove 1
entity.remove_relationship(Relationship.new(R_Effect.new(), null))    # remove all
```

### System Groups & Scene Architecture

```
Main.tscn
+-- World (World node)
+-- Systems (Node)
|   +-- input (SystemGroup)
|   |   +-- PlayerControlsSystem
|   +-- gameplay (SystemGroup)
|   |   +-- HealthSystem
|   |   +-- DeathSystem
|   +-- physics (SystemGroup)
|   |   +-- MovementSystem
|   |   +-- CollisionSystem
|   +-- run-last (SystemGroup)
|       +-- PendingDeleteSystem
+-- Entities (Node — spawned entities go here)
+-- Level (Node3D — level geometry)
```

SystemGroup nodes auto-assign their name as the `group` property of child Systems.

## Reference Files

Read the relevant file when you need detailed API beyond this quick reference:

| Need | File | When to read |
|------|------|-------------|
| Entity lifecycle, prefabs, spawning | [`references/entity.md`](references/entity.md) | Creating entities, scene prefab setup, on_ready/on_destroy |
| Component design, @export patterns | [`references/component.md`](references/component.md) | Defining new components, constructor patterns |
| System impl, CommandBuffer, timers | [`references/system.md`](references/system.md) | Writing systems, sub_systems, tick rates, deps, parallel |
| World setup, entity management | [`references/world.md`](references/world.md) | World init, add/remove entities/systems, process groups |
| Queries, Relationships, Observers | [`references/query.md`](references/query.md) | Complex queries, entity linking, reactive systems |
| Debug tools, profiling | [`references/debug.md`](references/debug.md) | Runtime inspection, editor debugger, performance |
| Naming, file org, scene architecture | [`references/patterns.md`](references/patterns.md) | Project structure, cross-cutting patterns, ECS_DESIGN adaptation |

## MANDATORY: Read gotchas.md Before Writing ECS Code

**Before writing ANY gecs code**, read [`gotchas.md`](gotchas.md). It contains 19 hard-won pitfalls with wrong→correct code examples.

**If you hit a compile or runtime error**, check `gotchas.md` first — most ECS errors are covered there.

## Critical Gotchas (summary)

1. **All `@export` properties MUST have default values** — Godot errors on Resource export without defaults
2. **`get_component()` takes the CLASS, not an instance** — `entity.get_component(C_Health)` not `entity.get_component(health_instance)`
3. **Never put logic in Components** — all behavior belongs in Systems
4. **Use `cmd` for structural changes during iteration** — direct add/remove during `process()` causes entity skipping
5. **Avoid `with_group()` in queries** — ~50x slower than `with_all([C_Tag])` due to SceneTree traversal. Use tag components instead
6. **`define_components()` must return fresh `.new()` instances** — returning cached/shared instances causes state leakage between entities
7. **Entity extends Node, NOT Node2D** — `entity.position` does NOT work. Store position in a `C_Position` component. See gotchas.md G1
8. **Component `_init()` must have default params** — `func _init(v: float = 0.0)` so `Component.new()` works for duplication
9. **Components are inaccessible before `add_entity()`** — `get_component()` returns null until entity enters scene tree. See gotchas.md G2
10. **Never call `system.process()` directly in tests** — causes Array[Entity] type error + CommandBuffer not flushed. **Never write `test_system_has_query`** — `q` is null outside World. See G10, G14
11. **`add_system()` second param is `bool`, not group name** — set `system.group` before `add_system()`. See G15
12. **`world.process(delta)` without group skips grouped systems** — must pass group name. See G16
13. **NodePath `@export` in `.tscn` unreliable for World** — set `entity_nodes_root`/`system_nodes_root` in `_init()`. See G17
14. **Area2D overlap data stale in `_process`** — overlap systems must run in `physics` group. See G18
15. **`:=` type inference fails with ternary + null** — use explicit type annotation. See G19
Pliki w paczce (11)
  • SKILL.md 11 KB
  • gotchas-examples.md 7 KB
  • gotchas.md 4 KB
  • evals/evals.json 4 KB
  • references/component.md 6 KB
  • references/debug.md 7 KB
  • references/entity.md 9 KB
  • references/patterns.md 12 KB
  • references/query.md 12 KB
  • references/system.md 13 KB
  • references/world.md 9 KB

Wersje

W bazie nie ma innych skilli o nazwie gecs.

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

Pobrania w ostatnich 30 dniach: 2 · ranking

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

Podobne skille

  • 100ecs-system-and-component-design
    Pomaga projektować systemy i komponenty w Arch ECS: zapytania, czyszczenie, singletony, testy oraz przegląd użycia World, Entity i komponentów.
  • 100project-scaffold
    Generuje nowy projekt gry w Godot ze standardową strukturą ECS i narzędziami, gdy plan gry jest zatwierdzony albo podano nazwę gry i gatunek.
  • 100ecs-guide
    Prowadzi przez projektowanie Entity-Component-System zorientowanego na dane: magazyn archetypów, ciągłe tablice komponentów, systemy filtrujące i synchronizację stanu z rendererem lub fizyką.
  • 90entity-component-system
    Modeluje obiekty gry jako encje z komponentami danych przetwarzanymi przez systemy i pokazuje, kiedy złożoność ECS się opłaca, przy architekturze gier i ucieczce od głębokich hierarchii dziedziczenia.
  • 100godot-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.
  • 100godot-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.

Uwagi i zgłoszenia

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