PhoneHub + Pulse docs

PhoneHub + Pulse Phone — installation guide

Integrated edition 1.4.0 · ZeroDev

This edition combines Pulse Phone, the PhoneHub building, the custom PhoneHub OS, 3D handset kiosk, repair workbench and staff stock/delivery system. It is a separate product from the phone-only edition. Install the phone, map and all four canopy companion resources together. Do not run two copies of phone or two versions of the PhoneHub map.

1. Before installation

  • Back up your existing phone resource, map resource, configuration and database.
  • Use OneSync and GTA game build 2699 or newer.
  • Start your database, framework, inventory and voice resources first.
  • Keep the resource names exactly phone and zerodev_phonehub_mlo.
  • Remove previous PhoneHub resources from the active resources directory and remove duplicate ensure lines. Store backups outside that directory.
  • Keep any other map replacing the same Portola Drive building disabled.
  • Close FiveM completely and stop the server before replacing map files. Start the server, then launch FiveM again. Disconnect clients before replacing or restarting this streamed MLO. A connected client can retain the map even when away from the building; hot-restarting it can crash that client.

This package does not include a server licence key, framework, inventory or paid third-party scripts. After Keymaster processing, the server key must belong to the account entitled to this new combined asset. An entitlement to the old phone-only edition does not grant this new edition.

2. Copy the resources

Copy resources/[phone]/phone and resources/[maps]/zerodev_phonehub_mlo into your server resources directory. Also copy the four phonehub_canopy_* folders from resources/[maps]. Category folder names may differ; the resource names may not.

Add these lines after your existing dependencies in server.cfg:

server.cfg
ensure phone
ensure zerodev_phonehub_mlo
ensure phonehub_canopy_glass_assets_139
ensure phonehub_canopy_glass
ensure phonehub_canopy_floor_139
ensure phonehub_canopy_seal_139

Do not copy an old phone engine or UI into the new package. On an upgrade, migrate the settings you need into the new configuration files. Retain your database, resource KVP storage, media and ownermedia directories. The new phone/config/phonehub_business.lua includes delivery settings absent from the phone-only edition.

The configured shop counter is -749.541, -216.952224, 36.256562, heading 210. The store location is already configured in the clean integrated edition. Press the PhoneHub key (E by default), or use /phonehub, at the floor kiosk, a repair bench, the service counter or the rooftop control point to open the PhoneHub terminal. The kiosk opens Shop and a repair bench opens Repair. The key can be changed in FiveM key bindings. The command requires the same proximity as the key; staff actions still require server permission.

3. Framework, inventory and other scripts

Begin with Config.Framework = 'auto' and the automatic provider settings in phone/config/config.lua. The phone's startup health report identifies the actual providers it selected. Check that report before making purchases.

Framework Setup
ESX Legacy Start es_extended and the inventory before phone. Import setup/phonehub_esx_jobs.sql; this adds missing job grades without assigning a player.
QBCore Add the supplied setup/phonehub_qb_job.lua job entry to your core's shared jobs table. Register phone items using the phone's item guide.
Qbox Register the same job/grades through your installed Qbox job configuration or supported job registration API. Use ox_inventory item definitions.
ox_core / vRP Configure the phone's existing framework adapter and a job provider that returns the PhoneHub job and numeric grade. Use ACE-controlled building access if your job system does not expose them.
Standalone / custom Public shopping is available through the phone's existing standalone/custom bridge. Staff access needs a configured job provider or a trusted administrator ACE.

Inventory adapters cover ox_inventory, supported framework inventory functions, and the named third-party providers listed in phone/guides/integrations.md (or the integration guide included with your phone build). Each provider needs its real item definitions and compatible API version. Missing items are reported by phone health checks; do not suppress those errors. Item setup examples ship under phone/config/items/.

The phone's editable bridges cover voice, society accounts, banking, garages, housing, dispatch and other integrations. Keep exactly one selected provider per function. Pin renamed resources through Config.ResourceNames; use Config.Providers to select a provider explicitly. Arbitrary third-party exports are not automatically compatible: implement the documented custom bridge when your script is not listed. Framework adapters and automated contract tests are not a claim that every third-party version has been tested live.

