nachoiannella/scroll-3d-landing

Landing 3D con scroll (para cualquier objeto)

Esta skill sirve para construir una landing de una sola página donde un objeto 3D es el protagonista. El objeto se queda fijo detrás del contenido y cambia de pose, de estilo de render y de contexto a medida que el usuario scrollea. Sirve para cualquier cosa que se pueda mostrar como objeto: una botella de vino, un auricular, una silla, una guitarra, un reloj, un auto, una maqueta de edificio, una escultura, una cámara antigua, un frasco de perfume, una herramienta o un juguete.

El caso de referencia es toppervenom.com, de Evil Rabbit (post original), y de ese proyecto salió la idea de esta skill. Muestra una zapatilla Topper de básquet de los 90; su modelo 3D no es un escaneo, sino una reconstrucción hecha con IA a partir de material de archivo y de imágenes generadas de todas sus vistas. La página arranca como plano técnico (wireframe blanco sobre cuadrícula azul), se "rellena" con el material real, muestra sus medidas y partes, cambia de color y termina girando. La zapatilla es solo el ejemplo; lo que se replica es la forma de construir la página y su nivel de calidad. Cada proyecto elige su propio concepto visual, su secuencia de actos y el efecto de revelado que mejor le queda a su objeto (ver "Adaptar al objeto" más abajo).

Por qué estas webs se ven tan bien (leé esto antes de empezar)

La calidad no viene del stack. toppervenom.com son unos 90 KB de HTML/CSS/JS más Three.js (según su autor, la página la generó una IA de un tirón): no tiene framework, ni GSAP, ni bundler. La calidad viene de cinco cosas, y cada decisión del proyecto tiene que servir a alguna:

1. Un asset 3D real y bien preparado. Un escaneo con textura fotográfica, una reconstrucción con IA bien cuidada (como la de toppervenom) o un modelo con detalle real, limpio, liviano y con escala real. Si el modelo es malo, nada de lo demás lo salva. → references/3d-capture.md, references/3d-alternatives.md
2. Render con criterio fotográfico. Iluminación de tres puntos, environment map, tone mapping neutro, sombra de contacto y materiales corregidos (un escaneo suele traer metalness falso que hace ver el cuero como plástico). → references/rendering.md
3. Un concepto de dirección de arte llevado hasta el último detalle. "Plano técnico" en toppervenom: la cuadrícula, las cotas, la tipografía mono, el loader dice "PLOTTING DRAWING Nº 01", el rail dice "REV. 0 — BLUEPRINT". Todo cuenta la misma historia. → references/art-direction.md
4. Movimiento con física, no con keyframes. Las poses se declaran por sección; el JS interpola con smoothstep y además amortigua cada valor con decaimiento exponencial. Eso da peso e inercia. → references/choreography.md
5. Efectos de shader que justifican el 3D. Revelado wireframe→sólido con un plano que barre el objeto, superficie fantasma con fresnel, recoloreo por luminancia. Son cosas que un video no puede hacer. → references/shaders.md

Si el usuario pide "algo así", el trabajo real es: conseguir un buen modelo + elegir un concepto + ajustar con paciencia. La plantilla resuelve la ingeniería.

Adaptar al objeto (no copies la zapatilla)

La plantilla trae una secuencia de ejemplo (plano → medidas → partes → revelado → números → origen → cierre), pero la forma del objeto y su historia deciden la composición, el efecto y los actos. Antes de escribir poses, ubicá el objeto en esta tabla:

Forma del objeto	Ejemplos	Composición	Revelado que mejor funciona	Actos típicos
Alargado horizontal	zapatilla, auto, guitarra, cuchillo, lapicera, tren	Objeto a un costado y texto al otro; perfil puro para las cotas	Barrido a lo largo (punta → cola)	Perfil técnico, detalle de piezas, velocidad o uso
Vertical / de revolución	botella, perfume, lámpara, florero, trofeo, edificio	Objeto centrado o a un tercio, texto a los costados en dos columnas; plano contrapicado para el clímax	Barrido de abajo hacia arriba ("se llena") o corte transversal	Silueta, material o contenido, origen, ritual de uso
Compacto / caja	auricular, cámara, parlante, reloj, consola, joya	Primeros planos grandes (scale 1.4–2) que recorren el objeto como una macro	Despiece (vista explosionada) o barrido diagonal	Diseño, interior/componentes, materiales, especificaciones
Plano / de lectura frontal	libro, disco, cuadro, placa, tarjeta, tablet	Rotaciones cortas (±0.4 rad) para mostrar el espesor; nunca de canto mucho tiempo	Puntos que se condensan, o pintura que "aparece"	Frente, dorso, detalle de textura, contexto
Orgánico / escultórico	escultura, comida, planta, fósil, juguete	Giros lentos y amplios, mucha luz de contorno	Nube de puntos → superficie, o fantasma con fresnel	Forma, textura, historia, escala humana
Ensamblado de piezas	mueble, máquina, maqueta, producto modular	Vista 3/4 alta, todo el conjunto en cuadro	Despiece por scroll: cada pieza se separa sobre su eje y vuelve	Conjunto → despiece → pieza por pieza → armado
Gran escala	casa, edificio, terreno, barco	Cámara más lejos, rotación de "maqueta" sobre la mesa	Barrido vertical por pisos, cortes de sección	Emplazamiento, plantas, cortes, materiales

