Ir al contenido
Senzu

threejs-webgl

  • Grupo: 3D / WebGL
  • Cuándo se activa: 3D, WebGL/WebGPU, modelos GLB/GLTF, shaders, partículas, configuradores, heros 3D
  • Se instala: Opcional: llega con un paquete de skills.

Skill upstream (inglés): SKILL.upstream.md (fundamentos, WebGPU, materiales, postprocesado, patrones), references/api_reference.md, references/materials_guide.md, references/optimization_checklist.md, assets/starter_scene/, scripts/setup_scene.py. Capa Senzu (español): references/es/ y templates/. Para React declarativo existe además la skill react-three-fiber; para combinar 3D + GSAP + Motion, web3d-integration-patterns.

Construyes 3D útil y rápido: refuerza el producto, carga en < 2 s, no rompe el LCP, funciona en móvil y desaparece con elegancia sin WebGL o con prefers-reduced-motion. Estética y tono salen del senzu/design-system/*/MASTER.md (skill ui-ux-pro-max); el movimiento ligado al scroll se coordina con gsap-scrolltrigger.

1. Detectar el stack e integrar

Sección titulada «1. Detectar el stack e integrar»
Stack (perfil Senzu) Integración Referencia Plantillas
Vue 3 (SPA o Laravel + Inertia) TresJS (@tresjs/core + @tresjs/cientos) references/es/tresjs-vue.md templates/HeroScene.vue, HeroContent.vue, useWebGLSupport.ts
Next.js / React React Three Fiber + drei, next/dynamic ssr:false references/es/r3f-next.md (+ skill react-three-fiber) templates/HeroScene.tsx
Astro clase vanilla + <script> con View Transitions references/es/vanilla-astro.md templates/scene.ts, scene-astro.ts, loading-overlay.html
Vanilla / otros clase Scene (init/resize/loop/dispose) SKILL.upstream.md, references/es/fundamentals.md templates/scene.ts

Comprueba versiones instaladas (@tresjs/cientos cambió la API de useGLTF; nombres de @tresjs/post-processing dependen del release): lee node_modules/@tresjs/*/dist/*.d.ts si dudas. No inventes APIs.

1b. Lectura mínima por tarea

Sección titulada «1b. Lectura mínima por tarea»
Tarea Lee solo
Hero 3D con modelo GLB referencia ES de tu stack (§setup + §GLTF) + plantilla HeroScene.* + references/es/assets-loaders.md §optimizar
Configurador de producto referencia ES de tu stack + references/es/fundamentals.md §materiales/luces
Partículas / shader / distorsión de imagen references/es/shaders-basics.md (sección del efecto)
Scroll-driven 3D references/es/gsap-three.md
Va lento / consume memoria references/es/performance.md §presupuesto + §dispose
Se ve lavado, negro o no aparece references/es/pitfalls.md (Grep por el síntoma)
API concreta de Three.js references/api_reference.md upstream (Grep) o SKILL.upstream.md por sección

2. Flujo

Sección titulada «2. Flujo»
  1. Objetivo y presupuesto: qué aporta el 3D, dispositivo objetivo, peso del asset (hero ≤ 2 MB, texturas ≤ 2048 px, draw calls < 100 en móvil), tiempo de carga aceptable.
  2. Asset (references/es/assets-loaders.md): GLB con transforms aplicados, gltf-transform optimize in.glb out.glb --texture-compress webp (+ Draco/Meshopt), verificado en un visor; en public/models/.
  3. Renderer correcto: outputColorSpace = SRGBColorSpace, toneMapping = ACESFilmicToneMapping, setPixelRatio(Math.min(devicePixelRatio, 2)), sombras solo si aportan.
  4. Carga progresiva: canvas lazy (defineAsyncComponent / next/dynamic / client:visible), overlay de progreso accesible, placeholder estático que mantiene el LCP.
  5. Interacción: Raycaster o eventos de TresJS/R3F; OrbitControls con damping y límites; sin zoom por rueda en heros.
  6. Rendimiento y limpieza (references/es/performance.md): pausar fuera del viewport y con pestaña oculta; dispose() de geometrías/materiales/texturas/renderer al desmontar (las SPA navegan sin recargar).
  7. Fallbacks: sin WebGL → imagen/vídeo; reduced-motion → escena estática; webglcontextlost gestionado.
  8. Verificar: FPS ≥ 50 en móvil medio (CPU 4x), memoria estable tras navegar 5 veces, consola limpia, Lighthouse ≥ 85.

3. Reglas duras

Sección titulada «3. Reglas duras»
  • Nada de Three.js en SSR: importar solo en cliente. Un solo WebGLRenderer por página.
  • Siempre dispose al desmontar. Pixel ratio ≤ 2 (1,5 en móvil si hace falta).
  • Color space correcto (texture.colorSpace = SRGBColorSpace solo en mapas de color).
  • Sin modelos > 5 MB sin aprobación; texturas KTX2/WebP, geometría Draco/Meshopt.
  • El 3D no bloquea el contenido: texto y CTA son HTML accesible encima del canvas.
  • Sin Stats, Leva, helpers ni markers en producción.
  • Errores frecuentes y solución: references/es/pitfalls.md (40 casos).

4. Decisiones rápidas

Sección titulada «4. Decisiones rápidas»
Necesidad Solución
Hero con modelo que gira y sigue al ratón TresJS/R3F + useGLTF + loop con lerp hacia el puntero
Producto configurable Un GLB, material.color.set(token), Environment HDRI, ContactShadows
Scroll-driven 3D (cámara por secciones) GSAP timeline con labels + ScrollTrigger scrub (references/es/gsap-three.md)
Fondo de partículas ligero Points + shader (references/es/shaders-basics.md), ≤ 20k puntos en móvil
Distorsión de imagen al hover plane + ShaderMaterial con uHover/uTime
Escena hecha en Spline exportar GLB e integrarlo aquí (evita el runtime de Spline) — ver skill spline-interactive
Muchas copias del mismo objeto InstancedMesh
Vidrio/reflejos realistas MeshPhysicalMaterial + transmission + Environment (solo desktop)

5. Salida esperada

Sección titulada «5. Salida esperada»

Antes del código: objetivo, presupuesto, integración elegida, fallback y limpieza. Después: código + pasos de optimización del asset + verificación (FPS, memoria, consola).