Live-tested stack for this release: ESX Legacy, ox_inventory, oxmysql and pma-voice. On another framework, run the first-run checks in section 7 before opening the store.

4. Public shop or player-owned business

Run either command in the server console:

phonehubmode public
phonehubmode business

The selected mode persists across restarts. Public mode retains normal shopping. Business mode applies persistent stock and reservations to purchases made at the PhoneHub counter. Business mode disables counter trade-ins. The same phone checkout validates prices, payments and item delivery.

Set the job name and grades in phone/config/phonehub_business.lua:

Grade Default duties
0 — trainee View business terminal, receive arrived deliveries, building controls
1 — sales Trainee duties plus supplier ordering
2 — technician Ordering/receipt and configured repair role
3 — manager All staff controls plus cancellation/refund of pending supply orders

Assign jobs with your framework's normal administration tools. Open Services → My Work → PhoneHub → Staff and account on the phone for Company management. It uses the selected framework's supported staff/society functions. The combined edition also supports durable player ownership through an in-game purchase in the Business tab or the administrator assignment command described below. All ownership prices are in-game currency amounts.

For ESX with esx_addonaccount, also import setup/phonehub_esx_society.sql before starting the account resource, then restart your server. This creates the zero-balance society_phonehub company account without replacing an existing balance. If you renamed the job, update the account suffix to match. Other banking providers need their normal company-account setup for the configured job. Verify a small deposit and withdrawal in Company before opening the business.

The operating budget is a separate internal stock-purchasing ledger. Sales add to it; supplier orders deduct from it. It is not automatically a society bank account and is not a withdrawable player cash balance.

5. Supplier orders and inventory delivery

At the service counter, press E to open the PhoneHub terminal, then Stock. Choose a product, configuration and quantity. The server calculates the supplier quote and checks the employee's grade, proximity and operating budget.

Default delivery takes 120 seconds. It remains in transit across restarts. After it arrives, an employee selects Receive delivery at the terminal. The default destination='stock' adds goods to the store stock ledger consumed by checkout, independently of the buyer's player inventory provider. Repeated receipt requests cannot add the same shipment twice. Managers can cancel an unreceived shipment for a single budget refund.

Configuration:

Lua
delivery = {
    seconds = 120,
    autoReceive = false,
    destination = 'stock',
    resource = '',
    export = '',
}

For a custom warehouse/stash, set destination='custom' and specify a server export. It receives (shipment, source) and must use shipment.id as a durable deduplication key. Return true only when every line is stored successfully. Configure your inventory's item/SKU mapping in that adapter. Custom delivery does not also add items to the internal sales ledger; connect your warehouse sale flow explicitly to avoid duplicate stock. No universal stash adapter is assumed.

An uncertain external handover is held for review, never retried blindly. After checking the destination inventory, use:

phonehubdelivery <shipment-id> delivered
phonehubdelivery <shipment-id> retry

For an uncertain customer checkout reservation, inspect the payment and inventory records before using phonehubresolve <reservation-id> returned|delivered.

6. Store controls

Press E near the service-control point or rooftop-control pedestal.

  • Space: front-door and rooftop-door locks, store lights, the lounge display, the terrace canopy (automatic in rain or snow, or open/closed), terrace heaters or airflow, terrace power and a 15-second sprinkler test.
  • Cameras: Entrance overview, Showroom overview and Service counter. Back to the terminal closes the camera; Escape exits.
  • Stock and Business: supplier orders, deliveries, takings, the sales and repair ledger, and team access.

Building controls require the PhoneHub job or the configured staff/admin ACE. Terrace public control access is configured separately in systems_config.lua. Grant phonehub.admin only to your trusted administrator principal; never to everyone. Set phoneResource='phone' in the MLO systems configuration.

Automatic doors use proximity sensors when unlocked. Their moving leaves must remain solid, including while open. Furniture, glass and lighting are authored map assets; not every decorative object has a gameplay interaction.

