EffectCraft

EffectCraft — operación del agente

EffectCraft es un compositor nativo de motion graphics / VFX escrito en Rust (clase After Effects) cuya interfaz de agente está integrada: cada acción es un comando con un id. La GUI, los menús, la CLI, el canal de control y el servidor MCP todos manejan el mismo motor. Verificado contra 0.17.0 en Windows.

Rutas de máquina y entorno

Plataforma	Binario	CLI	Directorio de datos por defecto
Windows	C:\Archivos de Programa\EffectCraft\effectcraft.exe	C:\Archivos de Programa\EffectCraft\effectcraft-cli.exe	%LOCALAPPDATA%\EffectCraft (Caché de disco)
Linux	/usr/bin/effectcraft	/usr/bin/effectcraft-cli	~/.local/share/effectcraft

• Puerto de control: --control <puerto> o EFFECTCRAFT_CONTROL_PORT (sin token — el puente acepta conexiones loopback simples, a diferencia de FilmCraft)
• Comandos: 734 en 55 namespaces (439 habilitados en un contexto headless fresco; el resto necesita una selección / comp activa / modo de herramienta)
• Efectos: 307 en el registro (list_effects); 149 familias de fuentes (list_fonts)

Modelo mental

• Un proyecto (.ecproj) contiene elementos: Composition, Folder, Solid, Footage. get_project devuelve el árbol de elementos, la bandera de sucio y la comp activa. Una comp está activa; la mayoría de los comandos actúan sobre ella.
• Una comp es {width, height, frameRate, duration, startTime, background, renderer: classic3D|advanced3D}. Los tiempos están en segundos (floats, no ticks — aquí no hay matemática de ticks, a diferencia de FilmCraft).
• Una capa es Texto, Forma, Sólido, Nulo, Composición (precomp), Ajuste, Luz o Cámara. Las capas se apilan 1 = arriba. Dirígete a las capas por id, #n (índice de pila) o name.
• Cada capa tiene un árbol de propiedades: Transform (anchor, position, scale, rotation, opacity), más effects, masks, contenido de texto o forma contents. Las rutas de propiedades aceptan transform.position y Transform/Position — pero un position desnudo (sin grupo) es rechazado.
• Animación = fotogramas clave en propiedades (prop.addKey) o expresiones (prop.setExpression, JavaScript de AE). prop.get {time} devuelve el valor interpolado, la lista de claves y la bandera animated.
• Los parámetros se validan estrictamente: un nombre de parámetro desconocido falla el comando con la lista de claves aceptadas; lo mismo ocurre con un id de comando desconocido. Esto es lo opuesto a los parámetros descartados silenciosamente de FilmCraft — lee el error, corrige la llamada, no reintentes a ciegas.
• Verifica leyendo de vuelta (get_state, get_project, get_comp, get_layer, get_property) o renderizando (render_frame — un PNG detecta posiciones incorrectas, capas invisibles y efectos faltantes que ninguna lectura de vuelta muestra).

Dos modos de conexión

Modo	Inicio	Úsalo para
Headless	effectcraft-cli mcp --demo (--project p.ecproj, --empty, --autosave)	sin ventana, builds por lotes, renders, scripts
Puente de app	effectcraft --control 50052 + effectcraft-cli mcp --bridge 50052	la ventana real: estado de UI, capturas de pantalla, clics, teclas, comandos solo de GUI

Cada invocación CLI es su propia sesión. El estado construido en una ejecución run se pierde cuando el proceso termina — finaliza con file.saveAs + --save-as, o haz todo (construir → renderizar) en una sola invocación render/run.

Lanzando EffectCraft a petición del usuario ("起動して" / "iniciar EffectCraft")

1. Verifica si ya está ejecutándose: Get-Process effectcraft / pgrep effectcraft. Si se está ejecutando, prueba el puerto: effectcraft-cli --bridge 50052 info. Si se ejecuta sin un puerto de control, pide al usuario que lo reinicie con --control (de lo contrario se perdería el trabajo no guardado).
2. Lanza con --control <puerto> (por defecto 50052):
   • Windows — usa scripts/launch.ps1 para que la ventana aparezca en el escritorio visible en lugar de una sesión en segundo plano: powershell -File scripts/launch.ps1 -Port 50052
   • Linux: ./scripts/launch.sh 50052
3. Verifica: espera 1–3 s, luego effectcraft-cli --bridge 50052 info — imprime la versión, los recuentos de comandos/efectos y el proyecto abierto.

Las herramientas MCP

El modo headless expone 27 herramientas; el puente añade 9 herramientas de UI (ui_inspect, ui_elements, ui_click, ui_drag, ui_key, ui_set, ui_type, screenshot, control) más script_ui para diálogos ScriptUI = 36.

Herramienta	Propósito
command_list / list_commands	cada comando (--filter, --enabled)
command_run / execute_command	ejecuta un {id, params} (deshacible)
command_batch / batch	varios comandos, un paso de deshacer (batch)
describe_command	esquema de un comando
doc_inspect / get_project	árbol del proyecto + comp activa en una llamada
get_comp	una comp: ajustes, capas, área de trabajo
get_layer	árbol completo de propiedades de una capa
get_property / set_property	leer / escribir una propiedad (establece claves cuando está animada)
add_keyframe	fotogramas clave para una propiedad (activa el cronómetro)
add_effect / list_effects	aplicar un efecto (+params en una llamada) / el registro de 307 efectos
list_fonts	149 familias de fuentes utilizables por capas de texto
run_script	ExtendScript al estilo After Effects (app.project, comps, capas)
render_frame / render_preview	PNG de la comp (activa) en time
open_project / save_project	abrir (path, demo:true, empty:true) / guardar (+Guardar como)
undo / redo / history	historial de deshacer ramificado
get_state	comp activa, tiempo actual, selección, reproducción
script_ui	manejar diálogos/paletas ScriptUI de scripts abiertos

