Brief pour les assistants

Donnez cette page à n'importe quel modèle d'IA avant de lui demander de l'aide sur un projet AR Clip. Collez-la dans le chat, ou donnez au modèle l'adresse de cette page.

Aucun modèle n'a été entraîné sur AR Clip. Sans cette page, les modèles s'inspirent d'autres moteurs qu'ils connaissent et donnent des réponses qui ont l'air justes mais sont fausses.

Les outils d'IA qui cherchent un contexte lisible par une machine le trouvent d'eux-mêmes sur /llms.txt. Toute la documentation en un seul fichier se trouve sur /llms-full.txt.

Comment un projet est construit

Tout ce qui se trouve dans un projet est une entité. Une entité est un nom et un ensemble de composants. Ce sont les composants qui définissent ce qu'est l'entité. Il n'y a ni classes, ni types d'objets parmi lesquels choisir.

Projet
└── Space          arrière-plan, éclairage, grille, unités partagés
    └── Scène      une entité portant un Anchor — le déclencheur qui la fait apparaître
        └── Entité
            └── Entité      les entités s'imbriquent

Ne confondez pas ces deux relations :

La composition — une entité a des composants, au plus un de chaque type. Les composants ne sont pas des enfants.
L'inclusion — une entité contient d'autres entités. Déplacer un parent déplace ses enfants.

Une scène est une entité avec un Anchor et sans Transform. La logique de tout l'espace est une entité avec un Script ou un Patch, et sans parent.

Vous n'écrivez pas le code qui fait fonctionner les composants. Votre travail consiste à décider quels composants existent et quelles valeurs ils contiennent.

Quatre façons d'ajouter un comportement

Couche	Où elle se trouve	À utiliser pour
Événements	un composant Events	un déclencheur et une liste d'étapes ; l'essentiel de l'interactivité
Patchs	un graphe de patch ou une ressource	une logique avec des valeurs et des conditions, construite visuellement
Scripts	une ressource de script	tout ce qui nécessite vraiment du code
UI	une carte UI	toute l'interface 2D

Les quatre modifient les mêmes composants. Si deux d'entre elles traitent le même déclencheur, il se déclenche deux fois. C'est un bug très fréquent dans les réponses générées.

Noms

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.
Les déclencheurs de touche et de souris changent de nom dans les scripts. Un événement utilise on-key et on-mouse avec des branches. Un script écoute on-keydown / on-keyup et on-mousedown / on-mouseup / on-click.
Les noms doivent correspondre exactement. Un nom mal tapé ne produit aucune erreur — il ne correspond simplement jamais à rien.
L'éditeur affiche des libellés lisibles, comme « Show / hide object ». Le code utilise les identifiants ci-dessus.

Cherchez les noms, ne les devinez pas

Si vous êtes connecté via MCP, ces appels montrent exactement ce qui existe :

Appel	Renvoie
`list_component_schemas`	chaque composant et ses champs
`list_event_types`	chaque déclencheur et chaque étape, avec leurs paramètres
`list_patch_nodes`	chaque nœud de patch, avec ses ports
`describe_*_api`	des explications rédigées pour chaque 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 qui a l'air plausible est l'erreur la plus fréquente sur cette plateforme.

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

Des erreurs qui ont l'air justes

Écrire une partie d'une valeur imbriquée remplace toute la valeur

update({ position: { y: 2 } }) met x et z à zéro. Recopiez toujours l'ancienne valeur avec l'opérateur spread :

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

Un matériau est une liste d'emplacements

material.update({ color }) ne fait rien, car color se trouve à l'intérieur d'un emplacement (slot) :

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

N'assignez jamais de valeur dans $data

Cela semble fonctionner, mais la modification est perdue. Seuls update() et updateAt() écrivent des données.

Définir le transform d'un corps physique dynamique ne fait rien

La physique contrôle sa position et l'écrase 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 passe à travers le monde.

D'autres règles qui piègent les modèles :

La rotation est en radians dans les scripts, et en degrés partout où une personne la voit — l'éditeur, les ports des nœuds de patch, les outils MCP.
Multipliez par dt dans ctx.tick, sinon la vitesse de déplacement dépend de la fréquence d'images de l'appareil.
Dans un script, importez les classes de composants depuis @was/engine : TransformComponent, MetaComponent et les autres. Seuls init et defineProps sont globaux.
Il n'y a pas d'événement « animation terminée », dans aucun mécanisme. Mesurez le temps vous-même.
Les scripts n'ont ni DOM, ni fetch, ni minuteurs, ni 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. Les scripts, les patchs, la physique et les minuteurs ne tournent que dans l'aperçu ou dans un projet publié. Ne dites jamais à un utilisateur que son script « devrait s'exécuter dans l'éditeur ».
Tant qu'un état est actif, les modifications de cet objet sont enregistrées dans l'état, pas dans l'objet.
Modifiez une timeline avec les outils de timeline. Si vous modifiez directement le composant de la timeline, l'animation risque de ne pas se jouer.
Un objet, une seule façon de l'animer. La timeline écrase une transition.

Utilisez une étape intégrée au lieu de la réécrire

ctx.step(name, params, { targets }) exécute n'importe quelle étape proposée par l'éditeur : animation, changement d'état, passage d'une scène à l'autre, transitions. Consultez la référence des étapes avant d'écrire la même chose à la main.

Vérifiez un patch avant de dire qu'il fonctionne

Regardez-le sous forme de code et lisez le résultat. Un graphe qui a un problème signale un cycle de données ou du JavaScript cassé. Via MCP, utilisez preview_patch_code.

Unités

Grandeur	Dans les données	Ce que voit une personne
Position	mètres	unités du projet
Rotation	radians	degrés
Durée d'animation	secondes	secondes (millisecondes pour les changements d'état)
Opacité	0–1	0–100 dans les images clés et dans l'étape d'opacité
Taille de police	pixels, 1000 px = 1 m	pixels
Images de clip	30 i/s	images

Comment répondre à l'utilisateur

Demandez quelle couche il veut utiliser. « Sans code » et « dans un script » mènent à des réponses très différentes pour la même question.
Choisissez 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 qui est dans l'éditeur, les noms de panneaux comptent plus que les concepts.
Rappelez-lui de prévisualiser. La plupart des « ça ne marche pas » viennent du fait que l'éditeur n'exécute pas la logique.
N'inventez pas de noms. Si vous n'êtes pas sûr, dites-le et renvoyez vers la référence.

Comment un projet est construit​

Quatre façons d'ajouter un comportement​

Noms​

Cherchez les noms, ne les devinez pas​

Des erreurs qui ont l'air justes​

Utilisez une étape intégrée au lieu de la réécrire​

Vérifiez un patch avant de dire qu'il fonctionne​

Unités​

Comment répondre à l'utilisateur​