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.
- 🎯 Godot Integration - Works with nodes, scenes, and editor
- 🚀 High Performance - Optimized queries with automatic caching
- 🔧 Flexible Queries - Find entities by components, relationships, or properties
- 📦 Editor Support - Visual component editing and scene integration
- 🎮 Battle Tested - Used in games being actively developed
# Create entities with components
var player1 = Entity.new()
player1.add_component(C_Health.new(100))
player1.add_component(C_Velocity.new(Vector2(5, 0)))
var player2 = Entity.new()
player2.add_component(C_Health.new(100))
player2.add_component(C_Velocity.new(Vector2(-5, 0)))
# Add entity to the world
ECS.world.add_entities([player1, player2])
# Add relationships to entities
# Player 1 is an Ally to Player 2
player1.add_relationship(Relationship.new(C_AllyTo.new(), player2))
# Player 2 is a little suspicious of Player 1
player2.add_relationship(Relationship.new(C_SuspiciousOf.new(), player1))
# Components define data only
class_name C_Velocity extends Component
@export var velocity := Vector3.ZERO
# Systems process entities with specific components
class_name VelocitySystem extends System
# Systems define queries to select entities and iterate their components
func query() -> QueryBuilder:
return q.with_all([C_Velocity, C_Transform]).iterate([C_Velocity, C_Transform])
# Systems implement process to handle selected entities
func process(entities: Array[Entity], components: Array, delta: float) -> void:
var c_velocities = components[0] # C_Velocity (first in iterate)
var c_transforms = components[1] # C_Transform (second in iterate)
# Process all velocity and transform components on entities that match query
for i in entities.size():
var c_velocity := c_velocities[i] as C_Velocity
var c_transform := c_transforms[i] as C_Transform
c_transform.transform.global_position += c_velocity.velocity * delta
# Add systems to the world
ECS.world.add_system(VelocitySystem.new())
# Progress the world and call all systems
ECS.world.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. 😄