Hyper-Real Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Hyper-Real Engine is a core rendering and visual effects module within the TAMV MD-X4 ecosystem, specifically designed to power immersive DreamSpaces and XR experiences. It leverages React Three Fiber and Three.js to provide high-fidelity 3D environments, including cinematic introductions with quantum particles and volumetric effects.
As part of the MD-X4 visual pipeline, the engine is responsible for maintaining visual integrity across different hardware tiers while providing sensory-rich interactions. It is closely integrated with the KAOS Audio System to provide audio-reactive environments and multisensorial feedback.
Sources: PLAN-TAMV-MODULAR.md:82-84, README_TAMV_COMPLETO.md:32-40
Architecture and Technical Stack
The engine is built on a modern 3D web stack that emphasizes performance and modularity. It serves as the primary rendering logic for the "DreamSpaces" domain.
- Core Frameworks: React 18.3, Three.js, and @react-three/fiber.
- Optimization Layer: Utilizes @react-three/drei for advanced helpers and performance optimizations like LOD (Level of Detail).
- State Management: Integrated with Zustand for global quantum state persistence.
- Visual Pipeline: Includes support for volumetric lighting, quantum particle systems, and holographic UI components.
Sources: README_TAMV_COMPLETO.md:10-15, PLAN-TAMV-MODULAR.md:84-85
Rendering Lifecycle and Data Flow
The engine follows a structured rendering flow where visual quality is dynamically adjusted based on the client's performance metrics.
The diagram above illustrates the high-level rendering flow from initialization to asset disposal, including the performance-based quality adjustment loop.
Sources: 02_MODULOS/M03_XR/INTERNO/XR-PERFORMANCE-GUIDELINES.md:14-45, src/App.tsx:55-60
Performance and Governance
To ensure a stable experience across mobile and desktop devices, the Hyper-Real Engine adheres to strict performance guidelines.
Level of Detail (LOD) Configuration
The engine implements an automatic quality switching mechanism based on FPS thresholds. If the framerate drops below 45 FPS for 3 consecutive seconds, the engine lowers the quality level; conversely, it raises quality if performance is stable above 55 FPS.
| Metric | Target Minimum | Target Optimal |
|---|---|---|
| FPS (Medium Hardware) | 45 fps | 60 fps |
| Loading Time (XR Route) | < 2s (perceived) | < 1s |
| Three.js Memory Usage | < 200MB | < 100MB |
| Audio Latency | < 50ms | < 20ms |
Sources: 02_MODULOS/M03_XR/INTERNO/XR-PERFORMANCE-GUIDELINES.md:6-14, 02_MODULOS/M03_XR/INTERNO/XR-PERFORMANCE-GUIDELINES.md:30-40
Resource Management
The engine enforces a mandatory cleanup pattern for all 3D components to prevent memory leaks. Geometries, materials, and textures must be explicitly disposed of during the component unmount phase. Creating new Three.js objects within the useFrame render loop is strictly prohibited as an anti-pattern.
Sources: 02_MODULOS/M03_XR/INTERNO/XR-PERFORMANCE-GUIDELINES.md:47-65
Sensory Integration
The engine is designed to be audio-reactive, but it implements throttling to ensure the FFT (Fast Fourier Transform) analysis does not degrade visual performance.
This sequence diagram shows the throttled communication between the audio system and the rendering engine to maintain high FPS during audio-reactive events.
Sources: 02_MODULOS/M03_XR/INTERNO/XR-PERFORMANCE-GUIDELINES.md:74-85
Key Implementation Patterns
Code Splitting
To optimize initial bundle size, all XR and Hyper-Real routes are loaded lazily. This is enforced by the MSR-XR-01 rule, which requires the use of React.lazy() and Suspense for the Metaverse and DreamSpaces routes.
// Required implementation pattern in App.tsx
const Metaverse = lazy(() => import('./pages/Metaverse'));
const DreamSpaces = lazy(() => import('./pages/DreamSpaces'));
Sources: 02_MODULOS/M03_XR/INTERNO/XR-PERFORMANCE-GUIDELINES.md:18-28
Feature Availability
| Feature | Implementation Status | Path |
|---|---|---|
| InstancedMesh | Permitted (Particles) | src/components/effects/ |
| Volumetric Shadows | Conditional (Quality-based) | src/components/effects/ |
| Post-processing | Feature Flag Required | src/components/effects/ |
| Audio Throttling | Mandatory (30fps max) | src/systems/ |
Sources: 02_MODULOS/M03_XR/INTERNO/XR-PERFORMANCE-GUIDELINES.md:87-98, TASKS-TAMV-MODULAR.md:52-57
Conclusion
The Hyper-Real Engine provides the visual foundation for the TAMV MD-X4 ecosystem's 3D and XR layers. By combining advanced Three.js rendering with strict performance governance and sensory integration, it enables high-fidelity experiences that remain accessible across various device categories. Future developments focus on further optimizing the audio-reactive throttling and expanding the library of "DreamSpaces" templates.