gfxr-hud

Framework-agnostic RedM HUD with player vitals, metabolism, contextual horse widget, money, player info, clock/weather, voice indicator, minimap controller, and a fully in-game NUI settings menu. Settings are persisted entirely in the browser's localStorage — no database required.

Features

• Player vitals: health, stamina, and Dead Eye — each shows a core value and a bar (e.g. Dead Eye bar vs. Dead Eye core)
• Needs: hunger, thirst, and stress (0–100); master toggle for servers without a metabolism resource
• Contextual horse widget: health, stamina, and cleanliness — auto-shows on mount, auto-hides on dismount
• Money widget: cash, gold, and bank (bank is 0 on VORP which has no core bank)
• Player info widget: identifier, character name, and current job
• Clock and weather widget: in-game time and a weather icon mapped from the settled weather hash
• Voice indicator: detects pma-voice, yaca, saltychat, or mumble by priority; shows range (whisper/normal/shout) and talking state
• Minimap controller: circle, square, or off shape; zoom level; fog-of-war toggle
• In-game NUI settings menu opened via a rebindable keybind or console command — supports drag-to-reposition, scale slider, enable/disable per element, theme picker with live preview, and minimap shape selector
• Three UI themes: Authentic (Western ornate), Minimal (clean), Ornate (detailed)
• Settings persisted in the NUI's CEF localStorage — survive game restarts, no SQL required
• Event-driven money and needs updates via the bridge OnMoneyChange / OnNeedsChange — no server polling for either (see Performance below)
• Delta-only NUI pushes: only changed values are sent to the React layer, keeping idle resmon near zero

Architecture

gfxr-hud is fully client-side. There are no server scripts and no database. The fxmanifest.lua declares only client_scripts; the server_scripts block and sql/ directory have been removed entirely.

Settings (theme, element positions/scale/enabled state, minimap shape/zoom) are stored in the NUI's CEF localStorage under the single key gfxr-hud:settings. Because CEF localStorage is machine-wide, settings are shared by all characters on the same PC and persist across game restarts and resource restarts without any server interaction.

Dependencies

Installation

1. Add to server.cfg (must come after gfxr-bridge):

   ensure gfxr-bridge
   ensure gfxr-hud
   

2. NUI: the web/build/ folder is pre-built. If you need to rebuild after editing web/src/:

   cd resources/[gfx]/gfxr-hud/web
   npm install
   npm run build
   

No SQL import step is required.

Configuration

config/client_config.lua

Config.ELEMENTS

Each entry has the shape { ENABLED, X, Y, SCALE } where X/Y are viewport-normalized (0–1) and SCALE is a multiplier.

All elements default to ENABLED = true and SCALE = 1.0.

Settings Persistence

Settings are saved entirely inside the NUI's CEF localStorage under the key gfxr-hud:settings. This includes:

• Active theme (1 = Authentic, 2 = Minimal, 3 = Ornate)
• Per-element position (X/Y), scale, and enabled state
• Minimap shape and zoom level

Save / Reset behaviour:

• Clicking Save in the settings menu writes the current layout to localStorage immediately. The minimap shape/zoom is also applied to the in-game radar via a setMinimap NUI callback.
• Clicking Reset clears the stored settings and restores the Config.* defaults defined in config/client_config.lua.

Machine-wide scope: because CEF localStorage is per-machine (not per-character or per-account), all characters played on the same PC share the same HUD layout. There is no per-character or per-server storage.

Performance

Money and needs are event-driven, never polled from the server by the HUD itself:

• OnMoneyChange — RSG fires its native RSGCore:Client:OnMoneyChange event; VORP/RedEM diff the local character object on a low-rate client loop. Zero server calls.
• OnNeedsChange — RSG reads client metadata on RSGCore:Player:SetPlayerData; VORP listens to vorp_metabolism client events with a 2 s fallback loop (all client-local). RedEM is the sole exception: the bridge does a 3 s server poll internally because RedEM exposes no client needs signal.

Only local natives (player cores, horse entity, clock, weather hash) are polled by the HUD's own UPDATE_INTERVAL loop. The NUI React layer never polls — it only updates when the Lua side pushes a delta.

Client Exports

ShowHud

Show or hide the HUD.

exports['gfxr-hud']:ShowHud(state)

IsHudVisible

Returns whether the HUD is currently visible.

local visible = exports['gfxr-hud']:IsHudVisible()

Returns: boolean

SetMinimapShape

Change the minimap shape immediately (applies the radar native; does not persist — use the settings menu to persist to localStorage).

exports['gfxr-hud']:SetMinimapShape(shape)

Invalid values are silently ignored.

OpenSettings

Open the HUD settings menu programmatically.

exports['gfxr-hud']:OpenSettings()

No-op if the menu is already open.

Net Events

gfxr-hud:forceRefresh (client)

Forces the HUD to re-push its current config and locale to the NUI and clear the delta cache so all values are re-sent on the next tick. Trigger from the server when a live config reload is needed.

TriggerClientEvent('gfxr-hud:forceRefresh', source)

Locale

Three languages are included. Set Locale = 'en' (or 'tr' / 'fr') at the top of config/locale.lua.