aframe-webxr
Escenas 3D/VR/AR declarativas en HTML con A-Frame (ECS sobre Three.js): WebXR, controladores VR, AR hit-test, visores 360, componentes custom. No para control fino de Three.js (threejs-webgl) ni para
SKILL.mdcore/skills-overlay/aframe-webxr/SKILL.md
GitHubaframe-webxr (índice Senzu, ES)
Documentación completa upstream (inglés): SKILL.upstream.md (1076 líneas). No la leas entera: usa el mapa y lee solo la sección que necesites (Read con offset/limit o Grep).
Cuándo usar / cuándo NO
- Usar: experiencias VR/AR en navegador (WebXR) con poco JavaScript, prototipos 3D con primitivas HTML (
<a-box>,<a-sky>). - Usar: visores de foto/vídeo 360, interacción con controladores/gaze/cursor, colocar objetos en AR con hit-test.
- NO usar: cuando necesitas control imperativo del renderer, shaders o postprocesado →
threejs-webgl; escena 3D dentro de un árbol React →react-three-fiber. - NO usar: motor de juego completo con física/editor →
babylonjs-engineoplaycanvas-engine.
Lectura mínima por tarea
| Tarea | Lee solo |
|---|---|
| Empezar un proyecto/starter | SKILL.upstream.md L17-78 (§Core Concepts: ECS y Scene Setup) + assets/starter_aframe/ |
| Controladores VR / agarrar objetos | L277-341 (§Pattern 1) + references/webxr_guide.md |
| AR con hit-test | L403-457 (§Pattern 3) + references/webxr_guide.md |
| Galería 360 / skybox / modelos GLTF | L342-402, L576-671 (§Pattern 2, 6, 7) |
| Componente custom / interacción click-gaze | L242-274 (§8) + L458-506 (§Pattern 4) o scripts/component_builder.py |
| Integrar con Three.js / GSAP / React | L672-770 (§Integration Patterns) |
| Depurar / rendimiento | L771-893 (§Performance) + L894-1061 (§Pitfalls) |
Mapa de SKILL.upstream.md
| Líneas | Sección | Para qué |
|---|---|---|
| 8-16 | When to Use This Skill | Casos de uso listados por el autor |
| 17-274 | Core Concepts | ECS (19), escena (51), cámaras/rig (79), luces (125), materiales (151), animación (178), assets (211), componentes custom (242) |
| 275-671 | Common Patterns | Controladores VR (277), galería 360 (342), AR hit-test (403), mouse/gaze (458), escena dinámica (507), entorno/skybox (576), GLTF (619) |
| 672-770 | Integration Patterns | Acceso a Three.js (674), GSAP (697), React con useEffect (731) |
| 771-893 | Performance Best Practices | <a-assets>, pooling, low-poly, draw calls, throttle tick(), stats |
| 894-1061 | Common Pitfalls and Solutions | Entidad invisible, eventos sin raycaster, FPS, z-fighting, VR móvil, CORS/carga |
| 1062-1076 | Resources / Related Skills | Enlaces oficiales y skills relacionadas |
Recursos
references/api_reference.md— API A-Frame 1.7: escena, entidad, componentes core, primitivas, sistemas.references/components_library.md— componentes de la comunidad (environment, physics, locomoción, loaders, UI).references/webxr_guide.md— configuración VR/AR, controladores, hand tracking, hit testing.scripts/scene_generator.py— genera escena basic/vr/ar/360/networked:py -3 scripts/scene_generator.py vr MiProyecto(Linux/mac:python3 …).scripts/component_builder.py— boilerplate de componente basic/interactive/animation/physics/networked:py -3 scripts/component_builder.py interactive mi-comp.assets/starter_aframe/— index.html + main.js + style.css listos;assets/examples/README.md— patrones avanzados (two-handed grab, networking, física).
Reglas duras
- Precarga todo en
<a-assets>y espera al eventoloadedde la escena antes de añadir entidades dinámicamente; añadecrossorigin="anonymous"en recursos externos. - Nada de crear/destruir entidades por frame: usa pooling; throttlea
tick()y limita luces (máx. ambient + directional en móvil). - Interacción requiere raycaster:
<a-cursor raycaster="objects: .interactive">y clase en los objetivos; sin ello no lleganclick/mouseenter. - En VR móvil limita
renderer="maxCanvasWidth: 1920; maxCanvasHeight: 1920", usa low-poly y valoraantialias: false. - Ofrece siempre fallback no-XR (desktop/móvil con look-controls) y respeta
prefers-reduced-motiondesactivandoanimation__*en bucle.
Integración con el stack del proyecto
- Detecta el stack como indica la skill
front-activation/skill-router(senzu/senzu.json → package.json). A-Frame es vanilla/HTML-first: en Vue o Astro funciona con el script CDN oimport 'aframe'solo en cliente (no SSR). - En React usa
useEffect+ refs (L731-770) y registra componentes antes de montar<a-scene>; si el proyecto ya es React+Three, prefierereact-three-fiber.