How data reaches an overlay

How the data travels

An overlay never talks to the game directly. Racelink does that part for every game it supports and hands overlays the same data in the same form, whatever is running. That is why one overlay works in iRacing and in Assetto Corsa without a line of code for either.

The Overlay API runs on the player’s own computer. Nothing on the way leaves it: there is no server in between, and an overlay reaches only Racelink unless the player allows it more (Security).

Topics

The data comes in topics, each a group of fields that change together: car for pedals, speed and gear, timing for lap times, drivers for every car of the session, weather, fuel and more. A topic arrives at the rate its data changes:

car: about 60 times a second
vehicle: about 20 times a second, and the radar too
controls: about 10 times a second, and the drivers too
session: about 4 times a second, and timing and fuel too
weather: once a second, and the track map too

You never subscribe by hand. The first time your code reads a topic, the SDK asks Racelink for it; a topic you never read is never sent. Read only what you show.

src/main.ts

overlay.on('telemetry', ({ car, timing }) => {
  // Reading car and timing subscribes to both; nothing else is sent.
  render(car.speedKph, timing.lap.lastSeconds);
});

src/App.tsx

const { telemetry } = useOverlay();
// Reading car and timing subscribes to both; nothing else is sent.
const { car, timing } = telemetry;

The latest value, not a stream

A topic is a value that is replaced, not a list of events. Each message holds the whole topic as it is now; the SDK keeps the newest in overlay.telemetry. An overlay that opens late gets the current value of every topic at once.

One set of units

Every value is in the same unit in every game, and the unit is in the field’s name: car.speedKph is km/h, fuel.levelLiters litres, weather.trackTemperatureC °C. Pedals are 0..1, steering −1..1, angles radians, times seconds, distances metres. How the player likes values shown is a separate field (session.displayUnits): convert when you format, never before.

A missing value is null

A field always exists, so telemetry.car.rpm never throws. When the running game does not give a value, it is null; lists are empty. Show a dash or hide the element:

src/main.ts

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

Before the first message of a topic its fields are empty too. Until Racelink sends the overlay its settings, overlay.ready is false: draw nothing before it.

Common fields and the fields of one game

A field that means the same in racing games in general (throttle, lap times, tyre temperatures) has one name for all of them. Something that exists in one game only, such as iRacing’s iRating, lives under ext.<game> of its record: drivers[i].ext.iracing?.iRating. How to write for several games at once: One overlay for every game.

Demo data

Without a game, an overlay gets demo data: a session in progress with cars, laps, weather and a map. Open the dev page with ?demo (or ?demo=le-mans-ultimatefor one game). With Racelink running it is Racelink’s own demo; without it the SDK makes the same demo in the page. The demo has the same shape as live data, so whatever works on it works in a race.

Every field, its unit and the games that fill it are in the field reference.