EffectCraft

EffectCraft — operação do agente

EffectCraft é um compositor nativo em Rust para motion graphics / VFX (classe After Effects) cuja interface de agente é embutida: cada ação é um comando com um id. A GUI, menus, a CLI, o canal de controle e o servidor MCP acionam o mesmo motor. Verificado na versão 0.17.0 no Windows.

Caminhos da máquina e ambiente

Plataforma	Binário	CLI	Diretório de Dados Padrão
Windows	C:\Program Files\EffectCraft\effectcraft.exe	C:\Program Files\EffectCraft\effectcraft-cli.exe	%LOCALAPPDATA%\EffectCraft (Cache de Disco)
Linux	/usr/bin/effectcraft	/usr/bin/effectcraft-cli	~/.local/share/effectcraft

• Porta de controle: --control <porta> ou EFFECTCRAFT_CONTROL_PORT (sem token — a ponte aceita conexões loopback simples, diferente do FilmCraft)
• Comandos: 734 em 55 namespaces (439 habilitados em contexto headless novo; o restante precisa de seleção / comp ativo / modo de ferramenta)
• Efeitos: 307 no registro (list_effects); 149 famílias de fontes (list_fonts)

Modelo mental

• Um projeto (.ecproj) contém itens: Composition, Folder, Solid, Footage. get_project retorna a árvore de itens, a flag dirty e o comp ativo. Um comp está ativo; a maioria dos comandos age sobre ele.
• Um comp é {width, height, frameRate, duration, startTime, background, renderer: classic3D|advanced3D}. Tempos são em segundos (floats, não ticks — sem matemática de ticks aqui, diferente do FilmCraft).
• Uma camada é Texto, Forma, Sólido, Nulo, Composição (precomp), Ajuste, Luz ou Câmera. As camadas empilham 1 = topo. Enderece camadas por id, #n (índice da pilha) ou nome.
• Toda camada tem uma árvore de propriedades: Transform (anchor, position, scale, rotation, opacity), mais effects, masks, conteúdo de texto ou forma. Caminhos de propriedade aceitam transform.position e Transform/Position — mas um position simples (sem grupo) é rejeitado.
• Animação = keyframes em propriedades (prop.addKey) ou expressões (prop.setExpression, JavaScript do After Effects). prop.get {time} retorna o valor interpolado, a lista de keyframes e a flag animated.
• Parâmetros são validados estritamente: um nome de parâmetro desconhecido falha o comando com a lista de chaves aceitas; o mesmo para um id de comando desconhecido. Isso é o oposto do FilmCraft, que descarta parâmetros silenciosamente — leia o erro, corrija a chamada, não tente novamente cegamente.
• Verifique lendo de volta (get_state, get_project, get_comp, get_layer, get_property) ou renderizando (render_frame — um PNG captura posições erradas, camadas invisíveis e efeitos ausentes que nenhuma leitura mostra).

Dois modos de conexão

Modo	Iniciar	Usar para
Headless	effectcraft-cli mcp --demo (--project p.ecproj, --empty, --autosave)	sem janela, builds em lote, renderizações, scripts
Ponte do app	effectcraft --control 50052 + effectcraft-cli mcp --bridge 50052	a janela real: estado da UI, capturas de tela, cliques, teclas, comandos apenas da GUI

Cada invocação da CLI é sua própria sessão. O estado construído em uma execução run se perde quando o processo sai — termine com file.saveAs + --save-as, ou faça tudo (construir → renderizar) em uma única invocação render/run.

Iniciando EffectCraft por solicitação do usuário ("起動して" / "start EffectCraft")

1. Verifique se já está em execução: Get-Process effectcraft / pgrep effectcraft. Se estiver em execução, teste a porta: effectcraft-cli --bridge 50052 info. Se estiver em execução sem uma porta de controle, peça ao usuário para reiniciá-lo com --control (trabalho não salvo seria perdido caso contrário).
2. Inicie com --control <porta> (padrão 50052):
   • Windows — use scripts/launch.ps1 para que a janela apareça na área de trabalho visível em vez de uma sessão em segundo plano: powershell -File scripts/launch.ps1 -Port 50052
   • Linux: ./scripts/launch.sh 50052
