{"id":50316477,"url":"https://github.com/msitarzewski/thezonexr","last_synced_at":"2026-05-29T00:03:31.497Z","repository":{"id":341934759,"uuid":"1150924320","full_name":"msitarzewski/thezonexr","owner":"msitarzewski","description":"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.","archived":false,"fork":false,"pushed_at":"2026-02-06T15:13:00.000Z","size":1678,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T04:12:39.014Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/msitarzewski.png","metadata":{"files":{"readme":"README-Performance.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-05T21:12:33.000Z","updated_at":"2026-02-06T15:14:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/msitarzewski/thezonexr","commit_stats":null,"previous_names":["msitarzewski/thezonexr"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/msitarzewski/thezonexr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msitarzewski%2Fthezonexr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msitarzewski%2Fthezonexr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msitarzewski%2Fthezonexr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msitarzewski%2Fthezonexr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msitarzewski","download_url":"https://codeload.github.com/msitarzewski/thezonexr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msitarzewski%2Fthezonexr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33631002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T00:03:27.024Z","updated_at":"2026-05-29T00:03:31.487Z","avatar_url":"https://github.com/msitarzewski.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Battlezone XR Performance Monitoring System\n\nA comprehensive WebXR performance monitoring and optimization framework designed to ensure 90fps comfort targets and \u003c512MB memory constraints across Apple Vision Pro, Meta Quest, and desktop platforms.\n\n## Features\n\n### 📊 Real-Time Performance Monitoring\n- **Frame Rate Tracking**: Continuous 90fps monitoring with frame drop detection\n- **Motion-to-Photon Latency**: Sub-20ms latency measurement and optimization\n- **Memory Usage Monitoring**: 512MB constraint enforcement with predictive alerts\n- **Comfort Metrics**: Motion sickness risk assessment and prevention\n\n### 🎯 Automatic Optimization Framework\n- **Dynamic LOD System**: 4-level Level of Detail with distance-based culling\n- **Asset Management**: Intelligent caching with usage-based cleanup\n- **Garbage Collection**: Proactive memory management and leak prevention\n- **Draw Call Optimization**: Render pipeline efficiency monitoring\n\n### 🔧 Platform-Specific Optimization\n- **Apple Vision Pro**: Foveated rendering, thermal management, 90fps targeting\n- **Meta Quest**: Aggressive optimization, mobile-specific rendering, battery awareness\n- **Desktop**: High-quality fallback with development tools integration\n- **Cross-Platform**: Unified API with platform-specific adaptations\n\n### 📈 Development Dashboard\n- **Real-Time Metrics**: Live performance graphs and statistics\n- **Comfort Tracking**: User experience monitoring and alerts\n- **Session Analytics**: Comprehensive performance reporting\n- **Test Integration**: Automated performance validation suite\n\n## Quick Start\n\n### Basic Integration\n\n```javascript\nimport { createPerformanceSystem } from './src/performance/index.js';\n\n// Initialize performance system\nconst performanceManager = await createPerformanceSystem(scene, {\n  targetFPS: 90,\n  memoryLimit: 512 * 1024 * 1024, // 512MB\n  autoOptimize: true\n});\n\n// XR session integration\nrenderer.xr.addEventListener('sessionstart', async () =\u003e {\n  const session = renderer.xr.getSession();\n  await performanceManager.startXRSession(session);\n});\n```\n\n### A-Frame Integration\n\n```html\n\u003ca-scene\u003e\n  \u003ca-entity performant-cockpit=\"performanceProfile: balanced; enableLOD: true\"\u003e\u003c/a-entity\u003e\n\u003c/a-scene\u003e\n```\n\n```javascript\nimport { integrateWithAFrame } from './examples/performance-integration.js';\n\nconst performanceManager = await integrateWithAFrame();\n```\n\n### Development Setup\n\n```javascript\nimport { createDevPerformanceSystem } from './src/performance/index.js';\n\nconst performanceManager = await createDevPerformanceSystem(scene, {\n  enableDashboard: true,\n  enableTesting: true,\n  showAdvancedMetrics: true\n});\n\n// Toggle dashboard with Ctrl+Shift+P\n// Run performance tests through dashboard UI\n```\n\n## Architecture\n\n### Core Components\n\n1. **PerformanceMonitor**: Real-time metrics collection\n2. **OptimizationFramework**: Automated quality adjustment\n3. **PlatformOptimizer**: Platform-specific adaptations\n4. **PerformanceDashboard**: Developer tools and visualization\n5. **PerformanceTestSuite**: Automated validation and regression testing\n6. **PerformanceManager**: Central coordination and API\n\n### Performance Profiles\n\n- **maximum-quality**: Highest visual fidelity, may sacrifice performance\n- **balanced**: Optimal balance of quality and performance (default)\n- **maximum-performance**: Prioritizes frame rate over visual quality\n- **comfort-first**: Optimized for motion sickness prevention\n\n## Platform Specifications\n\n### Apple Vision Pro\n- **Target**: 90fps, 512MB memory limit\n- **Features**: Foveated rendering, thermal management, spatial optimization\n- **Optimizations**: Dynamic resolution, eye tracking integration\n\n### Meta Quest\n- **Target**: 90fps, 256MB memory limit\n- **Features**: Aggressive LOD, mobile optimizations, battery awareness\n- **Optimizations**: Reduced shader complexity, texture compression\n\n### Desktop Fallback\n- **Target**: 60fps, 2GB memory limit\n- **Features**: High-quality rendering, development tools\n- **Optimizations**: Full feature set, debugging capabilities\n\n## Performance Testing\n\n### Automated Test Suite\n\n```javascript\n// Run all performance tests\nconst testReport = await performanceManager.runPerformanceTests();\n\n// Run specific tests\nawait performanceManager.runPerformanceTests([\n  'baseline',\n  'load-stress',\n  'comfort-validation'\n]);\n```\n\n### Available Tests\n\n1. **Baseline Test**: Standard performance measurement\n2. **Load Stress Test**: Progressive quality degradation testing\n3. **Memory Stress Test**: Memory management validation\n4. **Comfort Validation**: Motion sickness prevention testing\n5. **Platform Optimization**: Platform-specific feature testing\n6. **Endurance Test**: Long-term stability validation\n7. **Regression Test**: Performance comparison against baselines\n\n## LOD (Level of Detail) System\n\n### Registration\n\n```javascript\n// Register object for automatic LOD management\nperformanceManager.registerLODObject(object3D, {\n  meshes: [highPoly, mediumPoly, lowPoly, veryLowPoly],\n  materials: [highQuality, medium, low, veryLow],\n  maxDistance: 100,\n  important: false // Skip aggressive optimizations\n});\n```\n\n### Automatic Optimization\n\n- Distance-based LOD selection\n- Performance-driven quality adjustment\n- Memory-aware asset management\n- Platform-specific optimization levels\n\n## Asset Management\n\n### Intelligent Loading\n\n```javascript\n// Performance-aware asset loading\nconst asset = await performanceManager.loadAsset(url, type);\n\n// Preload with performance consideration\nawait performanceManager.preloadAssets([\n  'cockpit-high.gltf',\n  'dashboard-medium.gltf',\n  'environment-low.gltf'\n]);\n```\n\n### Memory Management\n\n- Usage-based cache eviction\n- Automatic garbage collection triggering\n- Memory pressure detection and response\n- Asset priority queue management\n\n## Performance Dashboard\n\n### Keyboard Shortcuts\n- `Ctrl+Shift+P`: Toggle performance dashboard\n- Dashboard tabs: Overview, Performance, Comfort, System\n\n### Features\n- Real-time performance graphs\n- Memory usage visualization\n- Comfort score tracking\n- Active optimization display\n- Test control interface\n- Report export functionality\n\n## Event System\n\n```javascript\n// Performance event handling\nperformanceManager.on('frameDrop', (data) =\u003e {\n  console.warn('Frame drop detected:', data);\n  // Implement custom response\n});\n\nperformanceManager.on('memoryWarning', (data) =\u003e {\n  console.warn('Memory pressure:', data);\n  // Trigger asset cleanup\n});\n\nperformanceManager.on('comfortRisk', (data) =\u003e {\n  console.warn('Comfort risk:', data);\n  // Enable comfort features\n});\n```\n\n## Configuration Options\n\n```javascript\nconst performanceManager = await createPerformanceSystem(scene, {\n  // Core settings\n  targetFPS: 90,\n  memoryLimit: 512 * 1024 * 1024,\n  \n  // Feature toggles\n  enableMonitoring: true,\n  enableOptimization: true,\n  enableDashboard: false,\n  enableTesting: false,\n  \n  // Optimization behavior\n  autoOptimize: true,\n  adaptiveQuality: true,\n  aggressiveOptimization: false,\n  \n  // Comfort settings\n  comfortThreshold: 0.8,\n  motionLatencyThreshold: 20\n});\n```\n\n## Comfort Metrics\n\n### Motion Sickness Prevention\n- Frame rate stability monitoring\n- Motion-to-photon latency tracking\n- Sudden movement detection\n- Comfort score calculation (0-1 scale)\n\n### Recommendations\n- Automatic quality reduction on comfort risk\n- Comfort-first profile for sensitive users\n- Real-time comfort feedback\n- Session comfort analytics\n\n## API Reference\n\n### PerformanceManager\n\n```javascript\n// System control\nawait performanceManager.startXRSession(xrSession)\nperformanceManager.stopXRSession()\n\n// Profile management\nperformanceManager.applyPerformanceProfile('balanced')\nconst profiles = performanceManager.getPerformanceProfiles()\n\n// Performance data\nconst metrics = performanceManager.getPerformanceMetrics()\nconst report = performanceManager.generatePerformanceReport()\nconst isAcceptable = performanceManager.isPerformanceAcceptable()\n\n// Optimization control\nperformanceManager.forceOptimizationLevel('maximum-performance')\nperformanceManager.resetOptimizations()\n\n// Asset integration\nconst asset = await performanceManager.loadAsset(url, type)\nawait performanceManager.preloadAssets(urls)\n\n// LOD system\nperformanceManager.registerLODObject(object3D, lodConfig)\nperformanceManager.updateDrawCalls(count)\n\n// Testing\nconst testReport = await performanceManager.runPerformanceTests()\nconst results = performanceManager.getTestResults()\n\n// Dashboard\nperformanceManager.showDashboard()\nperformanceManager.hideDashboard()\nperformanceManager.toggleDashboard()\n```\n\n## Best Practices\n\n### Integration Guidelines\n1. Initialize performance system early in application lifecycle\n2. Register LOD objects as soon as they're created\n3. Use performance-aware asset loading for all resources\n4. Monitor comfort metrics continuously during XR sessions\n5. Apply appropriate performance profiles based on platform detection\n\n### Optimization Strategies\n1. Use automatic optimization for most scenarios\n2. Implement custom performance event handlers for app-specific needs\n3. Test across all target platforms regularly\n4. Monitor long-term performance trends through dashboard\n5. Use performance testing in CI/CD pipeline\n\n### Memory Management\n1. Preload essential assets, lazy-load optional ones\n2. Implement asset priority systems for loading order\n3. Use LOD system for all 3D models\n4. Monitor memory usage patterns in dashboard\n5. Test memory stress scenarios regularly\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Frame Rate Below Target**\n   - Check current LOD level and force lower quality if needed\n   - Review asset loading and reduce concurrent operations\n   - Enable aggressive optimization mode\n\n2. **Memory Warnings**\n   - Trigger garbage collection manually\n   - Review asset cache size and cleanup unused assets\n   - Check for memory leaks in custom code\n\n3. **Comfort Issues**\n   - Switch to comfort-first performance profile\n   - Review motion patterns and reduce sudden movements\n   - Check frame stability and optimize rendering pipeline\n\n### Debug Information\n\nUse the performance dashboard to analyze:\n- Real-time performance metrics\n- Memory usage patterns\n- Comfort score trends\n- Active optimization levels\n- Platform-specific information\n\n## Contributing\n\nPerformance system improvements should:\n1. Maintain 90fps target on all platforms\n2. Respect memory constraints (512MB Vision Pro, 256MB Quest)\n3. Include comprehensive tests\n4. Update documentation\n5. Consider comfort impact of changes\n\n## License\n\nPart of Battlezone XR project. See main project LICENSE for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsitarzewski%2Fthezonexr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsitarzewski%2Fthezonexr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsitarzewski%2Fthezonexr/lists"}