z1fex/3d-cartoon-animation

Animación 3D en Caricatura

Versión 1.0.1 (edición pública) · método y aspecto aprobados por el propietario en la ronda 1 ("Cómo se descubrió la gravedad", v3, 26 de octubre de 2026). 1.0.1 hace que las herramientas funcionen en cualquier computadora; las películas se renderizan igual que en 1.0.0.

"El propietario" en estos archivos es la persona para quien se hacen las películas: quien solicita la película y la aprueba.

Storyboard primero (regla del propietario, 27 de octubre de 2026). Cada película, y cada nueva versión, comienza como un storyboard en el marco del propietario. Nada se narra, construye en detalle o renderiza hasta que él lo apruebe (skill 4).

Este paquete es una forma completa y reutilizable de hacer un tipo de video: un video explicativo corto, rápido y cálido en 3D estilo caricatura. Funciona para cualquier tema. El ejemplo práctico trata sobre la gravedad, pero nada en el método depende de ello: los skills indican cómo encontrar el ángulo, elegir los personajes, construir los escenarios, convertir cada número en un objeto, sincronizar cada gesto con la voz, diseñar el sonido y revisar cada fotograma, para cualquier tema que venga.

Cómo es un video terminado

• Formato: 1080×1920, 30 fps, 30–60 s. Una cláusula de narración = una toma (una nueva imagen cada 1.1–1.5 s aproximadamente). La última línea se enlaza con el primer fotograma.
• Historia: un gancho en los primeros 2 s que abre una pregunta; una recompensa temprana; algo en juego contado a "ti"; escalada; un nuevo gancho a los dos tercios; un giro mostrado como una imagen literal; un final en bucle.
• Aspecto: sombreado suave de caricatura, contornos de tinta, luces prácticas cálidas, luz de borde, profundidad de campo, brillo de luz y grano. Rostros con tonos de piel; colores de marca (Rouge Noir, Blue Coral, Cognac, White Sand, Anthracite) en ropa, accesorios y escenarios. Las cosas reales se ven reales (la Tierra es azul y verde).
• Personajes: cabeza esférica, cuerpo de frijol, extremidades de palo, manos de mitón; rostros pintados sin sincronía de labios; los rostros cambian mediante un parpadeo justo antes de la palabra acentuada; las poses inmóviles están totalmente quietas.
• Cámara: siempre en movimiento, arrastrándose entre movimientos, acelerando en disoluciones de 6 fotogramas en la primera palabra de cada oración.
• Los hechos son objetos: cada número hablado aterriza en su fotograma como un contador, calendario, cinta métrica, medidor o letrero iluminado.
• Texto: una pregunta temática en la parte superior durante los primeros 2–3 s ("¿Cómo se encontró la gravedad?"), y bloques de texto editorial al 70% de altura (TODO sobre lo sabes).
• Sonido: una voz (ElevenLabs), una base musical original 18 LU por debajo de ella, un sonido foley sutil en cada acción visible y un acento en cada latido narrativo, masterizado a −14 LUFS.

La pipeline (cada paso es un skill)

#	Paso	Skill	Salida
1	Convertir el tema en una idea de película	tema-a-pelicula	ángulo, gancho, elenco, lugares, lista de números, panorama general
2	Escribir el guión	guión-y-retención	script.md con fuentes
3	Grabar la voz y sincronizar cada palabra	voz-y-tiempos	vo/voice-final.wav, vo/words-final.json
4	Storyboard de cada toma; el propietario lo aprueba	storyboard-y-plan-de-tomas	storyboard.md, imágenes del storyboard, el tablero del propietario (storyboard/<v>/<Título> - storyboard <n>.png y .html)
5	Definir el aspecto visual	aspecto-iluminación-y-marca	preajuste de luz, paleta, lente por toma
6	Construir el elenco	personajes-y-rostros	rigs, vestuarios, cambios de rostro
7	Actuar cada cláusula	movimiento-y-actuación	claves de pose, gags, física
8	Mover la cámara	cámara-y-transiciones	un movimiento orbital por toma
9	Hacer físicos los números	hechos-como-objetos	un dispositivo por número
10	Construir y decorar los lugares	escenarios-y-accesorios	lugares del kit, decorados
11	Escribir el texto en pantalla	subtítulos-y-gancho-del-título	bloques de subtítulos, pregunta del título
12	Diseñar el sonido	diseño-de-sonido-y-mezcla	lista de claves, mezcla, pistas
13	Renderizar y revisar cada fotograma	renderizado-y-controles-de-calidad	el MP4, el registro de QA
14	Revisar con el propietario y aprender	rondas-de-revisión-y-aprendizaje	retroalimentación, siguiente versión, actualización del paquete

Realiza los pasos en este orden. Los pasos 4–11 ocurren dentro de un archivo por película (film.mjs), así que en la práctica planificas el storyboard, luego construyes toma por toma, renderizando imágenes a medida que avanzas.

Lo que no se negocia