Recursos: effectcraft://document y effectcraft://commands.

Flujo de trabajo estándar

1. Sondear. get_state + get_project; headless comienza vacío a menos que --demo/--project. ui_inspect primero en modo puente.
2. Construir. comp.new {name,width,height,frameRate,duration} → layer.newText/newShape/newSolid/newNull (parámetros de estilo en línea) → file.import {paths} para material de archivo → colocación al estilo layer.addItem.
3. Animar. prop.addKey {layer,path,time,value} por clave; keys.setEase, keys.interpolation, prop.setExpression.
4. Estilizar. effect.apply {effect:"Desenfoque gaussiano", layers:[id]} + rutas de parámetros bajo effects/#1/...; máscaras (mask.new), animadores de texto, trazos de degradado de forma.
5. Verificar. get_property en momentos clave; render_frame en esos momentos y mirar los PNG (posición, easing y desenfoque son todos visibles).
6. Renderizar. render --out archivo.mp4 --format h264 (CLI), o renderQueue.add + renderQueue.render; render-frame --transparent para RGBA; render --template t.ectemplate --values v.json para trabajos con plantilla.
7. Guardar. file.saveAs {path} (o CLI --save-as); releer get_project — la bandera de sucio se limpia después de guardar.

Encontrar comandos

command_list {filter:"mask"} coincide con id, etiqueta y menú. Desde un shell: effectcraft-cli commands --filter mask, y describe_command/describe para el esquema de un comando. Los 734 ids con documentación de parámetros están en references/catalog/commands.md; JSON verificado paso a paso en references/recipes.md.

Comienza con: 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.

Errores que cuestan tiempo

1. Validación estricta en todas partes. Parámetro desconocido → invalid parameters … accepted: name, width, … con la lista completa de claves; id de comando desconocido → unknown command. Los errores son la documentación — pero un parámetro válido con un tipo de valor incorrecto aún puede comportarse mal, así que lee el estado de vuelta.
2. Tiempo de capa vs tiempo de composición. Los comandos de escritura (prop.addKey, keys.set, prop.set) toman time en segundos de capa por defecto (timeBase:"layer"|"comp" cambia); prop.get lee time en segundos de comp. Con una capa que comienza en 0 coinciden; después de layer.move no. Base incorrecta = claves desplazadas silenciosamente por el inicio de la capa.
3. Muchos comandos necesitan una selección. prop.set, effect.apply, keys.easyEase muestran enabled:false sin nada seleccionado (headless comienza vacío). Pasa parámetros explícitos layer/layers, o layer.select primero.
4. comp.new devuelve {comp: id} y la convierte en la comp activa (verificado: dos llamadas comp.new, una capa de texto aterriza en la segunda). Cambia con comp.open {comp: id|name} y confirma mediante get_state — los comandos y renders que apuntan a "la comp activa" fallan con no active composition en un proyecto --empty fresco antes del primer comp.new.
5. Las rutas de propiedades necesitan el grupo: transform.position / Transform/Position funcionan, position desnudo da error con no property. Encuentra rutas exactas con props <comp> <layer> --flat o get_layer.
6. Los parámetros de efectos son rutas bajo el efecto, p.ej. effects/#1/Blurriness (índice = orden de aplicación). effect.apply devuelve paths:["effects/#1"] — úsalos.
7. Cada invocación CLI es una sesión fresca (ver arriba). Las sesiones MCP mantienen el estado hasta que el servidor termina.
8. render escribe --out relativo al directorio de trabajo del proceso; pasa siempre una ruta absoluta para una salida predecible.
9. Las capas de texto toman el estilo completo en la creación (layer.newText {size,fill,tracking,…} — docenas de parámetros). El reestilizado posterior pasa por propiedades de fuente/documento de texto; comprueba get_layer para las rutas exactas.
10. Superficie solo GUI: ui_*, screenshot, control, script_ui existen solo en el puente; window.*, view.* y help.* necesitan principalmente la GUI.
11. mcp --autosave persiste las ediciones headless no guardadas al salir; sin ellas se pierden (esperado para ejecuciones desechables, sorprendente para trabajo real).

Mapa de referencia

Archivo	Contenido
references/recipes.md	JSON verificado: construir, texto, forma, fotogramas clave, easing, expresiones, efectos, máscaras, render, exportar, GUI
references/catalog/commands.md	los 734 comandos agrupados por namespace con documentación de parámetros
references/mcp-and-control.md	las 27+9 herramientas, formas de error, recursos, detalles del puente
references/cli.md	subcomandos de effectcraft-cli, formatos de render, plantillas, bench
references/bugs-and-workarounds.md	defectos reproducidos con reproducciones mínimas
references/maintenance.md	re-verificar la versión, volcar comandos, refrescar esta habilidad
scripts/probe.sh / .ps1	handshake MCP + recuento de herramientas + versión
scripts/dump-commands.sh / .ps1	regenerar el catálogo de comandos
scripts/launch.sh / .ps1	iniciar la GUI con un puerto de control (escritorio visible)
scripts/smoke-test.sh / .ps1	construir → fotograma clave → renderizar → validar

Comunidad: https://discord.gg/artcraft · https://getartcraft.com/apps/effectcraft.