Server exports

Documents

Server exports that give, check, suspend and delete the documents shown in Kartlarim: identity cards and licences.

Kartlarim is the notebook's wallet of documents and deeds. Documents are given by other scripts: a licence office, a doctor, a stable. These exports are in apps/kartlarim/server/exports.lua.

#Rules for every Kartlarim export

  • target is a player server id (online) or a character id ('vorp:12', 'rsg:ABC12345'). A character id works when the character is offline. Then pass the name yourself (holder), because the server cannot read it.
  • Every export returns its value, or false and a reason.
  • They wait for the database. Call them from a thread or an event handler.
  • Callers: apps/kartlarim/config_server.lua > API.AllowedResources. Empty means every resource may call. See Access lists.
  • When the owner is online, the open Kartlarim page reloads and a notification is shown. It needs no signal.
Reason When
disabled Config.Kartlarim.Enabled is false
forbidden The calling resource is not on the allow list
failed The database call failed. Check that sql/install.sql ran.
invalid_arguments An argument has the wrong type or range
character_unavailable The player id has no loaded character, or the character id is malformed
invalid_type The document type is not a valid name
not_found No document with that id
database The row could not be written

#IssueDocument

Gives a document to a character.

lua---@param target integer|string player server id or character id
---@param data table document fields, see below
---@return integer|false id
---@return string numberOrReason the document number, or the reason
exports['fx-pocketbook']:IssueDocument(target, data)
lualocal id, number = exports['fx-pocketbook']:IssueDocument(source, { type = 'avci', days = 30 })
if not id then print('licence failed: ' .. number) end
Field What it does
type Required. A key of Config.Kartlarim.DocumentTypes (kimlik, avci, balikci, silah, saglik, at by default) or any other name of lowercase letters, numbers and _, up to 32 characters. A type not in the config is shown plain.
title Card title, up to 80 characters. Default: the type's label.
number Document number, up to 32 characters. Default: the type's prefix and five digits, for example AV-10014.
class Line under the name, up to 80 characters. Default: the type's class.
issuer Office that gave it, up to 120 characters. Default: the type's office.
signer Name under the signature, up to 80 characters. Default: the type's signer.
role Signer's title, up to 64 characters. Default: the type's role.
terms Conditions text, up to 400 characters. Default: the type's terms.
issued Unix time of issue. Default: now.
expires Unix time it expires.
days Days it is valid, used when expires is not given. Default: the type's days. 0 never expires.
reason One line shown under the paper, up to 160 characters.
holder Name on the document, up to 120 characters. Default: the online character's name.
extra A table kept for your own script, up to 4000 bytes as JSON. Larger tables are not saved. GetDocuments returns it.

#RevokeDocument

Deletes a document.

lua---@param id integer document id
---@return boolean|false ok
---@return string? reason
exports['fx-pocketbook']:RevokeDocument(id)
luaexports['fx-pocketbook']:RevokeDocument(42)

With Config.Kartlarim.AutoIdentity.Enabled = true, a deleted identity card is created again the next time the player opens Kartlarim. To take an identity card away, use SetDocumentStatus(id, 'hold'), or turn AutoIdentity off when an office sells identity cards.

#SetDocumentStatus

Marks a document valid, suspended or expired. The change is added to the document's history (last 20 entries).

lua---@param id integer document id
---@param status string 'ok', 'hold' or 'expired'
---@param reason? string one line shown under the paper, up to 160 characters
---@return boolean|false ok
---@return string? reason
exports['fx-pocketbook']:SetDocumentStatus(id, status, reason)
luaexports['fx-pocketbook']:SetDocumentStatus(42, 'hold', 'Suspended by the court until 12 May.')
Status Also accepted Meaning
ok gecerli Valid again
hold askida Suspended
expired suresi doldu Expired

#GetDocuments

Returns a character's documents (up to 60), optionally of one type.

lua---@param target integer|string
---@param type? string
---@return table|false list
exports['fx-pocketbook']:GetDocuments(target, type)
luafor _, doc in ipairs(exports['fx-pocketbook']:GetDocuments(source, 'avci') or {}) do
    print(doc.number, doc.state, doc.expiresAt)
end

Each row:

Field What it is
id Document id
type Type name
number Document number
holder Name on it
issuedAt Unix time of issue
expiresAt Unix time it expires, 0 for never
state 'ok', 'hold' or 'expired'
extra The extra table you gave to IssueDocument, or nil

#HasValidDocument

Returns whether a character holds a document of this type that is not suspended and not expired.

lua---@param target integer|string
---@param type string
---@return boolean valid
exports['fx-pocketbook']:HasValidDocument(target, type)
luaif not exports['fx-pocketbook']:HasValidDocument(source, 'silah') then
    return TriggerClientEvent('my-gunstore:noLicence', source)
end
  • On a wrong argument it returns false, 'invalid_arguments'.