Installation Guide

Step-by-step setup for oxide-postaljob.

Prerequisites

Required resources

These must be installed and running on your server before the postal job will start:

What this job uses from o-link

You don't need to configure anything here — this is just so you know which parts of your server this job talks to through o-link:

• notifications and on-screen hints
• phone messages, as texts or mail (shift updates, crew news, and the pay summary)
• paying players and charging fines
• player names and identity
• the interaction eye/target on the supervisor, boxes, the van, and drop-off points
• progress bars and menus
• vehicle keys and fuel for the delivery van
• work uniforms (optional)

If o-link is already working with your other Oxide resources, you are good to go.

Installation

ensure ox_lib
ensure oxmysql
ensure o-link
ensure oxide-postaljob

CREATE TABLE IF NOT EXISTS `job_progression` (
    `char_id`            VARCHAR(60)      NOT NULL,
    `job`                VARCHAR(40)      NOT NULL,
    `level`              TINYINT          NOT NULL DEFAULT 1,
    `total_count`        INT              NOT NULL DEFAULT 0,
    `daily_streak`       INT              NOT NULL DEFAULT 0,
    `last_activity_date` DATE             NULL,
    `complaints`         TINYINT UNSIGNED NOT NULL DEFAULT 0,
    `timeout_until`      DATETIME         NULL,
    PRIMARY KEY (`char_id`, `job`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Config.Debug = false             -- extra console logging, leave off normally
Config.usePhone = true           -- send shift messages to the player's phone
Config.shiftSummary = 'text'     -- how the end-of-shift pay summary is shown
Config.menuStyle = 'nui'         -- which style of shift menu to use
Config.MaxSlotsPerLocation = 3   -- how many players can work from one depot at once

Verification

Startup check

Start your server and watch the console. The resource should load without any red errors. If a required resource is missing or started in the wrong order, you will see a dependency error naming the missing resource — fix the start order and restart.

In-game check

If all of that works, the resource is installed correctly.

Optional Setup

Phone shift messages

With Config.usePhone on (the default), the depot sends players messages on their phone during a shift:

• a welcome message at clock-in, telling them where to load up
• a message to both players when someone joins a crew
• a notice when the delivery van is destroyed, with the repair fee that was taken
• a notice when their deliveries are cancelled because they died or went down, and another when they're clocked out after going to hospital
• the end-of-shift pay summary (see Shift summary mode below)

These are delivered through o-link, which supports these phone resources: qb-phone, lb-phone, gksphone, okokPhone, qs-smartphone, qs-smartphone-pro, yseries, and Oxide Phone (oxide-phone).

How a message arrives depends on the phone:

If a text can't be sent, the same message arrives as mail instead.

Oxide Phone's Gigs app

If you run Oxide Phone, its Gigs app shows this job with nothing to set up: the depots and whether each has room, the player's current shift (loading the van or the stop they're on, how many stops are done, their crew role, and the pay so far), and their job level. While a player carries an Oxide Phone and the Gigs app is on (it is by default), shift updates arrive there as Gigs notifications instead of texts. The pay summary at clock-out never goes to the Gigs app — it always arrives as a text or mail.

Servers without a phone

If your server doesn't run a supported phone, the messages simply won't arrive — nothing breaks. Set Config.usePhone = false (the Use phone toggle under General in /postaljob settings) to show these messages as on-screen notifications instead. Important moments (pay received, van destroyed, etc.) always also show as regular on-screen notifications.

Shift summary mode

Config.shiftSummary controls how the end-of-shift pay breakdown is shown at clock-out:

• 'text' (default): sent to the player's phone as a text or mail (see Phone shift messages above), with a simple clock-out notification on screen. With Config.usePhone off, a short net-pay notification is shown instead
• 'nui': a pop-up summary on screen, with either menu style. Nothing is sent to the phone

A shift that ends any other way than a clock-out (its depot deleted, or a resource restart) gets the breakdown as with 'text', in either mode.

Menu mode

Config.menuStyle controls what the shift menu looks like:

• 'nui': the full custom menu with a camera view of the depot (default)
• 'menu': a simple text menu — use this if you prefer something lightweight

Uniforms

Work uniforms are off by default. To turn them on, open /postaljob settings (admins only) → Uniforms and switch Uniforms on (Config.uniformsEnabled). The change saves to your database right away, no restart needed. On a new install that has never started, you can instead set this in shared/config/outfits.lua before the first start:

Config.uniformsEnabled = true

When enabled, players get a button in the shift menu to put on a GoPostal uniform while clocked in. Their own clothes are restored when they take it off or clock out. The outfit pieces are under Male outfit and Female outfit in the same part of /postaljob settings (on the Advanced tab) if you want to change the look.

Admin permission

/postaljob settings and the /postalbuilder location builder are limited to admins. To make someone an admin, add them to the admin group and grant that group the admin ace in your server.cfg:

add_principal identifier.license:<their-license> group.admin
add_ace group.admin admin allow

If you already run QBCore, Qbox, or ESX admins, you don't need to do anything extra — your existing framework admins pass automatically. See Admin Tools for how it works.

Note for UI Developers

The resource ships with a ready-built interface in web/dist — you do not need to build anything. Rebuilding is only necessary if you edit the source files under web/src:

cd web && npm install && npm run build

Next Steps