X-HUD einrichten

Modulares HUD mit Live-Studio für ESX Legacy und QBCore — inklusive eigenem Meldungssystem, das die Benachrichtigungen deines Frameworks und die GTA-Standardmeldungen ersetzt. Diese Anleitung führt dich vom Download bis zum fertig eingerichteten HUD.

Das HUD und das Studio kannst du vorher in der Live-Demo im Browser durchklicken.

Voraussetzungen

FiveM Server mit aktuellem Artifact
es_extended (ESX Legacy) oder qb-core — X-HUD läuft auch standalone
Keine Datenbank nötig. Die Einstellungen deiner Spieler landen in settings.json innerhalb der Resource.

Optional, wird automatisch erkannt:

Voice: pma-voice, saltychat oder mumble-voip
Tank: ox_fuel, cdn-fuel, lc_fuel, ps-fuel, LegacyFuel oder die native Tankanzeige

Installation

Lade x-hud aus dem Cfx.re Portal herunter.
Entpacke den Ordner nach resources/[x-solution]/x-hud. Der Ordnername muss genau x-hud lauten.
Trage die Resource in deiner server.cfg ein, nach dem Framework:

ensure es_extended
ensure x-hud

Server neu starten. In der Konsole steht dann, welches Framework, welcher Voice- und welcher Tank-Anbieter erkannt wurde:

[x-hud] framework: esx
[x-hud] voice: pma-voice
[x-hud] fuel: ox_fuel
[x-hud] HUD bereit (ESX Legacy)

Wenn du bereits ein eigenes Meldungs-Script einsetzt, lies zuerst den Abschnitt Meldungen — sonst siehst du jede Meldung doppelt.

Sprache

Config.Locale = 'de'

de und en sind fertig dabei und schalten beides um: die Meldungen aus dem Script und die komplette Oberfläche des Studios. Eigene Sprachen legst du als Kopie in locales/ an, zum Beispiel locales/fr.lua mit Locales['fr'] = { … }. Fehlt ein Eintrag, greift automatisch Deutsch, es bleibt also nie ein leeres Feld stehen.

Befehle und Tasten

