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
• 🔍 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.x (tested with 4.6+)

Search for "GECS" in the Godot editor AssetLib tab and click Install.

Download the release zip, copy addons/gecs/ into your project, then enable the plugin in Project Settings > Plugins.

git submodule add -b release-v6.8.1 https://github.com/csprance/gecs.git addons/gecs

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)

1. Install: Download to addons/gecs/ and enable in Project Settings
2. Follow Guide: Get your first ECS project running in 5 minutes →
3. 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.