Entity Component System for Godot 4.6+
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.
- 🎯 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
Godot 4.6 or newer. (Versions up to and including 4.5 cannot parse the per-system performance monitor code introduced in GECS v8.0.0.)
git submodule add -b release-v8.0.0 https://github.com/csprance/gecs.git addons/gecsDownload the release zip, copy addons/gecs/ into your project, then enable the plugin in Project Settings > Plugins.
Search for "GECS" in the Godot editor AssetLib tab and click Install.
Then enable the plugin in Project Settings > Plugins.
# 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)- 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 →
All documentation is located in the addon folder:
→ Complete Documentation Index
- 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
- Component Queries - Advanced property-based filtering
- Relationships - Entity linking and associations
- Observers - Reactive systems for component changes
- Performance Optimization - Make your games run fast
- GECS-101 - A simple example
- Zombies Ate My Neighbors - Action arcade game
- Breakout Clone - Classic brick breaker
- Discord: Join our community
- Issues: Report bugs or request features
- Discussions: Ask questions and share projects
MIT - See LICENSE for details.
GECS is provided as-is. If it breaks, you get to keep both pieces.