All resources

rsg-hud — Developer Docs#

Horse hunger & thirst#

When mounted, rsg-hud shows two extra horse circles (wheat = hunger, droplet = thirst) next to the horse health/stamina/clean/bonding circles. They turn red at 30% or below and can be dragged/resized in edit mode like the others. They are part of the horse group in /hudpreset visibility.

Data source#

Horse hunger/thirst live in rsg-stables (activeHorse.hunger / activeHorse.thirst, synced from the server session). rsg-hud reads them every HUD tick (500 ms) through a client export:

-- rsg-stables/client/client.lua (anywhere after `local activeHorse`)
exports('GetActiveHorseNeeds', function()
    if not activeHorse or not activeHorse.entity or not DoesEntityExist(activeHorse.entity) then return nil end
    return { entity = activeHorse.entity, hunger = activeHorse.hunger or 100, thirst = activeHorse.thirst or 100 }
end)

rsg-hud only shows the values when needs.entity matches the horse you're riding, so a borrowed, stolen or wild horse shows no hunger/thirst. If rsg-stables is stopped or the export is missing, the call is wrapped in pcall and the circles simply stay hidden.

Config#

OptionDefaultDescription
Config.ShowHorseNeedstrueShow horse hunger + thirst circles
Config.IconColors.horse_hungernormal #f2f2f2 / low #e0554fHunger icon colours
Config.IconColors.horse_thirstnormal #f2f2f2 / low #e0554fThirst icon colours

NUI payload (hudtick)#

horsehunger / horsethirst — number 0–100, or omitted (nil) when there's no data for the mounted horse.

Debug#

Horse hunger/thirst come from exports['rsg-stables']:GetActiveHorseNeeds() and only show for your own active horse; otherwise the circles show --.

Locales#

horse_hunger_label, horse_thirst_label (all locale files).

HUD settings window#

Opened with /hudsettings (or /hudpreset), or from another script with exports['rsg-hud']:OpenSettings().

Saved data (client KVP rsghud_preset)#

{
  size = 'medium', align = 'bottom-center', orientation = 'horizontal', offsetX = 0, offsetY = 0,
  hidden = { health = true, horsebond = true, ... },  -- hideable keys: health stamina deadeye hunger thirst cleanliness stress temp voice mail outlaw horse horsebond horsehunger horsethirst
  display = {
    showPct = false, alwaysShow = false, voiceAlways = true, money = true,
    opacity = 100,  -- Config.SettingsLimits.minOpacity..100
    scale = 100,    -- Config.SettingsLimits.minScale..maxScale (multiplies the preset circle/badge size)
    mapFoot = 'map', mapMount = 'map', -- 'off' | 'map' | 'compass' (player value only used when Config.AllowPlayerMinimap)
    ringWarn = 70, ringBad = 30,  -- ring turns orange / red at or below these % (red is always ≥5 below orange)
    colors = { ['health.normal'] = '#4fa3e0', ['health.alert'] = '#c0392b', ['ring.good'] = '#6fbf73' }, -- only when Config.AllowPlayerColors
  }
}

Everything is sanitised client-side in sanitiseDisplay / sanitiseHidden; missing values fall back to Config. /togglehudpct now flips display.showPct in the KVP (the old rsghud_showpct localStorage value is no longer read).

NUI messages / callbacks#

NameDirectionNotes
openPresetMenu / closePresetMenuLua → NUIcarries preset
applyPresetLua → NUIapplies layout classes, hidden icons and display (applyDisplay)
setConfigLua → NUIadds allowMap, limits
savePresetNUI → Luafull preset; thenEdit = true saves then enters edit mode
closePresetMenuNUI → Luacancel, reverts the live preview

Window position#

The settings window position is stored in NUI localStorage (rsghud_settings_pos) and clamped to the screen on open/resize.

NUI focus#

All focus goes through applyNuiFocus; while the settings window or edit mode has focus, game controls are disabled except Config.PushToTalkControls.

Locales#

settings_title, settings_subtitle, tab_*, set_*, map_off, map_map, map_compass (all locale files).

Colours#

