HUD Layouts

A layout is a self-contained HTML file plus assets in a folder under layouts/. It binds DOM elements to state fields with data-hud-* attributes. Folders in layouts/ are auto-discovered and listed in /tels → HUD Layout.

tELS ships CRX-600 and SPX-1800.

Create a layout

<div
  class="ui-root"
  style="position:relative;width:440px;height:214px;overflow:hidden"
  data-radio-width="440"
  data-radio-height="214"
  data-hud-show="inVehicle"
>
  …
</div>

layouts/MyLayout/
  ui.html
  icons/       PNG / SVG assets
  sounds/      LIGHTS_ON.ogg, TONE_CHANGE.ogg, …

Layouts run isolated

Each layout loads as its own page, in a sandbox: its own document, its own window, no access to the HUD around it or to the game.

Data bindings

Processed on every update. Dot paths reach nested state: leds.R1 is state.leds.R1.

<div data-hud-show="inVehicle">
  <span data-hud-text="patternName">—</span>
  <div data-hud-led="sirenOn" class="indicator">SIREN</div>
  <div data-hud-eq="taMode:left" class="arrow">◄</div>
  <div data-hud-led-color="leds.R1" class="pip"></div>
  <button data-hud-btn="cycle_pattern">Next</button>
</div>

State keys

Only keys the layout references through data-hud-* or data-hud-keys are sent.

Core

Pattern

Siren

Modes

Vehicle

Lights, controls and signals

Doors

LEDs

Bind one with data-hud-led-color="leds.<name>". LED colours stream at roughly 20 Hz, independently of the ~5 Hz full state update.

Layout scripts

For derived values or dynamic HTML, add a <script data-hud-script> block. tELS looks for exactly the two function names below.

<script data-hud-script>
  (function () {
    window.__telsLayoutUpdate = function (state, root) {
      var el = root.querySelector(".reverse-indicator");
      if (el) el.style.display = state.reverse ? "" : "none";

      var kphEl = root.querySelector(".speed-kph");
      if (kphEl) kphEl.textContent = Math.round((state.speedMph || 0) * 1.609);
    };

    window.__telsLayoutDestroy = function () {
      // cancel timers, detach listeners
    };
  })();
</script>

Cache your query selectors in the closure — the callback runs every tick. If a script needs a key no attribute binds, declare it, or Lua never computes it and your script gets undefined:

<div data-hud-keys="sirenTones,maxStage,sirenTone">…</div>

What a script can and cannot do

To use a specific typeface, embed it as a data: URL.

If a skin comes up empty, check the client console. A script that throws is reported there by layout name and reason, and the rest of the HUD keeps running.

Buttons

data-hud-btn="<action>" fires a tels:hudButton client event with the action string. Wire it to your own handlers in a separate resource, or reuse the built-ins.

AddEventHandler("tels:hudButton", function(action)
  if action == "cycle_pattern" then
    ExecuteCommand("+lbar_pattern")
  end
end)

Sounds

tELS plays a file from your optional sounds/ folder on five actions, named verbatim for the action: layouts/<your-layout>/sounds/<ACTION>.ogg.

A missing file plays nothing and is not an error, so ship only what you want.

UI Studio

Build and publish layouts with the UI Studio.