Installation

Required stack: ox_lib + oxmysql + one supported framework (QBox, QBCore or ESX). Framework and inventory detection is automatic — plug and play.

1. Load order

cfg

ensure oxmysql
ensure ox_lib
ensure ox_inventory     # optional — falls back to the framework inventory
ensure qbx_core         # or es_extended / qb-core
ensure orb-phone

2. Database — automatic

You don't need to run any SQL by hand. On startup the resource reads sql/install.sql and creates/verifies every orb_* table (idempotent CREATE TABLE IF NOT EXISTS — existing data is never touched). You'll see:

[orb-phone] database ready (N tables verified)

Upgrades are automatic too: new tables and new columns are added on their own (information_schema checks + ALTER ADD COLUMN only when missing). Non-destructive — no DROP, no data loss.

3. Register the phone item

The item name is configurable (Config.PhoneItem, default phone).

ox_inventory — add to ox_inventory/data/items.lua:

lua

['phone'] = {
    label = 'Phone', weight = 190, stack = false, close = true, consume = 0,
    server = { export = 'orb-phone.usePhone' },
    client = { export = 'orb-phone.usePhone', image = 'phone.png' },
},

qb-inventory (QBCore) — the default phone item already exists in qb-core/shared/items.lua; the resource registers the use handler itself (CreateUseableItem). unique = true recommended.

ESX native inventory — ensure the item exists in your items table:

sql

INSERT INTO items (name, label, weight) VALUES ('phone', 'Phone', 1)
ON DUPLICATE KEY UPDATE label = label;

The native inventory has no per-item metadata, so the number is anchored to the character identifier (NPWD style). The item is still required to open the phone.

Only one handler per item: if another phone script (lb_phone, qb-phone, npwd) already registers `phone`, disable it.

4. Build the NUI

bash

cd resources/[theorb]/orb-phone/ui
npm install
npm run build

The bundle ends up in ui/dist/ and is what the resource serves. Rebuild after any frontend change.

5. Camera (optional)

ensure screenshot-basic before orb-phone, then set an upload webhook:

cfg

set orb-phone:camera_webhook "https://discord.com/api/webhooks/..."

Without it, Camera works as a gallery viewer but can't capture new photos.

6. Test & smoke checks

01/giveitem phone 1 and use the item — the first use generates a unique XXX-XXX number.
02Press F1 to open/close (rebindable in FiveM → Settings → Key Bindings).

Console signals: [orb-phone] Bridge ready: qbx (server) and [orb-phone] client ready (locale=en) (F8).

Next: Configuration.