Как данные попадают в оверлей

Путь данных

Оверлей никогда не общается с игрой напрямую. С играми работает Racelink и отдаёт оверлеям одинаковые данные, какая бы игра ни была запущена. Поэтому один и тот же оверлей работает и в iRacing, и в Assetto Corsa без отдельного кода под каждую игру.

Всё это происходит на компьютере игрока: данные никуда не отправляются, промежуточного сервера нет. Оверлей может обращаться только к Racelink, если игрок не разрешил ему большего (Безопасность).

Блоки данных

Данные разделены на блоки — группы связанных значений, которые приходят вместе. Например, car — педали, скорость и передача, timing — времена кругов, drivers — все машины сессии. В коде и API блок называется topic. Все блоки и их поля есть в справочнике полей.

Каждый блок приходит так часто, как обычно меняются его данные:

car: около 60 раз в секунду
vehicle: около 20 раз в секунду; радар так же
controls: около 10 раз в секунду; список машин так же
session: около 4 раз в секунду; времена кругов и топливо так же
weather: раз в секунду; карта трассы так же

Подписываться на блоки вручную не нужно. Когда ваш код впервые обращается к блоку, SDK сам просит Racelink его присылать. Блок, к которому код не обращается, не приходит. Поэтому читайте только то, что показываете.

src/main.ts

overlay.on('telemetry', ({ car, timing }) => {
  // Код читает car и timing, поэтому приходят только эти два блока.
  render(car.speedKph, timing.lap.lastSeconds);
});

src/App.tsx

const { telemetry } = useOverlay();
// Код читает car и timing, поэтому приходят только эти два блока.
const { car, timing } = telemetry;

Всегда последнее значение

Каждое сообщение содержит весь блок целиком в его текущем состоянии. Новое сообщение заменяет старое, а SDK хранит самое свежее в overlay.telemetry. Оверлей, открытый позже других, сразу получает текущее состояние всех блоков.

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

Во всех играх значения приходят в одних и тех же единицах, и единица указана в имени поля: car.speedKph — км/ч, fuel.levelLiters — литры, weather.trackTemperatureC — градусы Цельсия. Педали — от 0 до 1, руль — от −1 до 1, углы — в радианах, время — в секундах, расстояния — в метрах.

Если игрок привык к милям или галлонам, это видно в отдельных полях, например session.displayUnits. Переводите значения в его единицы только при выводе на экран.

Нет значения — null

Поле существует всегда, поэтому обращение к telemetry.car.rpm не вызовет ошибку. Если игра значение не даёт, в поле null, а списки пустые. В таком случае покажите прочерк или спрячьте элемент:

src/main.ts

const rating = driver.ext.iracing?.iRating ?? null;
cell.textContent = rating === null ? '—' : String(rating);

Пока блок ни разу не пришёл, его поля тоже пустые. А пока Racelink не прислал оверлею его настройки, overlay.ready равно false: до этого момента ничего не рисуйте.

Общие поля и поля одной игры

Если значение есть в гоночных играх вообще (газ, времена кругов, температура шин), у него одно имя для всех игр. То, что есть только в одной игре, лежит в ext.<игра>. Например, iRating есть только в iRacing, поэтому он в drivers[i].ext.iracing?.iRating. Подробнее — Один оверлей для всех игр.

Демо-данные

Если игра не запущена, оверлей может работать на демо-данных: это выдуманная гонка с машинами, кругами, погодой и картой. Откройте страницу dev-сервера с ?demo в адресе, а для конкретной игры — например, с ?demo=le-mans-ultimate.

Если Racelink запущен, демо-данные даёт он; если нет, SDK создаёт такие же прямо в странице. Демо-данные устроены так же, как настоящие, поэтому то, что работает на них, работает и в гонке. Проверить оверлей на настоящей гонке без игры помогут записи сессий.