`pulsar_hud` covers the status HUD, notifications, and every modal-style overlay (menus, confirms, input). 9 `plsr` components. ## Components in this reference | plsr.X | Covers | |---|---| | `Hud` | status HUD, vehicle HUD, minimap, death/damage screen effects | | `Notification` | toast alerts | | `Action` | keybind-style interaction prompts (bottom-right) | | `Progress` | progress-bar actions (animation, prop, movement lock) | | `Buffs` | HUD buff icons | | `Interaction` | the F-key radial/list interaction menu | | `ListMenu` | generic nested list menu overlay | | `Confirm` | yes/no confirmation dialog | | `Input` | text/number/multiline input form | | `InfoOverlay` | full-screen title+description overlay | Also see [Cross-resource event contracts](#cross-resource-event-contracts) — plain events other resources fire directly instead of calling `plsr.X`. # plsr.Hud ### IsDisabled() / IsDisabledAllowDead() **Returns:** `boolean` — `true` if HUD-gated interactions should be blocked: dead, cuffed, mid-`Progress`, inventory/phone/crafting open, hospitalized, or escorted. `IsDisabledAllowDead` is the same minus the dead check, for things that should still work while dead (hospital menus). ```lua if not plsr.Hud:IsDisabledAllowDead() then plsr.Interaction:Show() end ``` ### Show() / Hide() / Toggle() Shows/hides the whole HUD (status bars, minimap). **Returns:** nothing ```lua plsr.Hud:Toggle() ``` Automatically restarts its own update threads on `Show`/`Toggle`-on — you don't need to re-trigger anything after. ### RegisterStatus(name, current, max, icon, color, flash, update, options?) Registers a status bar — hunger, thirst, stress, oxygen, radio frequency, a job timer, anything. | Param | Type | Description | |---|---|---| | `name` | `string` | stable id | | `current`, `max` | `number` | | | `icon` | `string` | FontAwesome-style icon name | | `color` | `string` | hex | | `flash` | `boolean` | flash when low | | `update` | `boolean` | `false` to create it; `true` to redefine an already-registered bar (icon/color/options, e.g. switching the oxygen bar's icon when scuba gear goes on) — **not** how you push a routine value change, see below | | `options` | `table?` | e.g. `{ hideHigh = true, order = 3 }` | **Returns:** nothing ```lua plsr.Hud:RegisterStatus('radio-freq', 0, 1000, 'walkie-talkie', '#4056b3', false, false) ``` Once a bar is registered, push value updates with a local `TriggerEvent('Status:Client:Update', name, value)` instead of calling `RegisterStatus` again — this is the pattern `pulsar_status`, `pulsar_radio`, and `pulsar_laptop`'s boosting minigame all actually use. If the value needs to be server-trusted, fire it from the server via `TriggerClientEvent` instead of locally. ```lua TriggerEvent('Status:Client:Update', 'radio-freq', currentFrequency) ``` ### ResetStatus() **Returns:** nothing — clears every registered status bar from the HUD ### Vehicle.Show() / Vehicle.Hide() / Vehicle.Toggle() Vehicle HUD (speed, RPM, fuel, seatbelt, signals). **Returns:** nothing Driven automatically off `GLOBAL_VEH` by `Show`/`Toggle` above — you shouldn't need to call these directly in normal resource code. ### Overlay.Show(itemData) / Overlay.Hide() Full-screen item-use overlay (reading a document, looking at a map). | Param | Type | Description | |---|---|---| | `itemData` | `table` | `Show` only | **Returns:** nothing ```lua plsr.Hud.Overlay:Show(itemData) plsr.Hud.Overlay:Hide() ``` Used by `pulsar_inventory`'s item-use system and `pulsar_labor`'s hunting job. ### GemTable.Open(quality) / GemTable.Close() Gem-quality inspection minigame overlay, used by jewelry-store robbery scripts (`vangelico`, `sagma`, `jewel`). | Param | Type | Description | |---|---|---| | `quality` | `number` | `Open` only | **Returns:** nothing ```lua plsr.Hud.GemTable:Open(quality) plsr.Hud.GemTable:Close() ``` ### Meth.Open(tierConfig) / Meth.Close() Meth-cooking minigame overlay, paired with `pulsar_drugs`' meth table system. **Returns:** nothing `Open` takes that system's own tier/config table — not a generic HUD contract, don't build against this unless you're extending that specific minigame. ### DeathTexts.Show(type, deadTime, releaseTime, keyOverride?) / Release() / Hide() Full-screen death/knockout overlay (`pulsar_damage` owns this end-to-end). | Param | Type | Description | |---|---|---| | `type` | `string` | `'death'` or `'knockout'` | | `deadTime` | `number` | | | `releaseTime` | `number` | | | `keyOverride` | `string?` | | **Returns:** nothing `Release()` shows the "releasing" transition state. ### Flashbang.Do(durationMs, strength) / Flashbang.End() Screen-flash effect for flashbang grenades. | Param | Type | Description | |---|---|---| | `durationMs` | `number` | `Do` only | | `strength` | `number` | `Do` only | **Returns:** nothing ```lua plsr.Hud.Flashbang:Do(durationMs, strength) plsr.Hud.Flashbang:End() ``` ### Dead(state) Sets/clears the dead-screen visual state. | Param | Type | Description | |---|---|---| | `state` | `boolean` | | **Returns:** nothing ```lua plsr.Hud:Dead(true) ``` ### UpdateVoip(level, talking, iconOverride?) Pushes VOIP talk state to the HUD's mic icon. Owned by `pulsar_voip`. | Param | Type | Description | |---|---|---| | `level` | `number` | | | `talking` | `boolean` | | | `iconOverride` | `string?` | | **Returns:** nothing ```lua plsr.Hud:UpdateVoip(level, talking, iconOverride) ``` ### NOS(level) Updates the NOS meter (vehicle HUD). | Param | Type | Description | |---|---|---| | `level` | `number` | | **Returns:** nothing ```lua plsr.Hud:NOS(level) ``` ### ForceHP() Pushes a one-off HP/armor refresh to the HUD outside the normal update loop. **Returns:** nothing Rarely needed — the vehicle/status threads already keep HP live while the HUD is shown. `ID.Toggle` (nearby player ID overhead) also exists but is wired to a keybind (`ids_toggle`) inside `pulsar_hud` itself — you shouldn't need to call it directly. # plsr.Notification Toast alerts, top-right. ### Success / Warn / Error / Info / Standard / Custom(message, duration?, icon?) | Param | Type | Description | |---|---|---| | `message` | `string` | | | `duration` | `number?` | ms, defaults to config | | `icon` | `string?` | | **Returns:** nothing ```lua plsr.Notification:Success('Saved') plsr.Notification:Error('Not enough cash', 5000) ``` ### Clear() **Returns:** nothing — clears every visible notification ### Persistent.Success / Warn / Error / Info / Standard / Custom / Remove(id, message?) Same six variants as above, plus `Remove`, for a notification that stays until dismissed by id instead of timing out. **Returns:** nothing ```lua plsr.Notification.Persistent.Warn('robbery-timer', 'Police alerted') plsr.Notification.Persistent.Remove('robbery-timer') ``` # plsr.Action Bottom-right keybind prompt — "press E to interact" style. ### Show(id, message) / Hide(id) / HideAll() | Param | Type | Description | |---|---|---| | `id` | `string` | call `Show` again with the same id to replace its message; `Hide` removes just that id | | `message` | `string` | supports `{keybind}bindName{/keybind}` to render the player's actual bound key inline | **Returns:** nothing ```lua plsr.Action:Show('bennys', '{keybind}primary_action{/keybind} Customize Vehicle') plsr.Action:Hide('bennys') plsr.Action:HideAll() ``` `HideAll` fires automatically on logout — you don't need to clean up your own prompts on character switch. # plsr.Progress Progress-bar actions: animation, prop attachment, movement lock, all driven from one call. ### Progress(action, finish) / ProgressWithStartEvent(...) / ProgressWithTickEvent(...) / ProgressWithStartAndTick(...) | Param | Type | Description | |---|---|---| | `action` | `table` | see fields below (all optional except `duration`/`label`) | | `finish` | `function` | `(cancelled)` | **Returns:** nothing ```lua plsr.Progress:Progress({ name = 'blindfold_action', duration = 5000, label = 'Putting on blindfold', useWhileDead = false, canCancel = true, disarm = false, controlDisables = { disableMovement = true, disableCarMovement = true, disableCombat = true, }, animation = { animDict = 'random@mugging4', anim = 'struggle_loop_b_thief', flags = 49, }, }, function(cancelled) -- finish(cancelled) end) ``` `action` fields: | Field | Type | Description | |---|---|---| | `name` | `string` | id, readable back via `CurrentAction` | | `duration` | `number` | ms | | `label` | `string` | | | `useWhileDead` | `boolean` | | | `canCancel` | `boolean` | whether the cancel keybind works on it | | `ignoreModifier` | `boolean` | skip any active `Modifier` speed change | | `disarm` | `boolean` | unequip current weapon first | | `controlDisables` | `table` | `{ disableMovement, disableCarMovement, disableMouse, disableCombat }` | | `animation` | `table` | `{ animDict, anim, flags }` or `{ task = 'SCENARIO_NAME' }` or `{ anim = 'emoteName' }` (routes through `plsr.Animations.Emotes`) | | `prop` / `propTwo` | `table` | `{ model, bone?, coords?, rotation? }` — attached to the ped for the duration | | `vehicle` | `boolean` | auto-fails if the player isn't in a vehicle | | `tickrate` | `number` | ms — only relevant with a `tick` callback | `ProgressWithStartEvent`/`ProgressWithTickEvent`/`ProgressWithStartAndTick` add a `start()` (fires once, immediately) and/or `tick()` (fires on a loop while the action runs) callback ahead of `finish(wasCancelled)`. ### Modifier(percent, durationMs) Applies a temporary speed multiplier to progress durations (e.g. a skill bonus). | Param | Type | Description | |---|---|---| | `percent` | `number` | | | `durationMs` | `number` | | **Returns:** `boolean` — `false` if one's already active; only one modifier can run at a time ```lua plsr.Progress:Modifier(50, 10000) -- 50% speed for 10s ``` ### Cancel(force?) / Fail() / Finish() / CurrentAction() | Param | Type | Description | |---|---|---| | `force` | `boolean?` | `Cancel` only — bypass `canCancel` | **Returns:** `CurrentAction` → name of the running action, or errors if none; others → nothing ```lua plsr.Progress:Cancel() -- respects canCancel unless force = true plsr.Progress:Fail() -- always cancels, distinct NUI state plsr.Progress:CurrentAction() ``` Only one `Progress` action can run at a time — starting a second while one is active shows an "Already Doing An Action" error instead of queueing or replacing it. # plsr.Buffs HUD buff icons (top of screen) — status effects like speed boosts, healing ticks, debuffs. ### RegisterBuff(id, icon, color, duration, type) Must be called once before a buff type can be applied. | Param | Type | Description | |---|---|---| | `id` | `string` | | | `icon` | `string` | | | `color` | `string` | hex | | `duration` | `number` | `-1` for types where duration is set per-application instead | | `type` | `string` | `'timed'` (countdown, auto-clears) or `'permanent'` (stays until removed) | **Returns:** nothing ```lua plsr.Buffs:RegisterBuff('speed', 'bolt-lightning', '#8419C2', -1, 'timed') ``` `pulsar_hud` itself doesn't pre-register anything except its own `prog_mod`/`stress_ticks`/`heal_ticks`/`armor_ticks`. ### ApplyBuff(buffId, val, override?, options?) / ApplyUniqueBuff(...) | Param | Type | Description | |---|---|---| | `buffId` | `string` | | | `val` | `number` | seconds for timed buffs | | `override` | `any?` | icon/label override, buff-specific | | `options` | `table?` | | **Returns:** nothing ```lua plsr.Buffs:ApplyUniqueBuff('speed', 30, false) -- 30s speed buff ``` `ApplyUniqueBuff` replaces any existing instance of that buff (refreshes duration instead of stacking) — used for the vast majority of real call sites. Plain `ApplyBuff` is only used for flags like `godmode` that don't have a duration to refresh. ### UpdateBuff(buffId, val) / IconOverride(buffId, icon) / RemoveBuffType(buffId) | Param | Type | Description | |---|---|---| | `buffId` | `string` | | | `val` | `number` | `UpdateBuff` only | | `icon` | `string` | `IconOverride` only | **Returns:** nothing ```lua plsr.Buffs:UpdateBuff('speed', 15) -- push a new value without restarting the buff plsr.Buffs:RemoveBuffType('speed') ``` # plsr.Interaction The F-key interaction menu (global, one instance). ### RegisterMenu(id, label, icon, action, shouldShow?, labelFunc?) Adds an entry to the top-level menu. Call once at resource start, not per-interaction. | Param | Type | Description | |---|---|---| | `id` | `string` | | | `label` | `string` | | | `icon` | `string` | | | `action` | `function` | `(data)` — `data` is whatever `shouldShow` returned | | `shouldShow` | `function?` | `(): boolean \| any` — omit to always show; re-evaluated every time the menu opens | | `labelFunc` | `function?` | `(): string` — re-evaluates the label every open, for dynamic text | **Returns:** nothing ```lua plsr.Interaction:RegisterMenu('apt-exit', 'Exit Apartment', 'door-open', function(data) plsr.Interaction:Hide() plsr.Apartment:Exit() end, function() return plsr.State.flags.apartmentId ~= nil end) ``` ### Show() / Hide() / ShowMenu(items) / Back() | Param | Type | Description | |---|---|---| | `items` | `table` | `ShowMenu` only — same item shape as `RegisterMenu` produces internally | **Returns:** nothing `Show()` opens the top-level menu. `ShowMenu(items)` pushes a submenu layer, used for menus built from dynamic data rather than static registration. `Back()` pops one layer. # plsr.ListMenu Generic nested list overlay — separate from `Interaction`, used for anything more like a settings/browse menu than a contextual radial. ### Show(menus) / Close() | Param | Type | Description | |---|---|---| | `menus` | `table` | keyed by submenu id, each `{ label, items }` | **Returns:** nothing Item shape: `{ label, description?, event?, submenu?, disabled? }` — `event` fires a **local** `TriggerEvent` with the item's `data` field when clicked; `submenu` switches to another key in the same `menus` table instead. ```lua plsr.ListMenu:Show({ main = { label = 'Settings', items = { { label = 'Notifications', description = 'Configure alerts', submenu = 'notifs' }, { label = 'Reset', description = 'Reset to defaults', event = 'MyResource:Client:Reset' }, }, }, notifs = { label = 'Notifications', items = { { label = 'Back...', description = '' } }, }, }) ``` # plsr.Confirm Yes/no confirmation dialog. ### Show(title, events, description, data?, denyLabel?, acceptLabel?) / Close() | Param | Type | Description | |---|---|---| | `title` | `string` | | | `events` | `table` | `{ yes: string, no: string }` — local event names, fired via `TriggerEvent` with `(data)`; use `''` for the one you don't care about | | `description` | `string` | supports basic HTML (`
` seen in real usage) | | `data` | `any?` | passed through to whichever event fires | | `denyLabel`, `acceptLabel` | `string?` | button text overrides | **Returns:** nothing ```lua plsr.Confirm:Show( 'Confirm Purchase', { yes = 'MyResource:Client:Confirmed', no = '' }, 'Are you sure you want to buy this?', { vehicleId = id } ) ``` # plsr.Input Text/number/multiline input form. ### Show(title, label, inputs, event, data?) / Close() | Param | Type | Description | |---|---|---| | `title` | `string` | | | `label` | `string` | | | `inputs` | `table` | array of `{ id, label?, type: 'text'\|'number'\|'multiline', options?: { disabled?, value?, inputProps?: { min?, max?, maxLength? } } }` | | `event` | `string` | local event, fires `(values, data)` on submit, `values` keyed by each input's `id` | | `data` | `any?` | passed through to the submit event | **Returns:** nothing ```lua plsr.Input:Show('Give Cash', 'Amount To Give', { { id = 'target', label = 'Target', type = 'number', options = { disabled = true, value = targetSid } }, { id = 'amount', type = 'number', options = { inputProps = { min = 1, max = 5000 } } }, }, 'Hud:Client:DoGiveCash', { target = targetSid }) AddEventHandler('Hud:Client:DoGiveCash', function(values, data) plsr.Callbacks:ServerCallback('Wallet:GiveCash', { target = data.target, amount = values.amount }) end) ``` Closing without submitting fires `Input:Closed` locally with `(event, data)` — listen for that if you need to clean something up on cancel. # plsr.InfoOverlay Full-screen title+description overlay — simplest of the modal overlays, no interactivity beyond dismissing it. ### Show(title, description) / Close() / IsOpen() | Param | Type | Description | |---|---|---| | `title` | `string` | `Show` only | | `description` | `string` | `Show` only | **Returns:** `IsOpen` → `boolean`; others → nothing ```lua plsr.InfoOverlay:Show('Rules', 'No fail-RP. No combat logging.') plsr.InfoOverlay:Close() ``` # Cross-resource event contracts Plain local/networked events other resources fire directly instead of calling `plsr.X` — the real integration surface for systems that don't own their own HUD rendering. ### Status:Client:Update Covered above under [RegisterStatus](#registerstatusname-current-max-icon-color-flash-update-options) — the actual way to push a status bar value after registering it. ### Vehicle HUD (owned by pulsar_vehicles) `pulsar_hud` listens for these local events and updates the vehicle dash accordingly — it doesn't poll or own vehicle state itself: | Event | Params | |---|---| | `Vehicles:Client:EnterVehicle` | `(vehicle, seat)` — shows/hides the vehicle HUD and sets `GLOBAL_VEH` | | `Vehicles:Client:ExitVehicle` | `(vehicle, seat)` | | `Vehicles:Client:Seatbelt` | `(state)` | | `Vehicles:Client:Cruise` | `(state)` | | `Vehicles:Client:Ignition` | `(state)` | | `Vehicles:Client:Fuel` | `(amount, hide)` | ### Targeting menu chrome (owned by pulsar_targeting) Renders the eye icon and context-menu NUI for `pulsar_targeting` — owns none of the raycast logic itself: | Event | Params | |---|---| | `Targeting:Client:UpdateState` | `(isTargeting, hasTarget)` — shows/hides the eye icon | | `Targeting:Client:OpenMenu` | `(menuData)` | | `Targeting:Client:CloseMenu` | `()` | | `Targeting:Client:MenuSelect` | fired *by* `pulsar_hud` on selection, `(event, data)`, for `pulsar_targeting` to handle | ### Blindfold Reactive, no `plsr.Hud` call needed — it just watches the flag: ```lua plsr.State:SetPublicFlag(target, 'isBlindfolded', true) ``` No separate client call needed once the flag flips — `pulsar_hud`'s own `blindfold` inventory item uses exactly this to trigger it server-side. ### Particles:Server:DoFx / Particles:Client:StopFx A small standalone particle-effect utility, unrelated to any `plsr.X` component. | Param | Type | Description | |---|---|---| | `fx` | `string` | `'smoke' \| 'flash' \| 'spark'` — the only three registered in `pulsar_hud/client/ptfx.lua`'s effect table | ```lua TriggerEvent('Particles:Server:DoFx', coords, 'spark') -- server-side; relays to every nearby client TriggerServerEvent('Particles:Server:DoFx', coords, 'smoke') -- client-side; same relay ``` Used across `pulsar_robbery` (thermite sparks) and `pulsar_inventory` (muzzle flash, smoke).

Hud/UI