SAF HUD Configuration | SAF Scripts Docs

Everything you would want to change is in config.lua. Framework hooks (who is loaded, seatbelt, fuel, permissions) are in bridge/, covered in Custom servers.

General

Option	Default	What it does
`Config.Units`	`'mph'`	Speedometer unit: `'mph'` or `'kmh'`
`Config.Refresh.vehicle`	`50`	Milliseconds between HUD updates in a vehicle. Lower is a smoother needle and slightly more CPU
`Config.Refresh.foot`	`250`	Milliseconds between updates on foot
`Config.Refresh.postal`	`300`	Milliseconds between nearest-postal lookups

Theme

Config.Theme sets every colour and the font. Any CSS colour works: '#d7262c', 'rgb(215, 38, 44)' or 'rgba(0, 0, 0, 0.6)'.

Key	Default	Used for
`accent`	`'#d7262c'`	Icons, highlights and the announcement timer
`text`	`'#ffffff'`	Main text
`subtext`	`'#b9c0cc'`	Secondary text
`panel`	`'rgba(12, 13, 16, 0.78)'`	Info bar cells and the announcement background
`panelBorder`	`'rgba(255, 255, 255, 0.08)'`	Borders around the cells
`health`	`'#6fd11b'`	Health bar
`armor`	`'#ff9a0a'`	Armour bar
`barEmpty`	`'rgba(92, 62, 36, 0.42)'`	The empty part of both bars
`font`	`'Segoe UI', 'Roboto', Arial`	Font stack for the whole HUD
`scale`	`1.0`	Overall size. `1.2` makes everything 20% bigger
`rpm`	see below	Speedometer ring colour by engine load
`good`, `warn`, `bad`	green, yellow, red	Fuel and engine indicator colours

The speedometer ring changes colour as the engine gets closer to the limiter:

Lua

rpm = { cruise = '#3ddc6b', near = '#facc15', shift = '#f97316', limit = '#ef4444' },

Show and hide parts

Set any key in Config.Show to false to hide that part of the HUD. All are true by default.

Key	Part
`bars`	Health and armour under the minimap
`status`	SOE and AOP list next to the minimap
`compass`	Compass heading
`postal`	Nearest postal cell
`street`	Street name
`zone`	Zone name
`speedometer`	Speedometer
`fuel`	Fuel indicator
`engine`	Engine health indicator
`seatbelt`	Seatbelt indicator

Postals

Option	Default	What it does
`Config.Postals.file`	`'postals.json'`	File in the `saf-hud` folder with a list of `{ code, x, y }`
`Config.Postals.commands`	`{ 'p', 'postal', 'gps' }`	Commands that set a waypoint. `/p 609` sets one, `/p` on its own clears it

With no file, the postal cell and the commands turn off on their own.

SOE levels

Config.Levels lists the State of Emergency levels in order, from open to closed. Add as many as you like.

Key	Example	What it does
`id`	`'red'`	Saved value, and what `/soe` accepts
`label`	`'Red'`	Shown on the HUD and in announcements
`color`	`'#ef4444'`	Banner and HUD colour
`hudColor`	`6`	GTA colour id for the `'gta'` announcement style
`aliases`	`{ 'r' }`	Other words `/soe` accepts for this level
`message`	`'No priorities...'`	The line players read in the announcement

GTA colour ids for hudColor: 6 red, 9 blue, 12 yellow, 18 green, 21 purple, 116 light blue, 1 white.

Lua

Config.Levels = {
    { id = 'green', label = 'Green', color = '#43c04a', hudColor = 18, aliases = { 'g', 'normal' },
      message = 'Priorities are open. You can start one.' },
    { id = 'amber', label = 'Amber', color = '#ffb020', hudColor = 12, aliases = { 'a', 'yellow', 'orange' },
      message = 'Light priorities only. Keep crime small for now.' },
    { id = 'red', label = 'Red', color = '#ef4444', hudColor = 6, aliases = { 'r' },
      message = 'No priorities. Police are busy or just finished a big one, so hold off on anything that needs them.' },
}

SOE areas

