Configuration (config.lua)
| Section | What it controls |
|---|---|
Config.Framework, Config.Locale, Config.Debug | 'auto' detects qbx_core → qb-core → es_extended → standalone. Locales: tr, en (locales/*.lua). |
Config.Commands, Config.Keybinds | Command names (hud, hudfocus, cinematic, togglehud, freecam, carcontrol, cruise, limiter, indleft, indright, hazard, hudreset, hudtest) and default keys (empty = unbound, players can bind). |
Config.Editor | `permission = 'everyone' |
Config.Permissions.adminAce | ACE used for admin tools (framework admin groups are also accepted). |
Config.Storage | `backend = 'auto' |
Config.Limits | Max profiles per player, widgets per layout, rules per layout, payload size, profile name length. |
Config.Security | Request token bucket, per-action cooldowns (ms), suspicious log cooldown, optional kick threshold. |
Config.Update | Loop intervals: vehicle, onFoot, idle, world (street/zone), fuel, status, display, and nuiFlush (batch window). |
Config.Display | useSafeZone, followGameAspect (keep HUD in the game's aspect on multi-monitor), maxAspectRatio (e.g. 2.39 keeps it 21:9 on 32:9 screens), autoCollapse (a hidden widget's slot is closed by the widgets stacked behind it). |
Config.Units, Config.Time | Default speed unit; clock source 'server' (real server time, server timezone) or 'game'; 24 h default. |
Config.Minimap | Default minimap mode (always, vehicle, never) and hiding GTA's health/armour bars under the minimap. |
Config.NativeHud | GTA HUD components hidden while in a vehicle / armed (frame loop runs only then). |
Config.Context | Hide when paused / dead, default phone behaviour, phone state bag keys, vehicle classes without seatbelt. |
Config.Focus.widgets | Widgets kept in focus mode (external widgets opt in with focus = true). |
Config.Cinematic | What cinematic mode hides, critical notifications, black bars and their size, DisplayHud(false). |
Config.Freecam | Freecam / photo mode, see below. |
Config.CarControl | Car control panel, cruise control, limiter, indicators, see below. |
Config.Voice | Adapter (auto, pma-voice, saltychat, mumble, none) and range label locale keys. |
Config.Notifications | Max visible per stack, queue size, de-dup window, per-resource rate limit, durations and sounds per level, text limits. callerPosition (default false): when true, a script's own position (e.g. lib.notify({ position = 'top-right' })) overrides the player's chosen notification position. |
Config.Fonts | Fonts offered in the editor (files in nui/fonts). |
Config.ColorThemes, Config.Colorblind | Accent presets and colour-blind palettes (hex). |
Config.DefaultPrefs | Preferences of a player who never opened the editor. |
Config.Themes | Per theme: label, matching layout, font, radius, default variants (status, speed, rpm), colours (--c-* CSS variables). |
Config.Widgets | Built-in widget defaults: kind, icon, colour variable, context, priority, size, resize mode, anchor and offset. hidden = true hides it by default. |
Config.Layouts | Ready layouts: theme + per-widget overrides + optional rules. Players save their own copies. |
Config.Rules | Global rules, always active. |
Config.WeaponLabels | Fallback weapon names when no inventory / framework provides one. |
Freecam
| Key | Meaning |
|---|---|
enabled | false turns /freecam off for everyone. |
permission, ace | 'everyone', 'ace' (players with ace, e.g. add_ace group.streamer ns-hud.freecam allow) or 'admin'. Checked by the server on every start. |
maxDistance, collision | How far (m) the camera may leave the character (0 = unlimited) and whether walls / objects stop it. Keeps players from scouting inside buildings. |
admin | Limits for admins (Config.Permissions.adminAce / framework admin): default unlimited, no collision, unlimited lock range (playMaxDistance). |
allowInVehicle, exitOnDamage | Usable in a vehicle; leave the freecam as soon as the character is hurt. Death always closes it. |
farFocusDistance | Beyond this distance the world streams around the camera instead of the character. |
move, look, fov, roll, orbit | Speeds, mouse sensitivity, zoom range and wheel step, roll limit, orbit distances and auto-spin limit. |
path | Keyframe limit and duration range of the camera path. |
play | Lock & play (K): enabled; maxDistance = how far (m) the locked camera may sit from the character (0 = unlimited; a camera further away is pulled in when locking); allowCombat = aim / shoot / melee while locked (default off, so a wide camera can't be used to fire around corners); turnSpeed = how fast the camera swings round with a turning vehicle. |
world | Allow local time, weather, hidePlayer (only the player sees them; time / weather sync scripts may override them). |
weathers, filters, shakes, letterbox, grids | Lists offered in the panel. A filter is a GTA timecycle modifier name with a locale label. |
controls, keyLabels | GTA control ids used while flying and the key names shown in the hints. Change both together if a key clashes with another script. |
Car control
| Key | Meaning |
|---|---|
enabled | false turns the panel, its commands and the synced state off. |
keepDriving | The panel takes the mouse, the keyboard keeps driving the car (look / shoot / pause are blocked while it is open). false = the panel takes all input. |
cursorToggle | { control = 19, key = 'Alt' }: hides the cursor with the panel still open, so the mouse looks around / the game gets every input; pressing it again (or clicking the key chip in the header) brings the cursor back. control is a GTA control id, key the same key as a browser key name (also shown in the header). ESC still closes the panel. |
radial | Adds a Car control item to the ox_lib radial menu while the player is in a vehicle (ignored without ox_lib). |
disabledClasses | GTA vehicle classes the panel never opens for (21 = trains). |
access | Who may use each control: 'driver', 'front' (driver + front passenger), 'any' (every seat) or 'none' (hidden). ownDoor / ownWindow = the door / window next to the player's seat. engine, cruise, limiter, anchor, extras act on the driver's car and only accept 'driver' or 'none'. The server checks the seat on every synced change. |
outside | enabled, distance (m), requireKeys (qbx_vehiclekeys; without a keys resource the vehicle must be unlocked), controls = what is offered on foot (doors, hood, trunk, windows, interior, neon, roof). |
engine.requireKeys | Starting the engine needs the keys when qbx_vehiclekeys runs. |
seats | maxSpeed (km/h), blockWithSeatbelt, preventAutoShuffle (passengers are not moved into a free driver seat). |
cruise | minSpeed / maxSpeed (km/h), step (in the player's unit), gain (throttle per m/s below the set speed), resumeAfterAccelerate. |
limiter | minSpeed / maxSpeed (km/h), step. Switched on standing still it starts at 50 km/h (or the last value). |
indicators | autoCancel, turnAngle (degrees turned before it may cancel), straightRate (deg/s that counts as straight), straightMs. |
roof.maxSpeed, extras.maxSpeed, anchor.maxSpeed | km/h above which these are refused. |
Keys: Config.Commands.carControl / cruise / limiter / indicatorLeft / indicatorRight / hazard and the matching Config.Keybinds entries (empty by default, players bind them). The panel position is stored per player (client KVP).
Positions
anchor is one of tl tc tr cl c cr bl bc br (relative to the GTA safe zone) or mr (beside the minimap) / mt (above the minimap). x/y are reference pixels at 1080p pointing inward from the anchor; for centre anchors positive x is right and positive y is down. Everything scales with screen height and HUD scale, and is clamped into the safe area.
With Config.Display.autoCollapse on, a hidden widget's slot is closed automatically: widgets on the same anchor that are stacked behind it (further from the anchor edge, overlapping on the other axis) slide in. Works vertically (status bar column) and horizontally (icon row); a slide that would push a widget into another one is skipped. Saved offsets never change, and the editor always shows them as saved. When the minimap is hidden, mr widgets take its corner and mt widgets sit on top of them instead of falling into them.
Contexts
always, vehicle, onfoot, weapon, firearm, underwater, belt (vehicle with seatbelt), job (has a job / matches jobs), data (has data), manual (only via exports).
Rules
{ id = 'low_fuel', when = { { 'vehicle', '==', true }, { 'fuel', '<', 15 } }, actions = { { 'style', 'fuel', 'warning' } } }
Every condition must match; actions run in order (later wins). Evaluation order: Config.Rules → active layout rules → script rules. Players' "Visible = off" always wins; "Smart hide = off" ignores context and rules.
Adding a theme
Copy a block in Config.Themes, change label (add the locale key), colors and variants, and point layout to a layout in Config.Layouts. Picking a theme in the editor also applies that layout's widget sizes and positions (one undo step), because variants only fit their own sizes; script widgets keep their places.