EffectCraft

EffectCraft — Agentenbetrieb

EffectCraft ist ein nativer Rust Motion-Graphics-/VFX-Compositor (After Effects-Klasse), dessen Agentenschnittstelle eingebaut ist: Jede Aktion ist ein Befehl mit einer ID. Die GUI, Menüs, die CLI, der Control-Channel und der MCP-Server treiben alle eine Engine an. Verifiziert gegen 0.17.0 unter Windows.

Maschinen- und Umgebungspfade

Plattform	Binärdatei	CLI	Standard-Datenverzeichnis
Windows	C:\Program Files\EffectCraft\effectcraft.exe	C:\Program Files\EffectCraft\effectcraft-cli.exe	%LOCALAPPDATA%\EffectCraft (Disk-Cache)
Linux	/usr/bin/effectcraft	/usr/bin/effectcraft-cli	~/.local/share/effectcraft

• Control-Port: --control <port> oder EFFECTCRAFT_CONTROL_PORT (kein Token – die Bridge akzeptiert einfache Loopback-Verbindungen, anders als FilmCraft)
• Befehle: 734 in 55 Namespaces (439 aktiviert in einem frischen Headless-Kontext; der Rest benötigt eine Auswahl / aktive Komp / Werkzeugmodus)
• Effekte: 307 in der Registry (list_effects); 149 Schriftfamilien (list_fonts)

Mentales Modell

• Ein Projekt (.ecproj) enthält Elemente: Composition, Folder, Solid, Footage. get_project gibt den Elementbaum, das Dirty-Flag und die aktive Komp zurück. Eine Komp ist aktiv; die meisten Befehle wirken auf sie.
• Eine Komp ist {width, height, frameRate, duration, startTime, background, renderer: classic3D|advanced3D}. Zeiten sind Sekunden (Fließkommazahlen, keine Ticks – es gibt hier keine Tick-Mathematik, anders als bei FilmCraft).
• Eine Ebene ist Text, Form, Vollton, Null, Komposition (Vorkomposition), Anpassungsebene, Licht oder Kamera. Ebenen stapeln sich: 1 = oben. Adressiere Ebenen nach id, #n (Stapel- index) oder name.
• Jede Ebene hat einen Eigenschaftsbaum: Transform (anchor, position, scale, rotation, opacity), plus effects, masks, Text oder Form contents. Eigenschaftspfade akzeptieren transform.position und Transform/Position — aber ein nacktes position (ohne Gruppe) wird abgelehnt.
• Animation = Keyframes auf Eigenschaften (prop.addKey) oder Ausdrücke (prop.setExpression, AE JavaScript). prop.get {time} gibt den interpolierten Wert, die Keyframe-Liste und das animated-Flag zurück.
• Parameter werden streng validiert: Ein unbekannter Parametername schlägt den Befehl mit der Liste der akzeptierten Schlüssel fehl; ebenso eine unbekannte Befehls-ID. Dies ist das Gegenteil von FilmCrafts stillschweigend fallengelassenen Parametern – lies den Fehler, behebe den Aufruf, wiederhole nicht blind.
• Verifiziere durch Rücklesen (get_state, get_project, get_comp, get_layer, get_property) oder durch Rendern (render_frame – ein PNG erkennt falsche Positionen, unsichtbare Ebenen und fehlende Effekte, die kein Rücklesen zeigt).

Zwei Verbindungsmodi

Modus	Start	Verwende für
Headless	effectcraft-cli mcp --demo (--project p.ecproj, --empty, --autosave)	kein Fenster, Batch-Builds, Renderings, Skripte
App-Bridge	effectcraft --control 50052 + effectcraft-cli mcp --bridge 50052	das echte Fenster: UI-Zustand, Screenshots, Klicks, Tasten, GUI-only-Befehle

Jeder CLI-Aufruf ist eine eigene Sitzung. Der in einem run aufgebaute Zustand ist weg, wenn der Prozess beendet wird – schließe mit file.saveAs + --save-as ab, oder erledige alles (Build → Render) in einem einzigen render/run-Aufruf.

EffectCraft auf Benutzerwunsch starten ("起動して" / "start EffectCraft")