7. First-run acceptance

  1. Start the server and run phone:health. Confirm the expected framework, inventory, database and voice providers, and no missing required items.
  2. Join normally and visit the shop. Walk from the pavement through both entrance pairs, up/down the stairs and through the rooftop doorway with noclip disabled.
  3. Open and close the canopy. Its eight panels must remain aligned within the guide tracks at every position. Test automatic rain/snow closure separately.
  4. Open each CCTV view, switch between them and exit. The scene must be visible and normal player view/focus must return.
  5. Lock both door groups with a staff account. Check collision from both sides. Unlock and verify the proximity opening animation again.
  6. Check day/night lighting, display on/off, glass, signage, seats and all edges. Walk and drive toward/away from the building to inspect streaming transitions.
  7. Buy a phone/accessory in public mode. In business mode, check stock decrement, employee ordering, arrival/receipt, insufficient funds and unauthorized access.
  8. Restart the server and confirm the shop mode, stock and pending deliveries persist. Repeat a duplicate receipt/cancellation attempt; no duplicate goods or refund should appear. Verify multiple players see the same store state.

phonehubcheck in the client F8 console reports actual cover alignment; each panel should report alignment close to 1. It is a diagnostic, not proof that visual quality or collisions are correct. Automated checks cannot certify every camera angle or all server combinations.

8. Troubleshooting and updates

Port 30120 busy: another server instance is already running. Stop it through your txAdmin (or host panel) rather than starting a second FXServer.

Controls missing: verify both resources started, their names are unchanged, and the player is at the control point. Inspect the client F8 and server errors.

No staff access: check the configured job, numeric grade, service-counter proximity and selected job provider. Public shop mode does not grant staff rights.

Old map/old interface persists: remove duplicate resources/ensure entries. Close FiveM completely, stop the server, replace the files, then start the server and launch FiveM again. A reconnect alone can retain stale streamed assets. Do not hot-reload the MLO while a client is connected, even far from the building.

Rollback: stop these resources, restore the backed-up resource folders and configuration, then restart with your existing txAdmin. Preserve database/KVP storage unless deliberately restoring a consistent data backup.

Keep the supplied release hashes (SHA256.json) for support requests.

PhoneHub OS and ownership

Config.PhoneHubOS in phone/config/phonehub_business.lua controls this edition. ownership='both' allows in-game purchase and administrator assignment. Set 'admin' or 'purchase' to allow only one route. purchasePrice is an in-game currency amount. Administrators use phonehubowner <online player id> from the server console or with the phonehub.admin ACE. Assignment is blocked while a purchase payment is pending. An owner is stored against the framework character identifier, never a transient player source number. Ownership activates the existing durable stock and operating-budget system.

Owners add nearby staff or managers in the Business tab. These independent roles work through the framework identity bridge; they do not change a player's main job. Existing PhoneHub job roles and configured administrative access still work. Managers can order supplies, and staff can receive arrived shipments by default. Stock remains reserved until a purchase or supplier delivery is confirmed.

service='hybrid' permits both assisted and self-service checkout and repairs. 'self' permits direct service; 'staff' requires a customer-approved staff offer at this shop. The standalone product keeps its existing shopping OS.

At the floor kiosk, approach and press E. The Shop tab loads the actual protected Pulse model, with drag rotation, front/back inspection, zoom and selected finish. A price comes from the phone server. Payment requires confirmation and uses the configured inventory, money and boxed-phone delivery. A timeout is not proof of a failed charge; check the inventory and payment journal before trying again.

Customers ask for sales or repair help in the Help tab and get a queue number. Staff choose a nearby customer in the Counter tab and prepare an offer; only that customer can approve and pay. Both must remain at the same shop in the same routing bucket. Repair approval binds to the selected unique device and its quoted price. Changing device invalidates it.

For assisted repairs, the technician opens the terminal at a free repair bench, prepares the customer's repair offer, and remains there for acceptance. The bench is reserved before payment. A successful paid repair runs the assembly sequence with that player as technician; self-service uses the shop technician. The phone engine owns the device repair and recovers paid work after an interrupted server session. The client props never create or replace an inventory phone.

The Space tab, at the rooftop and counter control points, controls the canopy, climate, locks, lighting and display. Geometry, weather protection, flooring and seating from the completed MLO are retained.