Character select, creation, and the login → spawn flow. Most resources only need one thing from this resource: the `Characters:Client:Spawn` event ## Components in this reference | plsr.X | Side | Covers | |---|---|---| | `Characters` | both | logout, last-known-location lookup | | `Fetch` (extended) | server | `CharacterSource`/`ID`/`SID`/`CharacterData` lookups — added onto `pulsar_core`'s `plsr.Fetch`, not a separate component | | `Reputation` | both | per-character reputation levels | | `Spawn` | client | character creation/select scene + world-spawn (overrides `pulsar_core`'s no-op default) | # Login → spawn event flow The chain almost every resource actually hooks into, in order: 1. Player picks a character in the NUI → client calls the `Characters:GetCharacterData` server callback, gets the full character row back. 2. Client fires `Characters:Client:SetData` locally, which populates `plsr.State.character` and fires `Characters:Client:Updated(key)`. 3. `plsr.Spawn:SpawnToWorld(cData, cb)` runs — sets the player model, positions them, restores HP. 4. Client fires `TriggerServerEvent('Characters:Server:Spawning')`. 5. Server: `plsr.Middleware:TriggerEvent('Characters:Spawning', source)` fires — **the extension point**, see [Middleware hooks](#middleware-hooks). 6. `pulsar_characters` hooks `Characters:Spawning` at the lowest priority (runs last), firing `TriggerClientEvent('Characters:Client:Spawned', source)`. 7. Client's `Characters:Client:Spawned` handler fires `TriggerEvent('Characters:Client:Spawn')` **locally** and sets `plsr.State.flags.loggedIn = true`. Step 7 is the one to hook — `Spawn` (no "ed"), what ~60 other files in this codebase use. `Spawned` (with "ed") is the internal networked handoff; hook that instead and your code runs before `loggedIn` is even set. ```lua AddEventHandler('Characters:Client:Spawn', function() -- character is fully in the world, plsr.State.flags.loggedIn is true end) ``` The same handler also fires `TriggerServerEvent('Characters:Server:Spawn')` — checked every resource in this codebase, nothing listens for it server-side. Dead as of this writing; don't build against it. ### Characters:Client:Updated(key) Local event, fires every time a character field changes via `Characters:Client:SetData` (both the full-replace on login and any individual-field push from `plsr.DataStore`). | Param | Type | Description | |---|---|---| | `key` | `any` | `-1` means a full replace (login); otherwise the single field name | ```lua AddEventHandler('Characters:Client:Updated', function(key) if key == -1 or key == 'Cash' then end end) ``` Used across `pulsar_hud`, `pulsar_mdt`, `pulsar_phone`, `pulsar_inventory`, `pulsar_laptop`, and others to react to specific field changes. ### Characters:Logout() — client Fades out and returns to character select. **Returns:** nothing ```lua plsr.Characters:Logout() ``` # Middleware hooks The real extension points for character creation, spawning, and logout. All go through `plsr.Middleware` (see the `pulsar_core` doc for `Add`/`TriggerEvent`/`TriggerEventWithData`). ### Characters:Creating `TriggerEventWithData`, fired when a new character is inserted. Return an array with one table to merge extra fields into the new character document (before it's written to the DB). ```lua plsr.Middleware:Add('Characters:Creating', function(source, doc) return { { HUDConfig = defaultConfig } } end) ``` ### Characters:Spawning `TriggerEvent`, fired server-side right before the client is told to finalize spawn (step 5 above). `pulsar_characters` itself hooks this at the lowest priority so everyone else's hooks run first. ### Characters:GetSpawnPoints `TriggerEventWithData(source, characterId, char)`, fired when the client asks for spawn points after selecting a character. Return an array of `{ id, label, location = { x, y, z, h }, icon?, event? }`. `event`, if set, is a server callback name called with the chosen entry before spawn finalizes — how `pulsar_jail`'s `Jail:SpawnJailed` and `pulsar_damage`'s `Hospital:SpawnICU` reroute jailed/hospitalized characters. Only called when the character isn't new, jailed, or in the ICU — those three cases short-circuit to a fixed spawn point before this middleware ever fires. ### Characters:ForceStore(source) `TriggerEvent` — forces an immediate save outside the normal logout/interval cycle. ```lua plsr.Middleware:TriggerEvent('Characters:ForceStore', source) ``` Used by `pulsar_jobs`, `pulsar_businesses`, `pulsar_police` before anything that shouldn't be lost to a crash (paycheck, seizure, etc). ### Characters:Logout(source) `TriggerEvent` — fires before the character's data store is torn down. `pulsar_characters` itself hooks this to force-save. # plsr.Fetch additions (server) `pulsar_characters` extends `pulsar_core`'s `plsr.Fetch` (via `ExtendComponent`, not a new component) with character lookups — the standard way to go from a source/id/state-id to a character's `DataStore`. | Method | Params | Returns | |---|---|---| | `CharacterSource` | `(source)` | the character store for a connected player, or `nil` | | `ID` | `(characterId)` | by database row id | | `SID` | `(stateId)` | by state id (the short in-game character id) | | `CharacterData` | `(key, value)` | first online character where `key` matches `value` | | `AllCharacters` | `()` | every online character, keyed by source | | `CountCharacters` | `()` | `number` | | `GetOfflineData` | `(stateId, key)` | reads one field from an offline character's DB row directly (synchronous, awaits the query) | ```lua local char = plsr.Fetch:CharacterSource(source) local cash = char:GetData('Cash') ``` This is the same `DataStore` object documented in the `pulsar_core` doc — `GetData`/`SetData`. Writes to `"Character"`-keyed stores auto-broadcast to that player's client via `Characters:Client:SetData` (except `HP`/`Armor`). # plsr.Reputation Per-character reputation levels (weed dealing, pawn shop standing, etc) — a generic system any resource can register its own reputation type into. ### Create(id, label, levels, hidden?) — server Call once at startup to define a reputation type and its level thresholds. | Param | Type | Description | |---|---|---| | `id` | `string` | | | `label` | `string` | | | `levels` | `table` | array of `{ label, value }`, ascending thresholds | | `hidden` | `boolean?` | hide from the player-facing rep list | **Returns:** nothing ```lua plsr.Reputation:Create('weed', 'Weed', { { label = 'Rank 1', value = 3000 }, { label = 'Rank 2', value = 6000 }, { label = 'Rank 3', value = 12000 }, }, true) ``` ### GetLevel(source?, id) / HasLevel(source?, id, level) | Param | Type | Description | |---|---|---| | `source` | `number?` | server-side only; client reads its own character | | `id` | `string` | reputation type | | `level` | `number` | `HasLevel` only | **Returns:** `GetLevel` → `number`; `HasLevel` → `boolean` ```lua plsr.Reputation:GetLevel(source, 'weed') -- server, needs source plsr.Reputation:GetLevel('weed') -- client, own character only plsr.Reputation:HasLevel(source, 'weed', 2) ``` ### Modify.Add(source, id, amount) / Modify.Remove(source, id, amount) — server | Param | Type | Description | |---|---|---| | `source` | `number` | | | `id` | `string` | reputation type | | `amount` | `number` | | **Returns:** nothing ```lua plsr.Reputation.Modify:Add(source, 'weed', 500) plsr.Reputation.Modify:Remove(source, 'weed', 500) ``` ### View(source) / ViewList(source, list) — server | Param | Type | Description | |---|---|---| | `source` | `number` | | | `list` | `table` | `ViewList` only — `{ [id] = true }` allowlist | **Returns:** `View` → every non-hidden reputation the character has progress in, each with `current`/`next` level data for a progress-bar style UI; `ViewList` → same, filtered to `list` # plsr.Spawn (client) Overrides `pulsar_core`'s default no-op `plsr.Spawn` — see that doc's `Registering your own component` section for why this pattern exists. | Method | Params | Effect | |---|---|---| | `InitCamera` | `()` | sets up the character-creation/select scene ped and camera | | `Init` | `()` | fades in and shows the character-select NUI | This file also defines `SpawnToWorld`, but `pulsar_ped` (always loaded alongside this resource) extends the same component and replaces it. See the `pulsar_ped` doc for the version that actually runs. Not something you'd normally call directly — the NUI flow drives it. Relevant mainly if you're replacing character creation/select entirely. # Commands Admin/staff chat commands, all gated by staff/admin permission level: `/logout`, `/logoutsid `, `/logoutsource `, `/logoutall`, `/addrep`, `/remrep`, `/getrep`, `/phoneperm`, `/laptopperm`