Briefing pour les assistants

Cette page est écrite pour être donnée à un modèle d'IA. Collez-la dans une conversation, ou pointez le modèle vers cette URL, avant de lui demander de l'aide sur un projet AR Clip.

Les assistants qui cherchent un contexte lisible par machine le trouveront tout seuls à /llms.txt, avec toute la documentation dans un seul fichier à /llms-full.txt.

Elle existe parce qu'aucun modèle n'a été entraîné sur cette plateforme. Sans elle, ils se rabattent sur le moteur qu'ils connaissent (Unity, three.js, A-Frame) et produisent des réponses qui ont l'air justes et ne le sont pas.

Le modèle mental

Tout, dans un projet, est une entity. Une entity est un nom plus un ensemble de composants, et ce sont les composants qui décident de ce qu'elle est. Il n'y a ni hiérarchie de classes ni types d'objets à choisir.

Project
└── Space          fond, éclairage, grille et unités partagés
    └── Scene      une entity portant une Anchor — le déclencheur qui la fait apparaître
        └── Entity
            └── Entity      les entities s'imbriquent

Deux relations à ne pas confondre :

Composition — une entity a des composants. Un de chaque sorte. Les composants ne sont pas des enfants.
Contenance — une entity contient d'autres entities. Déplacer un parent déplace ses enfants.

Une scène est une entity avec une Anchor et sans Transform. La logique au niveau du space est une entity avec un Script ou un Patch et sans parent.

Vous n'écrivez jamais de systèmes. Le moteur réagit aux composants ; votre travail est de décider quels composants existent et quelles sont leurs valeurs.

Quatre façons d'ajouter du comportement

Couche	Vit dans	À utiliser pour
Events	un composant Events	déclencheur → liste d'étapes ; la plupart des interactions
Patches	un graphe ou une ressource patch	de la logique avec valeurs et conditions, bâtie visuellement
Scripts	une ressource script	tout ce qui est vraiment programmatique
UI	une carte DivKit	toute l'interface 2D

Les quatre écrivent dans les mêmes composants. Le même déclencheur traité dans deux d'entre elles se déclenche deux fois — un bug généré très courant.

Règles de nommage

Les déclencheurs sont en kebab-case : on-click, on-launch, on-collide.
Les étapes sont en snake_case : play_animation, set_visibility, scene_transit_action.
La résolution est exacte. Un nom mal tapé ne provoque pas d'erreur — il ne correspond simplement jamais.
L'éditeur affiche des libellés humains (« Afficher / masquer un objet ») ; les identifiants ci-dessus sont ce qu'utilise le code.

Ne devinez pas — consultez

Si vous êtes connecté via MCP, ceux-ci répondent depuis le moteur en fonctionnement :

Appel	Renvoie
`list_component_schemas`	chaque composant et ses champs
`list_event_types`	chaque déclencheur et étape avec ses paramètres
`list_patch_nodes`	chaque nœud de patch avec ses ports
`describe_*_api`	des explications rédigées par domaine

Appelez-les avant d'écrire quoi que ce soit qui nomme un composant, un déclencheur, une étape ou un nœud. Inventer un nom plausible est de loin le mode d'échec le plus courant ici.

Sans MCP, utilisez la référence générée : composants · déclencheurs · étapes · nœuds de patch · nœuds de shader.

Les pièges qui produisent du code faux et sûr de lui

Écrire une valeur imbriquée la remplace entièrement

update({ position: { y: 2 } }) met x et z à zéro. Étalez toujours :

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

Un matériau est une liste de slots

material.update({ color }) ne fait rien — color vit dans un slot :

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

N'affectez jamais dans $data

Cela a l'air de marcher et le changement est jeté. Seuls update() et updateAt() écrivent.

Fixer le transform d'un corps physique dynamique ne fait rien

La physique possède sa position et la réécrit au pas suivant. Utilisez ctx.physics.teleport pour le placer et applyImpulse / applyForce pour le déplacer.

Un modèle importé n'a pas de forme de collision

Un GLB n'est pas solide tant que vous ne lui donnez pas de collider. S'il est dynamique, il traverse le monde.

D'autres règles qui prennent les générateurs en défaut :

La rotation est en radians dans les scripts, en degrés partout où un humain regarde — l'éditeur, les ports des nœuds de patch, l'outillage MCP.
Multipliez par dt dans ctx.tick, sinon le mouvement suit la cadence d'images de l'appareil.
Il n'y a pas d'événement « animation terminée » dans aucun mécanisme. Comptez le temps vous-même.
Les scripts n'ont pas de DOM, pas de fetch, pas de minuteries, pas de bibliothèque de rendu. Utilisez ctx.tick, ctx.audio, ctx.store, et une carte UI pour l'interface.
L'éditeur n'exécute pas la logique. Scripts, patches, physique et minuteries ne tournent que dans l'aperçu ou une publication. Ne dites jamais à un utilisateur que son script « devrait tourner dans l'éditeur ».
Tant qu'un state est actif, les modifications de cet objet sont enregistrées dans le state, pas dans l'objet.
La timeline stocke des channels pour l'édition et une liste keyframes cuite pour la lecture. Écrire des channels sans recuire signifie que rien ne joue.
Un objet, un mécanisme d'animation. La timeline écrase une transition à chaque image.

Préférez l'étape intégrée à sa réimplémentation

ctx.step(name, params, { targets }) exécute n'importe quelle étape que l'éditeur propose — animation, changement de state, transitions de scène, transitions. Consultez la référence des étapes avant d'écrire du code à la main.

Validez un patch avant d'affirmer qu'il marche

Compilez-le et lisez le résultat. Un graphe qui ne compile pas signale un cycle de données ou du JavaScript cassé, et la source compilée est exactement ce qui s'exécutera. Via MCP, c'est preview_patch_code.

Unités

Grandeur	Dans les données	Là où un humain la voit
Position	mètres	unités du projet
Rotation	radians	degrés
Temps d'animation	secondes	secondes (millisecondes sur les changements de state)
Opacité	0–1	0–100 dans les keyframes et l'étape d'opacité
Taille de police	pixels, 1000 px = 1 m	pixels
Images d'un clip	30 ips	images

Bien répondre à un utilisateur

Demandez quelle couche il veut. « Sans code » et « dans un script » mènent à des réponses complètement différentes à la même question.
Préférez la couche la plus simple qui fonctionne. Un événement vaut mieux qu'un patch ; un patch vaut mieux qu'un script.
Dites où cliquer. Pour quelqu'un dans l'éditeur, les noms de panneaux comptent plus que les concepts.
Rappelez-lui de prévisualiser. La plupart des « ça ne marche pas » sont l'éditeur qui n'exécute pas la logique.
N'inventez pas de noms. En cas de doute, dites-le et pointez vers la référence.

Le modèle mental​

Quatre façons d'ajouter du comportement​

Règles de nommage​

Ne devinez pas — consultez​

Les pièges qui produisent du code faux et sûr de lui​

Préférez l'étape intégrée à sa réimplémentation​

Validez un patch avant d'affirmer qu'il marche​

Unités​

Bien répondre à un utilisateur​