GECS - Godot Entity Component System

A lightweight and performant ECS framework that integrates seamlessly with Godot 4.x, built to leverage Godot’s node system. It supports:

- Full integration with Godot’s node system
- Query-based filtering of entities with optimized component indexing
- System groups for organized processing
- Component resources that work in the editor
- Straightforward setup with automatic node management
- Clear examples (Zombies Ate My Neighbors, a 2D Breakout clone)

OVERVIEW

GECS follows the Entity Component System (ECS) pattern:

- Entity: A container (a node extending Entity) representing an object.
- Component: A data container resource (extends Component) with properties but no logic.
- System: A node (extends System) that defines a query for relevant entities and the logic to run on them.
- World: A central node (extends World) that manages entities and systems.

FEATURES

- Components: Simple resources, easy to edit in the Godot inspector.
- Entities: Node scenes that extend Entity and automatically synchronize component data.
- Systems: Nodes that define queries (for example using with\_all, with\_any) and process matching entities.
- System Groups: Specify a group name such as "physics" or "gameplay" to organize and process systems at different times.
- ECS Singleton: Global access to your current World, allowing you to call ECS.process(delta, group).
- Relationship Support: Use relationships as specialized resources to link entities.
- Advanced Queries: Use with\_relationship, with\_reverse\_relationship, and various conditions to refine your entity matching.

WHY USE GECS

- Improved code organization and maintainability
- Clean separation of data (components) and logic (systems)
- Intuitive queries for selecting and managing entities
- Works naturally with Godot’s scene and node structure

GETTING STARTED

1. Place the GECS addon in your project’s addons folder.
2. Enable the plugin in Project Settings > Plugins.
3. Ensure ECS.gd is autoloaded (done automatically when enabling the plugin).
4. Create your own entities, components, and systems.
5. Place a World node, attach your systems and entities, then call ECS.process(delta, group) as needed.

SIMPLE STEPS

- Create Components, for example Velocity or Bounce, each with exported properties.
- Create Entities, adding the desired components in the inspector.
- Create Systems, define queries such as with\_all, and implement the logic.
- Add Systems to your World node, optionally setting a group.
- Process them via ECS.process(delta, "group\_name").

USE CASES

- 2D and 3D games needing modular and scalable code
- Clean separation of concerns in larger projects
- Editor-based design of components without heavy scripting
- Simplified debugging of component data

SPECIAL FEATURES

- Relationship-based queries for advanced linking of entities
- System groups for controlling update order
- Resource-based components that can be instanced or shared
- Editor support for exporting component properties

CONCLUSION

GECS streamlines development with a concise Entity Component System approach that fits naturally into Godot’s node structure. Build maintainable, modular games with flexible queries, reusable data containers, and powerful system organization.