Resumen para asistentes

Dale esta página a cualquier modelo de IA antes de pedirle ayuda con un proyecto de AR Clip. Pégala en el chat o dale al modelo la dirección de esta página.

Ningún modelo se ha entrenado con AR Clip. Sin esta página, los modelos toman prestado de otros motores que conocen y dan respuestas que parecen correctas pero no lo son.

Las herramientas de IA que buscan contexto legible por máquinas lo encuentran solas en /llms.txt. Toda la documentación en un solo archivo está en /llms-full.txt.

Cómo se construye un proyecto

Todo lo que hay en un proyecto es una entidad. Una entidad es un nombre más un conjunto de componentes. Los componentes deciden qué es la entidad. No hay clases ni tipos de objeto entre los que elegir.

Proyecto
└── Espacio        fondo, iluminación, cuadrícula y unidades compartidos
    └── Escena     una entidad con Anchor: el disparador que la hace aparecer
        └── Entidad
            └── Entidad     las entidades se anidan

No confundas estas dos relaciones:

Composición: una entidad tiene componentes, como mucho uno de cada tipo. Los componentes no son hijos.
Contención: una entidad contiene otras entidades. Al mover un padre se mueven sus hijos.

Una escena es una entidad con Anchor y sin Transform. La lógica de todo el espacio es una entidad con Script o Patch y sin padre.

No escribes el código que hace funcionar los componentes. Tu trabajo es decidir qué componentes existen y qué valores tienen.

Cuatro formas de añadir comportamiento

Capa	Dónde vive	Para qué se usa
Eventos	un componente Events	un disparador y una lista de pasos; la mayor parte de la interactividad
Patches	un grafo o recurso de patch	lógica con valores y condiciones, construida de forma visual
Scripts	un recurso de script	todo lo que de verdad necesita código
UI	una tarjeta de interfaz	toda la interfaz 2D

Las cuatro cambian los mismos componentes. Si dos de ellas gestionan el mismo disparador, se dispara dos veces. Es un error muy habitual en las respuestas generadas.

Nombres

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.
Los disparadores de teclado y ratón cambian de nombre en los scripts. Un evento usa on-key y on-mouse con ramas. Un script escucha on-keydown / on-keyup y on-mousedown / on-mouseup / on-click.
Los nombres tienen que coincidir exactamente. Un nombre mal escrito no da ningún error: simplemente nunca coincide.
El editor muestra etiquetas legibles, como «Show / hide object». El código usa los ids de arriba.

Consulta los nombres, no los adivines

Si estás conectado por MCP, estas llamadas muestran exactamente lo que existe:

Llamada	Devuelve
`list_component_schemas`	todos los componentes y sus campos
`list_event_types`	todos los disparadores y pasos, con sus parámetros
`list_patch_nodes`	todos los nodos de patch, con sus puertos
`describe_*_api`	una guía escrita para cada área

Llámalas antes de escribir cualquier cosa que nombre un componente, un disparador, un paso o un nodo. Inventarse un nombre que suena bien es el error más habitual en esta plataforma.

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

Errores que parecen correctos

Escribir parte de un valor anidado lo sustituye entero

update({ position: { y: 2 } }) pone x y z a cero. Copia siempre el valor anterior:

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

Un material es una lista de slots

material.update({ color }) no hace nada, porque color está dentro de un slot:

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

Nunca asignes dentro de $data

Parece que funciona, pero el cambio se pierde. Solo update() y updateAt() escriben datos.

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

La física controla 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 colisionador. Si es dinámico, atraviesa el mundo y cae.

Más reglas que confunden a los modelos:

La rotación va en radianes en los scripts y en grados en todo lo que ve una persona: el editor, los puertos de los nodos de patch, las herramientas MCP.
Multiplica por dt en ctx.tick, o la velocidad del movimiento dependerá de los fotogramas por segundo del dispositivo.
En los scripts, importa las clases de componentes desde @was/engine: TransformComponent, MetaComponent y las demás. Solo init y defineProps son globales.
No hay un evento de «animación terminada» en ningún mecanismo. Controla el tiempo tú mismo.
Los scripts no tienen DOM, ni fetch, ni temporizadores, ni librería de renderizado. Usa ctx.tick, ctx.audio, ctx.store y una tarjeta de interfaz para la interfaz.
El editor no ejecuta la lógica. Los scripts, los patches, la física y los temporizadores solo se ejecutan en la vista previa o en un proyecto publicado. Nunca le digas a un usuario que su script «debería ejecutarse en el editor».
Mientras hay un estado activo, los cambios en ese objeto se guardan en el estado, no en el objeto.
Usa las herramientas de la línea de tiempo para cambiarla. Si editas directamente el componente de la línea de tiempo, puede que la animación no se reproduzca.
Un objeto, una forma de animarlo. La línea de tiempo sobrescribe una transición.

Usa un paso incluido en vez de reescribirlo

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

Revisa un patch antes de decir que funciona

Míralo como código y lee el resultado. Un grafo con un problema informa de un ciclo de datos o de un JavaScript roto. Por MCP, usa preview_patch_code.

Unidades

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

Cómo responder al usuario

Pregunta qué capa quiere. «Sin código» y «en un script» llevan a respuestas muy distintas para la misma pregunta.
Elige la capa más sencilla que funcione. Un evento es mejor que un patch; un patch es mejor que un script.
Di dónde hacer clic. Para alguien que 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» se deben a que el editor no ejecuta la lógica.
No te inventes nombres. Si no estás seguro, dilo y remite a la referencia.

Cómo se construye un proyecto​

Cuatro formas de añadir comportamiento​

Nombres​

Consulta los nombres, no los adivines​

Errores que parecen correctos​

Usa un paso incluido en vez de reescribirlo​

Revisa un patch antes de decir que funciona​

Unidades​

Cómo responder al usuario​