godot-shader-experiments/addons/gecs

GECS Documentation

Complete documentation for the Godot Entity Component System

Lightning-fast Entity Component System for Godot 4.x - Build scalable, maintainable games with clean separation of data and logic.

Discord: Join our community

📚 Learning Path

🚀 Getting Started (5-10 minutes)

• Getting Started Guide - Build your first ECS project in 5 minutes

🧠 Core Understanding (20-30 minutes)

• Core Concepts - Deep dive into Entities, Components, Systems, and Relationships
• Component Queries - Advanced property-based entity filtering

🛠️ Practical Application (30-60 minutes)

• Best Practices - Write maintainable, performant ECS code
• Relationships - Link entities together for complex interactions
• Observers - Reactive systems that respond to component changes
• Serialization - Save and load game state and entities

⚡ Optimization & Advanced (As needed)

• Debug Viewer - Real-time debugging and performance monitoring
• Performance Optimization - Make your games run fast and smooth
• Troubleshooting - Solve common issues quickly

🔬 Framework Development (For contributors)

• Performance Testing - Framework-level performance testing guide

📖 Documentation by Topic

Entity Component System Basics

Topic	Document	Description
Introduction	Getting Started	First ECS project tutorial
Architecture	Core Concepts	Complete ECS architecture overview
Data Patterns	Best Practices	Component and system design patterns

Advanced Features

Topic	Document	Description
Entity Linking	Relationships	Connect entities with relationships
Property Filtering	Component Queries	Query entities by component data
Event Systems	Observers	React to component changes
Data Persistence	Serialization	Save/load entities and game state

Optimization & Debugging

Topic	Document	Description
Debug Viewer	Debug Viewer	Real-time debugging and inspection
Performance	Performance Optimization	Game performance optimization
Debugging	Troubleshooting	Common problems and solutions
Testing	Performance Testing	Framework performance testing

🎯 Quick References

Naming Conventions

• Entities: ClassCase class, e_entity_name.gd file
• Components: C_ComponentName class, c_component_name.gd file
• Systems: SystemNameSystem class, s_system_name.gd file
• Observers: ObserverNameObserver class, o_observer_name.gd file

Essential Patterns

# Entity creation
var player = Player.new()
player.add_component(C_Health.new(100))
player.add_component(C_Position.new(Vector2.ZERO))
ECS.world.add_entity(player)

# System queries
func query(): return q.with_all([C_Health, C_Position])
func process(entities: Array[Entity], components: Array, delta: float): # Unified signature
# Use .iterate([Components]) for batch component array access

# Relationships
entity.add_relationship(Relationship.new(C_Likes.new(), target_entity))
var likers = ECS.world.query.with_relationship([Relationship.new(C_Likes.new(), entity)]).execute()

# Component queries
var low_health = ECS.world.query.with_all([{C_Health: {"current": {"_lt": 20}}}]).execute()

# Order Independence: with_all/with_any/with_node component order does not affect matching or caching.
# The framework normalizes component sets internally so these yield identical results:
# ECS.world.query.with_all([C_Health, C_Position])
# ECS.world.query.with_all([C_Position, C_Health])
# Cache keys and archetype matching are order-insensitive.

# Serialization
var data = ECS.serialize(ECS.world.query.with_all([C_Persistent]))
ECS.save(data, "user://savegame.tres", true)  # Binary format
var entities = ECS.deserialize("user://savegame.tres")

🎮 Example Projects

Basic examples are included in each guide. For complete game examples, see:

• Simple Ball Movement - Getting Started Guide
• Combat Systems - Relationships Guide
• UI Synchronization - Observers Guide

🆘 Getting Help

1. Check documentation - Most questions are answered in the guides above
2. Review examples - Each guide includes working code examples
3. Try troubleshooting - Troubleshooting Guide covers common issues
4. Community support - Join our Discord for discussions and questions

🔄 Documentation Updates

This documentation is actively maintained. If you find errors or have suggestions:

• Report issues for bugs or unclear documentation
• Suggest improvements for better examples or explanations
• Contribute examples showing real-world usage patterns

---

Ready to start? Begin with the Getting Started Guide and build your first ECS project in just 5 minutes!

GECS makes building scalable, maintainable games easier by separating data from logic and providing powerful query systems for entity management.