Briefing für Assistenten

Diese Seite ist dafür geschrieben, einem KI-Modell übergeben zu werden. Fügen Sie sie in eine Unterhaltung ein oder weisen Sie das Modell auf diese URL hin, bevor Sie um Hilfe bei einem AR-Clip-Projekt bitten.

Assistenten, die nach maschinenlesbarem Kontext suchen, finden ihn von selbst unter /llms.txt, mit der gesamten Dokumentation in einer Datei unter /llms-full.txt.

Sie existiert, weil kein Modell auf dieser Plattform trainiert wurde. Ohne sie greifen sie nach der Engine, die sie kennen (Unity, three.js, A-Frame), und liefern Antworten, die richtig aussehen und es nicht sind.

Das mentale Modell

Alles in einem Projekt ist eine Entity. Eine Entity ist ein Name plus ein Satz Komponenten, und die Komponenten entscheiden, was sie ist. Es gibt keine Klassenhierarchie und keine Objekttypen zur Auswahl.

Project
└── Space          gemeinsamer Hintergrund, Beleuchtung, Raster, Einheiten
    └── Scene      eine Entity mit einem Anchor — dem Auslöser, der sie erscheinen lässt
        └── Entity
            └── Entity      Entities verschachteln sich

Zwei Beziehungen, die nicht verwechselt werden dürfen:

Komposition — eine Entity hat Komponenten. Eine von jeder Sorte. Komponenten sind keine Kinder.
Enthaltensein — eine Entity enthält andere Entities. Ein Elternobjekt zu bewegen bewegt seine Kinder.

Eine Szene ist eine Entity mit einem Anchor und ohne Transform. Logik auf Space-Ebene ist eine Entity mit einem Script oder Patch und ohne Elternobjekt.

Sie schreiben nie Systeme. Die Engine reagiert auf Komponenten; Ihre Aufgabe ist zu entscheiden, welche Komponenten existieren und welche Werte sie haben.

Vier Wege, Verhalten hinzuzufügen

Ebene	Lebt in	Wofür
Events	einer Events-Komponente	Auslöser → Liste von Schritten; die meiste Interaktivität
Patches	einem Patch-Graphen oder einer Ressource	Logik mit Werten und Bedingungen, visuell gebaut
Scripts	einer Skript-Ressource	alles wirklich Programmatische
UI	einer DivKit-Karte	die gesamte 2D-Oberfläche

Alle vier schreiben in dieselben Komponenten. Derselbe Auslöser, in zweien davon behandelt, feuert zweimal — ein sehr häufiger generierter Fehler.

Benennungsregeln

