timeqsz/motion-atoms

Motion Atoms

Permite que o Agente crie animações a partir de descrições e também extraia ações e combinações reutilizáveis de vídeos de referência. O Agente é responsável por observar, entender o propósito e orquestrar; os átomos, validadores e ferramentas de renderização do pacote executam; o usuário não precisa escolher efeitos ou lembrar nomes de átomos. O pacote de distribuição contém 53 átomos 2D, divididos em 8 famílias, com implementação compartilhada com o site. Use caminhos relativos para acessar os recursos do pacote, sem depender do site online, repositório de código fonte ou instalação via npm. Para a primeira instalação, veja Instalação e Ambiente; o manifest.json registra a versão, arquivos e valores de verificação do pacote.

Leia por tarefa, não carregue todo o diretório de uma vez

Tarefa	Leia Primeiro	Em seguida, consulte
Gerar a partir de descrição, ou modificar efeitos existentes	Ciclo de Geração e Modificação	Mapeamento de Intenção
Decompor vídeo de referência, ou analisar como um movimento é implementado	Decomposição de Animação de Vídeo	Consulte a lista de átomos e uso com base na observação; use breakdown para capturar o vídeo original; separe por trilhas de tipo de animação, com separação clara entre trilhas; blocos de ação sem texto na mesma trilha são destacados individualmente
Animação 2D de texto, gráficos, propriedades	Catálogo 2D, filtre apenas a família necessária	atoms/<ID>.md e o .mjs de mesmo nome; Convenções de Entrada e Saída
Exportar arquivos de material 2D	Orquestração de Cena	scripts/motion.mjs; campos precisos em MotionSpec
Corrigir travamentos, deslocamentos, oclusão, ilegibilidade	Verificação de Tempo e Imagem	Corrija problemas reais e, em seguida, verifique os quadros e a reprodução afetados

Ao criar, defina primeiro o host, proporção de tela, taxa de quadros, alvo e entregável; ao decompor, confirme o vídeo assistível, o intervalo e o propósito da análise, preservando o código de tempo original. Mantenha as decisões já tomadas pelo usuário. Nomes, parâmetros e comportamentos de animação devem seguir as descrições do pacote.

Entregue o resultado solicitado pelo usuário, não apenas recomende átomos candidatos; para modificações de resultados existentes, preserve o arquivo de origem e verifique as alterações reais. O deliver 2D pode empacotar uma prévia independente, uma cena editável, recursos e um relatório de verificação; o relatório não deve disfarçar verificações numéricas como aceitação visual. Quando a capacidade implementada for insuficiente, explique a lacuna e, em seguida, use a implementação do host de chamada; não apresente efeitos semelhantes como se atendessem aos requisitos.

Núcleo da Criação

