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

Эта страница написана, чтобы её отдавали AI-модели. Вставьте её в разговор или направьте модель на этот URL, прежде чем просить помочь с проектом AR Clip.

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

Страница существует потому, что ни одна модель не обучалась на этой платформе. Без неё они тянутся к тому движку, который знают (Unity, three.js, A-Frame), и выдают ответы, которые выглядят правильными и таковыми не являются.

---

Ментальная модель

Всё в проекте — это entity. Entity — это имя плюс набор компонентов, и именно компоненты решают, чем она является. Никакой иерархии классов и никаких типов объектов на выбор.

Project
└── Space          общий фон, освещение, сетка, единицы измерения
    └── Scene      entity с якорем — триггером, который её показывает
        └── Entity
            └── Entity      entity вкладываются

Два отношения, которые нельзя путать:

• Композиция — entity имеет компоненты. По одному каждого вида. Компоненты — не дети.
• Вложенность — entity содержит другие entity. Перемещение родителя двигает детей.

Сцена — это entity с якорем и без Transform. Логика уровня space — это entity со Script или Patch и без родителя.

Системы вы никогда не пишете. Движок реагирует на компоненты; ваша задача — решить, какие компоненты существуют и какие у них значения.

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

Слой	Живёт в	Для чего
Events	компоненте Events	триггер → список шагов; большая часть интерактива
Patches	графе патчей или ресурсе	логика со значениями и условиями, собранная визуально
Scripts	ресурсе-скрипте	всё по-настоящему программируемое
UI	карточке DivKit	весь двумерный интерфейс

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

Правила именования

• Триггеры в kebab-case: on-click, on-launch, on-collide.
• Шаги в snake_case: play_animation, set_visibility, scene_transit_action.
• Сопоставление точное. Опечатка в имени не даёт ошибки — она просто никогда не совпадает.
• Редактор показывает человеческие подписи («Показать / скрыть объект»); идентификаторы выше — это то, чем пользуется код.

Не гадайте — посмотрите

Если вы подключены через 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.
• Умножайте на dt в ctx.tick, иначе движение пойдёт со скоростью кадров устройства.
• События «анимация закончилась» нет ни в одном механизме. Отмеряйте время сами.
• У скриптов нет DOM, fetch, таймеров и библиотек рендеринга. Используйте ctx.tick, ctx.audio, ctx.store и UI-карточку для интерфейса.
• Редактор не исполняет логику. Скрипты, патчи, физика и таймеры работают только в предпросмотре или в публикации. Никогда не говорите пользователю, что его скрипт «должен работать в редакторе».
• Пока состояние активно, правки этого объекта записываются в состояние, а не в объект.
• Таймлайн хранит channels для авторинга и запечённый список keyframes для воспроизведения. Запись в channels без повторного запекания означает, что ничего не проиграется.
• Один объект — один механизм анимации. Таймлайн перезаписывает переход каждый кадр.

Лучше встроенный шаг, чем его повторная реализация

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

Проверяйте патч, прежде чем утверждать, что он работает

Скомпилируйте и прочитайте результат. Граф, который не компилируется, сообщит о цикле в данных или о сломанном JavaScript, а скомпилированный исходник — это ровно то, что будет выполняться. Через MCP это preview_patch_code.

Единицы измерения

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

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

1. Спросите, какой слой ему нужен. «Без кода» и «в скрипте» ведут к совершенно разным ответам на один и тот же вопрос.
2. Предпочитайте простейший слой, который решает задачу. Событие лучше патча; патч лучше скрипта.
3. Говорите, куда нажимать. Тому, кто сидит в редакторе, названия панелей важнее концепций.
4. Напоминайте про предпросмотр. Большинство сообщений «не работает» — это редактор, который не исполняет логику.
5. Не выдумывайте имена. Не уверены — так и скажите и укажите на справочник.