Option	Default	What it does
`Config.SOE.enabled`	`true`	Turn the State of Emergency off entirely
`Config.SOE.prefix`	`'SOE'`	HUD label before each area. `''` hides it
`Config.SOE.command`	`'soe'`	`/soe <area> <level>`
`Config.SOE.allCommand`	`'soeall'`	`/soeall <level>` sets every area, one announcement after another
`Config.SOE.allStepSeconds`	`2.5`	Seconds between those announcements
`Config.SOE.onStart`	`'last'`	`'last'` keeps the levels from before a restart, `'default'` resets them
`Config.SOE.areas`	LS, SS, PB	The areas, see below

Each area:

Key	Example	What it does
`id`	`'ls'`	Saved state key. Don't change it once the server is live
`short`	`'LS'`	Shown on the HUD, as in `SOE \| LS`
`name`	`'Los Santos'`	Used in announcements
`command`	`'soels'`	Optional shortcut: `/soels red`. Everything also works through `/soe ls red`
`default`	`'green'`	Level on first start, and on every start with `onStart = 'default'`

Lua

Config.SOE.areas = {
    { id = 'ls', short = 'LS', name = 'Los Santos',   command = 'soels', default = 'green' },
    { id = 'ss', short = 'SS', name = 'Sandy Shores', command = 'soess', default = 'green' },
    { id = 'pb', short = 'PB', name = 'Paleto Bay',   command = 'soepb', default = 'green' },
}

Area of Play

Option	Default	What it does
`Config.AOP.enabled`	`true`	Turn the AOP off entirely
`Config.AOP.label`	`'AOP'`	HUD label
`Config.AOP.command`	`'aop'`	`/aop Sandy Shores`
`Config.AOP.onStart`	`'last'`	`'last'` keeps the AOP from before a restart, `'default'` uses the default below
`Config.AOP.default`	`'Statewide'`	AOP on first start
`Config.AOP.maxLength`	`40`	Longest AOP text allowed

Announcements

Config.Announce controls the banner everyone sees when SOE or AOP changes.

Option	Default	What it does
`enabled`	`true`	Turn announcements off
`style`	`'saf'`	How it looks, see the styles below
`seconds`	`8`	How long it stays up
`position`	`'center'`	`'top'` or `'center'` (the `'saf'` style only)
`showBy`	`false`	Add "Set by <name>" under the message
`feedPicture`	`'CHAR_CALL911'`	Picture for the `'feed'` style, any `CHAR_` texture
`sound`	`Short_Transition_In`	`{ name, set }` of a frontend sound. `nil` is silent
`aop`		Wording and colour of AOP announcements
`soe`		Wording of SOE announcements

Style	What players see
`'saf'`	A dark band across the screen with a large title (default)
`'gta'`	The GTA Online centre message, with the full text
`'feed'`	A GTA phone notification above the minimap
`'custom'`	Your own: write `Bridge.Announce` in `custom/client/`

The kicker, title and message texts can use these placeholders:

Placeholder	Filled with
`{area}`	The SOE area name
`{level}`	The SOE level label
`{message}`	The level's own message
`{aop}`	The new AOP
`{by}`	The staff member who made the change

Lua

aop = {
    kicker = 'Area of Play',
    title = '{aop}',
    message = 'Roleplay is now in {aop}. Head over there when you can.',
    color = '#3b82f6',
    hudColor = 9,
},
soe = {
    kicker = 'State of Emergency',
    title = '{area}: {level}',
    message = '{message}',
},

Chat replies

Config.Text holds the replies to whoever runs a command. %s is filled in by the script; keep the same number of them when you translate.

Key	Default
`noPermission`	`You can't change that.`
`soeUsage`	`Use /%s <area> <level>. Areas: %s. Levels: %s.`
`soeAreaUsage`	`Use /%s <level>. Levels: %s.`
`soeAllUsage`	`Use /%s <level>. Levels: %s.`
`aopUsage`	`Use /%s <area of play>.`
`gpsUsage`	`Use /p <postal>.`
`gpsSet`	`Waypoint set to postal %s.`
`gpsCleared`	`Waypoint cleared.`
`gpsMissing`	`Postal %s doesn't exist.`