Auslöser sind kebab-case: on-click, on-launch, on-collide.
Schritte sind snake_case: play_animation, set_visibility, scene_transit_action.
Die Auflösung ist exakt. Ein vertippter Name erzeugt keinen Fehler — er passt einfach nie.
Der Editor zeigt menschliche Beschriftungen („Objekt zeigen / verbergen"); die Ids oben sind das, was der Code benutzt.

Nicht raten — nachschlagen

Wenn Sie über MCP verbunden sind, antworten diese aus der laufenden Engine:

Aufruf	Gibt zurück
`list_component_schemas`	jede Komponente und ihre Felder
`list_event_types`	jeden Auslöser und Schritt mit Parametern
`list_patch_nodes`	jeden Patch-Knoten mit seinen Ports
`describe_*_api`	erläuternden Text je Bereich

Rufen Sie sie auf, bevor Sie irgendetwas schreiben, das eine Komponente, einen Auslöser, einen Schritt oder einen Knoten benennt. Einen plausiblen Namen zu erfinden ist hier der mit Abstand häufigste Fehlermodus.

Ohne MCP nehmen Sie die generierte Referenz: Komponenten · Auslöser · Schritte · Patch-Knoten · Shader-Knoten.

Fallen, die selbstbewusst falschen Code erzeugen

Einen verschachtelten Wert zu schreiben ersetzt ihn vollständig

update({ position: { y: 2 } }) setzt x und z auf null. Spreaden Sie immer:

t.update({ position: { ...t.$data.position, y: 2 } });

Ein Material ist eine Liste von Slots

material.update({ color }) tut nichts — color lebt in einem Slot:

material.update({
  materials: [{ ...material.$data.materials[0], color: '#ff0000' }],
});

Weisen Sie niemals in $data zu

Es sieht aus, als funktioniere es, und die Änderung wird verworfen. Nur update() und updateAt() schreiben.

Den Transform eines dynamischen Physikkörpers zu setzen bewirkt nichts

Die Physik besitzt seine Position und überschreibt sie im nächsten Schritt. Nehmen Sie ctx.physics.teleport zum Platzieren und applyImpulse / applyForce zum Bewegen.

Ein importiertes Modell hat keine Kollisionsform

Ein GLB ist nicht fest, bis Sie ihm einen Collider geben. Ein dynamisches fällt durch die Welt.

Weitere Regeln, an denen Generatoren scheitern:

Rotation ist im Skript Bogenmaß, überall wo ein Mensch hinschaut Grad — im Editor, an den Ports von Patch-Knoten, im MCP-Werkzeug.
Multiplizieren Sie in ctx.tick mit dt, sonst läuft Bewegung mit der Bildrate des Geräts.
Es gibt in keinem Mechanismus ein Ereignis „Animation beendet". Nehmen Sie die Zeit selbst.
Skripte haben kein DOM, kein fetch, keine Timer, keine Rendering-Bibliothek. Nehmen Sie ctx.tick, ctx.audio, ctx.store und eine UI-Karte für die Oberfläche.
Der Editor führt keine Logik aus. Skripte, Patches, Physik und Timer laufen nur in der Vorschau oder einer Veröffentlichung. Sagen Sie einem Nutzer nie, sein Skript „sollte im Editor laufen".
Solange ein State aktiv ist, werden Änderungen an diesem Objekt in den State geschrieben, nicht in das Objekt.
Die Timeline speichert channels fürs Autorenwerkzeug und eine gebackene keyframes-Liste fürs Abspielen. Channels ohne erneutes Backen zu schreiben heißt, dass nichts abspielt.
Ein Objekt, ein Animationsmechanismus. Die Timeline überschreibt eine Transition in jedem Bild.

Lieber der eingebaute Schritt als seine Nachbildung

ctx.step(name, params, { targets }) führt jeden Schritt aus, den der Editor anbietet — Animation, State-Wechsel, Szenenübergänge, Transitionen. Sehen Sie in der Schritt-Referenz nach, bevor Sie Code von Hand schreiben.

Prüfen Sie einen Patch, bevor Sie behaupten, er funktioniere

Kompilieren Sie ihn und lesen Sie das Ergebnis. Ein Graph, der nicht kompiliert, meldet einen Datenzyklus oder kaputtes JavaScript, und der kompilierte Quelltext ist genau das, was laufen wird. Über MCP ist das preview_patch_code.

Einheiten

Größe	In den Daten	Wo ein Mensch sie sieht
Position	Meter	Projekteinheiten
Rotation	Bogenmaß	Grad
Animationszeit	Sekunden	Sekunden (Millisekunden bei State-Wechseln)
Deckkraft	0–1	0–100 in Keyframes und im Deckkraft-Schritt
Schriftgröße	Pixel, 1000 px = 1 m	Pixel
Clip-Bilder	30 fps	Bilder

Einem Nutzer gut antworten

Fragen Sie, welche Ebene er will. „Ohne Code" und „in einem Skript" führen zu völlig verschiedenen Antworten auf dieselbe Frage.
Bevorzugen Sie die einfachste Ebene, die funktioniert. Ein Ereignis schlägt einen Patch; ein Patch schlägt ein Skript.
Sagen Sie, wo man klickt. Für jemanden im Editor zählen Panel-Namen mehr als Konzepte.
Erinnern Sie an die Vorschau. Die meisten „geht nicht"-Meldungen sind der Editor, der keine Logik ausführt.
Erfinden Sie keine Namen. Im Zweifel sagen Sie das und verweisen auf die Referenz.

Das mentale Modell​

Vier Wege, Verhalten hinzuzufügen​

Benennungsregeln​

Nicht raten — nachschlagen​

Fallen, die selbstbewusst falschen Code erzeugen​

Lieber der eingebaute Schritt als seine Nachbildung​

Prüfen Sie einen Patch, bevor Sie behaupten, er funktioniere​

Einheiten​

Einem Nutzer gut antworten​