Add settings

Keep npm run dev and Racelink running, with the overlay on screen as in “Run the overlay”.

Where the settings panel comes from

Settings are declared in the manifest racelink.overlay.json, in its settings field. From it Racelink draws the panel, stores the player’s choice for every overlay on screen and hands the values to the code. You never build the panel yourself. The template already has five settings; here is how they start:

"settings": {
  "pages": [
    {
      "id": "general",
      "label": "General",
      "groups": [
        {
          "label": "Display",
          "settings": [
            { "key": "showSpeed", "label": "Show speed", "type": "boolean", "default": true },
            {
              "key": "units",
              "label": "Speed units",
              "type": "select",
              "options": [
                { "value": "kph", "label": "km/h" },
                { "value": "mph", "label": "mph" }
              ],
              "default": "kph",
              "visibleIf": { "showSpeed": true }
            }
          ]
        }
      ]
    }
  ]
}

The panel has pages (tabs), pages have groups, groups have settings. Every setting has:

key

Its name in the code: overlay.settings.showSpeed. Latin letters, no spaces. Do not change it after publishing: players would lose the value they chose.

label

The name the player sees in the panel.

type

The kind of field: boolean (a switch), number (with min, max and step), select (a list), color, text, order (an order of items), binding (a key or wheel button).

default

The value until the player changes it.

visibleIf

Optional: show the setting only while another one has a value. Here the speed units show only while the speed is on.

Change a setting in Racelink

1. Open Layouts and select My HUD in the layout’s list of overlays. The Settings panel opens on the right, with a preview of the overlay.
2. Change Throttle to another colour and switch off Show speed. The overlay on screen changes at once, and Speed units disappears — that is visibleIf at work.

The same panel opens on screen too: in edit mode (Arrange overlays) an overlay has a Settings button with a sliders icon.

The choice is kept for this overlay in this layout. Put a second My HUD on screen and it has settings of its own.

How the code gets the values

In src/main.ts the settings are applied by applySettings:

const applySettings = (settings: Settings): void => {
  root.style.setProperty('--throttle', settings.throttleColor);
  root.style.setProperty('--brake', settings.brakeColor);
  root.style.setProperty('--opacity', String(settings.opacity / 100));
  if (speed) speed.hidden = !settings.showSpeed;
};

overlay.on('ready', (settings) => { applySettings(settings); /* … */ });
overlay.on('settings', applySettings);

• ready comes once, when the player’s settings are known. The template draws nothing before it, so the overlay never flashes its default look.
• settings comes every time the player changes something in the panel.
• overlay.settings is always complete and valid: every value is there and within its limits. There is nothing to check for.

Add a setting of your own

In “Show live data” you added the last lap time. Let the player switch it off: add a showLap setting. Do it in Studio or right in the file — the result is the same.

Way 1. In Racelink Studio

1. Open Studio, select My HUD and the Settings tab. On the left are the pages, groups and settings, in the middle the fields of the selected one, on the right a preview of the panel.
2. Select Show speed on the left and press + Setting: the new setting goes right after it.
3. Fill in: Type — “On/off”, Key — showLap, Name in the panel — Show last lap, and tick On by default.
4. Press Save (Ctrl + S). Studio writes the setting into racelink.overlay.json.

Way 2. In the file

In racelink.overlay.json add a line after showSpeed in the Display group and save the file:

{ "key": "showSpeed", "label": "Show speed", "type": "boolean", "default": true },
{ "key": "showLap", "label": "Show last lap", "type": "boolean", "default": true },

Whichever way you add it, the terminal running npm run dev shows:

[racelink] Updated src/racelink-settings.ts from racelink.overlay.json.

The SDK updated the settings types in src/racelink-settings.ts. Nobody edits that file: it is always built from the manifest. Now use the setting in the code — one line in applySettings:

  if (speed) speed.hidden = !settings.showSpeed;
  if (lap) lap.hidden = !settings.showLap;

Save. Open My HUD’s settings in Racelink: there is a Show last lap switch, and it hides the lap time. In a browser try ?demo&settings={"showLap":false}.

If something goes wrong

• The new setting is not in the panel. Look at the terminal: a manifest with a mistake shows racelink.overlay.json has problems and what is wrong. A missing comma between settings is a common one.
• Studio does not let you save. The field with the problem is marked: for example, a key with a space, or the same key as another setting.
• Studio says the file changed outside Studio. You changed the manifest in the editor while Studio had unsaved changes. Choose Load from the file to take the file’s version.