Server exports

SIM

Server exports for SIM cards, the GhostNet card and Anon reputation.

How the two SIM slots, SIM cards and the GhostNet card work is described in SIM cards.

#SIM cards

The write exports need Config.Sim.Enabled = true. With SIM cards off, GetSimOwner, GetPlayerFromNumber and GetSimsByIdentifier still answer from the phone record, and SearchSims returns an empty list.

A SIM is addressed by its ICCID, the serial number of the card. You get it from IssueSim and from the lookups.

RegisterSim, TransferSim, BlockSim, UnblockSim and ReissueSim take an optional last argument actor: a name for the SIM's history, such as 'police'. Without it your resource name is used.

#GetSimOwner

Returns who a number belongs to.

Also available as: GetSimByNumber

lua---@class SimRecord
---@field iccid string
---@field number string
---@field kind 'physical'|'esim'
---@field status 'active'|'blocked'|'lost'|'inactive'
---@field registered boolean
---@field owner { identifier: string, firstname: string, lastname: string, dob: string }|nil nil on a prepaid SIM
---@field boughtAt integer unix seconds
---@field boughtBy { identifier: string, name: string }|nil
---@field shop { id: integer, name: string }|nil
---@field insertedBy string|nil identifier of whose phone it is in now

---@param number string
---@return SimRecord|nil sim
exports['fx-phone']:GetSimOwner(number)
lualocal sim = exports['fx-phone']:GetSimOwner('5551234')
if sim and sim.owner then print(sim.owner.firstname, sim.owner.lastname) end

#GetPlayerFromNumber

Returns the character behind a number: the registered owner, or whoever has the SIM in their phone.

Also available as: GetNumberOwner

lua---@param number string
---@return string|nil identifier
exports['fx-phone']:GetPlayerFromNumber(number)
lualocal identifier = exports['fx-phone']:GetPlayerFromNumber('5551234')
  • A registered SIM that was lent to someone still returns its owner. To find whose phone a number rings in right now, use GetSourceFromNumber or GetIdentifierFromNumber: see Players and numbers.

#GetSimsByIdentifier

Returns every SIM of a character.

lua---@param identifier string
---@return SimRecord[] sims
exports['fx-phone']:GetSimsByIdentifier(identifier)
lualocal sims = exports['fx-phone']:GetSimsByIdentifier(citizenid)

#SearchSims

Searches SIMs.

lua---@param filter? { number?: string, name?: string, identifier?: string, status?: string, limit?: integer }
---@return SimRecord[] sims at most 50 rows
exports['fx-phone']:SearchSims(filter)
lualocal found = exports['fx-phone']:SearchSims({ name = 'Kaya', status = 'active' })
  • number and name match parts of the value.

#IssueSim

Creates a SIM.

lua---@class IssueSimOptions
---@field identifier? string the owner; required for a registered SIM and for an eSIM
---@field registered? boolean true (default): the owner's name is on it. false: prepaid
---@field kind? 'physical'|'esim' default 'physical'
---@field number? string a free number is picked when left out
---@field shopName? string kept in the SIM's record
---@field boughtBy? string identifier of the buyer, kept in the SIM's record

---@param opts IssueSimOptions
---@return { iccid: string, number: string, metadata: table }|nil sim
---@return string|nil err
exports['fx-phone']:IssueSim(opts)
lualocal sim, err = exports['fx-phone']:IssueSim({ identifier = citizenid, registered = true, kind = 'physical' })
if sim then exports.ox_inventory:AddItem(source, 'sim_card', 1, sim.metadata) end
  • A physical SIM is only a record: your script gives the player the item, with sim.metadata on it. The metadata carries the ICCID and number and, with Config.Sim.ItemText = true, the item's label and description.
  • An eSIM needs no item and switches on at once in a free slot of the owner's phone. With both slots taken the eSIM is created but stays switched off.
  • Errors: disabled (SIM cards are off), denied (prepaid SIMs are off in Config.Sim.AllowUnregistered), invalid (no identifier where one is needed), exists (the number is taken).
  • Fires the server event fx-phone:server:simIssued. See Server events.

#RegisterSim

Puts a character's name on a prepaid SIM.

lua---@param iccid string
---@param identifier string
---@param actor? string
---@return boolean ok
---@return string|nil err
exports['fx-phone']:RegisterSim(iccid, identifier, actor)
lualocal ok, err = exports['fx-phone']:RegisterSim(iccid, citizenid)
  • limit when the character already has Config.Sim.MaxPerPlayer SIMs.

