Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/msitarzewski/thezonexr

The primary target is WebXR gameplay from a tank cockpit perspective, with desktop mode acting as the fast iteration environment for movement, aiming, combat, and battlefield flow.
https://github.com/msitarzewski/thezonexr

Last synced: 30 days ago
JSON representation

The primary target is WebXR gameplay from a tank cockpit perspective, with desktop mode acting as the fast iteration environment for movement, aiming, combat, and battlefield flow.

Awesome Lists containing this project

README 

          
# Battlezone XR Performance Monitoring System



A comprehensive WebXR performance monitoring and optimization framework designed to ensure 90fps comfort targets and <512MB memory constraints across Apple Vision Pro, Meta Quest, and desktop platforms.



## Features



### 📊 Real-Time Performance Monitoring

- **Frame Rate Tracking**: Continuous 90fps monitoring with frame drop detection

- **Motion-to-Photon Latency**: Sub-20ms latency measurement and optimization

- **Memory Usage Monitoring**: 512MB constraint enforcement with predictive alerts

- **Comfort Metrics**: Motion sickness risk assessment and prevention



### 🎯 Automatic Optimization Framework

- **Dynamic LOD System**: 4-level Level of Detail with distance-based culling

- **Asset Management**: Intelligent caching with usage-based cleanup

- **Garbage Collection**: Proactive memory management and leak prevention

- **Draw Call Optimization**: Render pipeline efficiency monitoring



### 🔧 Platform-Specific Optimization

- **Apple Vision Pro**: Foveated rendering, thermal management, 90fps targeting

- **Meta Quest**: Aggressive optimization, mobile-specific rendering, battery awareness

- **Desktop**: High-quality fallback with development tools integration

- **Cross-Platform**: Unified API with platform-specific adaptations



### 📈 Development Dashboard

- **Real-Time Metrics**: Live performance graphs and statistics

- **Comfort Tracking**: User experience monitoring and alerts

- **Session Analytics**: Comprehensive performance reporting

- **Test Integration**: Automated performance validation suite



## Quick Start



### Basic Integration



```javascript

import { createPerformanceSystem } from './src/performance/index.js';



// Initialize performance system

const performanceManager = await createPerformanceSystem(scene, {

  targetFPS: 90,

  memoryLimit: 512 * 1024 * 1024, // 512MB

  autoOptimize: true

});



// XR session integration

renderer.xr.addEventListener('sessionstart', async () => {

  const session = renderer.xr.getSession();

  await performanceManager.startXRSession(session);

});

```



### A-Frame Integration



```html



  



```



```javascript

import { integrateWithAFrame } from './examples/performance-integration.js';



const performanceManager = await integrateWithAFrame();

```



### Development Setup



```javascript

import { createDevPerformanceSystem } from './src/performance/index.js';



const performanceManager = await createDevPerformanceSystem(scene, {

  enableDashboard: true,

  enableTesting: true,

  showAdvancedMetrics: true

});



// Toggle dashboard with Ctrl+Shift+P

// Run performance tests through dashboard UI

```



## Architecture



### Core Components



1. **PerformanceMonitor**: Real-time metrics collection

2. **OptimizationFramework**: Automated quality adjustment

3. **PlatformOptimizer**: Platform-specific adaptations

4. **PerformanceDashboard**: Developer tools and visualization

5. **PerformanceTestSuite**: Automated validation and regression testing

6. **PerformanceManager**: Central coordination and API



### Performance Profiles



- **maximum-quality**: Highest visual fidelity, may sacrifice performance

- **balanced**: Optimal balance of quality and performance (default)

- **maximum-performance**: Prioritizes frame rate over visual quality

- **comfort-first**: Optimized for motion sickness prevention



## Platform Specifications



### Apple Vision Pro

- **Target**: 90fps, 512MB memory limit

- **Features**: Foveated rendering, thermal management, spatial optimization

- **Optimizations**: Dynamic resolution, eye tracking integration



### Meta Quest

- **Target**: 90fps, 256MB memory limit

- **Features**: Aggressive LOD, mobile optimizations, battery awareness

- **Optimizations**: Reduced shader complexity, texture compression



### Desktop Fallback

- **Target**: 60fps, 2GB memory limit

- **Features**: High-quality rendering, development tools

- **Optimizations**: Full feature set, debugging capabilities



## Performance Testing



### Automated Test Suite



```javascript

// Run all performance tests

const testReport = await performanceManager.runPerformanceTests();



// Run specific tests

await performanceManager.runPerformanceTests([

  'baseline',

  'load-stress',

  'comfort-validation'

]);

```



### Available Tests



1. **Baseline Test**: Standard performance measurement

2. **Load Stress Test**: Progressive quality degradation testing

3. **Memory Stress Test**: Memory management validation

4. **Comfort Validation**: Motion sickness prevention testing

5. **Platform Optimization**: Platform-specific feature testing

6. **Endurance Test**: Long-term stability validation

7. **Regression Test**: Performance comparison against baselines



## LOD (Level of Detail) System



### Registration



```javascript

// Register object for automatic LOD management

performanceManager.registerLODObject(object3D, {

  meshes: [highPoly, mediumPoly, lowPoly, veryLowPoly],

  materials: [highQuality, medium, low, veryLow],

  maxDistance: 100,

  important: false // Skip aggressive optimizations

});

```



