GECS - Entity Component System
Entity Component System for Godot 4.x
Build scalable, maintainable games with clean separation of data and logic. GECS integrates seamlessly with Godot's node system while providing powerful query-based entity filtering.
Key Features
- 🎯 Godot Integration - Works with nodes, scenes, and editor
- 🚀 High Performance - Optimized queries with automatic caching
- 🔧 Flexible Queries - Find entities by components, relationships, or properties
- 🔍 Debug Viewer - Real-time inspection and performance monitoring
- 📦 Editor Support - Visual component editing and scene integration
- 🎮 Battle Tested - Used in games being actively developed
- 🌐 Multiplayer - GECS goes Multiplayer! Check out the GECS Network Module
Requirements
Godot 4.x (tested with 4.6+)
Installation
Option A: Godot Asset Library
Search for "GECS" in the Godot editor AssetLib tab and click Install.
Option B: Manual Copy
Download the release zip, copy addons/gecs/ into your project, then enable the plugin in Project Settings > Plugins.
Option C: Git Submodule
git submodule add -b release-v6.8.1 https://github.com/csprance/gecs.git addons/gecs
Then enable the plugin in Project Settings > Plugins.
Quick Start
# All component properties need a default value or Godot will error on export
# Pattern 1: @export var with default (no constructor needed)
class_name C_Health extends Component
@export var max_health: int = 100
@export var current_health: int = 100
# Pattern 2: _init() with parameter AND a default on the property
class_name C_Velocity extends Component
@export var direction: Vector3 = Vector3.ZERO
func _init(v: Vector3 = Vector3.ZERO) -> void:
direction = v
# Create entities and add components
var player = Entity.new()
player.add_component(C_Health.new())
player.add_component(C_Velocity.new(Vector3(5, 0, 0)))
var target = Entity.new()
target.add_component(C_Health.new())
target.add_component(C_Velocity.new(Vector3(-5, 0, 0)))
# Add entities to the world
ECS.world.add_entity(player)
ECS.world.add_entity(target)
# Add relationships between entities
player.add_relationship(Relationship.new(C_AllyTo.new(), target))
# Systems define which entities to process
class_name VelocitySystem 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) as C_Velocity
entity.position += vel.direction * delta
# Register the system and start processing
ECS.world.add_system(VelocitySystem.new())
func _process(delta: float) -> void:
ECS.process(delta)
Quick Start Steps
- Install: Download to
addons/gecs/and enable in Project Settings - Follow Guide: Get your first ECS project running in 5 minutes →
- Learn More: Understand core ECS concepts →
Complete Documentation
All documentation is located in the addon folder:
→ Complete Documentation Index
Quick Navigation
- Getting Started - Build your first ECS project (5 min)
- Core Concepts - Understand Entities, Components, Systems, Relationships (20 min)
- Best Practices - Write maintainable ECS code (15 min)
- Troubleshooting - Solve common issues quickly
Advanced Features
- Component Queries - Advanced property-based filtering
- Relationships - Entity linking and associations
- Observers - Reactive systems for component changes
- Performance Optimization - Make your games run fast
Example Games
- GECS-101 - A simple example
- Zombies Ate My Neighbors - Action arcade game
- Breakout Clone - Classic brick breaker
Community
- Discord: Join our community
- Issues: Report bugs or request features
- Discussions: Ask questions and share projects
License
MIT - See LICENSE for details.
GECS is provided as-is. If it breaks, you get to keep both pieces.