FunwayHQ/quar-design

Entwerfen und Animieren in Quar Animator

Quar Animator ist ein 2D-Vektor-Animationseditor; seine MCP-Tools lesen und bearbeiten die Cloud-Projekte des Benutzers. Du arbeitest wie ein Motion Designer, der seine Arbeit sehen kann: planen, bauen, schauen, korrigieren, animieren, die Bewegung anschauen, exportieren. Jeder Blick ist ein Bild vom Server – vertraue ihm mehr als dem, was du machen wolltest.

Wenn die quar-animator Tools nicht verfügbar sind, sag das und verweise den Benutzer auf die Einrichtung in der README dieser Fähigkeit (verbinde den MCP unter https://api.animator.quar.pro/mcp); improvisiere keine andere Möglichkeit, die Datei zu erstellen.

Die Schleife

1. Lesen. list_projects (oder create_project {name} für einen Neuanfang – gib dem Benutzer dessen editorUrl, die es im Editor öffnet; ein Projekt, das als stillUploading markiert ist, hat noch keine Version, seine Videos werden noch vom Editor hochgeladen: nichts zu öffnen, bis es eine hat), dann get_scene_context {project_id}. Beachte die seq – übergib sie als base_seq bei jeder Bearbeitung, damit ein Bearbeitungsschritt fehlschlägt, anstatt auf Änderungen zu landen, die du nicht gesehen hast. Beachte frameRate, duration, artboardTimelines und was gesperrt ist (das des Benutzers: lass es in Ruhe, es sei denn, du wirst darum gebeten).
2. Planen, bevor du etwas anfasst: der Rahmen (Artboard-Größe), das Layout, die Palette, die Schriftart, was sich bewegt und wann. Schreibe den Plan in ein paar Zeilen für den Benutzer auf. Verwende reference/design.md und reference/motion.md; folge für eine bekannte Art von Stück dem Rezept in recipes/.
3. Bauen mit einem Probelauf. Ein apply_edit_batch für einen zusammenhängenden Schritt (der Hintergrund, das Layout, die Schriftart…) mit dry_run: true. Es speichert nichts und gibt zurück, was sich ändern würde: placed – die at- und bounds-Werte jedes hinzugefügten oder geänderten Knotens im hypothetischen Ergebnis, um ein Layout vor dem Speichern zu messen – und ein Bild (preview_frame; preview_node, um ein Artboard oder einen Knoten anzuzeigen; preview_size bis zu 1024). Gib add_node deine eigenen IDs ("id": "title"), damit spätere Operationen im Batch darauf verweisen können.
4. Schauen und korrigieren. Beurteile das Bild anhand der Checkliste in reference/design.md: Ausrichtung, Abstände, Hierarchie, Kontrast, nichts abgeschnitten. Korrigiere den Batch und führe den Probelauf erneut durch, bis es stimmt. Sende ihn dann ohne dry_run, mit einer message („Layout: Titel, Untertitel und Logo“).
5. Animieren auf die gleiche Weise: animate-Operationen (eine pro Eigenschaft, die gesamte Kurve auf einmal) in einem Batch, Probelauf mit preview_frame an einem aussagekräftigen Zeitpunkt, dann festschreiben.
6. Die Bewegung anschauen. render_preview mit count: 8–12 (verteilt über die Timeline dessen, was es zeichnet – die eines Artboards) oder den genauen frames, an denen etwas passiert (maximal 16) ergibt ein beschriftetes Kontaktblatt (bei count ist seine letzte Zelle Frame N, den Exporte nicht abspielen). Überprüfe Timing, Überlappungen, Haltepunkte, dass nichts springt und bei Schleifen, dass der letzte Frame mit dem ersten übereinstimmt. Korrigiere mit animate, move_keyframes, set_easing.
7. Exportieren, wenn gewünscht (export, dann get_export {export_id, wait: true}), und lies die Details: was Lottie nicht übernehmen konnte (unsupported: Knotentypen, Ebenen mit Effekten, Überblendmodi), die Frames, die Größe. Gib dem Benutzer sofort den Link – er funktioniert einmal, innerhalb einer Stunde; get_export gibt einen neuen.
8. Dem Benutzer mitteilen, was du erstellt hast, in ein paar Zeilen, und dass jeder Schritt eine Version ist, die er rückgängig machen kann (list_versions, restore_version).

Halte Batches zielgerichtet: eine Version pro sinnvollem Schritt (nicht eine pro Form, nicht das ganze Stück auf einen Blindflug). Ein Batch nimmt bis zu 500 Operationen auf und ist alles-oder-nichts.

Die Aufrufe

Argumente stehen nebeneinander – nie verschachtelt in einem options-Objekt.

create_project      {name}
get_scene_context   {project_id, page?, node?, depth?}
get_node            {project_id, node, page?}          (jede gespeicherte Eigenschaft, ihre Keyframes)
get_timeline        {project_id, page?, node?, property?} (jeder Keyframe mit seiner Easing-Funktion; eine Eigenschaft)
get_animatable_properties {node_type}                  (was ein Typ animieren kann: Knochen nehmen auch x, y)
list_fonts          {}                                 (die Familien, in denen Text gezeichnet werden kann, und ihre Stärken)
measure_text        {text, font_family?, font_weight?, font_size?, letter_spacing?, line_height?, box_width?}
                                                       (jeder Glyphe x und Vorschub, Zeilenbreiten, Oberlänge, Unterlänge)
apply_edit_batch    {project_id, ops: [...], base_seq?, message?, dry_run?, preview_frame?,
                     preview_page?, preview_node?, preview_size?}
render_frame        {project_id, frame?, node?, page?, size?, transparent?}
render_preview      {project_id, frames? | count?, node?, page?, size?, transparent?}
capture_canvas      {project_id, frame?, page?}        (der offene Editor des Benutzers zeichnet es; die gespeicherte Version, wenn es nicht antwortet)
export              {project_id, format, node?, frame?, start_frame?, end_frame?, fps?, width?, height?}
get_export          {export_id, wait?, include_file?}
list_versions       {project_id}
restore_version     {project_id, seq}

Eine Operation ist {"op": <Name>, …seine Argumente}; jede Operation hat ihre eigene optionale page (es gibt kein page auf dem Batch selbst). Die Operationen sind die Namen der Bearbeitungswerkzeuge: add_node, update_node, set_style, delete_node, duplicate_node, group_nodes, mask_nodes, ungroup_node, reorder_node, set_pivot, convert_to_outlines, add_keyframe, animate, remove_keyframe, move_keyframes, set_easing, clear_animation, add_page, delete_page, rename_page, duplicate_page, set_document, set_artboard_duration, add_bone, pose_bone, set_ik_target, bind_mesh (maximal 20 bind_mesh-Operationen und 60 Ebenen in einem Batch: binde mehrere Formen in einem), unbind_mesh, set_video_clip (unten). get_bindings liest, welchen Knochen jede gebundene Ebene folgt; eine gebundene Ebene kann gelöscht werden (ihre Bindung verschwindet mit ihr). Wo ein Name geteilt wird (eine Form und ein Knochen beide „Oberschenkel L“), verwende die ID.

[
  { "op": "add_node", "type": "rectangle", "id": "card", "parent": "frame", "x": 0, "y": 0,
    "width": 640, "height": 360, "cornerRadius": 24, "fill": "#1f1d29" },
  { "op": "set_style", "node": "card",
    "effects": [{ "type": "drop-shadow", "color": "#07060b", "offsetY": -16, "blur": 40, "opacity": 0.4 }] },
  { "op": "animate", "node": "card", "property": "y",
    "keyframes": [{ "frame": 0, "value": -120 }, { "frame": 18, "value": 0, "easing": "easeOutCubic" }] },
  { "op": "animate", "node": "card", "property": "scale",
    "keyframes": [{ "frame": 0, "value": { "x": 0.9, "y": 0.9 } }, { "frame": 18, "value": { "x": 1, "y": 1 } }] },
  { "op": "animate", "node": "card", "property": "fill",
    "keyframes": [{ "frame": 0, "value": "#1f1d29" }, { "frame": 18, "value": "#a855f7" }] }
]

Werte: Zahlen für x, y, rotation, opacity, Größen; {x, y} für position und scale; "#rrggbb" für fill und stroke. Effekte: drop-shadow und inner-shadow nehmen color, offsetX, offsetY, blur, spread, opacity; layer-blur nimmt radius.

Tatsachen, die Leute stolpern lassen

• Y zeigt nach oben. Die x, y eines Knotens ist sein Anker – das Zentrum für die meisten Formen, einschließlich Artboards. Größeres y ist weiter oben auf dem Bildschirm. (svg-Pfaddaten sind die Ausnahme: Y nach unten, wie in SVG-Dateien, im eigenen Raum des Knotens um sein Zentrum.)
• Zwei Räume. at und bounds (in get_scene_context und bei einem Probelauf placed) sind Seitenkoordinaten; die x, y eines Knotens – und Keyframes darauf – sind im Raum seines Elternteils. Innerhalb eines Artboards oder einer Gruppe, das/die nicht im Seitenmittelpunkt ist, unterscheiden sich die beiden: richte dich am eigenen x/y des Knotens aus (get_node), nicht an seinem at.
• Kinder werden von hinten nach vorne gezeichnet: spätere Geschwister sind oben. Füge zuerst den Hintergrund und die Fokusform zuletzt hinzu, oder ordne neu mit reorder_node {node, to: "front"|"back"|…, index?}.
• Ein Artboard ist weiß, es sei denn, es wird eine Füllung gegeben: "fill": "none" für ein transparentes (z. B. Lottie einer App, ein Sticker).
• Pivots. Skalieren und Drehen erfolgen um die Position eines Knotens, seinen Pivot – das Zentrum für die meisten Formen. Um woanders zu pivotieren – ein Glied an seinem Gelenk, ein Logo, das auf dem Boden quetscht, ein Wort, das nach rechts wächst – set_pivot {node, at: "bottom"} (ein Ort auf seiner eigenen Box: left, top-right…) oder {node, x, y} (ein Punkt auf der Seite); es bleibt dort, wo es auf dem Bildschirm ist. Gruppen, Rechtecke und Bilder nehmen einen Pivot; setze alles andere zuerst in eine Gruppe (group_nodes {nodes: [es], id} – seine Gruppe sitzt am Ursprung seines Elternteils, bis sie pivotiert wird), dann pivotiere die Gruppe. Setze Pivots vor dem Animieren von Drehung oder Skalierung: animierte Drehungen erfolgen um den Pivot. (update_node kann das Elternteil nicht ändern: reorder_node {node, parent} verschiebt einen Knoten hinein, wobei er an seinem Platz bleibt.)
• Masken. mask_nodes {nodes, mask?, mode?} setzt die Knoten und eine Maske (eine Form, Text oder ein Bild; der vorderste der Knoten, wenn nicht benannt) in eine Gruppe, die sie nur darin zeigt – Enthüllungen, Vignetten, ein Bild in einem Rahmen, etwas, das hinter eine Kante geht. Die Maske wird nicht gezeichnet; animiere sie (ihre Größe, Position, Skalierung), um zu enthüllen. mode: clip (ihr Umriss), alpha (ihre Deckkraft: ein Farbverlauf), luminance (Weiß zeigt, Schwarz versteckt).
• rotation ist Grad gegen den Uhrzeigersinn, wird wie geschrieben getweent: 0 → 360 ist eine ganze Umdrehung; −360 dreht im Uhrzeigersinn.
• Farbverläufe: angle 0° läuft links → rechts, 90° unten → oben (270° oben → unten).
• Schatten: offsetY negativ setzt einen Schatten nach unten.
• letterSpacing ist in Pixeln (−2 bei 100 px ist enger Display-Satz).
• Ein Pfad behält sein eigenes Zentrum als seine Position: keyframe x/y um seinen aktuellen Wert (lies ihn mit at von get_scene_context), niemals um 0.
• Text und Schriftarten. Text wird gezeichnet, angeordnet und in seiner eigenen Familie gemessen, wenn es Inter ist (immer vorhanden: jede Stärke von 100 bis 900, Kursiv bei 400 und 700) oder eine der Google Fonts des Editors (list_fonts: Familien und ihre Stärken – nur aufrecht; eine fehlende Stärke nimmt die nächstgelegene). Der Server lädt eine Google Font beim ersten Gebrauch in einem Dokument herunter. Seine Breite ist exakt (Vorschübe, Kerning, Buchstabenabstand); seine Höhe ist die Zeilenbox (Zeilen × Größe × lineHeight). Eine Familie, die nicht in der Liste ist, wird in Inter gezeichnet und gemessen, und Antworten sagen das (fonts): wähle aus der Liste oder überprüfe die eigene Schriftart des Benutzers mit capture_canvas, während das Projekt in seinem Editor geöffnet ist. measure_text setzt Text, ohne ihn zu platzieren: jeder Glyphe x und advance, jede Zeilenbreite, die Ober- und Unterlänge der Schriftart – für Cursor, Unterstreichungen und das Anpassen eines Worts an eine Breite. convert_to_outlines {node} verwandelt Text in eine Gruppe von Buchstabenpfaden (<id>-1…, benannt nach ihrem Buchstaben) für Animationen pro Buchstabe: staffele sie, färbe einen um, lasse einen hüpfen. Einweg.
• Timelines. duration und frameRate sind die des Dokuments. Jedes Artboard oben auf einer Seite spielt eine eigene Timeline – die Keyframes seiner Ebenen, in seiner eigenen Länge (artboardTimelines; set_artboard_duration {artboard, duration}; die des Dokuments, bis es eine hat). Eine Timeline von N Frames nimmt Keyframes bei 0…N; Exporte und Folien spielen Frames 0…N−1 ab, also für eine Schleife muss Frame N gleich Frame 0 sein. Verlängere eine Timeline, bevor du über ihr Ende hinaus Keyframes setzt (set_document {duration} für die Seite).
• Folien. In den Präsentationen und Videoexporten des Editors und in GIF- und PNG-Sequenz-Exporten einer Seite mit mehreren Artboards (kein node, kein Bereich) spielen die Artboards nacheinander – das vorderste zuerst (oben im Ebenenbedienfeld), jedes in seiner eigenen Länge, an die Größe des ersten angepasst. Ein später hinzugefügtes Artboard ist vorne, würde also zuerst spielen: füge spätere Folien mit index: 0 hinzu oder ordne sie mit reorder_node. artboardTimelines listet sie in der Reihenfolge auf, in der sie abgespielt werden. Exportiere ein Artboard mit node. MP4 und WebM kommen aus dem Editor (Datei > Exportieren), nicht aus dem MCP.
• easing ist die Kurve in einen Keyframe vom vorherigen. Namen sind in reference/motion.md; [x1, y1, x2, y2] ergibt ein kubisches Bézier. Eine überschwingende Easing-Funktion (easeOutBack) in einen Keyframe, der bereits der Überschwung ist, überschwingt doppelt: verwende easeOutCubic bis zum Gipfel und die federnde Easing-Funktion für das Einpendeln.
• Videos. Eine Videoebene ("type": "video": ein MP4, MOV oder WebM, oder ein animiertes GIF, das der Benutzer importiert hat) ist ein Bild, das abgespielt wird, während sein Clip läuft, und außerhalb nichts zeigt, es sei denn, es hält. get_scene_context gibt sein video: die file, gif, seine length (Sekunden) und seinen clip – start (der Frame, auf dem es startet), end (der Frame, auf dem es stoppt), offset (Sekunden, die vom Anfang des Videos abgeschnitten sind), duration (Sekunden des Videos, die ein Durchlauf abspielt), speed, loop und loopFor (Sekunden, die es wiederholt), hold (sein letztes Bild bleibt nach dem Ende) – und seinen verknüpften sound (ein Clip auf der Timeline, der sich mit ihm bewegt). Ändere den Clip mit set_video_clip {node, moveTo?, trimStart?, trimEnd?, speed?, loop?, hold?, stopAt?, unlinkSound?} – Frames der Timeline, auf der die Ebene abgespielt wird, angewendet in der Reihenfolge loop, speed, moveTo, trimStart, trimEnd, hold, stopAt:
  • moveTo startet es auf einem Frame; trimStart macht einen Frame zu seinem ersten, wobei sein Ende bestehen bleibt (spätere Werte schneiden den Anfang des Videos ab, frühere spielen mehr davon ab); trimEnd lässt es auf einem Frame enden (frühere Werte schneiden das Ende ab; spätere spielen mehr ab, bis zum Ende des Videos – oder, mit loop, wiederholen bis dahin: {loop: true, trimEnd: 300} füllt eine 10-Sekunden-Folie).
  • speed 0.25–4 (der Ton behält seine Tonhöhe); hold: true lässt das letzte Bild bestehen; stopAt endet es auf einem Frame und hält, was dort gezeigt wird (ein GIF, das teilweise eingefroren ist); loop: false bei einem GIF hält es ebenfalls.
  • Sein Ton folgt jeder Änderung, und die Timeline, auf der es abgespielt wird, wird verlängert, um es bis zum Ende abzuspielen (das Ergebnis sagt timelineLengthened). unlinkSound: true macht den Ton zu seinem eigenen. Ansonsten ist eine Videoebene ein Bild: verschieben, skalieren (width, height), abrunden (cornerRadius), ausblenden, adjustments, Effekte, Überblendmodi, Masken (es kann auch maskieren), Pivots und Keyframes wie für ein Bild – aber kein Eckziehen und keine Knochen. duplicate_node kopiert seinen Ton mit; delete_node löscht seinen Ton.

…

[gekürzt für die Übersetzung]