### Automatic Optimization



- Distance-based LOD selection

- Performance-driven quality adjustment

- Memory-aware asset management

- Platform-specific optimization levels



## Asset Management



### Intelligent Loading



```javascript

// Performance-aware asset loading

const asset = await performanceManager.loadAsset(url, type);



// Preload with performance consideration

await performanceManager.preloadAssets([

  'cockpit-high.gltf',

  'dashboard-medium.gltf',

  'environment-low.gltf'

]);

```



### Memory Management



- Usage-based cache eviction

- Automatic garbage collection triggering

- Memory pressure detection and response

- Asset priority queue management



## Performance Dashboard



### Keyboard Shortcuts

- `Ctrl+Shift+P`: Toggle performance dashboard

- Dashboard tabs: Overview, Performance, Comfort, System



### Features

- Real-time performance graphs

- Memory usage visualization

- Comfort score tracking

- Active optimization display

- Test control interface

- Report export functionality



## Event System



```javascript

// Performance event handling

performanceManager.on('frameDrop', (data) => {

  console.warn('Frame drop detected:', data);

  // Implement custom response

});



performanceManager.on('memoryWarning', (data) => {

  console.warn('Memory pressure:', data);

  // Trigger asset cleanup

});



performanceManager.on('comfortRisk', (data) => {

  console.warn('Comfort risk:', data);

  // Enable comfort features

});

```



## Configuration Options



```javascript

const performanceManager = await createPerformanceSystem(scene, {

  // Core settings

  targetFPS: 90,

  memoryLimit: 512 * 1024 * 1024,

  

  // Feature toggles

  enableMonitoring: true,

  enableOptimization: true,

  enableDashboard: false,

  enableTesting: false,

  

  // Optimization behavior

  autoOptimize: true,

  adaptiveQuality: true,

  aggressiveOptimization: false,

  

  // Comfort settings

  comfortThreshold: 0.8,

  motionLatencyThreshold: 20

});

```



## Comfort Metrics



### Motion Sickness Prevention

- Frame rate stability monitoring

- Motion-to-photon latency tracking

- Sudden movement detection

- Comfort score calculation (0-1 scale)



### Recommendations

- Automatic quality reduction on comfort risk

- Comfort-first profile for sensitive users

- Real-time comfort feedback

- Session comfort analytics



## API Reference



### PerformanceManager



```javascript

// System control

await performanceManager.startXRSession(xrSession)

performanceManager.stopXRSession()



// Profile management

performanceManager.applyPerformanceProfile('balanced')

const profiles = performanceManager.getPerformanceProfiles()



// Performance data

const metrics = performanceManager.getPerformanceMetrics()

const report = performanceManager.generatePerformanceReport()

const isAcceptable = performanceManager.isPerformanceAcceptable()



// Optimization control

performanceManager.forceOptimizationLevel('maximum-performance')

performanceManager.resetOptimizations()



// Asset integration

const asset = await performanceManager.loadAsset(url, type)

await performanceManager.preloadAssets(urls)



// LOD system

performanceManager.registerLODObject(object3D, lodConfig)

performanceManager.updateDrawCalls(count)



// Testing

const testReport = await performanceManager.runPerformanceTests()

const results = performanceManager.getTestResults()



// Dashboard

performanceManager.showDashboard()

performanceManager.hideDashboard()

performanceManager.toggleDashboard()

```



## Best Practices



### Integration Guidelines

1. Initialize performance system early in application lifecycle

2. Register LOD objects as soon as they're created

3. Use performance-aware asset loading for all resources

4. Monitor comfort metrics continuously during XR sessions

5. Apply appropriate performance profiles based on platform detection



### Optimization Strategies

1. Use automatic optimization for most scenarios

2. Implement custom performance event handlers for app-specific needs

3. Test across all target platforms regularly

4. Monitor long-term performance trends through dashboard

5. Use performance testing in CI/CD pipeline



### Memory Management

1. Preload essential assets, lazy-load optional ones

2. Implement asset priority systems for loading order

3. Use LOD system for all 3D models

4. Monitor memory usage patterns in dashboard

5. Test memory stress scenarios regularly



## Troubleshooting



### Common Issues



1. **Frame Rate Below Target**

   - Check current LOD level and force lower quality if needed

   - Review asset loading and reduce concurrent operations

   - Enable aggressive optimization mode



2. **Memory Warnings**

   - Trigger garbage collection manually

   - Review asset cache size and cleanup unused assets

   - Check for memory leaks in custom code



3. **Comfort Issues**

   - Switch to comfort-first performance profile

   - Review motion patterns and reduce sudden movements

   - Check frame stability and optimize rendering pipeline



### Debug Information



Use the performance dashboard to analyze:

- Real-time performance metrics

- Memory usage patterns

- Comfort score trends

- Active optimization levels

- Platform-specific information



## Contributing



Performance system improvements should:

1. Maintain 90fps target on all platforms

2. Respect memory constraints (512MB Vision Pro, 256MB Quest)

3. Include comprehensive tests

4. Update documentation

5. Consider comfort impact of changes



## License



Part of Battlezone XR project. See main project LICENSE for details.