Elegí también el concepto visual según el objeto, no por defecto. "Plano técnico" le queda a todo lo diseñado o fabricado; un vino puede pedir "ficha de bodega"; una escultura, "catálogo de museo"; un gadget, "laboratorio"; algo vintage, "catálogo de época". El menú completo está en references/art-direction.md, y los efectos alternativos (despiece, puntos, corte, llenado) en references/shaders.md.

Flujo de trabajo

Seguí estas fases en orden. Antes de escribir código, confirmá con el usuario las decisiones de las fases 1 y 2, porque cambian todo lo que viene después.

Fase 1 — Brief y concepto (5 minutos con el usuario)

Preguntá o deducí:

• Qué objeto es y de qué material (cuero, vidrio, metal, plástico mate, tela). El material define cómo capturarlo y cómo iluminarlo.
• La historia en 5–8 actos. Cada acto es una sección y una pose del objeto. Ejemplo típico: presentación → plano/medidas → anatomía (partes) → revelado → números → origen/historia → cierre.
• El concepto visual, es decir, la metáfora que unifica todo. No copies "blueprint" por defecto: elegí la metáfora que tenga sentido para ese producto. En references/art-direction.md hay un menú de conceptos (plano técnico, ficha de museo, laboratorio, catálogo de los 90, editorial de moda, despiece industrial) con su paleta, tipografías y cómo se traduce cada uno al 3D.
• Contenido real. Datos, medidas, materiales, historia y créditos. Las webs de referencia se sienten auténticas porque usan datos reales del catálogo original y del escaneo. Si no hay datos, pedilos; no inventes especificaciones de un producto real.
• Idiomas (es/en) y si hay variantes de color.

Fase 2 — Conseguir el modelo 3D

Esta es la fase que más afecta la calidad final. Usá este árbol de decisión y leé la referencia que corresponda:

¿El usuario tiene el objeto físico?
├─ Sí → ESCANEARLO (references/3d-capture.md)
│   ├─ Objeto mate/con textura (zapatilla, comida, piedra, madera, tela) → fotogrametría con celular o cámara
│   ├─ Brillante, negro o transparente → spray matificante temporal + fotogrametría, o modelarlo
│   └─ Muy chico/fino (joyas, cables) → fotogrametría macro o modelarlo
└─ No → ALTERNATIVAS (references/3d-alternatives.md)
    ├─ Hay CAD/STEP del fabricante → convertir y texturizar
    ├─ Hay fotos buenas desde varios ángulos → IA image-to-3D (Meshy, Tripo, Rodin, Hunyuan3D, TRELLIS) + limpieza
    ├─ Forma geométrica (botella, lata, lámpara, mueble) → modelar en Blender (revolución/extrusión), 1–4 h
    ├─ Producto genérico → comprar o descargar con licencia (Fab, Sketchfab, CGTrader, Poly Haven)
    └─ Sin modelo posible → objeto procedural/estilizado (lathe, extrude de SVG, puntos, line-art)

Cualquiera sea el origen, el modelo pasa por el pipeline de optimización (references/asset-pipeline.md): limpieza, decimado a 100–300 k triángulos, textura de 2048–4096 en WebP, compresión Meshopt, escala real, origen y orientación correctos, y una malla aparte muy decimada para el wireframe. Ese detalle importa mucho: el wireframe de una malla densa se ve como ruido gris, no como un dibujo.

Hay un script listo para este paso: scripts/prepare-model.sh <entrada.glb|.obj|.fbx> <nombre>. Genera models/<nombre>.glb optimizado y models/<nombre>-wire.glb para las líneas. Con la Stratocaster de ejemplo pasó de 22,2 MB a 1,8 MB.