#TransferSim

Moves a registered SIM to another character.

lua---@param iccid string
---@param identifier string the new owner
---@param actor? string
---@return boolean ok
---@return string|nil err
exports['fx-phone']:TransferSim(iccid, identifier, actor)
luaexports['fx-phone']:TransferSim(iccid, newCitizenid)

#BlockSim

Blocks a SIM. It stays in the phone but gives no service; only emergency numbers work.

lua---@param iccid string
---@param reason? string
---@param actor? string
---@return boolean ok
---@return string|nil err
exports['fx-phone']:BlockSim(iccid, reason, actor)
luaexports['fx-phone']:BlockSim(iccid, 'Unpaid bills')
  • Returns true when the SIM is already blocked, and false, 'invalid' for a SIM that is lost.
  • Fires the server event fx-phone:server:simBlocked.

#UnblockSim

Lifts a block.

lua---@param iccid string
---@param actor? string
---@return boolean ok
---@return string|nil err
exports['fx-phone']:UnblockSim(iccid, actor)
luaexports['fx-phone']:UnblockSim(iccid)

#ReissueSim

Replaces a lost card. The old card stops working and a new physical card is created with the same number.

lua---@param iccid string
---@param actor? string
---@return { iccid: string, number: string, metadata: table }|nil sim
---@return string|nil err
exports['fx-phone']:ReissueSim(iccid, actor)
lualocal sim = exports['fx-phone']:ReissueSim(iccid)
if sim then exports.ox_inventory:AddItem(source, 'sim_card', 1, sim.metadata) end
  • Only for registered SIMs (not_owner otherwise). Giving the player the new item is up to you.

#useSimCard

The item hook ox_inventory calls when a SIM card, GhostNet card or power bank item is used. Do not call it from your own scripts; name it in the item definition.

lua---@param event string ox_inventory item event; only 'usingItem' is handled
---@param item table the ox_inventory item definition
---@param inventory table the player's ox_inventory inventory
---@param slot integer
---@return false|nil keep false keeps ox_inventory from consuming the item
exports['fx-phone']:useSimCard(event, item, inventory, slot)
lua['sim_card'] = { label = 'SIM Card', weight = 10, stack = false, server = { export = 'fx-phone.useSimCard' } },
  • The phone removes or keeps the item itself, so the export always answers false for usingItem. The full item definitions are in Item setup.

#GhostNet card

#HasSecondSim

Returns whether a player's GhostNet card works right now: in the phone, switched on, not expired.

lua---@param src integer
---@return boolean active
exports['fx-phone']:HasSecondSim(src)
luaif not exports['fx-phone']:HasSecondSim(source) then return end

#GetSecondSim

Returns the GhostNet card in a player's phone, whichever slot it is in.

lua---@param src integer
---@return { type: 'ghost', slot: integer, line: string, carrier: string, enabled: boolean, status: string, active: boolean, activatedAt: integer, expiresAt: integer }|nil sim
exports['fx-phone']:GetSecondSim(src)
lualocal sim = exports['fx-phone']:GetSecondSim(source)

#GiveSecondSim

Puts a GhostNet card in a player's phone without the item.

lua---@param src integer
---@param days? number default Config.SecondSim.Days
---@return boolean given
exports['fx-phone']:GiveSecondSim(src, days)
luaexports['fx-phone']:GiveSecondSim(source, 7)
  • The card goes into a free SIM slot. With both slots taken by other cards nothing is given and it returns false.
  • If the phone already has a GhostNet card, Config.SecondSim.Stack decides what happens.
  • Returns false when Config.SecondSim is off.

#Anon

#GetAnonProfile

Returns a player's Anon identity.

lua---@param src integer
---@return { handle: string, xp: integer, cracks: integer, rank: integer, title: string, nextXp: integer|nil, nextTitle: string|nil, floorXp: integer }|nil profile nil when the player has not picked a handle
exports['fx-phone']:GetAnonProfile(src)
lualocal profile = exports['fx-phone']:GetAnonProfile(source)

#AddAnonXp

Gives a player Anon XP, for example as the reward of a finished job.

lua---@param src integer
---@param xp number
---@return boolean added false when the player has no handle yet
exports['fx-phone']:AddAnonXp(src, xp)
luaexports['fx-phone']:AddAnonXp(source, 15)

See Anon.