Configuration Reference

Every setting in oxide-postaljob, explained in plain terms. Distances are in meters and times are in seconds unless a setting says otherwise. Start with How Settings Work — the job keeps its settings in your database, so editing the config files does not always do what you expect.

How Settings Work

Settings are edited in-game with the /postaljob settings command (admins only). Changes save to your database and apply instantly — no restart needed.

The config files in the shared/ folder are factory defaults. The first time the resource starts, every value is imported from the files into the database; from then on, the database is the source of truth and editing a file changes nothing for a setting that is already stored, even after a restart. Only brand-new settings added by a future update are imported from the files.

The job still reads the files at every start, and Reset to default on a setting in /postaljob settings loads that setting's file value, replacing the stored one. So a file edit takes effect only after you restart the resource and press Reset to default on that setting.

This includes the depots, delivery addresses, and letterboxes — everything is database-managed. A depot's name, Clerk spot, and van spawn are edited in /postaljob settings under Locations. Its pickup points, post boxes, letterboxes, delivery addresses, and menu camera are not in the menu: they change through shared/config/locations.lua, a restart, and Reset to default on Depots, usually with the /postalbuilder export (see Adding a second depot).

Two settings are never copied into the database, so they are always read from the files: Config.UseHudAccent in shared/config.lua, and Config.SettingsCommand in shared/config/models.lua, which only sets the command named in missing-model warnings.

So there are two ways to work:

1. First-time setup: edit the files in shared/ before the resource's first start. Your values are imported automatically.
2. Changing a setting later: run /postaljob settings in game as an admin. See The Settings Editor for how the menu works.

The tables below document every setting and its factory default.

Which File Does What

Main Switches

File: shared/config.lua

Pay, Crew, and Timers

File: shared/config/job.lua

Crew

Payment

Complaints

Timer

How a timer is calculated:

timeLimit = Config.Timer.baseTime + math.floor(distance * Config.Timer.timePerDistanceUnit)

In the settings editor these are the Delivery timer fields under Tasks & Dispatch.

Cancelling a round

Players can drop the round they're on without clocking out (see Cancelling the current round). This setting controls the short wait afterwards — Cancelling a round under Tasks & Dispatch in the settings editor.

Config.Cancel = {
    cooldownSeconds = 60,   -- seconds; 0 = no wait
}

The wait applies to the player who cancelled, and it's tied to the character, so relogging doesn't skip it. Because the whole point of cancelling is to escape a bad round rather than to be punished, there is no fine and no complaint attached to it — this cooldown is the only cost.

Levels

File: shared/config/levels.lua

Each entry in Config.Levels is one job level:

Default levels

Config.Levels = {
    [1] = { title = 'level.trainee',        requiredDeliveries = 0,   maxPackages = 3, maxLetters = 3, tipChance = 0.10, tipRange = { 5, 15 },  payMultiplier = 1.0,  spreadFactor = 1.0  },
    [2] = { title = 'level.mail_carrier',   requiredDeliveries = 20,  maxPackages = 4, maxLetters = 4, tipChance = 0.15, tipRange = { 5, 20 },  payMultiplier = 1.1,  spreadFactor = 0.75 },
    [3] = { title = 'level.senior_courier', requiredDeliveries = 50,  maxPackages = 5, maxLetters = 4, tipChance = 0.25, tipRange = { 10, 30 }, payMultiplier = 1.2,  spreadFactor = 0.5  },
    [4] = { title = 'level.route_manager',  requiredDeliveries = 100, maxPackages = 7, maxLetters = 5, tipChance = 0.30, tipRange = { 10, 40 }, payMultiplier = 1.35, spreadFactor = 0.25 },
    [5] = { title = 'level.head_postman',   requiredDeliveries = 200, maxPackages = 9, maxLetters = 6, tipChance = 0.40, tipRange = { 15, 50 }, payMultiplier = 1.5,  spreadFactor = 0.0  },
}