Escaneo o modelo hecho a mano. La malla de wire decimada es para escaneos, donde las aristas son ruido. En un modelo hecho a mano (CAD, Sketchfab, Blender), la malla decimada se convierte en triángulos largos que atraviesan las superficies y se lee como malla, no como dibujo. Ahí usá wireMode: 'edges' sobre la malla principal y wireModel: null, sin generar el wire. Se lee como un dibujo técnico y te ahorrás un archivo.

Descargas de Sketchfab: requieren sesión iniciada (cuenta gratuita). Si usás el navegador integrado, pedile al usuario que inicie sesión y confirmá nombre, tamaño y formato (GLB) antes de descargar. Guardá el original en una carpeta source/ aparte y acreditá al autor (CC BY) en el footer.

Fase 3 — Armar el proyecto desde la plantilla

Copiá assets/template/ a la carpeta del proyecto. Esto es lo que trae:

Archivo	Qué hace
index.html	Estructura: fondo fijo (cuadrícula + papel), <canvas> fijo, <svg> de overlay, loader, nav, rail de progreso, selector de colorway y secciones con atributos de pose (data-ry, data-x, data-reveal…).
styles.css	Sistema visual: tokens, tipografía fluida con clamp(), cuadrícula CSS, fondo papel, reveals con blur, curvas de easing, móvil.
main.js	Motor: renderer, luces, carga con progreso, shaders de revelado y colorway, wireframe y fantasma, sombras, coreografía de scroll, drag con resorte, overlays SVG (cotas y callouts), contadores, colorways. Todo configurable desde CONFIG al principio del archivo.

No necesita build. Se sirve con cualquier servidor estático (npx serve, python -m http.server). No funciona con file:// por los módulos ES. Three.js viene de jsDelivr con versión fija en el importmap; para producción conviene copiarlo a vendor/ y agregar modulepreload (ver references/performance.md).

Probala sin modelo: index.html?model=<url de un .glb>, o sin parámetro para ver el objeto procedural de reemplazo. Un buen glb de prueba es MaterialsVariantsShoe.glb de KhronosGroup/glTF-Sample-Assets.

Fase 4 — Ajustar el modelo a la escena

En main.js → CONFIG:

1. orient: rotá hasta que el objeto quede con Y hacia arriba y el largo sobre X (por ejemplo, [0, 0, -Math.PI/2] para acostar una guitarra que viene parada). La orientación se aplica al modelo antes de medirlo, así que la caja, las cotas, sweepDir, los callouts y el despiece se expresan siempre en el espacio ya orientado. Usá ?debug para ver los ejes.
2. realSizeCm: la medida real del lado más largo, en cm. De ahí salen todas las cotas que se muestran.
3. sweepDir: la dirección del barrido de revelado. Que siga la "lectura" natural del objeto: a lo largo en un objeto alargado ([1,0,0] o [0,0,1]), de abajo hacia arriba en una botella o un edificio ([0,1,0]) y en diagonal en un objeto compacto ([0.3,0.3,1]).
4. callouts: las posiciones de las partes, como fracciones de la caja (f, 0..1) o como coordenadas exactas del modelo (p, en sus unidades). El código las pega al vértice más cercano. Ordenalas de arriba hacia abajo para que las líneas no se crucen. Con ?debug, hacé clic sobre el modelo y la consola imprime la fracción exacta del punto.
5. colorways: definí oscuro/claro por variante (o borrá el selector si el objeto no tiene variantes). El shader recolorea por luminancia y preserva los detalles saturados; si el objeto en sí es de un color saturado, poné keepSaturated: 0.
6. Secciones: agregá, quitá o reordená <section> libremente. El motor lee las poses de cualquier cantidad de secciones, en cualquier orden.
7. Opciones del motor para casos especiales:
   • procedural: () => Object3D arma el objeto por código en lugar de cargar un glb.
   • wireMode: 'edges' dibuja solo las aristas de dibujo. Es lo mejor para objetos duros, CAD o procedurales.
   • extraKeys: ['screen'] + onFrame(cur, dt, t) sirven para efectos propios controlados por sección (data-screen). Por ejemplo, una pantalla que se enciende, una luz o una tapa que se abre.
   • Despiece con data-explode: cada pieza se mueve según su userData.explode = [x,y,z] (o se aleja del centro si no lo tiene).
   • Por pieza: userData.noRecolor (ignora los colorways), userData.noWire (no aparece en el plano) y userData.keepPbr (el motor no toca su material).
   • recolorOnly: ['BodyMaterial']: solo esos materiales (por nombre del glb) toman los colorways. En la guitarra se pinta el cuerpo y quedan intactos el golpeador, el mástil y los herrajes.
   • keepPbr: true respeta el PBR de modelos hechos a mano (metales reales, barniz con clearcoat). Por defecto, el motor corrige el metalness falso de escaneos e IA, y eso arruina un modelo bien hecho.
   • wireColors: [color con paper 0, color con paper 1] y edgeColor adaptan el plano a cualquier concepto, por ejemplo tinta sobre papel de patente en lugar de blanco sobre azul. Los dos estados del fondo (backdrop__grid y backdrop__paper) son solo nombres: se pueden estilar como lámina → escenario, vitrina → noche, etc.
   • data-rz (roll) para parar objetos largos, como una guitarra en su soporte. Las sombras de piso se apagan solas al pararlo.

