Cipher Trucking

Requirements

Required

• qbx_core or qb-core — the framework bridge detects which you run, so either works
• ox_lib
• ox_target
• oxmysql

Not required

• No SQL file to import. All nine tables create and migrate themselves on first start.
• No inventory resource. Trucking does not use items.

Installation

1. Drop the cipher-trucking folder into your resources directory.
2. Add ensure cipher-trucking to your server.cfg, after your framework, ox_lib, ox_target and oxmysql.
3. Restart the server. Watch the console for [cipher-trucking] database ready — 9 tables verified.
4. Grant the admin ACE if you want the console:
   add_ace group.admin cipher-trucking.admin allow

Upgrading later is the same process. Drop the new folder in and restart — missing columns are added automatically. Always replace the whole folder rather than individual files; a partial upload surfaces as unrelated-looking errors elsewhere, and the resource runs a self-check two seconds after boot that will name any file that failed to load.

Configuration

Everything lives in config.lua. The values most servers change first:

• Config.Trucking.jobLocation and computerCoords — where the depot and its contract terminal sit.
• Config.Trucking.truckSpawns and trailerSpawns — four bays each. The same pool is used for spawning and for returning at the end of a run.
• Config.Trucking.Contracts — add, remove or re-price loads. Each entry needs either a single destination or a stops array for multi-stop routes.
• Config.Trucking.KeysResource — set this to match your vehicle keys system, or the truck may refuse to start.
• Config.Trucking.payoutAccount — 'bank' or 'cash'.

Anything an admin changes in the console's Control tab overrides the config file for that value only. Untouched values keep tracking config.lua, and Reset hands control back to the file.

The delivery loop

1. Accept — target the depot computer, pick a contract from the board or the route map.
2. Hitch — a truck and trailer spawn at the depot. Back the truck onto the trailer; compatible pairs couple through the game's own physics, no keypress needed.
3. Deliver — drive to the marker. Multi-stop routes keep the trailer attached and move the target on after each drop.
4. Return — bring the truck back to any depot bay to get paid.

Every step is confirmed server-side against the vehicle's real position, so positions are never taken on trust from the client.

Trucks and trailers

The free depot rig always works and always will — buying is optional. Owned trucks add a payout bonus, take tracked condition damage, and can be upgraded, painted and serviced.

Specialised trailers are functional rather than cosmetic: a contract with a requiredTrailerType needs a matching trailer owned and selected. The free depot trailer covers general freight only.

Fuel and maintenance

Optional, and switched off entirely with Config.Trucking.Maintenance.enabled = false. Everything is a 0-100 percentage so each gauge shares a scale.

Fuel applies to every truck, including the free one — which always starts full, so a new driver never meets the system before their first delivery. Owned trucks keep whatever is left in the tank and refuel at the stations shown on the map. Burn scales with distance, rises while hauling a trailer, and idling costs a little too.

Wear — tyres, brakes and oil — applies to owned trucks only, matching how condition already worked. Worn tyres cut grip, worn brakes make collisions cost more condition, and low oil slowly drains engine health. Servicing is priced by how worn the part actually is.

Companies

Players found their own company for Config.Trucking.Company.foundingCost — they are not seeded by admins. The founder becomes Owner and can invite drivers by targeting them in the world.

• Ranks and permissions, editable per company.
• A treasury with a full transaction ledger.
• A shared fleet any member can drive, with buying and repairs gated behind a permission.
• Reputation tiers that award perk points, spent on a three-branch perk tree.
• Delivering with a company truck splits the payout between the driver and the treasury.

Admin console

Open with /truckingadmin. Gated behind the cipher-trucking.admin ACE and re-checked server-side on every action, so the client is never trusted about its own permissions.

• Overview — server totals and top earners.
• Players — set level, grant XP, reset rating, give cash, clear a stuck job.
• Fleet — inspect, repair and clear dispatch on any owned vehicle.
• Companies — oversight and force-disband.
• Control — around twenty economy knobs that persist and take effect immediately.
• Logs — recent deliveries.

Before going live

Troubleshooting

The truck spawns but will not start

Config.Trucking.KeysResource does not match your server's keys system. Set it and restart. Turn on Config.Debug to see the real error from the keys export.

The trailer will not hitch

Almost always the truck model. It has to be a tractor unit with a fifth wheel — a box truck cannot couple to anything. Check what the driver has selected in the Garage.

A tab sits on "Loading..."

Check the server console. Every callback reports its own errors by name, and a failed tab shows a Retry button rather than hanging.

Unknown column errors after updating

Almost always a partial upload. Re-upload the entire folder and restart; the boot self-check will name any file that did not load.

The admin command does nothing

The ACE is not granted. Run add_ace group.admin cipher-trucking.admin allow and make sure your identifier is in that group.

Updating

Replace the whole folder and restart. Schema changes apply themselves. There is no migration step and no SQL to run.

Support

Open an issue on GitHub, or ask in the Discord.