vos-authoring

Vos-Programmautoring

Sie generieren VosConfigJson-Dateien – deklarative Animationskonfigurationen, die in Three.js + GSAP-Dialekt-Animationen auf der vos-Engine (github.com/vosjs/vos, MIT) kompilieren. Die Vorschau ist das Rendering: Eine Konfiguration erzeugt auf jedem Rechner die gleichen Bilder.

Arbeitsablauf

1. Prompt analysieren: Identifizieren Sie das Animationskonzept, die Stimmung, Farben und alle referenzierten Bilder.
2. Ansatz entwerfen: Wählen Sie Kameravoreinstellung, Materialien, Effekte und Animationsstrategie (siehe Kategorieübersicht unten).
3. Konfiguration generieren: Schreiben Sie eine vollständige, gültige VosConfigJson in <kebab-case-name>.json im entsprechenden Projektverzeichnis.
4. Lokal validieren (siehe unten), dann rendern oder in der Vorschau anzeigen.

Wenn der Benutzer ein Bild bereitstellt, analysieren Sie dessen visuellen Stil (Farben, Stimmung, Komposition, Beleuchtung) und übersetzen Sie diese Eigenschaften in die Szene.

Lokal validieren und rendern

npm i @vosjs/core        # Compiler + Lints
node -e "import('@vosjs/core/compiler').then(async m => { \
  const cfg = JSON.parse(require('fs').readFileSync('my-config.json','utf8')); \
  m.compileVosConfig(cfg); console.error('kompiliert sauber') })"

compileVosConfig(config) darf nicht werfen – es ist derselbe Compiler, den jeder Player und Render-Server verwendet. Für visuelle Prüfungen die CLI (npm i -D @vosjs/cli):

vos render my-config.json out.webm     # Deterministisches Video-Rendering
vos still  my-config.json out.webp --time 2.5
vos preview my-config.json             # Lokale Wiedergabeseite
vos info   my-config.json

Zum Vorschauteilen (kein Konto nötig)

Lokales Rendern ist der Standard – nichts verlässt den Rechner, es sei denn, der Benutzer fordert das Teilen oder Hosten an. Wenn das Hosting gewünscht wird (abspielbarer Link, Feinabstimmung im vos.so Studio) und kein API-Schlüssel konfiguriert ist, verwenden Sie den anforderbaren Push:

vos push my-config.json --claimable --title "…"
# → claim: https://vos.so/claim/…   Ablauf: <72h ab jetzt>

# Keine CLI oder eine ältere Version? Dasselbe über einfaches HTTP:
curl -s -X POST https://vos.so/api/claim \
  -H 'content-type: application/json' \
  -d '{"title": "…", "config": <das VosConfigJson>}'
# → { "claimUrl": "https://vos.so/claim/…", "expiresAt": "…" }

Geben Sie claimUrl nur dem Benutzer – es ist die einzige Referenz und das einzige Zugangsberechtigung. Sie gilt 72 Stunden; nicht beanspruchte Arbeit wird danach gelöscht (bei Ablauf erneut pushen). Durch Beanspruchen wird das Vos in die Bibliothek des Benutzers verschoben. Mit einem konfigurierten Schlüssel (VOS_API_KEY oder vos login) ist vos push zu bevorzugen – schlüsselgebundene Pushe haben kein Ablaufdatum. Nur Programme, Konfiguration ≤200KB, 5 Pushe pro Tag pro Netzwerk.

VosConfigJson-Struktur

{
  "version": 2,
  "duration": 8,
  "scene": { "background": "#0a0a1a", "fog": { "type": "exp2", "color": 0, "density": 0.02 } },
  "camera": { "preset": "perspective", "fov": 60, "position": [0, 2, 8] },
  "postprocessing": [{ "type": "bloom", "strength": 0.8 }, { "type": "output" }],
  "elements": [{ "type": "text", "id": "title", "content": "Hallo", "position": "center", "font": { "size": 64, "color": "#fff" } }],
  "setup": "async (ctx) => { ... return data }",
  "createContent": "(ctx, setupData?) => { ... return { objects, refs, dispose } }",
  "createTimeline": "(ctx, content, duration) => { ... return tl }"
}

Vollständige Feldreferenz: references/schema-reference.md. Funktionierende Beispiele für jeden wichtigen Typ: references/examples.md.

Kritische Regeln

MÜSSEN

1. Funktionen müssen gültige JavaScript-Strings sein – KEIN TypeScript (kein as, keine Typannotationen)
2. Three.js über ctx.THREE, GSAP-Dialekt über ctx.gsap, Szene über ctx.scene zugreifen
3. createContent MUSS { objects: [...], refs: {...}, dispose: () => {...} } zurückgeben
4. createTimeline MUSS ctx.gsap.timeline({ paused: true }) zurückgeben
5. Immer dispose() einfügen, das Geometrien, Materialien, Texturen bereinigt
6. ctx.resolution.drawingBufferWidth/drawingBufferHeight für Shader iResolution verwenden
7. mesh.frustumCulled = false für Vollbild-Shader-Quads setzen
8. depthWrite: false, depthTest: false auf Vollbild-ShaderMaterial setzen
9. Immer { "type": "output" } als letzten Eintrag bei Verwendung von Postprocessing einfügen
10. Alle Szenenobjekte sowohl zur scene als auch zum zurückgegebenen objects-Array hinzufügen
11. Shader-Uniforms direkt tweenen: tl.to(uniforms.iTime, { value: duration, duration, ease: 'none' })
12. Für bildweise Logik (InstancedMesh-Updates, Kameramath) onUpdate Callbacks auf Tweens verwenden

