GECS v3.8.0 - Performance Boost & Documentation Overhaul

GECS v3.8.0 - Performance Boost & Documentation Overhaul

🎯 Major Improvements

⚡ Performance Optimizations

• 1.58x Query Performance Boost - Implemented QueryBuilder pooling and world-level query caching
• Fixed Component Replacement Bug - Entities no longer processed twice when components are replaced
• Array Operations Performance Revolution - 4.6x faster intersection, 2.6x faster difference, 1.8x faster union operations
• Memory Leak Prevention - Better resource management and cleanup

📚 Complete Documentation Restructure

• User-Friendly Learning Path - Progressive guides from 5-minute tutorial to advanced optimization
• Comprehensive Guides - New Getting Started, Best Practices, Performance, and Troubleshooting guides
• Addon-Centric Documentation - All docs now ship with the addon for better distribution
• Consistent Naming Conventions - Standardized C*, s*, e*, o* prefixes throughout
• Community Integration - Discord links throughout for support

🧪 Enhanced Testing Framework

• Performance Test Suite - Comprehensive benchmarking for all ECS operations
• Regression Detection - Automated performance threshold monitoring
• Better Test Organization - Restructured tests into logical groups (core/, performance/)

🔧 Technical Changes

Core Framework

• QueryBuilder Pooling - Reduced object creation overhead
• World-Level Query Caching - Hash-based caching with automatic invalidation
• Component Replacement Fix - Proper removal before replacement in entity.gd:97-111
• Array Performance Revolution - Algorithmic improvements from O(n²) to O(n) complexity using dictionary lookups

Documentation Structure

• Root README.md - Clean overview pointing to addon documentation
• addons/gecs/README.md - Complete documentation index for distribution
• addons/gecs/docs/ - All user guides properly organized
• Progressive Learning Path - 5min → 20min → 60min guide progression

Testing & Quality

• Performance Baselines - Established benchmarks for regression detection
• Comprehensive Coverage - Entity, Component, Query, System, and Integration tests
• Cross-Platform Compatibility - Improved test reliability

📈 Performance Metrics

Array Operations Benchmarks

• Intersection Operations: 4.6x faster (0.888ms → 0.194ms)
• Difference Operations: 2.6x faster (0.361ms → 0.141ms)
• Union Operations: 1.8x faster (0.372ms → 0.209ms)
• No Overlap Scenarios: 4.2x faster (0.629ms → 0.149ms)

Algorithmic Improvements

• O(n²) → O(n) Complexity: Replaced Array.has() with Dictionary lookups
• Smart Size Optimization: Intersect operations use smaller array for lookup table
• Uniqueness Tracking: Union operations prevent duplicates with dictionary-based deduplication
• Consistent Optimization Pattern: All array operations use same high-performance approach

Framework Performance

• Query Caching: 1.58x speedup for repeated queries
• Component Operations: Reduced double-processing bugs
• Memory Usage: Better cleanup and resource management
• Test Suite: Comprehensive benchmarking with automatic thresholds

🎮 For Game Developers

• Dramatically Faster Games - Up to 4.6x performance improvement in entity filtering and complex queries
• Better Documentation - Clear learning path from beginner to advanced
• Consistent Patterns - Standardized naming and organization conventions
• Community Support - Discord integration for help and discussions

🔄 Migration Notes

This is a backward-compatible update. No breaking changes to the API.

• Existing projects will automatically benefit from performance improvements
• Documentation has been reorganized but all links remain functional
• Test structure improved but does not affect game development

🌟 Community

• Discord: Join our community
• Documentation: Complete guides
• Issues: Report bugs or request features

---

Full Changelog: v3.7.0...v3.8.0

The v3.8.0 version reflects a significant minor release with substantial improvements to performance, documentation, and testing while maintaining full backward compatibility with the existing v3.x API.

3.7.0 - Caching/Debugging

2025‑05‑18

TL;DR

• Observers: event‑driven world monitoring with fine‑grained query filters.

• Debugger: first‑class hooks for live inspection of worlds, entities, and systems.

• Signals Galore: property_changed, world_changed, world_exited, plus per‑component change dispatch.

• System Ordering: topological sort and new Runs enum for deterministic execution.

• Performance: cached queries, cleaner logging, faster test‑suite.

• Docs & Assets: pause‑game workflow in README, updated Discord invite, new observer.svg.

---

✨ Highlights

Area	What changed	Why it matters
Core API	Observer class, World.observers list, automatic component‑change signals	Build reactive features without polling
Signals	Component.property_changed, _ECS.world_changed, _ECS.world_exited	Easier external tooling & analytics
System Exec	Runs enum + topological sort across system groups	Stable, declarative ordering
Debugger	Debugger stub, plugin wiring, conditional logging via GECSLogger.disabled	Step through ECS flow in‑engine
QueryBuilder	Result‑level caching & faster component processing	Less GC churn, fewer allocations
Testing	Consistent GdUnitSceneRunner usage, new array‑extension test‑suite	Higher coverage, clearer failures
Quality of Life	observer.svg baked into import config, formatted project_settings	Polished editor experience

---

🗂 Changelog (May 18 only)

• Add observer.svg asset and import rule

• World: observer list, component‑change relays, caching, debugger hooks

• Debugger: baseline implementation & plugin integration

• Tests: unified style, new array‑extensions, removed dead code

• Implement topological sort for grouped systems

• Component: property_changed signal

• _ECS core: world_changed, world_exited signals; improved world lifecycle

• Entity: stricter signal types, tidy formatting, better component API

• GECSLogger: toggleable output, clearer levels

• QueryBuilder: internal cache, tighter execution path

• Numerous formatting, UID housekeeping, footer cleanup

• Documentation: pause section, updated Discord link

(Commits: ba5fe2aa, f4592bd3, f35a5292, bf440125, 66d842c7, 0347e259, plus 15 others on 2025‑05‑18.)

---

📈 What’s Next

• Debugger UI

---

**Full Changelog**: https://github.com/csprance/gecs/compare/3.6.0...3.7.0

3.6.0 Pausing

1. Pause Functionality in Systems

   • Added a paused variable inside each System node, along with a check in _handle(delta) that skips updates if paused is true.
   • Added a new update_pause_state(paused: bool) method in World that updates each system’s paused status based on process modes, granting finer control over which systems continue or stop processing when the game is paused.

2. Minor Adjustments

   • Rearranged or slightly refactored some methods in ecs.gd (e.g., moving _on_world_exited()).
   • Revised initialization logic in Entity to call an _initialize() method from _ready().
   • Updated version in plugin.cfg from 3.5.1 to 3.6.0.
   • Performed minor housekeeping in QueryBuilder, entity.gd, and world.gd (such as reordering functions, updating logs, or reorganizing comment blocks).

Full Changelog: 3.5.0...3.6.0

3.5.1

Full Changelog: 3.5.0...3.5.1-rc1

3.5.0

• upgrade to godot 4.4
• add with_group and without_group to query builder class
• import/export world functionality to serliaze entities and reserialize them to save/load games
• entities are tools
• static query script template

Full Changelog: 3.4.1...3.5.0

3.5.1

Full Changelog: 3.5.0...3.5.1

3.4.1

Full Changelog: 3.3.0...3.4.0

Full Changelog: 3.4.0...3.4.1

3.3.0

Full Changelog: 3.2.0...3.3.0

3.2.0

Full Changelog: 3.1.0...3.2.0

3.1.2

Fix a small bug with the combine query
Full Changelog: 3.1.0...3.1.2