`pulsar_core` exposes every shared system through one global, `plsr`. Required in every resource's `fxmanifest.lua` before `plsr` is available to that script. ```lua shared_script('@pulsar_core/core/sh_pulsar.lua') ``` First access to `plsr.X` fetches and caches the component (polls up to 5s if not registered yet, so resource start order doesn't matter as long as `pulsar_core` is a dependency). Reads after that are free. ## Registering your own component ```lua local MyThing = { DoSomething = function(self, arg) return arg * 2 end, } AddEventHandler('Proxy:Shared:RegisterReady', function() exports['pulsar_core']:RegisterComponent('MyThing', MyThing) end) ``` `plsr.MyThing:DoSomething(5)` now works from any resource. Register from inside that event handler, not at the top level — every component in this codebase does it this way. Registering before `Proxy:Shared:RegisterReady` fires risks calling into a `pulsar_core` that isn't ready yet. ## Components in this reference | plsr.X | Side | Covers | |---|---|---| | `State` | both | player flags, character cache, entity state | | `Callbacks` | both | client↔server request/response | | `Fetch` | both | reading player data | | `Player` | both | own player data (server: all players, client: local player) | | `Logger` | both | console/file/Discord/database logging | | `DataStore` | both | generic key/value store | | `Utils` | both | table/math helpers | | `Middleware` | server | prioritized event hooks | | `Game` | both | object/vehicle/player spawn+query helpers | | `ShapeTest` | client | raycasting | | `Execute` | server | invoke a method on a specific client | | `Database` | server | SQL queries against the MariaDB backend | | `Core` | server | shutdown/mass-drop admin primitives | | `Punishment` | server | ban/kick, backed by the `bans` table | | `Sequence` | server | persisted per-key auto-increment counters | | `Stream` | client | blocking model/anim-dict/anim-set loaders | # State `plsr.State` replaces native statebags. Reads are a plain table lookup — no mutex, no native call. Native statebag reads go through `GET_STATE_BAG_VALUE`, which takes a mutex server-side — one report ([citizenfx/fivem#1942](https://github.com/citizenfx/fivem/issues/1942)) measured tick time going from under 5ms to 100-250ms+ past ~80 players. `plsr.State` never calls that native; it's a local table kept in sync over a lightweight broadcast instead. ### Namespaces (client) | Namespace | Contents | |---|---| | `flags` | this client's own runtime flags (`loggedIn`, `ped`, `isDead`, custom flags, ...) | | `character` | logged-in character data (`SID`, `Cash`, `Jobs`, ...) | | `player` | session data (`serverID`, `accountID`, `name`, `groups`) | ```lua if plsr.State.flags.isDead then end local cash = plsr.State.character.Cash local char = plsr.State:Get('character') -- whole table, for NUI (SendNUIMessage, json.encode) ``` `plsr.State.character` (no `:Get`) only works for single-key reads — it has no real keys of its own for `pairs()`/`json.encode` to see. Use `:Get('character')` for the whole table. ### SetClientFlag(key, value) Local-only write, this client only. | Param | Type | Description | |---|---|---| | `key` | `string` | flag name | | `value` | `any` | | **Returns:** nothing ```lua plsr.State:SetClientFlag('doingAction', true) -- same as: plsr.State.flags.doingAction = true ``` ### SetPublicClientFlag(key, value) Also notifies the server, which validates the key against an allowlist and rebroadcasts to every other client. | Param | Type | Description | |---|---|---| | `key` | `string` | flag name | | `value` | `any` | | **Returns:** nothing ```lua plsr.State:SetPublicClientFlag('isDead', true) ``` This value is client-originated. A cheater can send anything through this path — never gate server-side game logic on a flag that arrived via `SetPublicClientFlag`. ### GetPublicFlag(serverId, key) / PublicPlayer(serverId) Read another player's public flag. | Param | Type | Description | |---|---|---| | `serverId` | `number` | | | `key` | `string` | flag name | **Returns:** `any` ```lua plsr.State:GetPublicFlag(serverId, 'isDead') plsr.State:PublicPlayer(serverId).isDead -- same thing, dot-sugar ``` ### SetPlayerFlag(source, key, value, serverOnly?) — server | Param | Type | Description | |---|---|---| | `source` | `number` | | | `key` | `string` | | | `value` | `any` | | | `serverOnly` | `boolean?` | don't sync to the owning client either | **Returns:** nothing ```lua plsr.State:SetPlayerFlag(source, 'onDuty', 'police') ``` ### SetPublicFlag(source, key, value) — server Same as `SetPlayerFlag` but also broadcasts to every other client. | Param | Type | Description | |---|---|---| | `source` | `number` | | | `key` | `string` | | | `value` | `any` | | **Returns:** nothing ```lua plsr.State:SetPublicFlag(source, 'isCuffed', true) ``` ### GetPlayerFlag(source, key) / Player(source) — server | Param | Type | Description | |---|---|---| | `source` | `number` | | | `key` | `string` | | **Returns:** `any` ```lua plsr.State:GetPlayerFlag(source, 'onDuty') plsr.State:Player(source).onDuty -- same thing, dot-sugar plsr.State:Player(source).onDuty = 'police' -- write goes through SetPlayerFlag ``` ### Watch(namespace, key, callback) — client Reactive subscription — fires immediately with the current value, then again on every change. | Param | Type | Description | |---|---|---| | `namespace` | `string` | `'flags'`, `'character'`, or `'player'` | | `key` | `string` | key to watch, or `'*'` for any change in the namespace | | `callback` | `function` | `(value, old)`, or `(allFlags)` for `'*'` | **Returns:** nothing ```lua plsr.State:Watch('flags', 'isDead', function(value, old) end) plsr.State:Watch('flags', '*', function(allFlags) end) ``` ## Entity state Replaces `Entity(x).state.X` for **networked** entities (vehicles, networked peds/objects). Keyed by network ID. ### Entity(entity) | Param | Type | Description | |---|---|---| | `entity` | `number` | entity handle | **Returns:** a proxy table — read `.Key`, write `.Key = value` ```lua local vin = plsr.State.Entity(vehicle).VIN plsr.State.Entity(vehicle).Locked = true ``` ### Entity:Get(entity, key) / Entity:Set(entity, key, value) | Param | Type | Description | |---|---|---| | `entity` | `number` | entity handle | | `key` | `string` | | | `value` | `any` | `Set` only | **Returns:** `Get` → `any`; `Set` → nothing ```lua plsr.State.Entity:Get(vehicle, 'VIN') plsr.State.Entity:Set(vehicle, 'Locked', true) ``` ### Entity:SetMulti(entity, data) Write several keys in one call — always prefer this over multiple sequential `Set` calls on the same entity (vehicle spawn, etc). | Param | Type | Description | |---|---|---| | `entity` | `number` | entity handle | | `data` | `table` | `{ [key] = value, ... }` | **Returns:** nothing ```lua plsr.State.Entity:SetMulti(vehicle, { VIN = generatedVin, Owned = true, Locked = true, Fuel = 100.0, }) ``` ### Entity:WatchKey(key, callback) — client Fires for every entity when `key` changes, whichever client wrote it. | Param | Type | Description | |---|---|---| | `key` | `string` | | | `callback` | `function` | `(netId, value, old)` | **Returns:** nothing ```lua plsr.State.Entity:WatchKey('Locked', function(netId, value, old) end) ``` ### Entity:Delete(entity) — server Clears state for an entity everywhere. | Param | Type | Description | |---|---|---| | `entity` | `number` | entity handle | **Returns:** nothing ```lua plsr.State.Entity:Delete(vehicle) ``` Fires automatically on `entityRemoved` — you don't normally need to call this yourself. ## What stays native Non-networked entities (`CreateObject(model, x, y, z, false, ...)`) never get a network ID, so `plsr.State.Entity` can't track them: meth tables, moonshine stills/barrels, placed props, weapon-attach cosmetic props stay on native `Entity(x).state.X`. Permanent constraint, not a gap to close — these were never networked, so there's nothing for `plsr.State.Entity` to key them by. Run `/checkstate` in the F8 console to dump your `flags`/`character`/`player` namespaces (false-valued flags hidden). ## Pause menu branding `COMPONENTS.Core.Init` overrides two native GXT text entries so the game's own pause menu shows Pulsar branding instead of "GTA Online": ```lua AddTextEntry("FE_THDR_GTAO", "~p~Pulsar Framework~m~") AddTextEntry('PM_PANE_CFX', "Pulsar Framework") ``` `FE_THDR_GTAO` is the pause menu's main header, `PM_PANE_CFX` is FXServer's own added-pages label (Key Bindings, etc). `~p~`/`~m~` are GTA in-engine text color tags (purple / reset). This is the native Rockstar/CitizenFX pause menu, not NUI — only GXT overrides work here, not CSS/theme.css. # Client Functions ## plsr.Callbacks ### ServerCallback(event, data?, cb, extraId?) Ask the server for something, get a response back. | Param | Type | Description | |---|---|---| | `event` | `string` | | | `data` | `table?` | | | `cb` | `function` | `(result)` | | `extraId` | `string?` | use when firing the same event concurrently for multiple things | **Returns:** nothing ```lua plsr.Callbacks:ServerCallback('MyResource:GetSomething', { id = 5 }, function(result) if not result then return end print(result) end) ``` No built-in timeout — if the other side never calls `cb(...)`, your callback just never fires. ### RegisterClientCallback(event, handler) Register a handler the server can call via `ClientCallback`. | Param | Type | Description | |---|---|---| | `event` | `string` | | | `handler` | `function` | `(data, cb)` | **Returns:** nothing ```lua plsr.Callbacks:RegisterClientCallback('MyResource:Confirm', function(data, cb) cb(true) end) ``` ## plsr.Fetch ### Player() **Returns:** this client's own player data store ```lua local me = plsr.Fetch:Player() local name = me:GetData('Name') ``` ## plsr.Player ### LocalPlayer The raw data store — prefer `plsr.Fetch:Player()` over touching this directly. ```lua plsr.Player.LocalPlayer:GetData('Name') ``` ## plsr.Game (client) ### Game.Players:GetClosestPlayer(coords?) | Param | Type | Description | |---|---|---| | `coords` | `vector3?` | defaults to your own position | **Returns:** `playerId, distance` ```lua local playerId, distance = plsr.Game.Players:GetClosestPlayer() ``` ### Game.Players:GetPlayerPeds() **Returns:** `{ { ped = , id = }, ... }` ```lua local peds = plsr.Game.Players:GetPlayerPeds() ``` ### Game.Objects:GetAll() / GetInArea(coords, radius) | Param | Type | Description | |---|---|---| | `coords` | `vector3` | `GetInArea` only | | `radius` | `number` | `GetInArea` only | **Returns:** array of object handles ```lua local all = plsr.Game.Objects:GetAll() local nearby = plsr.Game.Objects:GetInArea(coords, radius) ``` ### Game.Objects:Spawn(coords, modelName, heading, cb) / SpawnLocal(...) `Spawn` is networked, `SpawnLocal` is `isNetwork = false`. | Param | Type | Description | |---|---|---| | `coords` | `vector3` | | | `modelName` | `string \| number` | | | `heading` | `number` | | | `cb` | `function` | `(obj)` | **Returns:** nothing (object handle delivered via `cb`) ```lua plsr.Game.Objects:Spawn(coords, 'prop_whatever', heading, function(obj) end) ``` ### Game.Objects:Delete(obj) | Param | Type | Description | |---|---|---| | `obj` | `number` | object handle | **Returns:** nothing ```lua plsr.Game.Objects:Delete(obj) ``` ### Game.Vehicles:Spawn(coords, modelName, heading, cb) / SpawnLocal(...) | Param | Type | Description | |---|---|---| | `coords` | `vector3` | | | `modelName` | `string \| number` | | | `heading` | `number` | | | `cb` | `function` | `(veh)` | **Returns:** nothing (vehicle handle delivered via `cb`) ```lua plsr.Game.Vehicles:Spawn(coords, 'adder', heading, function(veh) end) ``` ### Game.Vehicles:Delete(veh) | Param | Type | Description | |---|---|---| | `veh` | `number` | vehicle handle | **Returns:** nothing ```lua plsr.Game.Vehicles:Delete(veh) ``` ## plsr.ShapeTest ### ShapeTest.Ray:EntityHit(startCoords, endCoords, flags?, ignoreEntity?, ignoreFlags?) | Param | Type | Description | |---|---|---| | `startCoords` | `vector3` | | | `endCoords` | `vector3` | | | `flags` | `number?` | default `17` | | `ignoreEntity` | `number?` | default your own ped | | `ignoreFlags` | `number?` | default `7` | **Returns:** entity handle, or `false` ```lua local hit = plsr.ShapeTest.Ray:EntityHit(startCoords, endCoords) ``` ## plsr.Stream Blocks the calling thread until the resource loads, no callback needed. ```lua plsr.Stream.RequestModel('adder') -- number hash or string both work plsr.Stream.RequestAnimDict('mp_arresting') plsr.Stream.RequestAnimSet('move_ped_crouched') ``` Dot-call, not colon-call — none of these three take `self`. `plsr.Stream:RequestModel(...)` passes the wrong first argument. ## plsr.Utils ### Round(value, decimals) | Param | Type | Description | |---|---|---| | `value` | `number` | | | `decimals` | `number` | | **Returns:** `number` ```lua plsr.Utils:Round(4.732, 2) -- 4.73 ``` ### GetTableLength(t) / GetTableKeys(t) / DoesTableHaveValue(t, val) | Param | Type | Description | |---|---|---| | `t` | `table` | | | `val` | `any` | `DoesTableHaveValue` only | **Returns:** `number` / `table` / `boolean` respectively ```lua plsr.Utils:GetTableLength(t) plsr.Utils:GetTableKeys(t) plsr.Utils:DoesTableHaveValue(t, val) ``` ### WeightedRandom(pool) | Param | Type | Description | |---|---|---| | `pool` | `table` | `{ { weight, value }, ... }` | **Returns:** one `value` from the pool, weighted ```lua plsr.Utils:WeightedRandom({ { 70, 'common' }, { 25, 'rare' }, { 5, 'legendary' } }) ``` Same `Utils` API on both client and server. ## plsr.Notifications ### Notifications.Hint.ShowThisFrame(text) One-frame native help-text popup. | Param | Type | Description | |---|---|---| | `text` | `string` | supports native tags, e.g. `~INPUT_CONTEXT~` | **Returns:** nothing ```lua plsr.Notifications.Hint.ShowThisFrame('Press ~INPUT_CONTEXT~ to interact') ``` This is not the toast/alert system used elsewhere in the framework — that's `plsr.Notification` (singular), from `pulsar_hud`. ## Globals (not under plsr) ### EnumeratePeds() / EnumerateVehicles() / EnumerateObjects() / EnumeratePickups() **Returns:** iterator ```lua for ped in EnumeratePeds() do end for veh in EnumerateVehicles() do end ``` ## Commands ### /checkstate Dumps your `flags`/`character`/`player` state to the F8 console. # Server Functions ## plsr.Callbacks (server) ### ClientCallback(source, event, data?, cb, extraId?) Ask a specific client for something, get a response back. | Param | Type | Description | |---|---|---| | `source` | `number` | | | `event` | `string` | | | `data` | `table?` | | | `cb` | `function` | `(answer)` | | `extraId` | `string?` | use when firing the same event concurrently for multiple things | **Returns:** nothing ```lua plsr.Callbacks:ClientCallback(source, 'MyResource:Confirm', { prompt = 'Sure?' }, function(answer) if answer then end end) ``` ### RegisterServerCallback(event, handler) Register a handler the client can call via `ServerCallback`. | Param | Type | Description | |---|---|---| | `event` | `string` | | | `handler` | `function` | `(source, data, cb)` | **Returns:** nothing ```lua plsr.Callbacks:RegisterServerCallback('MyResource:GetSomething', function(source, data, cb) cb(SomeLookup(data.id)) end) ``` ## plsr.Fetch (server) ### Source(source) Get a connected player's data store by their server id. | Param | Type | Description | |---|---|---| | `source` | `number` | | **Returns:** player data store, or `nil` ```lua local player = plsr.Fetch:Source(source) if player then local name = player:GetData('Name') end ``` ### PlayerData(field, value) Find a connected player by matching a field. | Param | Type | Description | |---|---|---| | `field` | `string` | e.g. `'AccountID'` | | `value` | `any` | | **Returns:** player data store, or `nil` ```lua local player = plsr.Fetch:PlayerData('AccountID', someAccountId) ``` ### All() **Returns:** every connected player, keyed by source ```lua for source, player in pairs(plsr.Fetch:All()) do end ``` ### Count() **Returns:** `number` ```lua local online = plsr.Fetch:Count() ``` ## Player data shape Every connected player's store carries: | Field | Type | Notes | |---|---|---| | `Source` | `number` | server id | | `Groups` | `table` | permission group names | | `Name` | `string` | display name | | `GameName` | `string` | in-game name from `GetPlayerName` | | `ID` | `number` | account id from your auth backend | | `AccountID` | `number` | | | `Discord` | `string` | Discord id, if linked | | `Mention` | `string` | Discord mention string, if linked | | `Avatar` | `string` | avatar URL, if available | | `Identifier` | `string` | | | `Permissions` | `table` | see below | ```lua player.Permissions:IsStaff() player.Permissions:IsAdmin() player.Permissions:GetLevel() -- highest Permission.Level across their groups ``` Permission groups/levels come from `Config.Groups`. ## plsr.Logger ### Trace / Info / Warn / Error / Critical(component, log, flags?) | Param | Type | Description | |---|---|---| | `component` | `string` | | | `log` | `string` | | | `flags` | `table?` | `{ console, file, discord, database }` — omit for `{ console = true }` | **Returns:** nothing ```lua plsr.Logger:Info('MyResource', 'Player connected') plsr.Logger:Error('MyResource', 'Something failed', { console = true, discord = { embed = true, type = 'error', webhook = GetConvar('discord_log_webhook', '') }, }) ``` Console output is gated by the `log_level` convar. Cross-resource, no `plsr.X` needed: `TriggerEvent('Logger:Info', 'MyResource', 'message')`. ## plsr.DataStore ### CreateStore(owner, key, data?) | Param | Type | Description | |---|---|---| | `owner` | `number` | player source, or any fixed id | | `key` | `string` | namespace under that owner | | `data` | `table?` | | **Returns:** the store ```lua local store = plsr.DataStore:CreateStore(source, 'MyKey', { Foo = 'bar' }) store:SetData('Foo', 'baz') local foo = store:GetData('Foo') local whole = store:GetData() -- no key = full table ``` Writes to a store keyed `"Character"` also broadcast to that player's client via `Characters:Client:SetData` (except `HP`/`Armor`, which change too fast to broadcast on every write). ### DeleteStore(owner, key) | Param | Type | Description | |---|---|---| | `owner` | `number` | | | `key` | `string` | | **Returns:** nothing ```lua plsr.DataStore:DeleteStore(owner, key) -- or: store:DeleteStore() ``` ## plsr.Middleware ### Add(event, cb, prio?) | Param | Type | Description | |---|---|---| | `event` | `string` | | | `cb` | `function` | | | `prio` | `number?` | default `1`, lower runs first | **Returns:** nothing ```lua plsr.Middleware:Add('playerDropped', function(source, message) end, 2) ``` ### TriggerEvent(event, ...) **Returns:** nothing ```lua plsr.Middleware:TriggerEvent('playerDropped', source, 'Timed out') ``` ### TriggerEventWithData(event, ...) Handlers must return an array; results from every handler are merged and ID-sorted. **Returns:** merged array of every handler's results ```lua plsr.Middleware:Add('MyResource:GetExtraOptions', function(source, ctx) return { { label = 'Do Thing' } } end) local all = plsr.Middleware:TriggerEventWithData('MyResource:GetExtraOptions', source, ctx) ``` Registered handlers are cleared whenever any other resource restarts. Re-register on every start — don't assume a hook survives a hot reload. ## plsr.Execute ### Client(source, component, method, ...) Invoke a method on a component in a specific client's Lua state. | Param | Type | Description | |---|---|---| | `source` | `number` | | | `component` | `string` | e.g. `'SomeComponent'` | | `method` | `string` | | | `...` | `any` | passed through to the method | **Returns:** nothing ```lua plsr.Execute:Client(source, 'SomeComponent', 'SomeMethod', arg1, arg2) ``` Logged server-side for every call (except `Logger`/`Notification`/`Animations`/`Phone`). This is an admin-tool primitive — prefer `plsr.Callbacks` for normal request/response. ## plsr.Game (server) ### Objects:Spawn(coords, modelName, heading) Synchronous, networked. | Param | Type | Description | |---|---|---| | `coords` | `vector3` | | | `modelName` | `string \| number` | | | `heading` | `number` | | **Returns:** entity handle ```lua local obj = plsr.Game.Objects:Spawn(coords, 'prop_whatever', heading) ``` ### Objects:Delete(obj) | Param | Type | Description | |---|---|---| | `obj` | `number` | object handle | **Returns:** nothing ```lua plsr.Game.Objects:Delete(obj) ``` ## plsr.Database Every method wraps oxmysql, normalized to a `(success, result)` callback (oxmysql itself uses `(result, error)`). | Method | Purpose | |---|---| | `Query` | SELECT, every matching row | | `Single` | SELECT, first matching row (or `nil`) | | `Scalar` | SELECT, one value (e.g. `COUNT(*)`) | | `Insert` | INSERT, returns the new auto-increment id | | `Update` | UPDATE/DELETE, returns affected row count | | `Prepare` | prepared statement, for hot-path queries run often with different params | | `RawExecute` | escape hatch (DDL, multi-statement) | | `Transaction` | array of `{ query, values }`, all-or-nothing | ```lua plsr.Database:Query('SELECT * FROM characters WHERE account = ?', { accountId }, function(success, rows) end) plsr.Database:Insert('INSERT INTO characters (account, name) VALUES (?, ?)', { accountId, name }, function(success, id) end) plsr.Database:Transaction({ { query = 'UPDATE a SET x = 1', values = {} }, { query = 'UPDATE b SET y = 2', values = {} }, }) ``` ## plsr.Punishment Ban/kick, backed by the `bans` table. Every method checks the issuer's permission level against the target's and logs the action. | Method | Params | |---|---| | `Kick` | `(source, reason, issuer, afk?)` | | `CheckBan` | `(key, value)` — `key` is `'_id' \| 'account' \| 'identifier'` | | `CheckTokenBan` | `(tokens)` — array of `GetPlayerToken` values, for pre-connect checks | | `Ban.Source` | `(source, expiresDays, reason, issuer)` — `-1` expiresDays = permanent | | `Ban.AccountID` | `(accountId, expiresDays, reason, issuer)` | | `Ban.Identifier` | `(identifier, expiresDays, reason, issuer)` | | `Unban.BanID` / `Unban.AccountID` / `Unban.Identifier` | `(id \| accountId \| identifier, issuer)` | ```lua plsr.Punishment:Kick(source, 'AFK too long', 'System', true) plsr.Punishment.Ban:Source(source, 7, 'Cheating', issuerSource) -- 7-day ban plsr.Punishment.Unban:AccountID(accountId, issuerSource) ``` `issuer` is a source id, except the literal string `"Pwnzor"` — reserved for the anti-cheat resource, which skips the permission check entirely. Any other issuer needs a permission level higher than the target's or the call fails. ## plsr.Sequence ### Get(key) Persisted per-key auto-increment counter (ticket numbers, case numbers, etc). | Param | Type | Description | |---|---|---| | `key` | `string` | | **Returns:** `number` ```lua local caseNumber = plsr.Sequence:Get('mdt_case') ``` Saved automatically on an interval and on force-save — you never call `Save` yourself. ## plsr.Core | Method | Params | Effect | |---|---|---| | `Shutdown` | `(reason)` | logs the reason, then `os.exit()` after a 1s flush delay | | `DropAll` | `()` | drops every connected player with a restart-notice message | ```lua plsr.Core:Shutdown('Out of memory') ``` ## plsr.Convar Read-only snapshot of server convars, fetched once at startup. ```lua plsr.Convar.LOGGING.value plsr.Convar.ENVIRONMENT.value -- server-only, sv_environment convar plsr.Convar.PLSR_VERSION.value ```