Bloque 3D con Three.js para Gutenberg (WordPress)

Bloque de Gutenberg para mostrar modelos 3D interactivos en páginas y entradas de WordPress, con Three.js. Subes un archivo .glb o .gltf a la biblioteca de medios y el visitante lo puede rotar, acercar y mover con el mouse o el dedo. Las luces, el fondo, la cámara y las animaciones se ajustan desde el panel del bloque, con vista previa en vivo en el editor.

🇬🇧 English: Gutenberg block to embed interactive 3D models (.glb / .gltf) in WordPress using Three.js: orbit, zoom and pan with mouse or touch, configurable lights, background, camera and animations, and a live preview in the block editor.

Sirve para mostrar productos en 3D, maquetas de arquitectura, piezas industriales, personajes, diseños y renders sin salir de WordPress.

Características

• Visor 3D interactivo: órbita, zoom y desplazamiento con mouse o pantalla táctil, con inercia. Encuadra el modelo automáticamente, según su tamaño.

• Bloque nativo de Gutenberg: hecho con las APIs de bloques de WordPress (React de wp.element), block.json y renderizado dinámico en PHP.

• Vista previa en vivo en el editor: cada cambio del panel se ve al instante.

• Subida de .glb y .gltf a la biblioteca de medios: WordPress no la permite por defecto. El plugin la habilita y verifica que el contenido del archivo sea un modelo real, no solo la extensión.

• Parámetros configurables:

  Panel	Opciones
  Modelo	archivo de la biblioteca o URL, texto alternativo
  Lienzo y fondo	alto, color de fondo o fondo transparente
  Luces	intensidad, exposición, iluminación de entorno (reflejos realistas)
  Cámara y controles	campo de visión, rotación automática y su velocidad, zoom, desplazamiento
  Animación	reproduce la animación que trae el modelo

• Rendimiento:

  • el modelo se carga recién cuando el bloque se acerca a la pantalla;
  • dibuja solo cuando algo se mueve y se pausa fuera de pantalla;
  • limita la densidad de píxeles en celulares;
  • acepta modelos comprimidos con meshopt (EXT_meshopt_compression).

• Accesible: el lienzo tiene role="img" con el texto alternativo y, sin JavaScript, queda un enlace para descargar el modelo.

Instalación

1. Descarga el repo como ZIP y súbelo en Plugins → Añadir nuevo, o clónalo:

   cd wp-content/plugins
   git clone https://github.com/Joaquindati/gutenberg-threejs-3d-block.git

   La carpeta build/ ya viene compilada: no hace falta Node.

2. Activa Bloque 3D con Three.js para Gutenberg.
3. En el editor, agrega el bloque Modelo 3D (Three.js) y elige un .glb.

Desarrollo

npm install --include=dev
npm run build   # esbuild: src/ → build/ (editor.js, view.js, style.css y *.asset.php)

block.json                     metadatos, atributos y archivos del bloque
render.php                     HTML del frontend (bloque dinámico)
gutenberg-threejs-3d-block.php registro del bloque y subida de .glb/.gltf
src/viewer.js                  visor Three.js (lo usan el editor y el frontend)
src/editor.js                  edición: panel lateral y vista previa
src/view.js                    frontend: monta cada bloque al acercarse a la pantalla
build.mjs                      compilación con esbuild

Se compila con esbuild en lugar de @wordpress/scripts: el bloque usa las dependencias de WordPress como globales (wp.blocks, wp.element…) y build.mjs genera los *.asset.php para que se carguen en orden.

Ideas para seguir

Varias vistas o hotspots sobre el modelo, carga de texturas KTX2, y elegir el modelo desde un campo de ACF.

Requisitos

WordPress 6.3+ · PHP 7.4+ · navegador con WebGL. Probado con la última versión de WordPress, PHP 8.3 y Chrome (escritorio y celular).

Autor

Joaquín Dati, desarrollador WordPress, Three.js y full stack. joaquindati.com

Licencia GPL v2 o posterior. Three.js tiene licencia MIT.