События

События научат сцену реагировать на действия людей без единой строчки кода. Когда что-то происходит, объект выполняет то, что вы перечислили.

КОГДА  кто-то нажимает на дверь
ТО     плавно открыть её за 600 мс
       выключить табличку «заперто»
       отправить сигнал «door-open»

Когда — это триггер. То — список шагов. Событий у объекта может быть сколько угодно, и каждое работает само по себе.

Добавьте событие

1. Выберите объект.
2. В инспекторе нажмите + новый компонент и выберите События. В компоненте сразу есть одно событие с триггером Нажатие на объект.
3. Нажмите на событие. Откроется панель Настройка события. Чтобы добавить ещё одно событие, нажмите + добавить событие.
4. Выберите триггер или оставьте Нажатие на объект.
5. Нажмите + добавить действие и выберите шаг. В списке есть поиск, а шаги разбиты на группы Действия, Анимации, Состояния и Логика.
6. Так же добавьте остальные шаги. Они выполняются по порядку.

Два списка, которые стоит держать под рукой

В справочнике триггеров есть все триггеры, в справочнике шагов — все шаги. Оба всегда актуальны. Рядом с названием из редактора в них указано имя для скриптов: Отправить сигнал — это emit_signal, а Сигнал — on-signal.

Триггеры

Триггер — это момент, когда запускается событие. Настройки каждого триггера — в справочнике выше. А в таблицах ниже — для чего нужен каждый.

Указатель и клавиши

В редакторе	Срабатывает, когда
Нажатие на объект	по объекту тапают или кликают; есть ветки для клика, нажатия и отпускания
Наведение	курсор наводят на объект или уводят с него
Двойной клик	по объекту дважды кликают в пределах 300 мс
Долгое нажатие	объект удерживают 450 мс, не сдвигая
Клавиша	клавишу нажимают или отпускают
Прокрутка	крутят колёсико; можно выбрать направление
Перетаскивание	посетитель перетаскивает AR-контент, который разместил
Масштабирование	посетитель сводит или разводит пальцы, чтобы изменить размер размещённого AR-контента
Поворот	посетитель поворачивает размещённый AR-контент

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

Жизненный цикл

В редакторе	Срабатывает, когда
Запуск	сцена запускается; его получает каждый объект
Изменение размера	меняется размер окна или экрана
Сворачивание	приложение или вкладка уходит в фон
Возврат	приложение или вкладка возвращается
Видимость	объект показывают или скрывают

Останавливайте звук при сворачивании

Если посетитель переключится на другое приложение, звук продолжит играть, пока вы его не остановите. Останавливайте звук по триггеру Сворачивание — например, переключайте объект в состояние, где звук выключен, — и запускайте снова по триггеру Возврат.

AR-трекинг

В редакторе	Срабатывает, когда
Распознавание	найден маркер или поверхность
Потеря трекинга	трекинг потерян
Размещение	посетитель разместил контент
Готовность VPS	позиционирование запустилось
Локализация VPS	реальное положение посетителя найдено
Неудачная локализация VPS	положение пока не найдено
Ошибка VPS	позиционирование вообще не смогло запуститься

Редактор показывает только те триггеры, которые может дать якорь вашей сцены. Распознавание срабатывает один раз, когда начинается трекинг, а не в каждом кадре.

Неудачная локализация VPS — это нормально

Неудачная локализация VPS срабатывает часто, пока посетитель ходит и ищет место, которое есть на карте. Считайте это сигналом «пробуем дальше», а не ошибкой, которую нужно показать.

Время и расстояние

В редакторе	Срабатывает
Задержка	один раз, через заданное время
Каждые N секунд	снова и снова; число повторов 0 значит «бесконечно»
Расстояние	когда что-то приближается на заданное расстояние или удаляется
Изменение переменной	когда переменная получает новое значение

У триггера Расстояние есть параметр На старте. Включите его, если объект может оказаться рядом уже в момент открытия сцены. Без него событие ждёт, пока что-нибудь сдвинется.

Состояния, столкновения и сигналы

В редакторе	Срабатывает, когда
Активация состояния	объект переходит в выбранное состояние
Деактивация состояния	объект выходит из этого состояния
Столкновение	объект касается другого; с какими именно — задаёт поле Сталкивается
Действие интерфейса	на карточке интерфейса нажали кнопку
Сигнал	другое событие отправило сигнал
Игровое управление	персонаж встаёт на месте, начинает двигаться, бежать или прыгать