3. Verifique: aguarde 1–3 s, depois effectcraft-cli --bridge 50052 info — ele imprime a versão, contagens de comandos/efeitos e o projeto aberto.

As ferramentas MCP

Headless expõe 27 ferramentas; a ponte adiciona 9 ferramentas de UI (ui_inspect, ui_elements, ui_click, ui_drag, ui_key, ui_set, ui_type, screenshot, control) mais script_ui para diálogos ScriptUI = 36.

Ferramenta	Propósito
command_list / list_commands	todos os comandos (--filter, --enabled)
command_run / execute_command	executa um {id, params} (desfazível)
command_batch / batch	vários comandos, uma etapa de desfazer (batch)
describe_command	esquema de um comando
doc_inspect / get_project	árvore do projeto + comp ativo em uma chamada
get_comp	um comp: configurações, camadas, área de trabalho
get_layer	árvore completa de propriedades de uma camada
get_property / set_property	ler / escrever uma propriedade (definir keyframes quando animado)
add_keyframe	keyframes para uma propriedade (ativa o cronômetro)
add_effect / list_effects	aplicar um efeito (+parâmetros em uma chamada) / o registro de 307 efeitos
list_fonts	149 famílias de fontes utilizáveis por camadas de texto
run_script	ExtendScript estilo After Effects (app.project, comps, camadas)
render_frame / render_preview	PNG do comp (ativo) em time
open_project / save_project	abrir (path, demo:true, empty:true) / salvar (+ Salvar Como)
undo / redo / history	histórico de desfazer com ramificação
get_state	comp ativo, tempo atual, seleção, reprodução
script_ui	acionar diálogos/paletas ScriptUI de scripts abertos

Recursos: effectcraft://document e effectcraft://commands.

Fluxo de trabalho padrão

1. Sondar. get_state + get_project; headless inicia vazio a menos que --demo/--project. ui_inspect primeiro no modo ponte.
2. Construir. comp.new {name,width,height,frameRate,duration} → layer.newText/newShape/newSolid/newNull (parâmetros de estilo inline) → file.import {paths} para footage → colocação layer.addItem.
3. Animar. prop.addKey {layer,path,time,value} por keyframe; keys.setEase, keys.interpolation, prop.setExpression.
4. Estilizar. effect.apply {effect:"Gaussian Blur", layers:[id]} + caminhos de parâmetros sob effects/#1/...; máscaras (mask.new), animadores de texto, traços de gradiente de forma.
5. Verificar. get_property em momentos relevantes; render_frame nesses momentos e veja os PNGs (posição, easing e desfoque são todos visíveis).
6. Renderizar. render --out file.mp4 --format h264 (CLI), ou renderQueue.add + renderQueue.render; render-frame --transparent para RGBA; render --template t.ectemplate --values v.json para trabalhos de modelo.
7. Salvar. file.saveAs {path} (ou CLI --save-as); releia get_project — a flag dirty limpa após salvar.

Encontrando comandos

command_list {filter:"mask"} encontra id, rótulo e menu. De um shell: effectcraft-cli commands --filter mask, e describe_command/describe para o esquema de um comando. Todos os 734 ids com documentação de parâmetros estão em references/catalog/commands.md; JSON verificado passo a passo está em references/recipes.md.

Comece com: comp.new, comp.settings, comp.open, layer.newText, layer.newShape, layer.newSolid, layer.newNull, layer.select, layer.moveLater, layer.setTransform, layer.setText, prop.get, prop.set, prop.addKey, keys.setEase, keys.interpolation, prop.setExpression, effect.apply, mask.new, time.set, file.import, file.saveAs, renderQueue.add, renderQueue.render, app.quit.

Armadilhas que custam tempo

1. Validação estrita em todo lugar. Parâmetro desconhecido → invalid parameters … accepted: name, width, … com a lista completa de chaves; id de comando desconhecido → unknown command. Erros são a documentação — mas um parâmetro válido com um tipo de valor errado ainda pode se comportar mal, então leia o estado de volta.
2. Tempo de camada vs tempo de composição. Comandos de escrita (prop.addKey, keys.set, prop.set) recebem time em segundos de camada por padrão (`timeBase:"layer"|