Server exports

Custom app actions

Server exports that give your custom app its server actions, remove them and check a player again before a change.

Your app's page calls Pocketbook.request('action', payload). The notebook sends it to the server and runs the action your resource registered with these exports. See Custom apps overview for the whole flow.

They work only while Config.CustomApps.Enabled is true.

#RegisterApplication

Registers the server actions of your app. The calling resource becomes the owner.

lua---@param id string the same id you gave AddCustomApp
---@param actions table { [name] = function(source, character, payload) ... end }
---@return boolean ok
---@return string? reason
exports['fx-pocketbook']:RegisterApplication(id, actions)
lualocal function register()
    exports['fx-pocketbook']:RegisterApplication('ranch_ledger', {
        balance = function(source, character, payload)
            -- check ownership, job and permissions here, on the server
            return { ok = true, balance = 0 }
        end,
    })
end
AddEventHandler('onResourceStart', function(resource)
    if resource == GetCurrentResourceName() or resource == 'fx-pocketbook' then register() end
end)
Rule Value
id Same rules as AddCustomApp: lowercase letters, numbers and _, starts with a letter, up to 32 characters, not a built-in id, not registered already.
Action names Start with a letter, letters and numbers only, up to 32 characters.
Number of actions 1 to 32.

An action receives:

Argument What it is
source The player who made the request.
character { id, framework, name, job, grade, onDuty? }. id is 'vorp:...' or 'rsg:...'. Comes from the framework, not from the page.
payload The table the page sent. Treat every value in it as untrusted.

An action must return a table with a boolean ok. Anything else reaches the page as ok = false with an error text.

  • The table is sent back to the page. It must stay within the same size limits as a message: 32 KiB as JSON, 8 levels, 128 keys per table, strings up to 16384 bytes.
  • An optional audit table is written to the server log and removed before the result reaches the page. Keep secrets and long text out of it.
  • Logs go to PocketServerConfig.Apps['<your id>'].Logs in the core's config_server.lua when you add it, in the same shape as a built-in app. Without it the core log settings apply.
  • If your resource restarts while an action is running, the page gets ok = false (application restarted) instead of the old result. A change your handler already made is not undone.
  • The core does not check signal for custom apps. Call [CanUseOnline](/phone/docs/pocketbook/exports/server/notifications-and-signal) when the action needs a line.
  • With Config.CustomApps.RequireInstall = true, the player must install the app from the App Store first. Until then every action answers that the app is not installed.
  • Registering grants no money or inventory rights.

#UnregisterApplication

Removes your app's server actions.

lua---@param id string
---@return boolean removed false when the app is not yours
exports['fx-pocketbook']:UnregisterApplication(id)
luaexports['fx-pocketbook']:UnregisterApplication('ranch_ledger')

Actions are also removed when the owning resource stops.

#ValidateApplicationPlayer

Checks again, right before your action changes something, that the player still has the same character, still may use the notebook (item and access rules) and that your app is still the same registration.

lua---@param id string your app id
---@param src integer
---@param characterId string the character.id your action received
---@return boolean allowed
---@return string? reason
exports['fx-pocketbook']:ValidateApplicationPlayer(id, src, characterId)
luabalance = function(source, character, payload)
    local row = MySQL.single.await('SELECT balance FROM ranch_ledgers WHERE owner = ?', { character.id })
    local allowed, reason = exports['fx-pocketbook']:ValidateApplicationPlayer('ranch_ledger', source, character.id)
    if not allowed then return { ok = false, error = reason } end
    return { ok = true, balance = row and row.balance or 0 }
end,
  • Only the resource that registered id may call it.
  • It is a check at one moment, not a lock and not a money or inventory transaction. Your own checks (ownership, job, a nonce for writes) still apply.