Где показывается оверлей

Поверх игры: В прозрачном окне над игрой, там, куда его поставил игрок, и того размера, какой он задал. Здесь оверлей проводит почти всё время.
В режиме редактирования: Когда игрок двигает и растягивает оверлеи макета. Оверлей продолжает работать, и Racelink сообщает ему, что идёт редактирование.
В OBS: У каждого оверлея есть ссылка для источника «Браузер». В OBS открывается отдельная копия той же страницы с теми же настройками и данными.
В превью: Когда игрок наводит курсор на оверлей в окне «Добавить оверлей», и в анимации на странице оверлея в Мастерской. Превью показывает оверлей на демо-данных.
В вашем браузере: Во время разработки: http://localhost:5173/?demo, тот же код на демо-данных.

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

Прозрачный фон

Поверх игры всё, что оверлей не рисует, должно быть прозрачным. Не задавайте фон для html и body и не указывайте color-scheme: иначе браузер зальёт фон белым или чёрным. Свои панели рисуйте только там, где они нужны.

Любой размер

Игрок растягивает окно оверлея как хочет, в пределах, которые вы задали в манифесте (size.min и size.max). Оверлей должен заполнять окно любого размера: используйте относительные единицы, container queries или canvas и SVG по размеру окна.

Если оверлей нарисован под один размер, попросите масштабировать его целиком:

racelink.overlay.json

"size": { "default": [400, 300], "resize": "scale" }

Готовый первый кадр

Превью и только что открытая страница в OBS показывают оверлей сразу. Поэтому уже первый кадр должен выглядеть законченным:

Начинайте рисовать только после события ready. До него настройки ещё не игрока, а значения по умолчанию.
Не делайте анимацию появления. Первые 1,5 секунды SDK ставит атрибут data-racelink-starting на <html> и сразу завершает CSS-переходы. Не запускайте плавное появление и из кода.
Если оверлей показывает историю (след, график), в демо-режиме заполните её сразу из overlay.demoHistory(блок, секунды), чтобы она не начиналась с пустоты.

Всё это по шагам делается в главе руководства Доведите вид.

Режим редактирования

Пока игрок расставляет макет, overlay.editMode равно true, а событие host сообщает, когда режим включился или выключился. Используйте это, чтобы помочь поставить оверлей на место: покажите панель, которая вне гонки пустая, рамку или примерные значения.

src/main.ts

const showFrame = (editing: boolean): void => {
  root.classList.toggle('editing', editing);
};
showFrame(overlay.editMode);
overlay.on('host', (host) => showFrame(host.editMode));

src/App.tsx

const [editing, setEditing] = useState(overlay.editMode);
useEffect(() => overlay.on('host', (host) => setEditing(host.editMode)), [overlay]);