Befehl	Standardtaste	Wirkung
`/hud`	F7	Studio öffnen und HUD frei gestalten
`/hudtoggle`	F5	HUD ein- und ausblenden
`/hudreset`	—	Eigene Einstellungen zurücksetzen
—	B	Sicherheitsgurt
—	`[` und `]`	Blinker links und rechts
—	`\`	Warnblinker
—	ENTF	Tempomat

Befehle und Tasten änderst du in Config.Commands und Config.Keys. Setzt du eine Taste auf false, wird keine Belegung registriert und Spieler vergeben sie selbst in den FiveM-Einstellungen unter Tastatur.

Meldungen

X-HUD bringt ein vollständiges Meldungssystem mit. Du brauchst kein zusätzliches Notify-Script: Meldungen aus deinen eigenen Scripts, aus dem Framework und vom Server landen alle im selben Design.

Was X-HUD übernimmt

Config.Notifications = {
    enabled = true,
    maxVisible = 4,
    defaultDuration = 4500,
    sound = true,
    duplicateWindow = 350,
    hideNativeFeed = true,
    warnOnConflict = true,

    replaceEsx = true,
    replaceEsxAdvanced = true,
    replaceEsxHelp = false,
    replaceQb = true,
    replaceOxLib = true,
    replaceNodify = true
}

Einstellung	Wirkung
`replaceEsx`	`esx:showNotification` und `ESX:Notify` landen im HUD
`replaceEsxAdvanced`	ESX-Meldungen mit Absender und Betreff werden als Meldung mit Titel gezeigt
`replaceEsxHelp`	ESX-Hilfetexte werden zur TextUI unten am Bildschirm
`replaceQb`	`QBCore:Notify` landet im HUD
`replaceOxLib`	`ox_lib:notify` landet im HUD — nur, wenn `ox_lib` selbst nicht läuft
`replaceNodify`	`x-nodify:notify` landet im HUD — nur, wenn `x-nodify` selbst nicht läuft
`hideNativeFeed`	Blendet die grauen GTA-Standardmeldungen oben links aus
`duplicateWindow`	Dieselbe Meldung wird innerhalb dieser Zeit in Millisekunden nur einmal gezeigt
`warnOnConflict`	Schreibt beim Start eine Warnung in die Konsole, wenn ein anderes Notify-Script läuft

hideNativeFeed betrifft alle Meldungen im GTA-Feed, auch die von fremden Scripts, die direkt die Spiel-Natives benutzen. Genau das ist der Sinn: nichts soll am HUD vorbeilaufen. Vermisst du danach Meldungen eines bestimmten Scripts, setz den Wert auf false.

Ein anderes Notify-Script läuft noch

Läuft parallel x-nodify, okokNotify, mythic_notify, t-notify oder brutal_notify, siehst du jede Meldung zweimal — einmal von X-HUD, einmal vom anderen Script. X-HUD erkennt das beim Start und schreibt in die Konsole:

[x-hud] Achtung: "x-nodify" läuft parallel und zeigt eigene Meldungen an.

Nimm das alte Script aus der server.cfg heraus. Die Liste der geprüften Resources steht in Config.Notifications.conflictResources, du kannst sie um eigene ergänzen.

ESX-Meldungen aus dem Client

Server-Meldungen (xPlayer.showNotification, TriggerClientEvent('esx:showNotification', …)) fängt X-HUD von allein ab. Ruft ein Script dagegen im Client direkt ESX.ShowNotification(…) auf, entscheidet allein es_extended, wo die Meldung landet — da kommt kein anderes Script dazwischen.

Damit auch diese Meldungen im HUD erscheinen, öffne es_extended/client/functions.lua, such function ESX.ShowNotification und ersetze die Funktion durch:

function ESX.ShowNotification(message, notifyType, length, title, position)
    if GetResourceState('x-hud') == 'started' then
        return exports['x-hud']:Notify(notifyType or "info", length or 5000, message, title, position)
    end

    return GetResourceState('x-nodify') == 'started' and exports['x-nodify']:Notify(notifyType or "info", length or 5000, message, title, position)
end

Die zweite Zeile ist die Rückfalllinie: Ist X-HUD gestoppt, läuft alles wie vorher weiter. Dasselbe Muster funktioniert für ESX.TextUI und ESX.HideUI mit exports['x-hud']:TextUI(...) beziehungsweise exports['x-hud']:HideUI().

Meldungen aus eigenen Scripts

Im Client:

exports['x-hud']:notify({ type = 'success', title = 'Werkstatt', message = 'Auftrag erledigt', duration = 4000 })
exports['x-hud']:notify('Kurzform, reicht auch')
exports['x-hud']:showNotification('Nicht genug Geld', 'error', 3000)
exports['x-hud']:Notify('info', 4000, 'Meldung', 'Titel')

Auf dem Server, mit der Spieler-ID als erstem Wert:

exports['x-hud']:notify(source, { type = 'error', message = 'Nicht genug Geld' })
exports['x-hud']:notify(-1, { type = 'info', message = 'Der Server startet in 5 Minuten neu' })
exports['x-hud']:notifyAll({ type = 'warning', message = 'Neustart in 1 Minute' })
exports['x-hud']:showNotification(source, 'Willkommen zurück', 'success')

Oder per Event, wenn dir das lieber ist:

TriggerClientEvent('x-hud:notify', source, { type = 'info', message = 'Hallo' })

Für type gelten success, error, warning, info, money-in und money-out. Schreibweisen anderer Systeme wie inform, primary, fail oder danger versteht X-HUD ebenfalls. Die Dauer nimmst du in Millisekunden; Werte unter 100 werden als Sekunden gelesen, duration = 5 sind also 5000 ms. Farbcodes wie ~r~, ~b~, ^1 oder ~INPUT_CONTEXT~ werden automatisch entfernt, ~br~ wird zum Zeilenumbruch.

TextUI und Fortschritt

exports['x-hud']:textUI('Drücke E zum Öffnen', { key = 'E' })
exports['x-hud']:textUI('Achtung, Alarm ausgelöst', { icon = 'warning', type = 'warning', position = 'top-center' })
exports['x-hud']:hideTextUI()

exports['x-hud']:progress({ label = 'Wird durchsucht', duration = 5000 })
exports['x-hud']:cancelProgress()

Für position stehen top-center, bottom-center, left, right und center bereit. Ohne Angabe erscheint die TextUI unten mittig. Serverseitig gibt es textUI(source, text, options) und hideTextUI(source).

Wichtige Einstellungen

Anbindungen

Config.Providers = {
    framework = 'auto',
    voice = 'auto',
    fuel = 'auto'
}

auto prüft beim Start, welche Resources laufen. Nur wenn mehrere gleichzeitig laufen oder die Erkennung danebenliegt, trägst du hier fest ein, was genutzt werden soll.

Fahrzeug

Config.Vehicle = {
    speedUnit = 'kmh',
    maxSpeed = 300,
    fuelWarning = 15,
    engineWarning = 35,
    warningNotifications = true,
    cruiseControl = true,
    cruiseMinSpeed = 30
}

speedUnit akzeptiert kmh oder mph. Die Warnwerte sind Prozentangaben: Darunter färben sich Tank- und Motoranzeige rot, und mit warningNotifications = true bekommt der Fahrer zusätzlich einmalig eine Meldung. Erholt sich der Wert wieder, meldet sich X-HUD beim nächsten Unterschreiten erneut.

Sicherheitsgurt

Config.Seatbelt = {
    enabled = true,
    ejectSpeed = 110,
    ejectForce = 15.0,
    lethal = false,
    blockExitAbove = 20,
    warningSpeed = 60
}

Ohne Gurt fliegt der Fahrer ab ejectSpeed aus dem Fahrzeug. Mit lethal = true endet der Aufprall tödlich. blockExitAbove verhindert das Aussteigen oberhalb dieser Geschwindigkeit.

Status-Werte

Config.Status = {
    hunger = true,
    thirst = true,
    stamina = true,
    oxygen = true,
    stress = true,
    esxStatusNames = {
        hunger = 'hunger',
        thirst = 'thirst',
        stress = 'stress'
    }
}

Was hier auf false steht, können Spieler auch im Studio nicht einschalten. Nutzt dein Server abweichende Namen in esx_status, trag sie in esxStatusNames ein — sonst bleiben die Ringe leer.

Vermögen

Config.Money = {
    cash = true,
    bank = true,
    black = true,
    currency = '$',
    notifications = true,
    minNotify = 1
}

black = false blendet Schwarzgeld serverweit aus, im HUD wie in den Meldungen. minNotify unterdrückt Meldungen bei Kleinstbeträgen.

Module und Design

In Config.Modules schaltest du serverweit einzelne Bereiche ab, etwa weapon = false, wenn du keine Munitionsanzeige möchtest. Config.Design legt Grundfarbe, Skalierung, Deckkraft und Eckenradius fest.

Config.AllowPlayerLayout = true
Config.AllowPlayerTheme = true

Damit entscheidest du, ob Spieler Position und Farben selbst anpassen dürfen. Stehen beide auf false, gilt für alle dein Design aus der Config.

Leistung

Config.Performance = {
    pauseWhenHidden = true,
    pauseInPauseMenu = true,
    hideInPauseMenu = true
}

Ist das HUD ausgeblendet oder das Pausenmenü offen, hören die Abfragen auf zu laufen. hideInPauseMenu blendet das HUD im Pausenmenü zusätzlich aus, was besonders für Screenshots angenehm ist. Wie oft die einzelnen Bereiche aktualisiert werden, steuert Config.Rates — höhere Werte bedeuten weniger Last.

Studio

Das Studio öffnest du mit /hud oder F7. Elemente werden angeklickt, mit der Maus verschoben und gespeichert. Positionen werden in Prozent gespeichert und sitzen dadurch auf jeder Auflösung richtig.

Gespeichert wird pro Identifier in settings.json im Resource-Ordner. Sichere diese Datei vor einem Update, wenn du die Resource komplett ersetzt — sonst verlieren deine Spieler ihre Anpassungen.

Weitere Exports

exports['x-hud']:toggleHud(false)
exports['x-hud']:isHudVisible()
exports['x-hud']:isBuckled()
exports['x-hud']:isTextUIOpen()
exports['x-hud']:openStudio()
exports['x-hud']:closeStudio()
exports['x-hud']:getSettings()

Häufige Fragen

Das HUD erscheint nicht

Prüfe die Reihenfolge in der server.cfg: X-HUD muss nach dem Framework geladen werden. In der Serverkonsole steht beim Start, welches Framework erkannt wurde.

Jede Meldung erscheint doppelt

Es läuft noch ein zweites Notify-Script. Schau in die Serverkonsole, dort steht beim Start der Name. Nimm es aus der server.cfg.

Meldungen erscheinen weiterhin oben links im GTA-Stil

Setze Config.Notifications.hideNativeFeed = true. Bleiben einzelne Meldungen übrig, stammen sie aus einem Script, das ESX.ShowNotification direkt im Client aufruft — dann hilft der Eingriff in es_extended aus dem Abschnitt Meldungen.

Meldungen vom Server kommen nicht an

Config.Notifications.replaceEsx beziehungsweise replaceQb muss auf true stehen. Prüfe außerdem, ob das sendende Script wirklich esx:showNotification benutzt und nicht das Event eines fremden Notify-Scripts.

Die Tankanzeige bleibt leer

Dein Tank-Script wurde nicht erkannt. Trag es fest in Config.Providers.fuel ein, zum Beispiel 'ox_fuel' oder 'LegacyFuel'.

Hunger und Durst bleiben auf null

Die Statusnamen stimmen nicht. Vergleiche Config.Status.esxStatusNames mit dem, was esx_status auf deinem Server registriert.

Die Sprachanzeige reagiert nicht

Setze Config.Providers.voice fest auf 'pma-voice', 'saltychat' oder 'mumble', statt auf 'auto' zu vertrauen.

Ein Spieler hat sich das HUD zerschossen

/hudreset setzt die persönlichen Einstellungen zurück. Serverweit löschst du dafür die settings.json und startest die Resource neu.

Support

Kommst du nicht weiter, melde dich auf Discord. Halte bitte die Serverkonsole vom Start und deine Resource-Version bereit.

Etwas unklar geblieben?

Schreib uns auf Discord, wir ergänzen die Anleitung.

Discord