godot-shader-experiments/addons/gecs/docs/PERFORMANCE_TESTING.md

GECS Performance Testing Guide

Framework-level performance testing for GECS developers

This document explains how to run and interpret the GECS performance tests. This is primarily for framework developers and contributors who need to ensure GECS maintains high performance.

For game developers: See Performance Optimization Guide for optimizing your games.

📋 Prerequisites

• GECS framework development environment
• gdUnit4 testing framework
• Godot 4.x
• Test system dependencies: s_performance_test.gd and s_complex_performance_test.gd in tests/systems/

🎯 Overview

The GECS performance test suite provides comprehensive benchmarking for all critical ECS operations:

• Entity Operations: Creation, destruction, world management
• Component Operations: Addition, removal, lookup, indexing
• Query Performance: All query types, caching, complex scenarios
• System Processing: Single/multiple systems, different scales
• Array Operations: Optimized set operations (intersect, union, difference)
• Integration Tests: Realistic game scenarios and stress tests

🚀 Running Performance Tests

Prerequisites

Set the GODOT_BIN environment variable to your Godot executable:

# Windows
setx GODOT_BIN "C:\path\to\godot.exe"

# Linux/Mac
export GODOT_BIN="/path/to/godot"

Running Individual Test Suites

# Entity performance tests
addons/gdUnit4/runtest.cmd -a res://addons/gecs/tests/performance/performance_test_entities.gd

# Component performance tests
addons/gdUnit4/runtest.cmd -a res://addons/gecs/tests/performance/performance_test_components.gd

# Query performance tests
addons/gdUnit4/runtest.cmd -a res://addons/gecs/tests/performance/performance_test_queries.gd

# System performance tests
addons/gdUnit4/runtest.cmd -a res://addons/gecs/tests/performance/performance_test_systems.gd

# Array operations performance tests
addons/gdUnit4/runtest.cmd -a res://addons/gecs/tests/performance/performance_test_arrays.gd

# Integration performance tests
addons/gdUnit4/runtest.cmd -a res://addons/gecs/tests/performance/performance_test_integration.gd

Running Complete Performance Suite

# Run all performance tests with comprehensive reporting
addons/gdUnit4/runtest.cmd -a res://addons/gecs/tests/performance/performance_test_master.gd

# Quick smoke test to verify basic performance
addons/gdUnit4/runtest.cmd -a res://addons/gecs/tests/performance/performance_test_master.gd::test_performance_smoke_test

📊 Test Scales

The performance tests use three different scales:

• SMALL_SCALE: 100 entities (for fine-grained testing)
• MEDIUM_SCALE: 1,000 entities (for typical game scenarios)
• LARGE_SCALE: 10,000 entities (for stress testing)

⏱️ Performance Thresholds

The tests include automatic performance threshold checking:

Entity Operations

• Create 100 entities: < 10ms
• Create 1,000 entities: < 50ms
• Add 1,000 entities to world: < 100ms

Component Operations

• Add components to 100 entities: < 10ms
• Add components to 1,000 entities: < 75ms
• Component lookup in 1,000 entities: < 30ms

Query Performance

• Simple query on 100 entities: < 5ms
• Simple query on 1,000 entities: < 20ms
• Simple query on 10,000 entities: < 100ms
• Complex queries: < 50ms

System Processing

• Process 100 entities: < 5ms
• Process 1,000 entities: < 30ms
• Process 10,000 entities: < 150ms

Game Loop Performance

• Realistic game frame (1,000 entities): < 16ms (60 FPS target)

📈 Understanding Results

Performance Metrics

Each test provides:

• Average Time: Mean execution time across multiple runs
• Min/Max Time: Best and worst execution times
• Standard Deviation: Consistency of performance
• Operations/Second: Throughput measurement
• Time/Operation: Per-item processing time

Result Files

Performance results are saved to res://reports/ with timestamps:

• entity_performance_results.json
• component_performance_results.json
• query_performance_results.json
• system_performance_results.json
• array_performance_results.json
• integration_performance_results.json
• complete_performance_results_[timestamp].json

Interpreting Results

Good Performance Indicators:

• ✅ High operations/second (>10,000 for simple operations)
• ✅ Low standard deviation (consistent performance)
• ✅ Linear scaling with entity count
• ✅ Query cache hit rates >80%

Performance Warning Signs:

• ⚠️ Tests taking >50ms consistently
• ⚠️ Exponential time scaling with entity count
• ⚠️ High standard deviation (inconsistent performance)
• ⚠️ Cache hit rates <50%

🔄 Regression Testing

To monitor performance over time:

1. Establish Baseline: Run the complete test suite and save results
2. Regular Testing: Run tests after significant changes
3. Compare Results: Use the master test suite's regression checking
4. Set Alerts: Monitor for >20% performance degradation

🎯 Optimization Areas

Based on test results, focus optimization efforts on:

1. Query Performance: Most critical for gameplay
2. Component Operations: High frequency operations
3. Array Operations: Core performance building blocks
4. System Processing: Frame-rate critical
5. Memory Usage: Large-scale scenarios

⚠️ Common Issues

Missing Dependencies

If tests fail with missing class errors, ensure these files exist:

• addons/gecs/tests/systems/s_performance_test.gd
• addons/gecs/tests/systems/s_complex_performance_test.gd

gdUnit4 Setup

Beyond setting GODOT_BIN, ensure:

• gdUnit4 plugin is enabled in project settings
• All test component classes are properly defined

🔧 Custom Performance Tests

To create custom performance tests:

1. Extend PerformanceTestBase
2. Use the benchmark() method for timing
3. Set appropriate performance thresholds
4. Include in the master test suite

Example:

extends PerformanceTestBase

func test_my_custom_operation():
    var my_test = func():
        # Your operation here
        pass

    benchmark("My_Custom_Test", my_test)
    assert_performance_threshold("My_Custom_Test", 10.0, "Custom operation too slow")

📚 Related Documentation

• Performance Optimization - User-focused optimization guide
• Best Practices - Write performant ECS code
• Core Concepts - Understanding the ECS architecture

---

This performance testing framework ensures GECS maintains high performance as the codebase evolves. It's a critical tool for framework development and optimization efforts.