Briefing para asistentes

Esta página está escrita para entregársela a un modelo de IA. Pégala en una conversación, o apunta al modelo a esta URL, antes de pedirle ayuda con un proyecto de AR Clip.

Los asistentes que buscan contexto legible por máquina lo encontrarán por su cuenta en /llms.txt, con toda la documentación en un solo archivo en /llms-full.txt.

Existe porque ningún modelo se ha entrenado con esta plataforma. Sin ella recurren al motor que sí conocen (Unity, three.js, A-Frame) y producen respuestas que parecen correctas y no lo son.

El modelo mental

Todo en un proyecto es una entity. Una entity es un nombre más un conjunto de componentes, y los componentes deciden lo que es. No hay jerarquía de clases ni tipos de objeto donde elegir.

Project
└── Space          fondo, iluminación, rejilla y unidades compartidos
    └── Scene      una entity con un Anchor: el disparador que la hace aparecer
        └── Entity
            └── Entity      las entities se anidan

Dos relaciones que no hay que confundir:

Composición: una entity tiene componentes. Uno de cada clase. Los componentes no son hijos.
Contención: una entity contiene otras entities. Mover un padre mueve a sus hijos.

Una escena es una entity con Anchor y sin Transform. La lógica a nivel de space es una entity con Script o Patch y sin padre.

Nunca escribes sistemas. El motor reacciona a los componentes; tu trabajo es decidir qué componentes existen y qué valores tienen.

Cuatro formas de añadir comportamiento

Capa	Vive en	Úsala para
Events	un componente Events	disparador → lista de pasos; la mayoría de la interactividad
Patches	un grafo o recurso de patch	lógica con valores y condiciones, construida visualmente
Scripts	un recurso de script	cualquier cosa genuinamente programática
UI	una tarjeta DivKit	toda la interfaz 2D

Las cuatro escriben en los mismos componentes. El mismo disparador atendido en dos de ellas se dispara dos veces: un fallo generado muy habitual.

Reglas de nomenclatura

Los disparadores van en kebab-case: on-click, on-launch, on-collide.
Los pasos van en snake_case: play_animation, set_visibility, scene_transit_action.
La resolución es exacta. Un nombre mal escrito no da error: sencillamente no coincide nunca.
El editor muestra etiquetas humanas («Mostrar / ocultar objeto»); los identificadores de arriba son lo que usa el código.

No adivines: consúltalo

Si estás conectado por MCP, estos responden desde el motor en vivo:

Llamada	Devuelve
`list_component_schemas`	cada componente y sus campos
`list_event_types`	cada disparador y paso con sus parámetros
`list_patch_nodes`	cada nodo de patch con sus puertos
`describe_*_api`	orientación en prosa por área

Llámalos antes de escribir nada que nombre un componente, un disparador, un paso o un nodo. Inventarse un nombre plausible es, con diferencia, el modo de fallo más común aquí.

Sin MCP, usa la referencia generada: componentes · disparadores · pasos · nodos de patch · nodos de shader.

Trampas que producen código equivocado con aire de seguridad

Escribir un valor anidado lo reemplaza entero

update({ position: { y: 2 } }) pone x y z a cero. Expande siempre:

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

Un material es una lista de slots

material.update({ color }) no hace nada: color vive dentro de un slot.

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

Nunca asignes dentro de $data

Parece funcionar y el cambio se descarta. Solo escriben update() y updateAt().

Fijar el transform de un cuerpo físico dinámico no hace nada

La física es dueña de su posición y la sobrescribe en el siguiente paso. Usa ctx.physics.teleport para colocarlo y applyImpulse / applyForce para moverlo.

Un modelo importado no tiene forma de colisión

Un GLB no es sólido hasta que le das un collider. Uno dinámico atraviesa el mundo.

Más reglas con las que tropiezan los generadores:

La rotación va en radianes en los scripts y en grados en todos los sitios donde mira una persona: el editor, los puertos de los nodos de patch, las herramientas MCP.
Multiplica por dt dentro de ctx.tick, o el movimiento correrá a la tasa de fotogramas del dispositivo.
No hay evento de «animación terminada» en ningún mecanismo. Cronométralo tú.
Los scripts no tienen DOM, ni fetch, ni temporizadores, ni biblioteca de renderizado. Usa ctx.tick, ctx.audio, ctx.store, y una tarjeta de UI para la interfaz.
El editor no ejecuta la lógica. Scripts, patches, física y temporizadores solo corren en la vista previa o en una publicación. Nunca le digas a alguien que su script «debería correr en el editor».
Mientras un state está activo, las ediciones de ese objeto se registran en el state, no en el objeto.
La línea de tiempo guarda channels para la edición y una lista keyframes horneada para la reproducción. Escribir channels sin volver a hornear significa que no se reproduce nada.
Un objeto, un mecanismo de animación. La línea de tiempo sobrescribe una transición en cada fotograma.

Prefiere el paso integrado a reimplementarlo

ctx.step(name, params, { targets }) ejecuta cualquier paso que ofrezca el editor: animación, cambio de state, transiciones de escena, transiciones. Consulta la referencia de pasos antes de escribir código a mano.

Valida un patch antes de afirmar que funciona

Compílalo y lee el resultado. Un grafo que no compila informa de un ciclo de datos o de JavaScript roto, y el código compilado es exactamente lo que se ejecutará. Por MCP es preview_patch_code.

Unidades

Magnitud	En los datos	Donde la ve una persona
Posición	metros	unidades del proyecto
Rotación	radianes	grados
Tiempo de animación	segundos	segundos (milisegundos en los cambios de state)
Opacidad	0–1	0–100 en los keyframes y en el paso de opacidad
Tamaño de letra	píxeles, 1000 px = 1 m	píxeles
Fotogramas de clip	30 fps	fotogramas

Responder bien a una persona

Pregúntale qué capa quiere. «Sin código» y «en un script» llevan a respuestas completamente distintas para la misma pregunta.
Prefiere la capa más simple que funcione. Un evento gana a un patch; un patch gana a un script.
Dile dónde hacer clic. Para quien está en el editor, los nombres de los paneles importan más que los conceptos.
Recuérdale que use la vista previa. La mayoría de los «no funciona» son el editor sin ejecutar la lógica.
No te inventes nombres. Si no estás seguro, dilo y señala la referencia.

El modelo mental​

Cuatro formas de añadir comportamiento​

Reglas de nomenclatura​

No adivines: consúltalo​

Trampas que producen código equivocado con aire de seguridad​

Prefiere el paso integrado a reimplementarlo​

Valida un patch antes de afirmar que funciona​

Unidades​

Responder bien a una persona​