1. Prüfe, ob es bereits läuft: Get-Process effectcraft / pgrep effectcraft. Wenn es läuft, teste den Port: effectcraft-cli --bridge 50052 info. Wenn es ohne Control-Port läuft, bitte den Benutzer, es mit --control neu zu starten (nicht gespeicherte Arbeit würde sonst verloren gehen).
2. Starte mit --control <port> (Standard 50052):
   • Windows — verwende scripts/launch.ps1 damit das Fenster auf dem sichtbaren Desktop erscheint, anstatt in einer Hintergrundsitzung: powershell -File scripts/launch.ps1 -Port 50052
   • Linux: ./scripts/launch.sh 50052
3. Verifiziere: warte 1–3 s, dann effectcraft-cli --bridge 50052 info — es gibt die Version, Befehls-/Effektanzahl und das geöffnete Projekt aus.

Die MCP-Werkzeuge

Headless bietet 27 Werkzeuge; die Bridge fügt 9 UI-Werkzeuge hinzu (ui_inspect, ui_elements, ui_click, ui_drag, ui_key, ui_set, ui_type, screenshot, control) plus script_ui für ScriptUI-Dialoge = 36.

Werkzeug	Zweck
command_list / list_commands	jeden Befehl (--filter, --enabled)
command_run / execute_command	führe einen {id, params} aus (rückgängig machbar)
command_batch / batch	mehrere Befehle, ein Rückgängig-Schritt (batch)
describe_command	Schema eines Befehls
doc_inspect / get_project	Projektbaum + aktive Komp in einem Aufruf
get_comp	eine Komp: Einstellungen, Ebenen, Arbeitsbereich
get_layer	den vollständigen Eigenschaftsbaum einer Ebene
get_property / set_property	lese / schreibe eine Eigenschaft (setze Keys bei Animation)
add_keyframe	Keyframes für eine Eigenschaft (schaltet die Stoppuhr ein)
add_effect / list_effects	wende einen Effekt an (+Parameter in einem Aufruf) / die 307-Effekt-Registry
list_fonts	149 Schriftfamilien, die von Textebenen verwendet werden können
run_script	After Effects-artiges ExtendScript (app.project, Komps, Ebenen)
render_frame / render_preview	PNG der (aktiven) Komp zu time
open_project / save_project	öffne (path, demo:true, empty:true) / speichere (+Speichern unter)
undo / redo / history	verzweigter Rückgängig-Verlauf
get_state	aktive Komp, aktuelle Zeit, Auswahl, Wiedergabe
script_ui	steuere ScriptUI-Dialoge/Paletten-Skripte, die geöffnet wurden

Ressourcen: effectcraft://document und effectcraft://commands.

Standard-Workflow

1. Erkunden. get_state + get_project; Headless startet leer, außer --demo/--project. ui_inspect zuerst im Bridge-Modus.
2. Erstellen. comp.new {name,width,height,frameRate,duration} → layer.newText/newShape/newSolid/newNull (Styling-Parameter inline) → file.import {paths} für Footage → layer.addItem-artige Platzierung.
3. Animieren. prop.addKey {layer,path,time,value} pro Key; keys.setEase, keys.interpolation, prop.setExpression.
4. Stilen. effect.apply {effect:"Gaussian Blur", layers:[id]} + Parameterpfade unter effects/#1/...; Masken (mask.new), Text-Animatoren, Formverlauf-Striche.
5. Verifizieren. get_property zu aussagekräftigen Zeiten; render_frame zu diesen Zeiten und die PNGs betrachten (Position, Easing und Weichzeichner sind alle sichtbar).
6. Rendern. render --out file.mp4 --format h264 (CLI), oder renderQueue.add + renderQueue.render; render-frame --transparent für RGBA; render --template t.ectemplate --values v.json für Vorlagenaufträge.
7. Speichern. file.saveAs {path} (oder CLI --save-as); erneut get_project lesen — das Dirty-Flag wird nach dem Speichern gelöscht.

Befehle finden

command_list {filter:"mask"} durchsucht ID, Bezeichnung und Menü. Von einer Shell: effectcraft-cli commands --filter mask, und describe_command/describe für das Schema eines einzelnen Befehls. Alle 734 IDs mit Parameterdokumentation befinden sich in references/catalog/commands.md; verifizierte Schritt-für-Schritt-JSONs sind in references/recipes.md.