You can add more levels as extra rows under Levels in /postaljob settings. Note: a package round can never exceed the number of box positions inside the van (11 by default — see Config.VanBoxOffsets).

Locations

File: shared/config/locations.lua

Each entry in Config.Locations is one complete depot. The job ships with one, the GoPostal Depot.

Inside menuCamera:

Delivery zones and letterboxes

Each entry in deliveryZones and letterBoxes looks like:

Post boxes

Each entry in postBoxes is just a position and heading (vector4). One is picked at random as the mail bag pickup for each letter round. No prop is spawned there — the player interacts with a small invisible zone at those coordinates, so place them on or next to an existing post box prop for the best look.

Adding a second depot

The job ships with one depot, but Config.Locations is a list — you can add as many as you want, and each one is a complete, independent GoPostal branch. That means its own supervisor NPC, its own map blip, its own van spawn point, and its own set of pickup points and delivery addresses.

A few things worth knowing before you start:

• A shift belongs to the depot the player clocked in at. Someone working out of your Sandy Shores branch only ever gets Sandy Shores addresses. Depots never mix.
• NPCs and blips appear on their own. The job walks the whole Config.Locations list at startup, and again whenever the depots are saved in /postaljob settings, and creates a supervisor and a map blip for every entry. There is no list to register anything in and nothing else to switch on.
• Worker slots are counted per depot. Config.MaxSlotsPerLocation (default 3) applies to each depot separately, so two depots means six people can be on shift at the same time.
• Progression is shared. A player's level, delivery count, and streak follow their character, not the depot, so they keep their rank wherever they clock in.

A depot is one block inside Config.Locations in shared/config/locations.lua, so a second depot is a second block after the closing }, of the first one (the end of this section explains how a file change reaches a server that has already started). Here is a complete depot entry, with every field in place:

Config.Locations = {
    {
        -- ... the existing GoPostal Depot entry, leave it alone ...
    },
    {
        name = 'Sandy Shores Post Office',
        coords = vector3(1704.12, 3757.65, 34.70),
        heading = 220.0,
        vehicleSpawn = vector4(1698.40, 3752.10, 34.40, 30.0),

        menuCamera = {
            coords = vector3(1712.00, 3766.00, 40.00),
            heading = 200.0,
            fov = 50.0,
        },

        pickupPoints = {
            vector4(1692.55, 3746.80, 34.30, 120.0),
        },

        postBoxes = {
            vector4(1738.90, 3710.25, 34.15, 15.0),
        },

        letterBoxes = {
            { coords = vector3(1394.20, 3596.10, 34.90), minLevel = 1, label = 'Alhambra Drive' },
            { coords = vector3(1428.75, 3620.40, 34.85), minLevel = 2, label = 'Zancudo Avenue' },
        },

        deliveryZones = {
            { coords = vector3(1961.20, 3741.55, 32.35), minLevel = 1, label = 'Alhambra Drive' },
            { coords = vector3(1985.60, 3777.10, 32.20), minLevel = 3, label = 'Marina Drive' },
        },
    },
}

The easiest way to gather all these coordinates is the in-game /postalbuilder tool, which lets you stand where you want each thing and record it, then exports a finished block like the one above. See The Location Builder.

Where you make this change depends on whether the resource has ever started:

• On a brand-new install that has never started, paste the block into shared/config/locations.lua (after the closing }, of the first depot). The file is the factory default that gets imported on first boot.
• On a server that has already run this resource once, editing shared/config/locations.lua changes nothing by itself. A depot's name, Clerk spot (coords and heading), and vehicleSpawn can be added or changed in the in-game /postaljob settings editor (admins only) under Locations, where Place in world sets the Clerk spot and van spawn from where you stand. Those changes save to the database and apply instantly: the blip and supervisor appear or move on the spot, no restart needed. The other fields (pickupPoints, postBoxes, letterBoxes, deliveryZones, menuCamera) are not in the editor, so a depot added only there can't hand out rounds. A player who tries to start one there is turned away: a package round tells them the depot has no parcel routes yet (and the server console logs a warning naming the depot), a letter round that no letterboxes are available. To load complete depots, put the full list in shared/config/locations.lua (the /postalbuilder export is the easy way, see Where the export goes), restart the resource, then press Reset to default on Depots.

