Dioramas: el framework open source para crear webs 3D interactivas con three.js y modelos generados con IA

Dioramas es un framework open source para construir webs 3D interactivas en las que la escena de three.js no es un adorno del hero, sino la página entera: un objeto hiperdetallado, iluminación de estudio, una cámara coreografiada con el scroll y una interacción que el visitante puede tocar. Lo curioso es de dónde salen los objetos: no se modelan en Blender, se generan con IA a partir de un prompt (imagen con Nano Banana 2 y malla 3D con Meshy 7.1) y luego un pequeño engine sobre three.js se encarga de que parezcan caros.

En este artículo explicamos qué trae el repositorio, cómo funciona cada capa por dentro, cuánto cuesta generar los modelos, cómo ponerlo en marcha y cómo usarlo con un agente de código para crear tu propia página.

Qué es Dioramas

Es el repositorio blendi-remade/dioramas. Datos a fecha de esta revisión (28 de octubre de 2026):

• Licencia: el código es MIT. Los modelos 3D y las imágenes generadas se publican con CC BY 4.0 (puedes usarlos citando "Dioramas (github.com/blendi-remade/dioramas)").
• Versión: 0.1.0, publicada en un único commit el 29 de septiembre de 2026.
• Stack: three.js r186, postprocessing (pmndrs), N8AO, GSAP con ScrollTrigger y SplitText, Lenis, Rapier (física) y Vite 8.
• Contenido: el engine (src/core/, unas 840 líneas), los scripts del pipeline de assets (scripts/), 20 webs de ejemplo completas (examples/, unas 14.500 líneas solo en los main.js), los briefs de cada ejemplo (docs/briefs/) y los prompts exactos con los que se generó cada modelo (assets/jobs/).
• Peso: los modelos van dentro del repo sin Git LFS: public/models/ ocupa unos 310 MB con 91 archivos GLB.

No hay plan de pago, cuenta ni CLI que instalar. Solo pagas a fal si quieres generar modelos nuevos; para ver y modificar los 20 ejemplos no hace falta ninguna clave.

Las tres capas del framework

Dioramas se entiende mejor como tres piezas que encajan:

1. Pipeline de assets: prompt → imagen → modelo 3D → GLB optimizado para la web.
2. Engine: una capa fina sobre three.js con el post-procesado, la luz y el scroll ya resueltos.
3. Método: brief → build → review → revise, pensado para que un agente de IA construya la página.

Capa 1: el pipeline que genera los modelos 3D con IA

Todo empieza con un archivo JSON en assets/jobs/. Cada entrada es un objeto con un id y un prompt, por ejemplo el del casco del museo *Reliquary*: "An ancient Greek bronze Corinthian hoplite helmet, deep verdigris green-blue patina…".

El script scripts/gen.mjs hace dos pasos contra la API de fal:

1. Imagen de referencia con fal-ai/nano-banana-2. Si el job no lleva raw: true, el script añade al prompt un sufijo fijo que pide un objeto aislado, centrado, en vista de tres cuartos, sobre fondo blanco puro y sin sombras. Es la "placa de producto" ideal para la conversión a 3D. Sale en assets/src/<id>.png.
2. Malla 3D con meshy/v7.1/image-to-3d: topología de triángulos, 150.000 polígonos por defecto, geometría 4K, texturas PBR y remallado. El GLB en bruto (unos 25 MB) queda en assets/raw/<id>.glb.

Un detalle bien pensado: el request_id de cada malla se guarda en assets/manifest.json antes de empezar a esperar el resultado. Si el proceso se cae a mitad de una generación de Meshy (tardan minutos), al relanzarlo retoma la misma petición en lugar de pagar otra vez por el mismo modelo.

Después, scripts/optimize.mjs pasa cada GLB por glTF-Transform: dedup, weld, simplificación opcional, texturas a WebP de 2048 px, cuantización y compresión meshopt. Un modelo de 25 MB baja a 3-8 MB.

cp .env.example .env                                   # añade tu FAL_KEY
node scripts/gen.mjs all assets/jobs/<tu-job>.json     # imágenes + mallas (reanudable)
node scripts/optimize-all.mjs                          # → public/models/<ejemplo>/

Cuánto cuesta generar los modelos

Según el README, un modelo texturizado cuesta unos 1,20 USD en fal, y la colección completa (65 modelos y 111 imágenes) costó unos 90 USD. El manifest.json del repo confirma esas cifras: 111 imágenes y 65 mallas, todas con meshy/v7.1/image-to-3d.

Para una agencia la cuenta es sencilla: el objeto protagonista de una landing cuesta menos que una hora de un modelador 3D. Lo que sigue costando tiempo es todo lo demás (luz, cámara, interacción y textos), y para eso está el resto del framework.

Capa 2: el engine sobre three.js

El engine vive en src/core/ y la idea es que todas las páginas compartan el mismo aspecto de "render caro" sin repetir código. Lo que hay en cada archivo:

Un ejemplo de cómo se configura una página (extracto de examples/lithos/main.js):

const engine = new Engine({
  canvas: document.getElementById('gl'), fov: 30, near: 0.05, far: 60, dpr: 1.6, background: 0x040306,
  post: {
    ao: { aoRadius: 0.35, intensity: 2.4, distanceFalloff: 0.6, halfRes: false, denoiseRadius: 8 },
    bloom: { intensity: 1.0, luminanceThreshold: 0.6, luminanceSmoothing: 0.3, radius: 0.64 },
    pre: cam => {
      vol = new VolumetricSpotEffect(cam, { density: 0.026, noise: 0.92, noiseScale: 1.7, maxDist: 12, floorY: 0, wind: V3(0.03, 0.06, 0.01) });
      dof = new DepthOfFieldEffect(cam, { focusDistance: 3.5, focusRange: 1.4, bokehScale: 2.2, resolutionScale: 0.5 });
      return Q.has('nodof') ? [vol] : [vol, dof];
    },
    tone: 'agx', vignette: { offset: 0.18, darkness: 0.84 }, noise: 0.045, ca: 0.0008,
  },
});

El tone mapping se hace en el post-procesado y no en el renderer (renderer.toneMapping queda en NoToneMapping), para que el bloom trabaje sobre valores HDR reales. Es una de esas decisiones que separan una escena que "parece three.js por defecto" de una que parece una foto de producto.

Capa 3: el método brief → build → review → revise

Esta es la parte más interesante si trabajas con agentes. Cada uno de los ejemplos empezó como un brief de una página en docs/briefs/. El de *Lithos*, por ejemplo, define:

• La interacción estrella: "Crack the geode": mantener pulsado hace que aparezcan grietas violeta en la junta, la piedra tiembla y se abre.
• Las secciones de la página: navegación, hero, la grieta, la colección de cuatro especímenes, joyería, procedencia y pie.
• Dirección de arte: negro terciopelo, violeta amatista #9d6bff y platino; tipografías Cinzel o Italiana con Jost.
• Lo que tiene que ser verdad: el fotograma de la geoda abierta tiene que dejar con la boca abierta y el cuarzo tiene que parecer cristal, no plástico.

Luego un agente de código construyó cada página contra docs/ENGINE.md, la guía del engine. Ese documento es en la práctica un system prompt para el agente: describe toda la API, prohíbe tocar src/core/ (había varias páginas construyéndose en paralelo) y fija una lista de 11 preguntas de calidad que hay que responder con un "sí" antes de dar la página por buena: ¿pararía a alguien en Awwwards?, ¿la luz está motivada?, ¿hay al menos 4 secciones con textos reales?, ¿se sostiene a 390×844 en móvil?, ¿60 fps y cero errores en consola?

La revisión se hace con capturas automáticas. scripts/review.mjs abre el ejemplo en Chrome headless con GPU, hace capturas en 8 puntos del scroll más dos en móvil, las monta en una hoja de contactos y devuelve los errores de consola y los fps. Así el agente "ve" su propia página y puede iterar sin que nadie tenga que abrir el navegador.

Los 20 ejemplos y su interacción

Cada ejemplo es una marca ficticia con su propia paleta, tipografía e interacción. Los que más técnica enseñan:

Cómo instalar Dioramas y ver los ejemplos

Necesitas Node.js y git. El README recomienda una GPU de escritorio: todo está ajustado a 60 fps y el propio ENGINE.md avisa de que en un portátil irá 2-3 veces más lento.

git clone https://github.com/blendi-remade/dioramas && cd dioramas
npm install
npm run dev        # http://127.0.0.1:5190: la galería; cada ejemplo en /examples/<nombre>/

Ten en cuenta que el clon descarga unos 310 MB de modelos. Si solo quieres leer el código, git clone --depth 1 ahorra el historial, aunque los modelos vienen igual.

Para crear un mundo nuevo, la estructura es siempre la misma: una carpeta examples/<tu-mundo>/ con index.html, main.js y style.css, tus modelos en public/models/<tu-mundo>/ y tus imágenes en public/img/<tu-mundo>/. Vite detecta automáticamente cualquier carpeta de examples/ que tenga un index.html y la añade al build.

En esta revisión leímos todo el código del repositorio, pero no ejecutamos los ejemplos en un equipo con GPU. Las capturas son las que publica el propio proyecto en docs/media/ (CC BY 4.0) y el diagrama es nuestro, hecho a partir del código.

Cómo usarlo con Claude Code u otro agente

El repositorio está pensado para esto: "pásale un brief y docs/ENGINE.md a tu agente". Un flujo práctico con Claude Code:

1. Copia un brief existente de docs/briefs/ como plantilla y escribe el tuyo: marca, interacción estrella, secciones, paleta, tipografías y qué tiene que ser verdad.
2. Genera los modelos con un job propio en assets/jobs/ y gen.mjs, u opta por reutilizar los de los ejemplos (CC BY 4.0).
3. Pide al agente algo así:

Lee docs/ENGINE.md y examples/reliquary/ como implementación de referencia.
Construye examples/mi-marca/ siguiendo docs/briefs/mi-marca.md.
No edites src/core: si necesitas otro comportamiento, copia la función a tu carpeta.
Después de cada cambio importante, ejecuta node scripts/review.mjs mi-marca,
revisa la hoja de contactos y responde las 11 preguntas de calidad de ENGINE.md.

1. Itera con capturas hasta que todas las respuestas sean "sí", y revisa la versión móvil.

Si nunca has preparado un proyecto para que lo entienda un agente, la guía de skills de Claude Code explica cómo empaquetar instrucciones como estas para reutilizarlas.

Errores frecuentes y detalles a tener en cuenta

• ENGINE.md habla de pages/ y el repo usa examples/. La guía se escribió cuando la carpeta se llamaba pages/<slug> (y el visor de modelos /pages/_viewer/). Hoy todo está en examples/, y el visor en /examples/_viewer/. Corrígelo en el prompt de tu agente o lo buscará donde no está.
• Los scripts de capturas están pensados para Windows. shot.mjs y review.mjs lanzan Chrome con channel: 'chrome' y --use-angle=d3d11. En macOS o Linux tendrás que quitar ese argumento de ANGLE y asegurarte de que Chrome está instalado (o usar el Chromium de Playwright).
• Cristal que se ve blanco. Los materiales con transmisión refractan el color de fondo y el post-procesado limpia con alfa 0, así que sin scene.background el vidrio parece un vacío blanco. Pon un fondo o una malla detrás.
• envMapIntensity no hace nada. En three.js r186 solo se aplica si el material tiene su propio envMap; con scene.environment usa scene.environmentIntensity.
• PCFSoftShadowMap ya no existe en r186: el engine usa PCFShadowMap y ajustas light.shadow.radius.
• Personajes riggeados de Meshy: la animación idle puede venir rota y el GLB riggeado solo trae color base; reutiliza las texturas de normales y rugosidad del modelo estático (comparten UV).
• Peso de la página: la guía fija un máximo de 45 MB de descarga y 1,6 millones de triángulos en pantalla por página. Es mucho para móvil: si tu público entra desde el teléfono, simplifica con --ratio en optimize.mjs.
• Licencia de GSAP: el código de Dioramas es MIT, pero GSAP (incluidos ScrollTrigger y SplitText) va con su licencia estándar "sin coste" de GSAP, no con una licencia open source. Revísala si vas a usarlo en un producto comercial.

Para qué sirve (y para qué no)

Sirve para landing pages de producto, lanzamientos, portfolios de agencia y campañas en las que el objeto es el protagonista: un reloj, una zapatilla, un perfume, una moto. Ahí un modelo generado por 1,20 USD y un engine con la luz ya resuelta ahorran semanas.

No sirve como plantilla de web corporativa ni de blog. Cada ejemplo es código a medida (su main.js tiene entre 440 y 1.200 líneas) y la experiencia depende de la GPU del visitante. Tampoco es una librería que se instale con npm: es un repositorio que clonas, del que copias el engine y que adaptas.

Si te interesan otras formas de dar movimiento a una web con IA, en HyperFrames para webs hicimos dos landing pages con motion graphics guiadas por scroll, y Anatomy dibuja ilustraciones isométricas interactivas para explicar ideas técnicas.

Preguntas frecuentes

¿Dioramas es gratis?

Sí. El código es MIT y los modelos e imágenes son CC BY 4.0. Solo pagas a fal si generas modelos nuevos: unos 1,20 USD por modelo texturizado.

¿Necesito saber three.js?

Para ver los ejemplos, no. Para crear tu propio mundo ayuda mucho, aunque el método está pensado para que lo escriba un agente de IA siguiendo docs/ENGINE.md y tú revises el resultado.

¿Puedo usar los modelos 3D en un proyecto comercial?

La licencia CC BY 4.0 permite el uso comercial siempre que cites la fuente: "Dioramas (github.com/blendi-remade/dioramas)".

¿Funciona en móvil?

Cada ejemplo debe sostener el diseño a 390×844 y tener un equivalente táctil de su interacción, según la guía de calidad. El rendimiento depende del teléfono: son escenas pesadas.

¿Qué modelos de IA usa?

Nano Banana 2 para las imágenes de referencia y Meshy 7.1 image-to-3D para las mallas, ambos a través de fal.

Conclusión

Dioramas junta tres cosas que normalmente van por separado: generar el objeto 3D con IA, hacer que se vea bien en el navegador y un método para que un agente construya la página y se revise a sí mismo con capturas. El valor no está en copiar los 20 ejemplos, sino en el engine de src/core/ y en docs/ENGINE.md, que puedes dar a tu agente tal cual.

El siguiente paso: clona el repositorio, abre examples/reliquary/ (la implementación de referencia) y escribe tu primer brief.