Fase 5 — Coreografía de scroll

Cada <section> tiene atributos data-* que definen la pose y el efecto en su punto activo (0% de scroll de esa sección). El motor viaja linealmente de una pose a la siguiente, pero con relajación (smoothstep + amortiguación) para dar peso e inercia. Los atributos principales son:

• data-rx, data-ry, data-rz: rotación en cada sección, en radianes. Ejemplo: data-ry="0" y luego data-ry="-2.1".
• data-x, data-y, data-z: desplazamiento del objeto, en cm del mundo. Se usan para despiece, moverlo a un costado, etc.
• data-reveal: valor de revelado, de 0 a 1. 0 = solo wireframe (plano técnico), 1 = textura completa. El valor intermedio 0.2 arranca el relleno.
• data-scale: escala del modelo, de 0.2 a 2.
• data-fov: lente de la cámara en grados. 25 = tele; 55 = normal; 85 = gran angular.
• data-camDist: distancia de la cámara al objeto, como múltiplo de la diagonal del modelo. 1.5 = a 1.5 diagonales.
• data-camRotX, data-camRotY: rotación de la cámara en radianes, alrededor del target (el objeto). Se animan solos; no hace falta ponerlos si solo se usa el orbit de drag. Son útiles para encuadres exactos.
• data-explode: factor de despiece, de 0 (junto) a 1 (piezas en su posición).
• data-ghost: visibilidad del efecto fantasma (fresnel). 0 apagado, 1 prendido. Se usa para revelados etéreos.
• data-points: nube de puntos en vez de malla sólida. 0 = apagado, 1 = todos puntos.
• data-pointSize: tamaño de los puntos, típicamente 0.01–0.05.

Ejemplo de sección:

<section
  data-rx="0.3"
  data-ry="0.8"
  data-reveal="0.5"
  data-scale="1.2"
>
  <h2>Diseñada para la velocidad</h2>
  <p>Desde el primer trazo, cada curva tiene un propósito.</p>
</section>

Fase 6 — Refinamiento y pulido

Probá con ?debug para ver ejes, puntos de callout y velocidades. Ajustá los valores de pose hasta que la secuencia se sienta fluida. Revisá en móvil (la plantilla es responsive). Si el modelo se ve mal con cierta iluminación, ajustá envMapIntensity o el tonemapping en CONFIG. Para problemas de rendimiento, referí a references/performance.md.

Referencias adicionales

• references/3d-capture.md: Cómo escanear objetos con el celular (Meshroom, Polycam, Luma AI, RealityCapture).
• references/3d-alternatives.md: Cómo obtener modelos sin escaneo (IA, CAD, compra, procedural).
• references/rendering.md: Configuración de iluminación, environment maps, tone mapping, sombras.
• references/art-direction.md: Lista de conceptos visuales con paletas, tipografías y directrices 3D.
• references/shaders.md: Explicación de shaders de revelado, despiece, puntos, corte, fantasma.
• references/choreography.md: Detalles de interpolación, relajación y física de movimiento.
• references/asset-pipeline.md: Pipeline de optimización de modelos GLB.
• references/performance.md: Cómo reducir tiempos de carga y mejorar FPS.

Notas finales

• No olvides el caso de uso: esta skill es para cuando el usuario pide "una landing con un 3D que se arma al scrollear", "mostrar algo en 3D en la web", o "replicar el efecto de toppervenom". No la uses para portfolios simples, galerías de productos estáticas o webs corporativas genéricas.
• El objeto es el rey: si el modelo 3D no es de calidad, la página no funcionará. Priorizá siempre conseguir un buen asset antes de escribir una línea de código.
• La historia guía la técnica: primero definí los actos y el concepto visual; luego programá las poses. No dejes que la tecnología dicte la narrativa.