Бриф для ассистентов

Дайте эту страницу любой AI-модели, прежде чем просить её помочь с проектом AR Clip. Вставьте текст в чат или дайте модели адрес этой страницы.

Ни одна модель не обучалась на AR Clip. Без этой страницы модели берут знания из других знакомых им движков и дают ответы, которые выглядят правильными, но таковыми не являются.

AI-инструменты, которые ищут контекст в машиночитаемом виде, сами найдут его в /llms.txt. Вся документация одним файлом лежит в /llms-full.txt.

Как устроен проект

Всё в проекте — это сущности. Сущность — это имя плюс набор компонентов. Компоненты определяют, чем является сущность. Никаких классов и типов объектов, из которых нужно выбирать, нет.

Проект
└── Пространство   общие фон, освещение, сетка, единицы
    └── Сцена      сущность с компонентом Anchor — триггером, при котором сцена появляется
        └── Сущность
            └── Сущность    сущности вкладываются друг в друга

Не путайте два вида связей:

• Состав — у сущности есть компоненты, не больше одного каждого вида. Компоненты — не дочерние элементы.
• Вложенность — сущность содержит другие сущности. Когда двигается родитель, двигаются и дочерние.

Сцена — это сущность с Anchor и без Transform. Логика всего пространства — это сущность со Script или Patch и без родителя.

Код, который заставляет компоненты работать, писать не нужно. Ваша задача — решить, какие компоненты существуют и какие у них значения.

Четыре способа задать поведение

Слой	Где живёт	Для чего
События	компонент Events	триггер и список шагов; большая часть интерактивности
Патчи	граф патча или ресурс	логика со значениями и условиями, собранная визуально
Скрипты	ресурс скрипта	всё, чему действительно нужен код
UI	UI-карточка	весь 2D-интерфейс

Все четыре меняют одни и те же компоненты. Если два из них обрабатывают один и тот же триггер, он срабатывает дважды. Это очень частая ошибка в сгенерированных ответах.

Имена

• Триггеры пишутся в kebab-case: on-click, on-launch, on-collide.
• Шаги пишутся в snake_case: play_animation, set_visibility, scene_transit_action.
• В скриптах у триггеров клавиш и мыши другие имена. Событие использует on-key и on-mouse с ветками. Скрипт слушает on-keydown / on-keyup и on-mousedown / on-mouseup / on-click.
• Имена должны совпадать точно. Имя с опечаткой не вызывает ошибку — оно просто ни с чем не совпадает.
• В редакторе показываются понятные подписи, например «Показать / скрыть объект». В коде используются id, приведённые выше.

Проверяйте имена, а не угадывайте

Если вы подключены по MCP, эти вызовы показывают, что есть на самом деле:

Вызов	Что возвращает
list_component_schemas	все компоненты и их поля
list_event_types	все триггеры и шаги с параметрами
list_patch_nodes	все ноды патчей с их портами
describe_*_api	текстовые пояснения по каждой области

Вызывайте их, прежде чем писать что-либо, где упоминается компонент, триггер, шаг или нода. Придумать правдоподобное имя — самая частая ошибка на этой платформе.

Без MCP пользуйтесь справочником: компоненты · триггеры · шаги · ноды патчей · ноды шейдеров.

Ошибки, которые выглядят правильно

Запись части вложенного значения заменяет его целиком

update({ position: { y: 2 } }) обнуляет x и z. Всегда разворачивайте старое значение:

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

Материал — это список слотов

material.update({ color }) ничего не делает, потому что color лежит внутри слота:

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

Никогда не присваивайте значения в $data

Кажется, что это работает, но изменение теряется. Данные записывают только update() и updateAt().

Transform у динамического физического тела задавать бесполезно

Положением управляет физика и на следующем шаге перезаписывает его. Чтобы поставить тело в точку, используйте ctx.physics.teleport, а чтобы двигать — applyImpulse / applyForce.

У импортированной модели нет формы для столкновений

GLB не становится твёрдым, пока вы не дадите ему коллайдер. Динамическая модель без него проваливается сквозь мир.

Ещё правила, на которых модели ошибаются:

• Поворот в скриптах — в радианах, а везде, куда смотрит человек, — в градусах: в редакторе, в портах нод патчей, в инструментах MCP.
• В ctx.tick умножайте на dt, иначе скорость движения будет зависеть от частоты кадров устройства.
• Классы компонентов в скриптах импортируйте из @was/engine: TransformComponent, MetaComponent и остальные. Глобальны только init и defineProps.
• События «анимация закончилась» нет ни в одном механизме. Отсчитывайте время сами.
• В скриптах нет DOM, fetch, таймеров и библиотеки рендеринга. Используйте ctx.tick, ctx.audio, ctx.store, а для интерфейса — UI-карточку.
• Редактор не запускает логику. Скрипты, патчи, физика и таймеры работают только в предпросмотре или в опубликованном проекте. Никогда не говорите пользователю, что его скрипт «должен работать в редакторе».
• Пока активно состояние, правки объекта сохраняются в это состояние, а не в сам объект.
• Меняйте таймлайн инструментами таймлайна. Если править компонент таймлайна напрямую, анимация может не проиграться.
• Один объект — один способ анимации. Таймлайн перезаписывает переход.

Используйте встроенный шаг, а не пишите его заново

ctx.step(name, params, { targets }) запускает любой шаг, который есть в редакторе: анимацию, переключение состояний, переходы между сценами, переходы. Прежде чем писать то же самое вручную, загляните в справочник шагов.

Проверьте патч, прежде чем говорить, что он работает

Посмотрите на него в виде кода и прочитайте результат. Граф с ошибкой сообщает о цикле в данных или о сломанном JavaScript. По MCP используйте preview_patch_code.

Единицы

Величина	В данных	Что видит человек
Положение	метры	единицы проекта
Поворот	радианы	градусы
Время анимации	секунды	секунды (миллисекунды при переключении состояний)
Прозрачность	0–1	0–100 в ключевых кадрах и в шаге Прозрачность
Размер шрифта	пиксели, 1000 px = 1 м	пиксели
Кадры клипа	30 кадров/с	кадры

Как отвечать пользователю

1. Спросите, какой слой нужен. «Без кода» и «в скрипте» дают на один и тот же вопрос очень разные ответы.
2. Выберите самый простой слой, который справится. Событие лучше патча, патч лучше скрипта.
3. Скажите, куда нажать. Человеку в редакторе названия панелей важнее понятий.
4. Напомните про предпросмотр. Большинство жалоб «не работает» возникают потому, что редактор не запускает логику.
5. Не придумывайте имена. Если не уверены, так и скажите и отправьте к справочнику.