You can edit, reorder, or delete depots in the editor while players are on shift. A shift keeps its depot as long as the depot keeps either its name or its Clerk spot (coords), and the worker slots in use move with it. If you delete a depot (or change both its name and its Clerk spot in the same save), the shifts there end straight away and are paid, the pay summary goes out as with Config.shiftSummary = 'text', and the players are told their depot was removed.

Two practical tips:

• Give a new depot plenty of addresses. A round is only as big as the addresses the player qualifies for. A level 5 player can be sent to 9 package stops, so a depot with 6 addresses will simply hand out shorter rounds. Aim for at least as many minLevel = 1 entries as your highest level's round size.
• Labels and names can be plain English. The shipped depot uses translation keys like 'location.strawberry_ave' because it ships in several languages. If you type ordinary text like 'Alhambra Drive' instead, that exact text is what players see — no locale file editing needed.

NPCs and Blips

File: shared/config/npcs.lua

Map blip

The blip's name is always the depot's name — there is no separate blip label setting.

Customers

Config.CustomerPeds is the list of character models used for the customers who walk out to receive packages. One is picked at random per delivery. Add or remove models freely.

Uniforms

File: shared/config/outfits.lua

Config.PostalOutfitMale and Config.PostalOutfitFemale define the two uniforms. Each is a list of clothing pieces:

These use standard GTA clothing IDs — the same numbers you'd use in any clothing menu.

The Van and Props

File: shared/config/vehicles.lua

Van

Package pallet and boxes

Letters

Box positions

• Config.BoxOffsets — the 12 positions boxes occupy on the pallet
• Config.VanBoxOffsets — the 11 positions boxes occupy inside the van (this is also the van's maximum capacity)
• Config.VanBoxRotation — the rotation applied to boxes inside the van (default vector3(0, 0, 0))

Visuals

File: shared/config/visuals.lua

Delivery marker

The glowing marker at the delivery spot:

Delivery animation

Config.Animations.deliver is the hand-over animation played when delivering a package:

Floating waypoint

The 3D marker players see over the delivery address while holding H:

Tutorials

File: shared/config/tutorials.lua

Config.Tutorials defines the nine first-time hint prompts (icon, title, body text, and optionally screen position and duration). The text itself lives in locales/en.json. You normally won't need to change these unless you want to reposition a prompt or change its icon, which you do under Tutorial cards in /postaljob settings.

With Oxide HUD, every prompt left at the default position (top right) appears where each player puts the tutorial prompts in the /hud editor. A prompt you give another position keeps that position.

Models and Compatibility

File: shared/config/models.lua

Model replacements

The Compatibility section of /postaljob settings.

Every model the job spawns (the van, the supervisor, customers, the pallet, boxes, and the mail bag) is checked before it loads. If a model doesn't exist on a player's game build — older builds lack newer DLC props — it is skipped instantly with a warning naming the model, instead of freezing the load. A missing customer model is simply left out of the pool, and a missing van model cleanly cancels the spawn. Nothing is swapped automatically; you choose the replacement.

Config.ModelSwaps = {
    { from = 'h4_prop_h4_med_bag_01b', to = 'your_bag_prop' },
}

When a model is missing, online admins get a notification naming it, and the server log records it. Each missing model is reported once, and the warnings are capped per player and in total, so one misbehaving client can't flood admins or the log.

Mailbox models

The /postalbuilder Scan Post Boxes and Scan Letterboxes tools look for these props in the world. If your map replaces the stock mailboxes, add its models here so the scanner finds them (Post box models and Letterbox models under Props & Animations in the settings editor).

Anti-Spam Limits (Fixed)

The server enforces short cooldowns on player actions to block exploit spam. They are intentionally not configurable — they live in server/main.lua:

Next Steps