• Primeiro o propósito, depois a ação. Crie combinações para mostrar um produto, evento ou mudança de estado específico; cada átomo deve ter uma razão de ser. Consulte o sujeito, ritmo e transições de PVs reais; observe e extraia métodos após assistir, não copie cenas, não use ícones irrelevantes, controles falsos ou movimentos decorativos para preencher. Pequenos vídeos do site têm cerca de 5 segundos e 2–3 átomos; isso não é um limite de duração ou quantidade.
• Orquestre mudanças, não coloque efeitos especiais em pôsteres. Organize primeiro o principal e o secundário, depois descreva a entrada, mudança, estabilização e saída; as ações devem ter causalidade ou continuidade visual, com mudanças chave visíveis à primeira vista. Cada grupo deve usar métodos de entrada e saída adequados ao sujeito; após o texto parar, deixe tempo suficiente para leitura; remova texto pequeno e inútil.
• O movimento deve ser completo e coerente. Não interrompa prematuramente, não reproduza ao contrário uniformemente; ao editar, considere posição, direção, velocidade e brilho. Projete ações limitadas e loops contínuos separadamente; verifique o início e fim reais do loop; não use interpolação ou aumento da taxa de quadros nominal para esconder pausas.
• O sujeito como um todo. Imagens, logotipos e marcas compartilham coordenadas e pivôs corretos; máscaras reais e ordem de desenho determinam a oclusão. Verifique grupos de texto e detalhes na entrada e saída; não apenas mova o fundo; verifique alinhamento, nitidez e corte nas dimensões reais da tela e tamanho de exibição.
• Materiais servem à ação. Escolha materiais gratuitos para uso comercial que correspondam ao propósito e tenham licenças rastreáveis; lide com atribuição e distribuição de arquivos de origem conforme a licença; não use o mesmo material para preencher diferentes casos. Controle o volume de carregamento de material; ao referenciar a mesma cena para site e material promocional, sincronize materiais e movimentos.
• Aceite com a saída real. Verifique a reprodução real e o tamanho alvo em páginas web; ao criar vídeos, primeiro storyboard, depois renderize quadro a quadro, compile o vídeo, verifique a entrada/estabilização/saída/emendas após a codificação e reproduza completamente. Não afirme verificação de partes não visualizadas; entregue resultados reproduzíveis junto com o escopo da verificação. Para verificações técnicas específicas, veja Verificação de Tempo e Imagem.

2D: Incorporado no Host de Renderização

Copie apenas os .mjs necessários; copie atoms/draw.mjs apenas quando precisar desenhar. Os átomos são avaliados por quadros explícitos, sem reprodutor próprio. O host controla a ordem de desenho, coordenadas e tempo. As oito famílias respondem a uma pergunta cada: Propriedade (o que muda), Ritmo (como muda), Loop (movimento contínuo), Orquestração (quem vem primeiro), Transição (aparecer/desaparecer), Texto (movimento de texto), Textura (sobreposição), Geração (criação do nada).

import move from './atoms/prop.move.mjs';
import spring from './atoms/timing.spring.mjs';
import breathe from './atoms/loop.breathe.mjs';
import { drawAtom } from './atoms/draw.mjs';

const subject = { points: [[-50,-50],[50,-50],[50,50],[-50,50]], closed: true, fill: true };
const curve = (t) => spring({ frame: t, durationFrames: 1 }).value;   // Ritmo: apenas a curva
function renderFrame(ctx, frame) {
  const shape = move({ frame, durationFrames: 30, subject, params: { fromPx: -200, toPx: 0 }, ease: curve });
  const breath = breathe({ frame, startFrame: 30, durationFrames: 90 });   // Loop: sobreposto
  drawAtom(ctx, { ...shape, scale: shape.scale * breath.scale }, { x: 320, y: 200, color: '#f4f1ea' });
}

• params de funções independentes podem conter apenas as mudanças; MotionSpec clips deve conter todos os parâmetros. Não misture essas duas convenções.
• Ao combinar simultaneamente, verifique primeiro o papel e writes: deslocamento e ângulo são adicionados, escala, opacidade e estiramento são multiplicados, filtros são concatenados; átomos de orquestração retornam copies, e o host desenha cada um com o deslocamento e atraso da cópia. A saída de contorno de um único sujeito não pode ser feita espalhando dois layers com operador spread.
• Animações de propriedade do mesmo atributo em MotionSpec não podem ter tempo sobreposto; podem ser em sequência, com o valor final da anterior conectado ao valor inicial da próxima. Ritmo, loop, orquestração e textura são acumulativos. A exportação de arquivo não herdará automaticamente a estratégia de reprodução em loop do site.
• As coordenadas do gráfico são relativas à origem do sujeito; a posição do texto é a linha de base esquerda da primeira linha. Fontes do sistema (system, mono) podem ser usadas diretamente; fontes fixas são necessárias apenas para tipografia precisa entre máquinas.
• Exemplo mínimo executável: atoms/example.html, matriz × deslocamento × movimento × mola.

