basic ECS spawner
This commit is contained in:
216
addons/gecs/docs/PERFORMANCE_TESTING.md
Normal file
216
addons/gecs/docs/PERFORMANCE_TESTING.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# 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](PERFORMANCE_OPTIMIZATION.md) 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:
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
setx GODOT_BIN "C:\path\to\godot.exe"
|
||||
|
||||
# Linux/Mac
|
||||
export GODOT_BIN="/path/to/godot"
|
||||
```
|
||||
|
||||
### Running Individual Test Suites
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```gdscript
|
||||
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](PERFORMANCE_OPTIMIZATION.md)** - User-focused optimization guide
|
||||
- **[Best Practices](BEST_PRACTICES.md)** - Write performant ECS code
|
||||
- **[Core Concepts](CORE_CONCEPTS.md)** - 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._
|
||||
Reference in New Issue
Block a user