https://github.com/csprance/gecs

GECS

A lightweight ECS framework for Godot 4.x providing a data-driven architecture: When developing games or complex applications in Godot, organizing logic can be a challenge. An Entity Component System (ECS) offers a flexible, data-oriented paradigm that simplifies combining entities and their behaviors. GECS (Godot Entity Component System) is a lightweight ECS framework for Godot designed to fit seamlessly into Godot 4.x. This post highlights what ECS is, why it matters, and how GECS applies these concepts in Godot.

GECS helps keep your logic modular by separating data (in components) from behaviors (in systems), reducing complexity.

Why ECS?

Clearly divides data and logic: Traditional object-oriented approaches often bundle data and behavior together. Over time, that can become unwieldy or force complicated inheritance structures. ECS keeps data (components) separate from logic (systems). It revolves around three pillars:

1. Entities – Think of them as IDs or “slots” for your game objects.
2. Components – Pure data objects that define a piece of state (e.g., velocity, health).
3. Systems – Logic that processes all entities with specific components.

This pattern simplifies orginization and collaboration among team members and future refactoring. This structure makes it easier to add, remove, or modify behaviors, since everything is modular. Systems only act upon relevant components. Entities can freely change their makeup without breaking the overall design.

What Is GECS?

An extension of the Godot workflow giving you:

• Integration with Godot nodes (you can treat Entities as scenes and Components as resources).
• A World to manage all Entities and Systems.
• An ECS singleton to coordinate queries and processing.
• QueryBuilders for comprehensive entity queries, including property-based filtering.
• Relationship management that lets you define complex associations among entities.

Entities become merely data containers, while systems operate on them based on component queries.

Relationship-Driven Queries

Use relationships to link entities: GECS extends the ECS idea with relationship objects, letting you define links (e.g., “likes,” “belongs to,” “is attacking”) between two entities for easier dynamic querying.

For example, a “ParentOf” relationship can simplify hierarchical access in your game.

Core Concepts

1. Entity – Node with multiple component resources
2. Component – Resource storing data
3. System – Node with queries to process matched entities
4. World – Node owning entities and systems
5. ECS Singleton – Central manager to run queries or process frames

1. Entities

Entities are Godot nodes extending Entity.gd. They hold multiple components and can emit signals when components or relationships are added or removed.

2. Components

Components are data-only resources that hold properties. They do not contain game logic. For example, a Transform component might store a position, rotation, or scale.

3. Systems

Systems are nodes extending System.gd. They define a query (e.g., “which entities do I care about?”) and a process function that operates on those entities.

4. World

The central manager that holds all Entities and Systems. You typically place a World node in a scene, and it automatically handles adding or removing your Entities and Systems.

5. ECS Singleton

The ECS autoload offers global access to the active World. It can be used to process each frame (or physics frame) and run queries.

6. QueryBuilder

Queries can be built using a fluent API to find entities with required components or exclude those with certain components or relationships.

7. Relationships

GECS extends the ECS idea with relationship objects, letting you define links (e.g., “likes,” “belongs to,” “is attacking”) between two entities for easier dynamic querying.

Example Workflow

1. Create Entities and add components via the editor or code
2. Add Entities to the World
3. Create Systems that define queries and implement process
4. Add Systems to the same World
5. Call ECS.process(delta) each frame to update all systems

Next Steps

Explore how relationships can link multiple entities and how advanced queries filter entities by property data, giving you precise control over your game’s logic. This post serves as an overview of how ECS concepts map into Godot with GECS. Future posts will explore each feature—creating components, building queries, handling relationships, and more. Stay tuned!

GECS on Github

https://github.com/csprance/gecs