Briefing für Assistenten

Geben Sie diese Seite jedem KI-Modell, bevor Sie es um Hilfe bei einem AR-Clip-Projekt bitten. Fügen Sie sie in den Chat ein oder geben Sie dem Modell die Adresse dieser Seite.

Kein Modell wurde mit AR Clip trainiert. Ohne diese Seite greifen Modelle auf andere Engines zurück, die sie kennen, und geben Antworten, die richtig aussehen, aber falsch sind.

KI-Tools, die nach maschinenlesbarem Kontext suchen, finden ihn selbst unter /llms.txt. Die gesamte Doku in einer Datei liegt unter /llms-full.txt.

So ist ein Projekt aufgebaut

Alles in einem Projekt ist eine Entität. Eine Entität ist ein Name plus eine Reihe von Komponenten. Die Komponenten bestimmen, was die Entität ist. Es gibt keine Klassen und keine Objekttypen, aus denen man wählt.

Projekt
└── Raum           gemeinsamer Hintergrund, Licht, Raster, Einheiten
    └── Szene      eine Entität mit einem Anchor – dem Trigger, der sie erscheinen lässt
        └── Entität
            └── Entität     Entitäten lassen sich verschachteln

Verwechseln Sie diese beiden Beziehungen nicht:

Komposition – eine Entität hat Komponenten, von jeder Art höchstens eine. Komponenten sind keine Kinder.
Enthaltensein – eine Entität enthält andere Entitäten. Wird das Elternelement bewegt, bewegen sich seine Kinder mit.

Eine Szene ist eine Entität mit einem Anchor und ohne Transform. Logik für den ganzen Raum ist eine Entität mit einem Script oder Patch und ohne Elternelement.

Den Code, der Komponenten zum Laufen bringt, schreiben Sie nicht. Ihre Aufgabe ist zu entscheiden, welche Komponenten es gibt und welche Werte sie haben.

Vier Wege, Verhalten hinzuzufügen

Ebene	Wo sie liegt	Wofür
Ereignisse	eine Events-Komponente	ein Trigger und eine Liste von Schritten; der Großteil der Interaktivität
Patches	ein Patch-Graph oder eine Patch-Ressource	Logik mit Werten und Bedingungen, visuell gebaut
Skripte	eine Skript-Ressource	alles, was wirklich Code braucht
UI	eine UI-Karte	das gesamte 2D-Interface

Alle vier ändern dieselben Komponenten. Verarbeiten zwei davon denselben Trigger, löst er doppelt aus. Das ist ein sehr häufiger Fehler in generierten Antworten.

Namen

Trigger sind in kebab-case: on-click, on-launch, on-collide.
Schritte sind in snake_case: play_animation, set_visibility, scene_transit_action.
Tasten- und Maus-Trigger heißen in Skripten anders. Ein Ereignis nutzt on-key und on-mouse mit Zweigen. Ein Skript hört auf on-keydown / on-keyup und on-mousedown / on-mouseup / on-click.
Namen müssen exakt stimmen. Ein falsch geschriebener Name erzeugt keinen Fehler – er passt einfach nie.
Der Editor zeigt lesbare Bezeichnungen wie „Objekt ein-/ausblenden“. Im Code stehen die IDs von oben.

Namen nachschlagen, nicht raten

Wenn Sie über MCP verbunden sind, zeigen diese Aufrufe genau, was es gibt:

Aufruf	Liefert
`list_component_schemas`	jede Komponente mit ihren Feldern
`list_event_types`	jeden Trigger und jeden Schritt, mit Parametern
`list_patch_nodes`	jeden Patch-Node, mit seinen Ports
`describe_*_api`	schriftliche Hinweise für jeden Bereich

Rufen Sie sie auf, bevor Sie etwas schreiben, das eine Komponente, einen Trigger, einen Schritt oder einen Node benennt. Einen Namen zu erfinden, der plausibel klingt, ist der häufigste Fehler auf dieser Plattform.

Ohne MCP nutzen Sie die Referenz: Komponenten · Trigger · Schritte · Patch-Nodes · Shader-Nodes.

Fehler, die richtig aussehen

Wer einen Teil eines verschachtelten Werts schreibt, ersetzt den ganzen Wert

update({ position: { y: 2 } }) setzt x und z auf null. Übernehmen Sie immer den alten Wert per Spread:

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

Ein Material ist eine Liste von Slots

material.update({ color }) bewirkt nichts, weil color innerhalb eines Slots liegt:

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

