Muelles (paso del curso 08)
Transiciones suaves y económicas de A a B sobre una curva fija. El movimiento con masa acelera, sobrepasa ligeramente y se estabiliza. Los
muelles en lib/motion.js son respuestas de paso en forma cerrada, por lo que siguen siendo una función pura del tiempo: el fotograma 812 se renderiza
sin simular los fotogramas 0 al 811, y seek(t) sigue siendo determinista.
Importa desde lib/motion.js del proyecto de la película (rutas relativas al archivo: ../lib/motion.js desde film/film.js,
../../lib/motion.js desde film/scenes/*.js). Los números completos de los ajustes predefinidos se encuentran en
${CLAUDE_SKILL_DIR}/references/presets.md (references/presets.md).
1. API
| Función | Devuelve | Notas |
|---|---|---|
sp(t, preset = 'default') | 0 a 1 | la llamada cotidiana; t es el tiempo desde la liberación (lt - 0.2), 0 antes de la liberación |
spring(t, k, d, m = 1) / springVel(...) / springPV(...) | x / v / [x, v] | forma k/d pura; subamortiguado, críticamente amortiguado y sobreamortiguado exactos |
SPRINGS | { snappy, default, heavy, playful } | pares {k, d}, ver la tabla a continuación |
resolveSpring(p) | {k, d} | acepta un nombre de ajuste predefinido, {k, d} o {duration, bounce} en cualquier lugar donde se espere un muelle |
springFromFeel({ duration, bounce }) / feelFromSpring({k, d}) | {k, d} / {duration, bounce} | parámetros amigables para el diseñador (convención de Apple) |
track(t, keys, spring = 'default') / trackVel(...) | valor / velocidad | keys = [[time, value], ...] ordenados; un muelle por cambio, sumados; un tercer elemento opcional anula el muelle para ese cambio ([2.4, 420, 'heavy']) |
loopTrack(t, keys, dur, spring = 'default', cycles = null) | valor | bucles sin costuras. Los tiempos clave están dentro de un ciclo, 0..dur, y no se envuelven (fuera lanza error). El último valor debe ser igual al primero. Una clave exactamente en dur es el cambio de costura |
indicator(t, stops, { width = 120, lead = 'snappy', trail = {k: 140, d: 22} }) | { left, right } | indicador de pestaña que se estira: bordes en diferentes muelles |
swapAlpha(t, tIn, tOut, { inDelay = 0.08, inDur = 0.12, outLead = 0.1, outDur = 0.1 }) | 0 a 1 | texto dentro de un cuadro que se transforma: entra después de que comienza la transformación, sale antes de la siguiente |
stagger(i, step = 0.03) | segundos | retardo para el elemento i |
stepTime(t, rate = 12) | t escalonado | "en doses" solo para dibujos, nunca para la cámara o fundidos globales. Pasa c.frameLt (o c.frameT), el tiempo del fotograma de salida, para un corte brusco entre pasos; c.t / lt son tiempos de subfotograma y mezclan los dos pasos en los fotogramas donde cambia un paso |
loopT(t, dur) | t envuelto en [0, dur) | envoltura de tiempo; no es suficiente por sí solo para muelles (usa loopTrack) |
settleTime(spring, eps = 0.01) / overshoot(spring) | segundos / fracción | planificar esperas y puntos de corte |
easeOutCubic, easeInOutCubic | 0 a 1 | solo para fundidos no físicos (opacidad); nunca para cosas que se mueven |
2. Ajustes predefinidos
| Ajuste predefinido | k / d | Relación de amortiguamiento | Sobrepaso | Se estabiliza (1%) | Úsalo para |
|---|---|---|---|---|---|
snappy | 320 / 30 | 0.839 | 0.79% | 0.24 s | botones, alternadores, bordes principales, cursor |
default | 170 / 26 | 0.997 | 0 | 0.51 s | tarjetas, contenedores, cámara |
heavy | 90 / 20 | 1.054 | 0 | 0.78 s | textos grandes, objetos 3D, logotipos |
playful | 220 / 14 | 0.472 | 18.6% | 0.59 s | mascotas, pegatinas |
Regla de la casa: pequeño sobrepaso en la interfaz de usuario (snappy), ninguno en el texto (default o heavy para escala y posición del texto principal),
playful solo donde el sobrepaso sea la gracia. Números completos, conversiones de sensación y fórmulas:
references/presets.md.
3. Recetas
Dentro de una escena draw(g, lt, c): lt es el tiempo desde que comenzó la escena, c.t el tiempo de la película, c.L el diseño,
c.brand los tokens de la marca, c.grid la cuadrícula de tiempos, c.film.dur la duración de la película (c.dur es la duración de la escena). Con
el desenfoque de movimiento activado, c.t y lt son los tiempos de subfotograma que se están pintando (el desenfoque de movimiento se difumina por sí mismo); c.frameT / c.frameLt
son el tiempo del fotograma de salida y c.frame su índice, idéntico para cada subfotograma. Los fragmentos asumen
const { t, L } = c; e importaciones de lib/motion.js, lib/draw.js y lib/rng.js.
Entrada única (liberación 0.15 s después del inicio de la escena):
const s = sp(lt - 0.15, 'snappy');
withTransform(g, { x: L.cx, y: lerp(L.cy + 80 * L.u, L.cy, s), s: lerp(0.92, 1, s) }, () => { /* dibujar */ });
Este comienza visible: la posición y la escala están en sus valores iniciales mientras el muelle está en 0, por lo que el fotograma 0 no está vacío.
Estaría vacío si s impulsara lo único en pantalla a través de la opacidad o un recorte. Para una escena que está en pantalla en el
fotograma 0 (el gancho), abre a mitad de la acción liberando el muelle ANTES de la escena: sp(lt + 0.3, 'snappy'), o
kinetic(g, 'HAZLO MOVER.', x, y, lt + 0.3, { ... }), o kinetic(..., { delay: -0.3 }). En lt = 0, el texto está entonces a 0.3 s
de su subida en lugar de no dibujarse (kinetic omite cada glifo cuyo muelle aún está en 0). La crítica marca un fotograma 0 vacío
como P0 (el fotograma 0 está casi vacío).
Un valor con varios destinos (nunca reinicies un muelle; añade uno por cambio):
// cursor x en píxeles lógicos: reposa en 200, se mueve en 1.0 s y 2.4 s, regresa en 3.6 s
const cx = track(t, [[0, 200 * L.u], [1.0, 640 * L.u], [2.4, 420 * L.u], [3.6, 200 * L.u]], 'snappy');
El tiempo de la primera clave se ignora: su valor es el valor de reposo desde el inicio. Cada cambio después de eso inicia su propio muelle en su propio momento, y la suma permanece continua en posición y velocidad incluso cuando un nuevo destino llega antes de que el anterior se haya estabilizado.
Transformación de una sola forma (el contenedor nunca se corta; cada propiedad es una pista en los mismos tiempos clave):
const K = [0, 1, 2, 3].map((n) => c.grid.bar(n)); // cambios de estado en los tiempos fuertes, desde la cuadrícula
const w = track(t, [[K[0], 320], [K[1], 120], [K[2], 760], [K[3], 320]].map(([k, v]) => [k, v * L.u]));
const h = track(t, [[K[0], 96], [K[1], 120], [K[2], 480], [K[3], 96]].map(([k, v]) => [k, v * L.u]));
const r = track(t, [[K[0], 48], [K[1], 60], [K[2], 32], [K[3], 48]].map(([k, v]) => [k, v * L.u]));
fillRoundRect(g, L.cx - w / 2, L.cy - h / 2, w, h, Math.max(0, r), c.brand.colors.fg);
withAlpha(g, swapAlpha(t, K[1], K[2]), () => ring(g, L.cx, L.cy, 36 * L.u, sp(t - K[1] - 0.1), { color: c.brand.colors.accent }));
Colores: lleva un progreso de 0 a 1 con muelle y mezcla con mixColor(a, b, p) de lib/draw.js (limita p), o, para un color
con varios destinos, sigue cada canal y limita a 0 a 255. El radio y los tamaños que pueden sobrepasar por debajo de cero necesitan
Math.max(0, ...).
Indicador de pestaña que se estira entre paradas:
const { left, right } = indicator(t, [[0, x0], [1.5, x1], [3.0, x2]], { width: 140 * L.u });
fillRoundRect(g, left, y, right - left, 6 * L.u, 3 * L.u, c.brand.colors.accent);
Bucle sin costuras (el valor y su velocidad coinciden a través de la costura):
// bucle de 6 s: a en reposo, b en 1.5 s, c2 en 3 s, de vuelta a a en 4.5 s
const x = loopTrack(t, [[0, a], [1.5, b], [3, c2], [4.5, a]], c.film.dur, 'default');
// el mismo bucle con el retorno como cambio de costura: la última clave está exactamente en dur
const y = loopTrack(t, [[0, a], [1.5, b], [3, c2], [c.film.dur, a]], c.film.dur, 'default');
Reglas de loopTrack (verificadas con lib/motion.js):
| Regla | Detalle |
|---|---|
los tiempos clave permanecen en 0..dur | son relativos al ciclo y nunca se envuelven; un tiempo fuera lanza loopTrack: key <i> time <t> is outside 0..<dur> (se tolera un pelo más allá de dur por la aritmética de la cuadrícula) |
| la primera clave es el valor de reposo | su tiempo se ignora (aún debe estar en 0..dur); el valor es desde el que comienza el primer cambio |
| el último valor es igual al primero | de lo contrario, lanza the last value (...) must equal the first (...) |
una clave en dur es el cambio de costura | el muelle comienza en t = 0 del siguiente ciclo: el fotograma 0 (= fotograma dur) muestra el valor anterior a la costura y se suaviza hasta el primer valor. Equivale a escribir [[0, pre], [0, post], ...]. Escribe el cambio de costura una vez, en 0 o en dur |
un cambio justo antes de dur aún puede estar moviéndose en el fotograma 0 | la suma es exactamente periódica, por lo que la posición y la velocidad coinciden a través de la costura independientemente del tiempo. Para abrir en un fotograma fijo, mantén el último cambio al menos settleTime(preset) antes de dur (0.51 s para default) |
| ciclos | el número de ciclos anteriores sumados sigue el tiempo de estabilización y la clave más reciente, por lo que las claves tardías son seguras; cycles lo anula |
loopT simple más track saltan en la costura porque los muelles liberados cerca del final aún se están moviendo en t = 0.
loopTrack también suma los muelles de ciclos anteriores (suficientes para estabilizarse) y da, con las claves
[[0, 0], [2, 100], [4, 40], [6, 0]] y dur 6, los valores 0.001 / 99.997 / 40.002 en t = 1 / 3 / 5. Verifica la costura
en out/review/<fmt>/loop.png después de npm run critique: |last - first| debería verse como un paso normal y
|end - first| (el estado final no envuelto) debería ser negro.
Apariciones escalonadas (semillas por elemento, nunca un flujo compartido):
for (let i = 0; i < n; i++) {
const r = rngFor('tile', i);
const s = sp(lt - stagger(i, 0.035) - range(r, 0, 0.06), 'playful');
// dibujar el mosaico i escalado por s
}
Texto cinético: kinetic(g, str, x, y, lt, { size, family, weight, color, spring: 'snappy', stagger: 0.035, rise: 0.6, by: 'char' | 'word', mask, delay, alpha, align, baseline, style, tracking }). family por defecto a brand.fonts.display y weight al peso más cercano
que la familia tenga registrado, así que omite ambos a menos que el diseño requiera otra cara. mask: true recorta la ejecución a su
caja de línea para que los glifos surjan desde detrás de un borde en lugar de desvanecerse; delay desplaza toda la ejecución (negativo abre a mitad de la acción).
Para texto principal, pasa spring: 'default' o 'heavy' cuando la subida sea lo suficientemente grande como para que se muestre un sobrepaso del 0.8%.
Texto multilínea: wrapText(g, text, maxW, font(size, family)) devuelve las líneas (nunca cortando dentro de una sílaba Hangul);
dibújalas con y + i * 1.2 * size o más y dale a cada línea su propio delay.
Dibujos en doses (aspecto dibujado a mano): const td = stepTime(c.frameLt, 12) para la animación propia del dibujo (el tiempo del fotograma de
salida, por lo que cada paso es un corte brusco incluso con el desenfoque de movimiento activado); mantén los movimientos de cámara, los fundidos y la interfaz de usuario en
lt continuo, o los desplazamientos panorámicos dan pasos 12 veces por segundo y se leen como retraso.
4. Refactorizar una película completa
Usa la plantilla de indicaciones en el proyecto: lee prompts/refactor-springs.txt y síguela (o pégala como una tarea). Reemplaza
cada interpolación lineal y suavizado estándar que mueva algo con ajustes predefinidos, track(), loopTrack(),
indicator() y swapAlpha(), mantiene el tiempo e informa cada cambio. Luego:
npm run lint(debe estar limpio).npm run stillsynode tools/critique.mjs --strip-at <t>en el momento más concurrido:strip.pngmuestra 12 fotogramas consecutivos, lo que expone pops, reinicios y deslizamientos que una hoja de contactos oculta.- Registra el cambio en la siguiente ronda de crítica (
/motion-studio:critique-loop).
5. Errores a detectar
| Error | Aspecto | Solución |
|---|---|---|
reiniciar un muelle en cada destino (sp(t - tNew) desde el valor antiguo) | la velocidad salta a 0, un quiebre visible | track() con todos los destinos |
| sumas hechas a mano de muelles con sus propios valores iniciales | saltos cuando dos cambios se superponen | un track() por valor; los ajustes predefinidos por cambio van en el tercer elemento de la clave |
loopT solo en un valor de muelle | salto en la costura | loopTrack() con claves en 0..dur y último valor == primero |
| sobrepaso en el texto | el texto vibra, se ve barato | default / heavy para el texto |
playful en elementos de la interfaz de usuario | interfaz de aspecto de juguete | snappy para la interfaz de usuario |
| muelle solo en la opacidad mientras la posición es lineal | se desvanece bien, se desliza barato | usa muelle para la posición; la opacidad puede seguir easeOutCubic |
| todo en el mismo ajuste predefinido y retardo | mecánico, sin jerarquía | lidera con snappy, continúa con default, stagger() el resto |
Siguiente: /motion-studio:sound-design para sincronizar el movimiento con el ritmo, luego /motion-studio:critique-loop.