## Reference at a glance | plsr.Phone | Side | Covers | |---|---|---| | `UpdateJobData` | server | push job data + permission grants to a client | | `Notification.Add / AddWithId / Update / RemoveById` | server | push a phone notification | | `Email.Send` | server | send an in-game email to a player | | `GeneratePhoneNumber` | server | mint a unique `XXX-XXX-XXXX` number | | `IsAppUnlocked` | server + client | check the `restricted` gate on an app | | `OpenPayphone / Close` | client | open/force-close the phone UI | | `IsAppUsable` | client | `IsAppUnlocked` + actually installed | | `Permissions.Load / HasPermission` | client | per-app boolean permission grants | Other extension points, covered below: `restricted` app gating, the `Phone:Spawning` middleware hook, and the item→force-install pattern. # plsr.Phone (server) ### UpdateJobData(source, returnValues?) Pushes the caller's job data + job-scoped permission grants to their client (`Phone:Client:SetDataMulti`). | Param | Type | Description | |---|---|---| | `source` | `number` | server id | | `returnValues` | `boolean?` | if `true`, return the payload instead of sending it | **Returns:** nothing, unless `returnValues` is `true` — then `{ charJobPerms, jobData }` ```lua plsr.Phone:UpdateJobData(source) local data = plsr.Phone:UpdateJobData(source, true) -- { charJobPerms, jobData } ``` ### Notification.Add(source, title, description, time, duration, app, actions?, notifData?) Pushes a toast notification into the phone's notification center. | Param | Type | Description | |---|---|---| | `source` | `number` | server id | | `title` | `string` | notification title | | `description` | `string` | notification body | | `time` | `number` | unix seconds, usually `os.time()` | | `duration` | `number` | ms shown as a live toast; still logged to the notification center after | | `app` | `string` | which app icon/name it's attributed to (doesn't have to be installed) | | `actions` | `table?` | e.g. `{ view = "history/123" }`, a deep-link route opened if the player taps it | | `notifData` | `any?` | extra payload passed through to the client event | **Returns:** nothing ```lua plsr.Phone.Notification:Add( source, 'DigiKey Issued', "You've been given a new DigiKey", os.time(), 6000, 'homemanage', { view = '' } ) ``` Used by 28+ files outside `pulsar_phone` (`pulsar_labor`, `pulsar_finance`, `pulsar_inventory`, and more) — the standard way any resource notifies a player. ### Notification.AddWithId(source, id, title, description, time, duration, app, actions?, notifData?) Same as `Add`, tagged with a caller-chosen `id` for later `Update`/`RemoveById`. | Param | Type | Description | |---|---|---| | `source` | `number` | server id | | `id` | `string` | your own key; pass the same value to `Update`/`RemoveById` | | `title` | `string` | notification title | | `description` | `string` | notification body | | `time` | `number` | unix seconds, usually `os.time()` | | `duration` | `number` | ms shown as a live toast; still logged to the notification center after | | `app` | `string` | which app icon/name it's attributed to (doesn't have to be installed) | | `actions` | `table?` | e.g. `{ view = "history/123" }`, a deep-link route opened if the player taps it | | `notifData` | `any?` | extra payload passed through to the client event | **Returns:** nothing ```lua plsr.Phone.Notification:AddWithId(source, 'active-call', 'Incoming Call', callerName, os.time(), -1, 'phone') ``` ### Notification.Update(source, id, title, description) | Param | Type | Description | |---|---|---| | `source` | `number` | server id | | `id` | `string` | the id passed to the original `AddWithId` | | `title` | `string` | replaces the existing title | | `description` | `string` | replaces the existing description | **Returns:** nothing ```lua plsr.Phone.Notification:Update(source, 'active-call', 'Incoming Call', 'Now 00:42') ``` ### Notification.RemoveById(source, id) | Param | Type | Description | |---|---|---| | `source` | `number` | server id | | `id` | `string` | the id passed to the original `AddWithId` | **Returns:** nothing ```lua plsr.Phone.Notification:RemoveById(source, 'active-call') ``` For a ticking task-progress counter (e.g. `"Scrap Vehicles - 3/15"`), use a fixed `id` with `AddWithId` → `Update` per step → `RemoveById` on completion — this is `plsr.Labor.Offers:Start/Update`'s pattern. If your job/task tracking otherwise looks like Labor's, use `plsr.Labor` directly instead of reimplementing it. ### GeneratePhoneNumber() Mints a fresh `XXX-XXX-XXXX` number, guaranteed unique against both the live in-memory cache and `characters.phone` in the DB. **Returns:** `string` — the generated number ```lua local number = plsr.Phone:GeneratePhoneNumber() ``` ### IsAppUnlocked(source, app) Server-side restriction check — walks the app's `restricted` table (see [App registry & restrictions](#app-registry--restrictions)). | Param | Type | Description | |---|---|---| | `source` | `number` | server id | | `app` | `string` | app name from the registry, e.g. `'redline'` | **Returns:** `boolean` — `true` if unlocked, or if the app has no `restricted` field at all ```lua if plsr.Phone:IsAppUnlocked(source, 'redline') then -- ... end ``` # plsr.Phone (client) ### OpenPayphone() Opens the phone UI in payphone/limited mode — locked to the dialer only. Used by the payphone prop targeting handler. Call it yourself for a similar kiosk-style "phone, but limited" interaction. **Returns:** nothing ### Close(forced?, doJankyStuff?) Closes the phone UI. | Param | Type | Description | |---|---|---| | `forced` | `boolean?` | bypass normal close-blocking state | | `doJankyStuff` | `boolean?` | internal client-visual cleanup flag; leave unset unless matching a specific existing call site | **Returns:** nothing ```lua plsr.Phone:Close(true) -- force-close: call end, character death, PHONE state stripped mid-session ``` ### IsAppUnlocked(app) / IsAppUsable(app) Client mirrors of the server check. `IsAppUsable` also requires the app to be installed. | Param | Type | Description | |---|---|---| | `app` | `string` | app name from the registry, e.g. `'redline'` | **Returns:** `boolean` ```lua if plsr.Phone:IsAppUsable('redline') then -- ... end ``` ### Permissions.Load(perms) Overwrites the client's cached permission table. Called internally on spawn — you shouldn't need to call this yourself. | Param | Type | Description | |---|---|---| | `perms` | `table` | `{ [app] = { [permission] = boolean } }` | **Returns:** nothing ### Permissions.HasPermission(app, permission) | Param | Type | Description | |---|---|---| | `app` | `string` | app name | | `permission` | `string` | permission key within that app's grants | **Returns:** `boolean` ```lua if plsr.Phone.Permissions:HasPermission('redline', 'create') then -- show the "create race" button end ``` # App registry & restrictions Every installable app is one entry in `server/data.lua`'s `_appData`, copied into the global `PHONE_APPS` on boot and sent to client + NUI verbatim. ```lua { name = 'chopper', storeLabel = 'Chopper', label = 'Chopper', icon = 'screwdriver-wrench', color = '#8800c7', params = '', canUninstall = true, store = true, unread = 0, restricted = { state = 'ACCESS_CHOPPER' }, internal = { { app = 'view', params = ':id' } }, } ``` | Field | Meaning | |---|---| | `canUninstall` | `false` for the 6 core apps — always installed, never removable | | `store` | Whether it's listed in the App Store browse tab (`comanager` is `false` — installed programmatically, not browsed to) | | `restricted` | Optional gate — see below | | `icon` | Plain Font Awesome Solid name, or `[style, name]` — only the name half is used either way | `restricted` shapes supported by `plsr.Phone:IsAppUnlocked`: ```lua restricted = { job = { [jobId] = minGradeLevel } } -- any one matching job satisfies it restricted = { state = 'STATE_NAME' } -- char:GetData('States') must contain this ``` `job`/`state` are the only shapes exercised by real data (`chopper`→`ACCESS_CHOPPER`, `redline`→`RACE_DONGLE`, `blueline`→`{ police = 1 }`, `dyn8`→`{ realestate = 1 }`). `jobPermission`, `phonePermission`, `reputation` are implemented but unused. Enforced in 3 places independently: Store browse list, install request (`Check` and `Do`), post-install usability. ### Granting a restricted app via an item `chopper`/`redline`'s real pattern — pair `plsr.Inventory.Items:RegisterUse` with `plsr.Phone.Store.Install:Do(name, apps, "force")` to grant the state and install in the same breath (bypasses `IsAppUnlocked`, which is why it has to happen together): ```lua plsr.Inventory.Items:RegisterUse('chopping_invite', 'LSUNDG', function(source, item, itemData) local char = plsr.Fetch:CharacterSource(source) if char and not hasValue(char:GetData('States') or {}, 'ACCESS_CHOPPER') then if plsr.Inventory.Items:RemoveSlot(item.Owner, item.Name, 1, item.Slot, 1) then local states = char:GetData('States') or {} table.insert(states, 'ACCESS_CHOPPER') char:SetData('States', states) char:SetData('Apps', plsr.Phone.Store.Install:Do('chopper', char:GetData('Apps'), 'force')) end end end) ``` # Phone:Spawning middleware Extension point for injecting a per-app payload on every spawn (and `Phone:UIReset`). Register with `plsr.Middleware:Add`; return `{ type, data }` entries, merged into the same `Phone:Client:SetDataMulti` push. ```lua plsr.Middleware:Add('Phone:Spawning', function(source, char) return { { type = 'MyThing', data = GetMyThingFor(char) }, } end) ``` Real examples: `comanager` injects `NamedJobPermissions`/`externalJobs`; `blueline`/`redline` push their track catalogs this way instead of a callback. # Payphone / limited mode 11 payphone prop models are targetable in `client/main.lua`. Interacting calls `plsr.Phone:OpenPayphone()` — navigation locks to the dialer until close. # Chat commands | Command | Level | Purpose | |---|---|---| | `/resetphonepos` | Everyone | Resets phone screen position | | `/clearalias` | Admin | Clears a target's alias for a given app | | `/clearprofile` | Admin | Clears (and archives) a target's profile for a given app | | `/ctwitter` | Staff | Clears all tweets, optionally scoped to one SID | | `/twitteraccount` | Staff | Looks up the owner of a Twitter handle, including deleted characters | | `/govtweet` | Admin | Posts a tweet as a "government"-flagged account | | `/reloadtracks` / `/reloadpdtracks` | Admin | Reloads Redline / Blueline race track data | | `/raceinvite` | Admin | Mints `event_invite` items for a Redline event | # Apps What each app gives another resource to hook into: states/permissions to check, notifications sent, callbacks exposed. The 6 core apps (phone, messages, contacts, store, settings, email) are always installed and have no `restricted` gate. ## Phone (dialer) Calls route through `plsr.VOIP.Phone:SetCall`. A call requires the target to hold the `PHONE` state (app open/active), or it fails as "not online." `decryptable` on a call record is `true` if either party holds `PHONE_VPN` (granted by the `vpn` item). `CreateCall`'s `limited`/`anonymous` fields are hardcoded `false` for direct player-to-player calls — caller-ID blocking is ignored server-side. Business calls (`MakeBizCall`) respect it correctly. ## Email Same idea as `Notification:Add`, for the Email app — also what the `/email` admin command calls. | Param | Type | Description | |---|---|---| | `serverId` | `number` | target's current server id (not SID) | | `sender` | `string` | the "from" address shown, e.g. `"scaryman@something.net"` — not validated as a real profile | | `time` | `number` | unix seconds | | `subject` | `string` | subject line | | `body` | `string` | email body | | `flags` | `table?` | json-encoded as-is, app-defined | | `expires` | `number?` | unix timestamp; the mail auto-excludes itself from `Phone:Spawning`'s inbox load once past this, and is eligible for the player's own `Phone:Email:DeleteExpired` sweep | **Returns:** nothing ```lua plsr.Phone.Email:Send(source, 'dmv@lspd.gov', os.time(), 'License Suspended', 'Your license has been suspended.') ``` ## Media Backed by `plsr.Photos` (registered in `server/component.lua`, not this app): `Photos:Create(source, photo)`, `Photos:Fetch(source)`, `Photos:Delete(source, id)`. ## Crypto Thin wrapper over `plsr.Crypto.Exchange`/`plsr.Crypto.Coin` — see that component if you need to create a coin or move balances; this app doesn't own the logic. ## Chopper `restricted = { state = 'ACCESS_CHOPPER' }`. See [Granting a restricted app via an item](#granting-a-restricted-app-via-an-item) above — that's this app's exact code. No further server logic beyond the install gate. The actual chop-shop mechanic lives elsewhere (`pulsar_robbery` or a dedicated resource) — don't look here for it. ## Dyn8 (Dynasty 8) `restricted = { job = { realestate = 1 } }`. Search-only; buy/sell transactions live in `pulsar_properties`. ## Garage Thin wrapper: `Phone:Garage:GetCars` → `plsr.Vehicles.Owned:GetAll`, `Phone:Garage:TrackVehicle` → `plsr.Vehicles.Owned:Track`. Call those `plsr.Vehicles` methods directly if you need them outside the phone context. ## Loans / Bank (Fleeca) Neither has a `server/apps/*.lua` in `pulsar_phone` at all — both call `pulsar_finance`'s own callbacks directly (`Loans:GetLoans`, `Banking:GetAccounts`, `Billing:CreateBill`, etc). If you're integrating with loans or banking, go to `pulsar_finance`, not here. ## Documents Cross-character document sharing, 3 modes via `data.type`: `1` send a copy, `2` live reference (owner edits propagate), `3` same as `2` plus `Phone:Documents:Sign`. ## Twitter (Spammer) In-memory only, wiped on restart, unbounded growth (`/ctwitter` is the only cleanup). Don't build persistent features against this feed. ## Adverts In-memory, auto-cleaned on disconnect. Same caveat as Twitter — nothing persists. ## Labor (Jobs) Thin wrapper over `plsr.Labor` — use that component directly for anything beyond what the phone UI needs. See [Pattern: live task-progress notifications](#pattern-live-task-progress-notifications) above for its reusable `Offers:Start/Update` idiom. Real anti-double-dip enforcement lives here, not in `plsr.Labor`: starting/joining a labor job while on-duty `police`/`ems` gets you **dropped from the server**, not just blocked. ## Blueline (Trials) `restricted = { job = { police = 1 } }`. Requires the `PD_MANAGE_TRIALS` job permission to `CreateRace`. ## Redline `restricted = { state = 'RACE_DONGLE' }`. Two things worth knowing if you're touching adjacent systems: * Starting a race calls `plsr.Robbery:TriggerPDAlert(...)` at the starting checkpoint ("10-94 — Illegal Street Racing") — intentional, not a bug, if you're wondering why PD gets pinged. * Joining requires an accepted invite (`Phone:Redline:SendInvite/AcceptInvite`), unlike Blueline's open join. ## Comanager (BizWiz) Not store-installable — attached automatically alongside any job outside `config.ProtectedJobs`. Its `_jobPerms` table (~50 flags: `JOB_MANAGEMENT`, `BANK_ACCOUNT_*`, `dealership_stock`, etc), pushed as `NamedJobPermissions` via `Phone:Spawning`, is the source of truth for what a job grade's `Permissions` fields mean everywhere in the framework. Add new gated actions here first. `DisbandCompany` is a registered callback that unconditionally returns `{ success = false }` — disabled, not unimplemented. ## Homemanage (Properties) Thin wrapper over `plsr.Properties.Keys:Give/Take` and `plsr.Properties.Utils:ToggleLock` — use those directly if you need DigiKey logic outside the phone UI.