Keys are <icon>.normal / <icon>.alert (icon keys as in Config.IconColors: health, stamina, deadeye, hunger, thirst, cleanliness, stress, temp, voice, mail, outlaw, horse_health, horse_stamina, horse_clean, horse_bond, horse_hunger, horse_thirst) and ring.good / ring.warn / ring.bad. Alert replaces the low/active/hasmail/cold colour. Only #rrggbb values are kept (max 64 entries); a colour equal to the server default isn't stored. Ring colours are applied as CSS variables --ring-good/-warn/-bad on #ui-container. The picker is pure HTML (no native <input type="color">). Locales: tab_colors, col_*.

Ring thresholds#

Each player can set when stat rings change colour from /hudsettings → Display (Orange Ring Below / Red Ring Below, 5–95% in steps of 5). Defaults come from Config.RingWarnAt (70) and Config.RingBadAt (30). Saved in the player's preset (display.ringWarn / display.ringBad), clamped client-side so red always stays at least 5% below orange. Applies to health, stamina, dead eye, hunger, thirst, cleanliness and the horse rings; stress (inverted) and temperature keep their own fixed bands.

Server-owned needs (anti-tamper)#

With Config.ServerNeeds = true the server keeps the authoritative hunger / thirst / stress values:

  • Seeded from rsg-core metadata on RSGCore:Server:PlayerLoaded (not from the client's state bag).
  • Clients may raise hunger/thirst by up to Config.MaxNeedGainPerMinute and lower stress by up to Config.MaxStressReliefPerMinute per minute; anything beyond that is reverted.
  • Server exports SetNeed, GainStress and RelieveStress write the value directly and are not subject to these limits.
<!-- BEGIN AUTO-REFERENCE (generated from the code; re-run the generator instead of editing by hand) -->

Technical reference#

Generated from the source of rsg-hud 3.2.1. Names, arguments and defaults below are read straight from the code.

Dependencies#

rsg-core, oxmysql

Configuration#

OptionDefaultNotes
Config.StatusInterval5000how often to update hunger/thirst status in milliseconds
Config.HungerRate0.01Rate at which hunger goes down.
Config.ThirstRate0.01Rate at which thirst goes down.
Config.ServerNeedstrueserver-owned needs: the server decays hunger/thirst/stress and reverts client state bag tampering
Config.MaxStressReliefPerMinute50max stress a client may remove per minute (smoking, drinking, etc.); more is reverted
Config.MaxNeedGainPerMinute150max hunger/thirst a client may add per minute (eating/drinking); more is reverted
Config.LowNeedWarning20notify when hunger/thirst drops to this value (0 = off)
Config.LowHealthHeartbeat25play a heartbeat below this health % (0 = off)
Config.HeartbeatSound{ name = 'Heartbeat', set = 'RDRO_Sniper_Tension_Sounds' }rdr3_discoveries audio/frontend_soundsets
Config.StressChance0.1Default: 10% -- Percentage Stress Chance When Shooting (0-1)
Config.MinimumStress50Minimum Stress Level For Screen Shaking
Config.MinimumSpeed100Going Over This Speed Will Cause Stress
Config.StressDecayRate0.01Rate at which stress goes down.
Config.HidePlayerHealthNativetrue
Config.HidePlayerStaminaNativetrue
Config.HidePlayerDeadEyeNativetrue
Config.HideHorseHealthNativetrue
Config.HideHorseStaminaNativetrue
Config.HideHorseCourageNativetrue
Config.ShowDeadEyetruedeadeye core circle
Config.ShowHorseBondingtruehorse bonding level circle
Config.ShowHorseNeedstruehorse hunger + thirst circles (needs rsg-stables, own active horse only)
Config.BankCommand'bank'
Config.ShowVoicefalsetrue = show the voice icon on the HUD, false = voice icon disabled
Config.VoiceAlwaysVisibletruetrue = always visible, false = only when talking
Config.ShowPercentagesfalsedefault for the % under circle icons (players change it in /hudsettings or /togglehudpct, saved per player)
Config.SettingsCommand'hudsettings'opens the HUD settings window
Config.PresetCommand'hudpreset'old command name, opens the same window
Config.AllowPlayerMinimaptruelet players choose minimap / compass / off (on foot + mounted); false = server Config only
Config.AllowPlayerColorstruelet players recolour icons + rings with the colour picker; false = Config.IconColors only
Config.RingWarnAt70ring turns orange at or below this %
Config.RingBadAt30ring turns red at or below this %
Config.SettingsLimitstable
Config.AllowPushToTalkWhileOpentrueWhile NUI is open, block game controls but allow push-to-talk.
Config.PushToTalkControlstable
Config.DefaultPresettable
Config.OnFootMinimaptrueset to true/false to disable/enable minimap when on foot
Config.OnFootCompassfalsetrue = have the minimap set to a compass instead of off or normal minimap
Config.MountMinimaptrueset to false if you want to disable the minimap when on mount
Config.MountCompassfalseset to true if you want to have a compass instead of normal minimap while on a mount
Config.DoHealthDamagetrue
Config.DoHealthDamageFxfalse
Config.DoHealthPainSoundtrue
Config.TempFormat'celsius'
Config.TempFeaturefalse
Config.TempStaminaDrain10cold/heatstroke drains this much stamina core per StatusInterval before health is hit
Config.WearingHat0
Config.WearingShirt0
Config.WearingPants0
Config.WearingBoots0
Config.WearingCoat15
Config.WearingOpenCoat15
Config.WearingGloves0
Config.WearingVest0
Config.WearingPoncho0
Config.WearingSkirt0
Config.WearingChaps0
Config.EnableNoWarmthJobstrueset to true/false to enable/disable the feature
Config.NoWarmthJobstable
Config.MinTemp-5
Config.MaxTemp55
Config.FlyEffecttruetoggle flies on/off
Config.MinCleanliness30
Config.RemoveHealth1
Config.Intensitytable
Config.EffectIntervaltable
Config.IconColorstable

Exports#

Server

ExportArgumentsFile
SetNeedsrc, key, valueserver/server.lua
GetNeedssrcserver/server.lua
GainStresssrc, amountserver/server.lua
RelieveStresssrc, amountserver/server.lua
ShowAccountsrc, accountserver/server.lua

Client

ExportArgumentsFile
GetCurrentTemperature``client/client.lua
GetOutlawStatus``client/client.lua
OpenSettings``client/client.lua
GetNeeds``client/client.lua
GetNeedkeyclient/client.lua
SetNeedkey, valueclient/client.lua
AddNeedkey, amountclient/client.lua
GainStressamountclient/client.lua
RelieveStressamountclient/client.lua
SetHudVisiblevisibleclient/client.lua
IsHudVisible``client/client.lua
ToggleEditModeenabledclient/client.lua
IsEditMode``client/client.lua
-- example
local result = exports['rsg-hud']:SetNeed(src, key, value)

Callbacks#

CallbackSideArgumentsFile
hud:server:getoutlawstatusserversource, cbserver/server.lua
-- client side
RSGCore.Functions.TriggerCallback('hud:server:getoutlawstatus', function(result)
    -- use result
end)

Events#

Server events can be fired by any client, so every handler re-validates the player, the arguments and any permission, distance or cooldown on the server. Never add a reward to a handler without those checks.

EventSideArgumentsFile
HideAllUIclient``client/client.lua
RSGCore:Client:OnPlayerLoadedclient``client/client.lua
RSGCore:Client:OnPlayerUnloadclient``client/client.lua
hud:client:UpdateNeedsclientnewHunger, newThirst, newCleanlinessclient/client.lua
hud:client:UpdateHungerclientvclient/client.lua
hud:client:UpdateThirstclientvclient/client.lua
hud:client:UpdateStressclientvclient/client.lua
hud:client:UpdateCleanlinessclientvclient/client.lua
hud:client:GainStressclientamount, serverAppliedclient/client.lua
hud:client:RelieveStressclientamount, serverAppliedclient/client.lua
hud:client:ShowAccountsclienttype, amountclient/client.lua
hud:client:OnMoneyChangeclienttype, amount, isMinusclient/client.lua
hud:client:ToggleEditModeclient``client/client.lua
-- from a server script
TriggerClientEvent('HideAllUI', source)

Commands#

CommandNotesFile
/edithudclient/client.lua
/togglehudpctclient/client.lua
/resethudclient/client.lua

Locales#

Language files in locales/: de, el, en, es, fr, it, ja, nl, pl, pt-br, ro, ru. Set the language with setr rsg:locale "en".

<!-- END AUTO-REFERENCE -->