GECS

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.

Gecs

Install / Use

README