Beginne mit: 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.

Fallstricke, die Zeit kosten

1. Strenge Validierung überall. Unbekannter Parameter → invalid parameters … accepted: name, width, … mit der vollständigen Schlüsselliste; unbekannte Befehls-ID → unknown command. Fehler sind die Dokumentation — aber ein gültiger Parameter mit einem falschen Werttyp kann sich dennoch falsch verhalten, daher lies den Zustand zurück.
2. Ebenenzeit vs. Kompositionszeit. Schreibbefehle (prop.addKey, keys.set, prop.set) nehmen time standardmäßig in Ebenensekunden (timeBase:"layer"|"comp" schaltet um); prop.get liest time in Kompositions- sekunden. Bei einer Ebene, die bei 0 beginnt, fallen sie zusammen; nach layer.move tun sie das nicht. Falsche Basis = Keys werden still um den Ebenenstart versetzt.
3. Viele Befehle benötigen eine Auswahl. prop.set, effect.apply, keys.easyEase zeigen enabled:false bei nichts Ausgewähltem (Headless startet leer). Übergib explizite layer/layers-Parameter, oder layer.select zuerst.
4. comp.new gibt {comp: id} zurück und macht diese Komp zur aktiven (verifiziert: zwei comp.new-Aufrufe, eine Textebene landet in der zweiten). Wechsle mit comp.open {comp: id|name} und bestätige via get_state — Befehle und Renderings, die auf "die aktive Komp" abzielen, schlagen mit no active composition in einem frischen --empty-Projekt vor dem ersten comp.new fehl.
5. Eigenschaftspfade benötigen die Gruppe: transform.position / Transform/Position funktionieren, nacktes position erzeugt einen Fehler mit no property. Finde genaue Pfade mit props <comp> <layer> --flat oder get_layer.
6. Effektparameter sind Pfade unter dem Effekt, z. B. effects/#1/Blurriness (Index = Anwendungsreihenfolge). effect.apply gibt paths:["effects/#1"] zurück — verwende sie.
7. Jeder CLI-Aufruf ist eine neue Sitzung (siehe oben). MCP-Sitzungen behalten den Zustand, bis der Server beendet wird.
8. render schreibt relatives --out in das Arbeitsverzeichnis des Prozesses; übergib immer einen absoluten Pfad für vorhersagbare Ausgabe.
9. Textebenen erhalten das vollständige Styling bei der Erstellung (layer.newText {size,fill,tracking,…} — Dutzende von Parametern). Späteres Umstyling erfolgt über Textquellen-/Dokumenteigenschaften; überprüfe get_layer auf die genauen Pfade.
10. Nur-GUI-Oberfläche: ui_*, screenshot, control, script_ui existieren nur auf der Bridge; window.*, view.* und help.* benötigen meist die GUI.
11. mcp --autosave speichert ungesicherte Headless-Bearbeitungen beim Beenden; ohne sie gehen sie verloren (erwartet für Wegwerf-Läufe, überraschend für echte Arbeit).

Referenzkarte

Datei	Inhalt
references/recipes.md	verifiziertes JSON: Build, Text, Form, Keyframes, Easing, Ausdrücke, Effekte, Masken, Rendern, Export, GUI
references/catalog/commands.md	alle 734 Befehle gruppiert nach Namespace mit Parameterdokumentation
references/mcp-and-control.md	die 27+9 Werkzeuge, Fehlerformen, Ressourcen, Bridge-Details
references/cli.md	effectcraft-cli-Unterbefehle, Render-Formate, Vorlagen, Bench
references/bugs-and-workarounds.md	reproduzierte Fehler mit minimalen Reproduktionen
references/maintenance.md	Version erneut verifizieren, Befehle ausgeben, diese Fähigkeit aktualisieren
scripts/probe.sh / .ps1	MCP-Handshake + Werkzeuganzahl + Version
scripts/dump-commands.sh / .ps1	den Befehlskatalog neu generieren
scripts/launch.sh / .ps1	die GUI mit einem Control-Port starten (sichtbarer Desktop)
scripts/smoke-test.sh / .ps1	Build → Keyframe → Render → validieren

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