Pedrovbm1/biblioteca

Biblioteca 3D comunitaria

HOME3D = $EXPLICADORES_3D o ~/.explicadores-3d. La biblioteca está en HOME3D/biblioteca/: CATALOGO.md (una fila por modelo con miniatura, parámetros y defectos), manifiesto.json, modelos/, piezas/, base/ (estilos, lib2d, panel de ajustes), aportes/ (lo que suma la comunidad), vendor/ (three.js, three.quarks, Tweakpane, fuente Fredoka) y vista.html.

Todo es procedural y determinista: nada de texturas descargadas ni Math.random. Escala por defecto 1 u = 1 cm.

Buscar y usar un modelo

1. Busca por nombre o idea sin leer el catálogo entero (son ~200 líneas): grep -i "mosquito\|insecto" HOME3D/biblioteca/CATALOGO.md. Lee la fila: qué es, archivo → export(parámetros), estilo de color y defectos conocidos (sobre todo "⚠ ojos").
2. Míralo (opcional): sirve la carpeta (python -m http.server 8795 dentro de biblioteca/) y abre localhost:8795/vista.html?m=<id>; con &ajustes=1 sale el panel para mover cámara, colores y luces. O mira la miniatura miniaturas/<id>.png (en un subagente si tu harness lo permite, para no cargar imágenes en tu contexto).
3. Cópialo al proyecto (escena/modelos/), nunca lo importes desde la biblioteca, y ajusta el import del estilo (../../base/estilo3d.js → ../estilo3d.js). Si usa partículas (piezas/particulas/), copia también vendor/quarks/ y agrega "quarks.core" al importmap.
4. Cada archivo trae arriba su API (ejes, escala, métodos .poner* / .update(t)): eso va en una línea en el encargo del constructor.

Aportar modelos nuevos: viene activado (al terminar cada video)

Aportar es lo normal: al terminar un video se ofrece siempre, y el usuario solo tiene que decir que no si no quiere. La licencia es MIT para el código y CC BY 4.0 para los modelos, con crédito visible a quien aporta.

1. Detecta los modelos y piezas nuevas del proyecto (no gasta tokens; compara contra la biblioteca):

   python "SKILL_DIR/nuevos.py" <proyecto>
   

   Si dice "no hay modelos nuevos" o "el usuario ya dijo que no", no preguntes nada y termina.
2. Prepara todo antes de preguntar, uno por modelo. Saca --nombre y --que-es del comentario de arriba del archivo y --fn de su export principal. Revisa antes que no traiga nada personal (clientes, marcas, logos, textos de su canal), que sea determinista y que no tenga formas que se lean como ojos; lo que no cumpla, no se prepara.

   python "SKILL_DIR/aportar.py" --archivo <proyecto>/escena/modelos/regadera.js --fn crearRegadera --id regadera \
     --nombre "Regadera" --que-es "Regadera de jardín con asa y pico" [--autor "<nombre o @usuario>"] --estilo casa
   

   El autor se pide una sola vez (cómo quiere salir en el crédito) y queda en ~/.explicadores-3d/autor.txt. Esto deja miniatura 400x400, ficha.json (autor, fecha, CC BY 4.0), fila del manifiesto y del catálogo, y pasa el validador. No sube nada todavía.
3. Pregunta, en una línea, con la lista de lo preparado: ¿Los subo a la biblioteca? (S/n). Enter, "s", "sí" o "va" = sí. Solo "n" o "no" (o algo que claramente lo rechace) = no.
4. Sí → un solo PR con todos:

   python "SKILL_DIR/aportar.py" --publicar regadera,maceta
   python "SKILL_DIR/nuevos.py" <proyecto> --subido escena/modelos/regadera.js escena/modelos/maceta.js
   

   Dale el link del PR. No → python "SKILL_DIR/nuevos.py" <proyecto> --no y no vuelvas a preguntar en ese proyecto (tampoco en sesiones nuevas: queda en <proyecto>/.biblioteca.json).

• Sin gh: --publicar deja todo listo y explica los 3 pasos a mano (fork en la web, commit en una rama, PR). Para instalar gh: winget install GitHub.cli / brew install gh / cli.github.com, y luego gh auth login.
• Cada PR lo valida un GitHub Action (navegador sin cabeza, determinismo, sin red, tamaño, miniatura, fila y autor) y lo aprueba una persona. Al fusionarse, el autor sale en CATALOGO.md, en la galería index.html y en el ranking APORTADORES.md. Quien aporta recibe primero los paquetes nuevos o destacados (ver README, "Aportas y recibes").

Arreglar un defecto

Si en un video arreglas un defecto de un modelo de la biblioteca, propón el arreglo al repo también (PR normal, explicando el antes y el después); los cambios fuera de aportes/ los revisa a mano quien mantiene el repo.