Ветки

У некоторых триггеров есть ветки, поэтому одно событие может обработать все исходы. Например, одно событие Расстояние отвечает и на «подошёл ближе», и на «отошёл».

Триггер	Ветки
Расстояние	При сближении, При отдалении
Клавиша	При нажатии, При отпускании
Наведение	При наведении, При уходе
Нажатие на объект	При клике или тапе, При нажатии, При отпускании
Видимость	При показе, При скрытии
Игровое управление	В покое, При движении, При беге, При прыжке

У каждой ветки свой список шагов. У триггера без веток один список — При активации.

Выберите, на какие объекты действует шаг

У каждого шага есть поле Объект.

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

Нажатия доходят до родителей

Нажатие, наведение или действие на карточке доходят до объекта и до всех его родителей.

Поэтому можно поставить одно событие на группу, и оно поймает нажатие на любой объект внутри неё. Не нужно копировать одно и то же событие на сорок объектов.

Отсюда же следует:

• «нажатие в любом месте панели» — это одно событие на самой панели;
• если курсор переходит между двумя дочерними объектами одного родителя, у родителя не срабатывает ни наведение, ни уход: курсор его не покидал.

Некоторые триггеры работают иначе:

• Столкновение срабатывает только у объектов, которые соприкоснулись.
• Клавиша, Прокрутка, Изменение размера и Запуск не относятся к конкретному объекту, поэтому их получает каждый объект.

События, патчи и скрипты слышат одни и те же нажатия, клавиши и столкновения. Некоторые триггеры приходят в скрипты под другими именами. См. API ctx.

Обрабатывайте каждый триггер в одном месте

Если объект реагирует на один и тот же триггер и в событии, и в скрипте, реакция выполнится дважды. Когда что-то срабатывает два раза, причина почти всегда в этом.

Несколько клавиш для одного события

«Прыжок на пробел или W» — это одно событие, а не два. Кликните поле Клавиша и нажмите первую клавишу. Потом кликните или и нажмите следующую. Добавьте столько клавиш, сколько нужно.

• Каждая клавиша в списке работает сама по себе. Модификатор вроде Ctrl относится только к той клавише, вместе с которой его нажали.
• Остальные настройки триггера, например Автоповтор, действуют на все клавиши в списке.
• В этом же поле работает и кнопка мыши. Тогда в списке могут быть только кнопки мыши.

Событие хранит эти клавиши текстом. Ассистент или скрипт записывает их так:

ArrowUp        ctrl+KeyW        KeyA+KeyS        Space+double        mouse:middle

Вместо клавиши можно указать привязку клавиш. Привязки настраиваются в разделе Настройки проекта → Привязки клавиш. Поменяйте там клавишу для «прыжка» один раз, и все события с «прыжком» подхватят её. Это удобно, если кто-то попросит управление для левшей.

Шаги

Настройки каждого шага — в справочнике шагов.

Ссылки, звонки и смена сцен

В редакторе	Что делает
Переход на сцену	переходит на другую сцену
Переход на пространство	переходит в другое пространство, а если выбрать сцену — сразу на неё
Переход по URL ссылке	открывает ссылку в этой или в новой вкладке
Переход в мессенджер	открывает Facebook, VK, OK, Instagram, Telegram, WhatsApp или Viber
Вызов по номеру телефона	начинает телефонный звонок
Написать письмо	открывает новое письмо
Скачивание файла	скачивает файл из вашего проекта
Скачивание контакта	предлагает сохранить карточку контакта из заполненных полей

Шагу Переход в мессенджер для каждого приложения нужны свои данные:

• ID страницы для Facebook, VK и OK;
• имя пользователя для Instagram и Telegram;
• номер телефона для WhatsApp и Viber.

Показать, скрыть и изменить объекты

В редакторе	Что делает
Показать / скрыть объект	показывает или скрывает выбранные объекты; если выбрана сцена, делает её активной
Переключить состояние	включает сохранённое состояние; плавно, если задать длительность
Изменить свойства	один раз применяет несколько значений, как временное состояние

Анимация

В редакторе	Что делает
Проиграть анимацию	проигрывает анимацию из таймлайна; можно задать зацикливание, повторы, скорость и задержку
Остановить анимацию	останавливает её