Weisen Sie $data nie direkt etwas zu

Es scheint zu funktionieren, aber die Änderung geht verloren. Nur update() und updateAt() schreiben Daten.

Die Transformation eines dynamischen Physikkörpers zu setzen bewirkt nichts

Die Physik steuert seine Position und überschreibt sie beim nächsten Schritt. Nutzen Sie ctx.physics.teleport, um ihn zu platzieren, und applyImpulse / applyForce, um ihn zu bewegen.

Ein importiertes Modell hat keine Kollisionsform

Ein GLB ist erst fest, wenn Sie ihm einen Collider geben. Ein dynamisches Modell fällt durch die Welt.

Weitere Regeln, an denen Modelle oft scheitern:

Rotation ist in Skripten in Radiant angegeben, überall sonst, wo Menschen hinsehen, in Grad – im Editor, an den Ports von Patch-Nodes, in den MCP-Tools.
Multiplizieren Sie in ctx.tick mit dt, sonst hängt die Bewegungsgeschwindigkeit von der Bildrate des Geräts ab.
Importieren Sie Komponentenklassen in Skripten aus @was/engine: TransformComponent, MetaComponent und die übrigen. Global sind nur init und defineProps.
Es gibt kein Ereignis „Animation beendet“, in keinem Mechanismus. Messen Sie die Zeit selbst.
Skripte haben kein DOM, kein fetch, keine Timer und keine Rendering-Bibliothek. Nutzen Sie ctx.tick, ctx.audio, ctx.store und für das Interface eine UI-Karte.
Der Editor führt keine Logik aus. Skripte, Patches, Physik und Timer laufen nur in der Vorschau oder in einem veröffentlichten Projekt. Sagen Sie Nutzern nie, ihr Skript „sollte im Editor laufen“.
Solange ein Zustand aktiv ist, werden Änderungen an diesem Objekt im Zustand gespeichert, nicht im Objekt.
Ändern Sie eine Zeitleiste mit den Zeitleisten-Tools. Wenn Sie die Komponente der Zeitleiste direkt bearbeiten, wird die Animation unter Umständen nicht abgespielt.
Ein Objekt, eine Art, es zu animieren. Die Zeitleiste überschreibt einen Übergang.

Eingebaute Schritte nutzen statt nachbauen

ctx.step(name, params, { targets }) führt jeden Schritt aus, den der Editor anbietet: Animation, Zustandswechsel, Szenenwechsel, Übergänge. Sehen Sie in der Referenz der Schritte nach, bevor Sie dasselbe von Hand schreiben.

Einen Patch prüfen, bevor Sie sagen, dass er funktioniert

Sehen Sie ihn sich als Code an und lesen Sie das Ergebnis. Ein Graph mit einem Problem meldet einen Datenzyklus oder fehlerhaftes JavaScript. Über MCP nutzen Sie preview_patch_code.

Einheiten

Größe	In den Daten	Was eine Person sieht
Position	Meter	Projekteinheiten
Rotation	Radiant	Grad
Animationszeit	Sekunden	Sekunden (Millisekunden bei Zustandswechseln)
Deckkraft	0–1	0–100 in Keyframes und im Schritt für die Deckkraft
Schriftgröße	Pixel, 1000 px = 1 m	Pixel
Clip-Frames	30 fps	Frames

So antworten Sie dem Nutzer

Fragen Sie, welche Ebene gewünscht ist. „Ohne Code“ und „in einem Skript“ führen bei derselben Frage zu sehr unterschiedlichen Antworten.
Wählen Sie die einfachste Ebene, die funktioniert. Ein Ereignis ist besser als ein Patch, ein Patch ist besser als ein Skript.
Sagen Sie, wo man klicken muss. Für jemanden im Editor zählen die Namen der Panels mehr als Konzepte.
Erinnern Sie an die Vorschau. Die meisten Meldungen „es funktioniert nicht“ entstehen, weil der Editor keine Logik ausführt.
Erfinden Sie keine Namen. Wenn Sie unsicher sind, sagen Sie es und verweisen Sie auf die Referenz.

So ist ein Projekt aufgebaut​

Vier Wege, Verhalten hinzuzufügen​

Namen​

Namen nachschlagen, nicht raten​

Fehler, die richtig aussehen​

Eingebaute Schritte nutzen statt nachbauen​

Einen Patch prüfen, bevor Sie sagen, dass er funktioniert​

Einheiten​

So antworten Sie dem Nutzer​