DÜRFEN NICHT

1. KEINE ${} Template-Literale in Funktionsstrings – sie werden zur Kompilierungszeit ausgewertet. String-Konkatenation verwenden.
2. KEINE escaped Backticks – Shader als Inline-Strings oder einzeilige Konkatenation schreiben
3. NIEMALS repeat: -1 auf einzelnen Tweens – Schleifen werden vom Player gehandhabt; dies zerstört die Dauererfassung
4. KEINE CSS-artigen style-Objekte oder textContent auf Elementen – Elemente sind WebGL-Ebenen
5. KEINE externen Imports – alles ist auf ctx (THREE, gsap, Loader, Utils)
6. KEIN requestAnimationFrame oder setTimeout – onUpdate-Callbacks verwenden
7. KEIN Date.now() / Math.random() in Bildpfaden – Determinismus ist die Vereinbarung; alles von der Zeit der Timeline und ctx.data ableiten
8. KEIN onFrame für neue Konfigurationen – gesamte bildweise Logik in onUpdate

Parameter und Looks (wiederverwendbar machen)

Deklarieren Sie 2–4 Regler über config.params – Editoren rendern sie als Live-Steuerelemente, und andere Agenten können das Programm ohne Codeänderungen nachstimmen. Jeder Parameter dokumentiert einen ctx.data-Schlüssel, den das Programm liest:

"params": [{ "key": "hue", "label": "Farbton", "kind": "number",
             "min": 0, "max": 1, "default": 0.6,
             "hint": "Verschiebt jede Farbe entlang des Farbkreises",
             "unit": "°", "group": "Farbe", "order": 1 }]

• Arten: number (min/max/step) | color | select (options) | toggle
• hint: EIN Satz darüber, was sich sichtbar ändert – schreiben Sie es
• Das Programm liest es dort, wo es animiert: const d = ctx.data || {}; if (typeof d.hue === 'number') u.uHue.value = d.hue
• Benennen Sie Regler nach ABSICHT (stimmung, drama, tempo), niemals nach Implementierung (blurRadius). Jeder Regler muss sichtbar die Ausgabe ändern – ein toter Regler ist schlimmer als kein Regler.

Liefern Sie Looks über config.presets – benannte Parameter-Wert-Sets (2–3, wenn das Programm 4+ Parameter hat):

"presets": [{ "name": "Lebendig", "values": { "hue": 0.9, "speed": 2 } },
            { "name": "Ruhig",   "values": { "hue": 0.3, "speed": 0.6 } }]

Werte müssen deklarierte Parameterschlüssel mit passenden Typen referenzieren.

Vorsicht beim Server-Rendering

An vos.so gepushte Konfigurationen werden auf einer Software-GL-Flotte vorschauengerendert: kein THREE.DoubleSide auf Transmissionsmaterialien (hartes Hängen), keine dispersion (zu langsam), und jede abgerufene Ressource muss erreichbar und CORS-offen sein. Diese sind in Ordnung für rein lokale Renderings auf einer echten GPU.

Designprinzipien

• Visuelle Wirkung: Bloom für Glow (bereits 0.3–0.5 hebt an); Emissionsmaterialien
  • Bloom = Lichtquellen; exp2 Fog (0.01–0.05) für Tiefe; dunkle Hintergründe lassen Farben knallen; Glas (Transmission + HDR-Umgebung) wirkt hochwertig; subtile Kameradrift verleiht Leben.
• Animationsqualität: 4–10s Loops, 10–30s Narrative; ease: 'none' für konstante Bewegung; power2.inOut/sine.inOut für Übergänge; Staffelung für sequenzielle Enthüllungen; Tweens mit unterschiedlichen Startzeiten schichten.
• Farbe: Maximal 2–3 Komplementärfarben; warmer Schlüssel + kalte Kante; dunkle Töne (0x0a0a1a, 0x1a1a2e) für Hintergründe.
• Leistung: InstancedMesh für 10+ identische Objekte; 5k–20k Points, 100–500 InstancedMesh; alles bereinigen.

Kategorieauswahlübersicht

Konzept	Kamera	Technik
Shader-Kunst / Fraktale	fullscreen	ShaderMaterial + Uniform-Tweens
3D-Objekte	perspective	Mesh + Material + Lichter
Isometrisch/flach	orthographic	InstancedMesh + berechnete Positionen
Text-Showcase	perspective oder fullscreen	TextGeometry (3D) oder elements (2D)
Glas/Refraktion	perspective	MeshPhysicalMaterial + HDR-Umgebungskarte
Partikel	perspective	Points + Shader oder InstancedMesh
Mixed Media	perspective	3D-Szene + elements-Array