Проиграть анимацию может запустить анимацию любого объекта. Поэтому одна кнопка может запустить сцену, в которой сразу двигается несколько объектов.

Чтобы переместить объект, плавно скрыть его или сменить цвет, сделайте анимацию в панели Анимация, а потом запустите её этим шагом. Для одного изменения хватит шага Переключить состояние с длительностью.

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

Движение

В редакторе	Что делает
Следовать за объектом	всё время следует за другим объектом; вы задаёте расстояние, смещение, плавность и скорость
Смотреть на объект	поворачивается к цели, не двигаясь с места
Прекратить следование	перестаёт следовать и смотреть
Лететь по пути	движется по пути
Остановить полёт по пути	останавливает движение по пути

Логика

В редакторе	Что делает
Если — иначе	проверяет условие и выполняет один из двух списков шагов
Задать переменную	задаёт значение переменной, прибавляет к нему или переключает его
Отправить сигнал	отправляет сигнал выбранным объектам или всей сцене
Подождать и	ждёт, а потом выполняет вложенные шаги

Указатель

Захватить указатель прячет курсор мыши и отдаёт его движения сцене. Это нужно в играх от первого лица, чтобы курсор не уходил за пределы окна. Отпустить указатель возвращает курсор.

Триггеры и шаги из плагинов

Плагин, добавленный в проект, может принести свои триггеры и шаги. Они появляются в списках под названием плагина, и пользоваться ими можно как встроенными.

• Они есть только в проектах, в которые добавлен плагин.
• У триггера плагина могут быть настройки. Тогда событие срабатывает, только когда они совпадают. Оставьте настройку пустой, чтобы реагировать на каждый запуск.
• Если плагин убрали из проекта, его триггеры больше не срабатывают, а шаги пропускаются.

Как сделать свои — в разделе Код в проекте.

Добавьте условие

Условие — это шаг Если — иначе. Такие шаги можно вкладывать друг в друга, чтобы получить больше двух исходов.

Что проверять, выберите в поле Условие:

В редакторе	Проверяет	Какие поля заполнить
Всегда	ничего; условие всегда истинно	—
Переменная	значение переменной	Переменная, Сравнение, Значение
Расстояние	насколько объект этого события далеко от другого объекта	Объект, Сравнение, Порог
Состояние	в каком состоянии другой объект	Объект, Состояние
Видимость	виден ли объект	Объект, Ожидается
Случайность	случайный шанс	Порог, в процентах

Как сравниваются значения:

• 3 читается как число, true — как да/нет, всё остальное — как текст.
• == и != проверяют точное совпадение.
• >, >=, < и <= сравнивают числа.

Переменные, сигналы и таймеры

Переменные живут в пределах одного посещения. Каждый раз, когда кто-то открывает проект, они пустые. Чтобы задать начальные значения, задайте их в событии с триггером Запуск. Скрипт видит эти же переменные как глобальные.

Сигналы позволяют одному событию запускать другие, не копируя шаги. Например, несколько событий могут ждать сигнал level-complete, а отправить его может любое событие. Если сигнал раз за разом вызывает сам себя, через восемь кругов он остановится, чтобы сцена не зависла.

Таймеры (Задержка и Каждые N секунд) запускаются, когда их объект включается, и сбрасываются, когда он выключается. Когда объект снова включится, отсчёт начнётся заново. Пропущенные срабатывания не выполняются все разом.

Состояния

Состояние — это сохранённый вид объекта: положение, цвет, видимость и другое. Шаг Переключить состояние включает его. Если задать длительность, объект изменится плавно.

Используйте состояния для переключателя, подсветки или двери, которая бывает открыта и закрыта.

Пока выбрано состояние, правки попадают в него

Если у объекта выбрано одно из состояний, любые изменения объекта меняют это состояние. Когда вы собираете состояния, так и нужно. Но если вы забыли, что состояние выбрано, это сбивает с толку.

Подробнее — на странице Состояния.

Повторный трекинг

В AR-сценах у каждого события есть режим повторного трекинга. Он определяет, что происходит, когда маркер потерялся и нашёлся снова:

• сразу запустить шаги заново;
• больше не запускать их;
• запустить их заново, когда закончатся текущие шаги.

---

Дальше: Анимация — как заставить объекты двигаться.