Guía Rápida
1. Primeros Pasos con VXR Core
Para comenzar a desarrollar con VXR Core, necesitas un entorno de JavaScript/TypeScript moderno (como Vite, Next.js o un bundler estándar con soporte ESModules). Instala el paquete base junto con Three.js:
npm install github:Vickman123/Framework-XVR three @types/three
Crea tu primer punto de entrada instanciando la clase fachada XRApp. El framework se encarga de crear el canvas WebGL2, la cámara de perspectiva, la luz ambiental y el bucle de renderizado:
import { XRApp } from 'vxr';
const app = new XRApp({
container: '#app',
autoVRButton: true,
enableShadows: true,
enableGrid: true
});
// Cargar modelo con auto-centrado
await app.loadModel('./models/artefacto.glb', { autoGround: true });
app.start();
Diseño del Sistema
2. Arquitectura del Framework
VXR Core implementa el patrón Fachada Abierta (Open Facade): la clase maestra XRApp proporciona un punto de entrada ergonómico pero no bloquea el acceso a Three.js. Puedes acceder directamente a app.scene, app.camera y app.renderer en cualquier momento.
| Capa |
Módulo |
Responsabilidad |
| Fachada |
XRApp |
Ciclo de vida, render loop y orquestación general. |
| Escena |
XRScene |
Gestión de iluminación fotométrica, fondo y sombras. |
| Render |
XRRenderer |
WebGL2, pixelRatioCap adaptativo y resize automático. |
| Assets |
XRAssetManager |
GLTF/GLB, DRACOLoader, cálculo Box3 y auto-grounding. |
| Inmersivo |
XRSession |
WebXR Device API, Meta Quest Browser y mandos VR. |
Gráficos & Performance
3. Escenas y Renderizado
El subsistema XRScene incluye presets de iluminación fotométricos listos para producción que equilibran calidad y costo de cálculo en dispositivos con batería:
// Aplicar preset de iluminación en tiempo de ejecución
app.sceneManager.applyLightingPreset('studio'); // 'studio' | 'outdoor' | 'sunset' | 'cyber'
Por su parte, XRRenderer restringe el pixelRatio mediante la propiedad pixelRatioCap: 1.5. En pantallas Retina o visores VR con resolución 4K, esto previene la saturación térmica del chip gráfico manteniendo nitidez visual completa.
Pipeline de Modelos
4. Recursos 3D y Auto-Grounding
Uno de los dolores de cabeza más comunes en Three.js es cargar un modelo GLB con punto de pivote descentrado o flotando en el aire. XRAssetManager calcula la caja delimitadora (Box3) y ajusta su posición automáticamente:
const model = await app.loadModel('./models/escultura.glb', {
autoCenter: true, // Centra X y Z en el origen (0, 0)
autoGround: true, // Alinea la base del modelo exactamente sobre Y = 0
castShadow: true // Activa proyección de sombras en todas las mallas
});
Incluye además el método disposeObject(obj) para liberar geometrías, materiales y texturas de la GPU al desmontar experiencias.
Controladores & Entrada
5. Sistema de Interacción Unificada (XRInput)
XRInput mapea teclado (WASD, flechas), ratón (clic, drag) y controladores WebXR (sticks analógicos, gatillos) a acciones unificadas. Esto permite que el mismo código funcione en PC y en Meta Quest sin duplicar lógica de entrada.
import { XRInput } from 'vxr';
const input = new XRInput({ canvas: app.renderer.domElement });
input.on('select', (event) => {
console.log('Objeto seleccionado por raycast:', event.intersection?.object);
});
Realidad Virtual
6. Soporte WebXR y Meta Quest
VXR Core integra detección nativa de visores mediante XRSession. Si el navegador soporta WebXR, muestra el botón estándar inmersivo. Si se ejecuta en escritorio o móvil sin visor, activa automáticamente el modo DesktopRuntime con controles de ratón y cámara orbital.
# Auditar y compilar build WebXR optimizada para Meta Quest
npx vxr doctor
npx vxr build --target quest
npx vxr serve --https
Entornos Arquitectónicos
7. Escenarios y Salas Modulares (XRScenario / XRRoom)
Construye museos y laboratorios interconectados mediante código declarativo. XRRoom genera paredes, pisos, techos y puertas calculando los vanos para evitar colisiones invisibles entre habitaciones adyacentes:
import { XRRoom, XRScenario } from 'vxr';
const lobby = new XRRoom({
dimensions: { width: 12, height: 4, depth: 12 },
materials: { floor: 'marble', walls: 'white' },
doors: [{ wall: 'north', width: 2.5, height: 3 }]
});
const scenario = new XRScenario();
scenario.addRoom(lobby);
app.scene.add(scenario);
Referencia Completa
8. Referencia de la API Pública
Resumen de las clases principales disponibles en los paquetes @vxr/core y @vxr/ar:
| Clase |
Constructor / Opciones |
Métodos Clave |
XRApp |
XRAppOptions (container, shadows, vr) |
start(), stop(), loadModel(), dispose() |
XRScene |
XRSceneOptions (preset, fog) |
applyLightingPreset(), add(), remove() |
XRRenderer |
XRRendererOptions (pixelRatioCap) |
render(), setSize(), setAnimationLoop() |
ARExperience |
ARExperienceOptions (mode, camera) |
init(), start(), loadModel(), setMode() |
ARCamera |
ARCameraOptions (facingMode, fps) |
start(), stop(), fitElement() |
Tutoriales Paso a Paso
9. Ejemplos y Tutoriales Prácticos
Consulta las guías de implementación para casos de uso comunes del framework:
- ▸ Visor de Arquitectura con Inspección: Cómo calcular volumen y resaltar componentes estructurales con raycasting.
- ▸ Museo Virtual con Fichas y Audio: Cómo vincular pedestales con fichas técnicas que suenan al interactuar.
- ▸ Realidad Aumentada con Código QR: Cómo escanear un QR con BarcodeDetector para desplegar modelos 3D sin app nativa.
Diagnóstico & FAQ
10. Solución de Problemas (Troubleshooting)
Respuestas rápidas a las incidencias más frecuentes en desarrollo 3D/XR:
| Problema |
Causa Frecuente |
Solución Recomendada |
| WebXR no inicia en Meta Quest |
Conexión no segura (HTTP en red local). |
Usa npx vxr serve --https para habilitar SSL automático. |
| Audio bloqueado en móvil |
Políticas de autoplay del navegador. |
Llama a audio.unlock() en el primer evento de toque o clic del usuario. |
| Contexto WebGL perdido |
Exceso de texturas sin liberar en GPU. |
Invoca app.dispose() al cambiar de vista para vaciar shaders y buffers. |
| CORS al cargar modelos .glb |
Servidor de assets sin cabecera Access-Control. |
Configura Access-Control-Allow-Origin: * en tu servidor o usa rutas relativas locales. |