1. Storyboard primero. El propietario aprueba el tablero (skill 4) antes de que se grabe la voz, se construyan las tomas en detalle, o se renderice algo.
2. Copia la técnica, nunca el contenido. Cada personaje, escenario, letrero, chiste y nombre de marca inventado es propio. Las personas históricas reales se dibujan como nuestros propios personajes caricaturescos; nunca dibujes un personaje con derechos de autor.
3. Gancho primero. Los primeros 2 segundos deben abrir una pregunta; la pregunta del título nombra el tema.
4. Cada número se convierte en un objeto, que aparece en su palabra hablada. Nunca una superposición de texto plano.
5. Los gestos aterrizan 4 fotogramas antes de su palabra; los rostros cambian 2 fotogramas antes, mediante un parpadeo.
6. Cada acción visible tiene un sonido; no hay sonido sin una acción.
7. Cada fotograma se revisa (verificación automática de encuadre y escaneo de saltos, luego a ojo) antes de que el propietario lo vea.
8. Los hechos tienen fuente. Cuando las fuentes discrepan, usa palabras claras para matizar.
9. La marca del propietario: rostros con tonos de piel, los cinco colores de marca más Brand Red, y las tipografías incluidas: TeX Gyre Heros Bold + Instrument Serif Italic para subtítulos, Titan One para etiquetas (o Helvetica Bold con licencia + Editorial New Italic si el propietario las añade; di cuál). Todo en brand/.

Inicio rápido para un nuevo tema

1. Copia templates/new-film/ a examples/<slug-del-tema>/.
2. Completa la hoja de trabajo del nuevo tema (skill 1) y escribe el guión (skill 2) en SCRIPT dentro de film.mjs.
3. Construye las tomas con tiempos preliminares y renderiza imágenes del storyboard: node recipe/tools/render.mjs examples/<slug>/film.mjs <outDir> --stills shots --qa
4. Storyboard primero.
   • Copia templates/storyboard.json a examples/<slug>/storyboard/v1/storyboard-1.json, con un panel por toma y su imagen.
   • Dibuja el tablero: node recipe/tools/storyboard-board.mjs examples/<slug>/storyboard/v1/storyboard-1.json.
   • Entrega el tablero al propietario y revísalo (storyboard-2, …) hasta que lo apruebe.
   • Luego graba la voz: ELEVENLABS_API_KEY=… node recipe/tools/voiceover.mjs examples/<slug> (después de escribir vo/text.txt).
5. Vuelve a sincronizar con las palabras reales (automático), renderiza el video y luego el sonido: node recipe/tools/render.mjs examples/<slug>/film.mjs <out> --video --name silent.mp4 python -I recipe/tools/sound.py examples/<slug> <out>/silent.mp4 <out>/shots.json "<out>/<Título>.mp4"
6. Revisa: informe de encuadre, node recipe/tools/jump-scan.mjs <video> <out>/shots.json, python -I recipe/tools/sfx-levels.py <out> <out>/cue-sheet.txt, luego cada fotograma a ojo (skill 13).

Dónde están las cosas

Ruta	Qué
skills/	los 14 skills paso a paso
recipe/engine/	el motor de renderizado: core.mjs (aspecto, post-procesado, subtítulos, composición, controles), faces.mjs, character.mjs, props.mjs, props2.mjs, kit.mjs (lugares y preajustes de luz neutros al tema), places.mjs / places2.mjs (los lugares decorados del ejemplo), index.html, vendor/three (three.js r186, MIT), fonts/
recipe/tools/	storyboard-board.mjs (el tablero de storyboard del propietario, como PNG y página HTML interactiva), render.mjs, voiceover.mjs, sound.py, jump-scan.mjs, sfx-levels.py, paths.mjs (dónde se encuentran FFmpeg, Chrome y Playwright)
templates/	new-film/film.mjs (un iniciador neutro al tema que funciona con tiempos preliminares) y las hojas de trabajo
examples/how-gravity-was-found/	la película aprobada: fuente, voz, video final, storyboard, hoja de claves, pistas, versiones anteriores
references/	el estudio de referencia, la dirección del propietario, la API del motor, el catálogo de fallos, el historial de retroalimentación, notas del motor
brand/	los colores y tipografías de la película aprobada: palette.json, palette.css, style-sheet.png (dibujado por recipe/tools/style-sheet.mjs)
evaluation/	lista de verificación de entrega, criterios de aceptación, límites conocidos
preview/	style-card.json: el nombre del estilo, aspecto y formato en una tarjeta, apuntando al póster, película y storyboard del ejemplo

Configuración en una máquina nueva

Las herramientas necesitan:

• Node 22+;
• FFmpeg 6+ con ffprobe, en el PATH;
• Python 3.10+ con NumPy;
• una tarjeta gráfica que Chrome pueda usar para WebGL2.

En la carpeta del paquete, ejecuta npm install, npx playwright install chromium y pip install -r requirements.txt; el README tiene los pasos completos. Si FFmpeg está en otra ubicación, configura CARTOON_FFMPEG. Para usar otro Chrome, configura CARTOON_CHROME (consulta recipe/tools/paths.mjs).

Las películas deben estar dentro de la carpeta del paquete (examples/<slug>/), porque el renderizador sirve el paquete al navegador. La voz necesita una clave API de ElevenLabs con permiso de texto a voz, pasada como ELEVENLABS_API_KEY para el comando y nunca escrita en un archivo.