2D: Entregar Arquivos de Material

Os comandos abaixo são executados dentro do diretório motion-atoms/ extraído; a saída é gravada no diretório de trabalho do usuário. Antes de exportar, detecte o navegador/FFmpeg conforme necessário; não solicite essas ferramentas na consulta básica.

node scripts/motion.mjs describe transition.slices
node scripts/motion.mjs scaffold transition.slices --out work/slices.scene.json --width 1920 --height 1080 --fps 30 --duration 60
node scripts/motion.mjs validate work/slices.scene.json
node scripts/motion.mjs frames work/slices.scene.json --out work/check --frames 0,20,40,59 --transparent
node scripts/motion.mjs render work/slices.scene.json --out work/slices.mov --transparent

Cenas multi-átomo podem ser usadas diretamente, por exemplo:

node scripts/motion.mjs preview assets/examples/showcase.scene.json --out work/showcase.html
node scripts/motion.mjs breakdown assets/examples/showcase.scene.json --out work/showcase-breakdown.gif --title "Abertura · Decomposição de Átomos"

preview é HTML, não vídeo. render pode gerar MP4 (opaco), MOV / WebM (transparente); frames gera PNG; breakdown adiciona uma linha do tempo de átomos na parte inferior do quadro, gerando GIF, MP4 ou WebM: ao inserir uma cena, descreve a animação criada; ao inserir um arquivo de decomposição, captura o clipe do vídeo de referência para decomposição (veja Decomposição de Animação de Vídeo). verified: true apenas prova verificações de arquivo como dimensões, número de quadros e duração, não prova composição, ritmo ou oclusão corretos. Antes da entrega, veja Verificação de Imagem para verificar o resultado da codificação e reprodução real, e explique o escopo real da verificação. Retorna caminho do arquivo, caminho da cena, taxa de quadros, duração e canal alfa; esses materiais não têm trilha de áudio.

Limites de Capacidade

• A decomposição de vídeo é feita pelo Agente usando as ferramentas de reprodução, extração de quadros e áudio do host; o CLI do pacote não tem comandos de reconhecimento de vídeo; breakdown captura clipes do vídeo original com base no arquivo de decomposição escrito pelo Agente e desenha a linha do tempo de átomos na parte inferior. Ações além do escopo do pacote podem ser analisadas, mas deve-se distinguir entre diretamente utilizável, parcialmente aproximado e implementado separadamente pelo host; não afirme o projeto original, plugin ou parâmetros exatos a partir do vídeo final; os clipes capturados são apenas para análise, não republicados como material.
• A cena 2D tem apenas nós text / path, sem campos de imagem, vídeo, áudio, grupo pai-filho ou z-index. Saídas de propriedade, curva e cópia podem ser aplicadas pelo host a imagens ou vídeos; átomos geométricos lidam apenas com gráficos de polilinhas. O host é responsável pela composição de imagens e vídeos.
• Transições e texturas podem ser usadas para texto e gráficos; a caixa delimitadora de texto é medida com base na forma real da fonte durante a renderização. Loops e batidas não leem áudio.
• Os exemplos padrão e scaffold usam fontes do sistema; o pacote não carrega fontes. Quando a consistência entre máquinas é necessária, o host fornece fontes fixas licenciadas, declara caminho e hash, e verifica a forma da fonte.
• Atualmente não há átomos 3D; cenas 3D são implementadas pelo próprio host.
• A produção completa de vídeo continua a usar o storyboard, áudio, edição e fluxo de entrega do chamador; este Skill não impõe um host, estilo visual ou transição unificada.

Referências e Agradecimentos

O conceito inicial de indexação de animação do projeto MotionFlux ao qual este pacote pertence foi inspirado pela Tabela Periódica de Movimento de Kazuki Akamine. Agradecimentos pela inspiração na organização e exibição de animações básicas. MotionFlux é um projeto independente.