LED Naming Convention

Overview

tELS identifies individual LEDs by internal UUID, but each LED can carry a name field that groups it semantically. These names drive HUD display, trigger conditions, and pattern targeting by name.

This page defines the naming standard all vehicle configs should follow.

Format

[ZONE][FACE?][SIDE?][NUM]

Rules

1. All uppercase, no spaces, no special characters.
2. Forward/rearward-facing lights — use sequential numbers only. No L/R suffix. (RD1, RD2, LBF1, LBF2)
3. Side-facing lights — use an L/R suffix because they are physically separate units on opposite sides. Add a number after if there are multiple per side. (MRL, MRR, SRL1, SRL2) Omit NUM when there is only one unit per side — LBAL not LBAL1, PIL not PIL1.
4. Names describe physical location only. Functions like takedowns, traffic advisor, and alley lights are pattern behaviors, not LED names. The same physical LED can act as a takedown in one pattern and a standard flasher in another.
5. Numbers count left to right from the perspective of an observer standing outside the vehicle, looking directly at that face. Numbering typically starts at 1, but starting at 0 is permitted — and encouraged — when a vehicle has more LEDs than the standard cross-vehicle range. For example, a rear lightbar with 8 LEDs should use LBR0–LBR7: the LBR1–LBR6 core remains the cross-vehicle compatible zone (what patterns and the HUD reliably target), while LBR0 and LBR7 are vehicle-specific extensions. Patterns written for the full range silently skip any names that don't exist on a given vehicle, so a pattern targeting LBR0–LBR7 degrades gracefully on a vehicle that only defines LBR2–LBR5. This means:
   • Front-facing lights (LBF#, FG#, FB#, DS#, FV#, etc.) — #1 is on the vehicle's right, because the observer facing the front sees the vehicle's right on their left.
   • Rear-facing lights (LBR#, RD#, RV#, etc.) — #1 is on the vehicle's left, because the observer facing the rear sees the vehicle's left on their left.
   • Right-side lights (SRR#, DOR#, etc.) — #1 is toward the vehicle's rear, because the observer facing the right side sees the rear on their left.
   • Left-side lights (SRL#, DOL#, etc.) — #1 is toward the vehicle's front, because the observer facing the left side sees the front on their left.

Zone Reference

Roof

Alley lights: LBAL / LBAR are the physically side-facing LED units built into the ends of the lightbar. Whether they illuminate as alley lights, scene lights, or anything else is determined by the pattern — not the name.

Front Exterior

Front Interior (projects forward through windshield)

Side

Rear Interior (projects rearward through rear glass)

Rear Exterior

Specialty

HUD Default LEDs

The tELS HUD displays a row of colored LED indicators. When no layout specifies which LED names to show, tELS automatically resolves the best available set from the vehicle config using this fallback chain:

tELS uses whichever group has at least one matching LED on the vehicle. Only the LEDs that actually exist in the config are shown — if a vehicle only has RD1, RD2, and RD3, the HUD shows three indicators, not six.

If none of the above names exist on the vehicle, the HUD falls back to showing all LEDs.

Custom HUD layouts can override this entirely by declaring their own data-hud-led bindings.

Out of Scope

Factory light circuits (headlight flashers, tail light flashers) are not part of this convention. These are native vehicle lights driven by the game engine, not placed LEDs in the tELS config. If tELS ever gains addressable control over factory circuits, they will be assigned their own convention at that time. Do not invent names like HLF or TLF — there is no placed LED to attach them to.