Custom apps
Custom apps overview
How another resource adds its own app to the notebook: the three parts, the settings, the limits and the rules an app must follow.
All 29 built-in apps ship inside fx-pocketbook. Another resource can add its own app to the notebook's launcher without editing the core. The app lives in that resource: its page, its server code and its data.
This is the Pocketbook extension API, version 1. It is not a drop-in copy of another phone's API.
#The three parts
| Part | Where | What it does |
|---|---|---|
| Launcher entry | client, [AddCustomApp](/phone/docs/pocketbook/exports/client/custom-apps) |
Puts the app's name and icon in the launcher and says which page to load |
| Page | browser, [pocketbook.js](/phone/docs/pocketbook/custom-apps/browser-bridge) |
Your HTML, shown inside the notebook. It reads the theme and signal and sends requests. |
| Server actions | server, [RegisterApplication](/phone/docs/pocketbook/exports/server/custom-apps) |
The functions that answer the page's requests |
A request travels like this:
- The page calls
Pocketbook.request('balance', { ... }). - The notebook sends it to the server as the action
balanceof your app. - The server checks the player (character, notebook item, app installed) and calls your function with
source,characterand the payload. - Your function returns
{ ok = true, ... }or{ ok = false, error = '...' }. The page gets that table.
A full working resource is in Getting started.
#Settings
config.lua:
luaConfig.CustomApps = { Enabled = true, Maximum = 24, RequireInstall = true }
| Key | Default | What it does |
|---|---|---|
Enabled |
true |
Custom apps on or off. Off: AddCustomApp and RegisterApplication refuse every app. |
Maximum |
24 |
Custom apps that may be registered at the same time. |
RequireInstall |
true |
The player must install the app from the App Store before its server actions work. It is listed there as a custom app. false: it works without installing. |
To give your app its own log webhook, add PocketServerConfig.Apps['<your id>'].Logs in the core's config_server.lua, in the same shape as a built-in app's config_server.lua. Never put a webhook in a client or shared file.
#Your resource
luafx_version 'cerulean'
game 'rdr3'
rdr3_warning 'I acknowledge that this is a prerelease build of RedM, and I am aware my resources *will* become incompatible once RedM ships.'
dependency 'fx-pocketbook'
client_script 'client.lua'
server_script 'server.lua'
files { 'ui/index.html', 'ui/app.js', 'ui/style.css', 'ui/pocketbook.js', 'ui/icon.png' }
- List every file the page loads under
files. - Do not set a
ui_pagefor the app. The notebook makes the frame and owns the focus. - Copy
sdk/pocketbook.jsfrom fx-pocketbook into your page folder and load it before your own script. It needs nothing from the internet. - Start your resource after
fx-pocketbook.
#Restarts
- When your resource stops, its launcher entry, page and server actions are removed.
- When fx-pocketbook restarts, it forgets every custom app. Register again:
- client: on your own resource start and on [
fx-pocketbook:ready](/phone/docs/pocketbook/events/client-events), - server: on
onResourceStartfor your resource and forfx-pocketbook. - Registering an id that is already registered returns
falseand keeps the first one. Never remove another resource's app when your registration fails.
#Limits
| What | Limit |
|---|---|
| App id | Lowercase letters, numbers and _, starts with a letter, up to 32 characters, not a built-in id |
| App name | Up to 64 bytes |
| Server actions per app | 1 to 32; names of letters and numbers, starting with a letter, up to 32 characters |
| Payload, result and messages | 32 KiB as JSON, 8 levels deep, 128 keys per table, strings up to 16384 bytes |
| Requests waiting in one page | 4 |
| Request timeout in the page | 15 seconds |
| Requests per player | One at a time for the whole notebook, at least 250 ms apart |
#Rules your app must follow
- Decide everything on the server.
sourceandcharactercome from the core; never take a player id, character id, price, job or permission from the payload. - Check your own rules (ownership, job, grade) in every action. Registering an app gives it no money or inventory rights.
- After an awaited query, and right before a change, call [
ValidateApplicationPlayer](/phone/docs/pocketbook/exports/server/custom-apps) and your own checks again. - Make writes safe to repeat: send a stable nonce from the page and an expected revision. A timeout does not mean the change failed. Reuse the same nonce and read the saved result before you offer a retry, above all for money and items.
- Call [
CanUseOnline](/phone/docs/pocketbook/exports/server/notifications-and-signal) when an action needs a telegraph line. The core does not check it for you. - Put text on the page with
textContentor escaped templates, not raw HTML. - Wait for the first
onContextbefore you send requests. Theme and signal can change while the page is open; update colours without resetting a form. - The page is destroyed when the player leaves the app. Remove your listeners and timers, keep data on the server, and do not play world audio inside the page.
- Filter
customAppOpenedandcustomAppClosedby your own id. - Test: players without permission, copied ids, two saves at once, a character switch or disconnect, the notebook item removed, a resource restart during an action, a lost response, no signal and a small screen.