SAF HUD Custom servers | SAF Scripts Docs

bridge/client.lua and bridge/server.lua are open in every edition. They hold everything the HUD asks your framework. You can edit them, but the better place for your changes is custom/: updates never touch it.

How custom/ works

Files in custom/ load after config.lua and bridge/, so anything defined there replaces the original.

Folder	Use it for
`custom/shared/*.lua`	Changing `Config` values: areas, colours, text
`custom/client/*.lua`	Replacing any client `Bridge.*` function
`custom/server/*.lua`	Replacing any server `Bridge.*` function

File names don't matter. Pick something that says what the file does.

Config overrides

custom/shared/areas.lua

Config.SOE.areas = {
    { id = 'ls', short = 'LS', name = 'Los Santos',    command = 'soels', default = 'green' },
    { id = 'bc', short = 'BC', name = 'Blaine County', command = 'soebc', default = 'green' },
}

Config.Units = 'kmh'
Config.Theme.accent = '#e8a33d'

Permissions

Bridge.CanManage(src) decides who can change SOE and AOP. Return true to allow. src is 0 for the server console.

custom/server/permissions.lua

function Bridge.CanManage(src)
    if src == 0 then return true end
    return exports['my-staff']:IsStaff(src)
end

Server hooks

Function	What it does	Default
`Bridge.CanManage(src)`	Who can run `/soe`, `/soeall` and `/aop`	`hud.manage` ACE, plus ESX and QBCore admin groups
`Bridge.Name(src)`	Name used for `{by}` and "Set by"	The player's FiveM name, `Server` for the console
`Bridge.Reply(src, msg)`	How command replies reach the player	A chat message

Client hooks

Function	What it does	Default
`Bridge.IsLoaded()`	Is the player in the world with a character	Framework loaded state, or the first spawn on standalone
`Bridge.OnLoaded(cb)`	Runs `cb` every time a character loads	QBCore, ESX and `playerSpawned` events
`Bridge.HasSeatbelt()`	Seatbelt or harness on	`LocalPlayer.state.seatbelt` or `.harness`
`Bridge.GetFuel(veh)`	Fuel from 0 to 100	`Entity(veh).state.fuel`, then LegacyFuel, cdn-fuel, ps-fuel, lj-fuel, then the game value
`Bridge.Notify(msg)`	Small message for postal replies	GTA feed
`Bridge.Announce(a)`	Your own announcement for `style = 'custom'`	A chat message and the sound
`Bridge.ShouldHide()`	Extra reasons to hide the HUD	Always `false`

Seatbelt from another script

If your seatbelt script doesn't use a state bag, read it from its export:

custom/client/seatbelt.lua

function Bridge.HasSeatbelt()
    return exports['my-seatbelt']:IsBuckled()
end

Your own announcement

Set Config.Announce.style = 'custom' and Bridge.Announce gets every change:

custom/client/announce.lua

-- a = { kind = 'soe' | 'aop', kicker, title, message, by, color, hudColor, seconds }
function Bridge.Announce(a)
    exports['my-notify']:Show({ title = a.title, text = a.message, color = a.color, time = a.seconds * 1000 })
end

Hide during your own menus

custom/client/hide.lua

function Bridge.ShouldHide()
    return LocalPlayer.state.inCharacterMenu == true
end