hauling

Last updated on

A delivery job. Crates stand at surveyed points; every player in the site's routing bucket sees the same crates. A player picks one up with the target eye (ALT), carries it, loads it into a vehicle (it becomes a trunk item), drives to one of the site's drop-offs and sells it to the NPC there. No command, no start point: the eye is the whole entry. Sites are written in config/hauling.lua.

• Without target there is no way into the job (the client says so once).
• Without progress no bar is drawn, but the server still enforces the timing.
• Without inventory nothing can be loaded or sold.
• The manifest needs world.props (crates) and world.npcs (sellers).
• Target rows: hauling.pickup (crates), hauling.load (vehicles), hauling.sell (NPCs).

How the job runs

1. Pick up. ALT on a crate → Pick up the crate. The server checks distance (REACH), bucket and the site's job gate, claims the crate and runs a PICKUP_MS bar while the player plays the site's PICKUP_POSE. The crate is then attached (CARRY), the carry animation plays, weapons are holstered and blocked.
2. Put down (optional). DROP_KEY (X by default, rebindable as Hauling: put the crate down). The crate lands DROP_DISTANCE m in front; anyone may pick it up. Untouched for DROP_RETURN_MS, it goes back to its point on the next refill pass.
3. Load. ALT on a vehicle within VEHICLE_REACH → Load the crate, LOAD_MS bar. The prop is removed and one ITEM (hauling_crate, 10 kg) with metadata { site = <site key> } is added to that vehicle's trunk. A full, locked or foreign trunk refuses.
4. Sell. ALT on the seller NPC at a drop-off → Sell the crates, DELIVER_MS bar. Every crate of that site in the player's bag and in the trunk of every vehicle parked within the drop-off's RADIUS that the player owns or holds a key to (vehiclekeys.Holds) is sold at once. Someone else's truck parked there is not counted. Selling from the bag is intended (a drop-off may sit where no vehicle can park). On a server with neither vehicles nor vehiclekeys, every parked trunk counts, and the log says so once. Pay per crate: the site's PAY, else the HAUL_PAY_PER_CRATE tunable (starts at PAY_PER_CRATE), paid in CURRENCY. If payment fails the crates are put back: first where each came from, then into the bag or another trunk of the sale. Crates that fit nowhere are lost and recorded for a refund (not_paid_lost, audit event hauling.crateLost). The seller's citizen id is pinned before the first yield: if the player left or switched character during the sale, that character is paid anyway (through AddMoneyOffline when offline), opx:on:hauling:sold names them, and no toast reaches whoever now holds the connection. Begin and finish run on their own thread.

• Clocks. The server owns every clock: a completion sooner than the bar minus CLOCK_TOLERANCE_MS is refused. A claim not finished within its bar plus CLAIM_GRACE_MS is released by the refill pass.
• Getting into a vehicle with a crate puts it down at the player's feet (You put the crate down to get in. Load it into the trunk to take it along.); a bar under way ends. It no longer goes back to its point.
• Carry ends (crate back on its point) when the carrier disconnects, dies or changes bucket.
• Refill. Every REFILL_MS (tunable HAUL_REFILL_MS, live), each usable site gets up to SPAWN_PER_PASS new crates on free points. A point stays empty RESPAWN_MS after its crate leaves. MAX_CRATES caps the total across all sites.
• Disabled sites. At boot a site is disabled (with a log line) if any point or drop-off is the placeholder 0, 0, 0, two points are closer than MIN_POINT_GAP, a drop-off has no valid NPC, or the engine does not know its MODEL (tested by creating one crate).

Configuration

config/hauling.lua sets OPX.Config.MODULES.hauling. Shared script.

SITES = {
    pacifica_butcher = {                 -- the key: durable, used in logs and item metadata
        LABEL = 'Butcher shop and market',
        BUCKET = 0,
        MODEL = 'crate.delivery',        -- optional, else MODEL
        PICKUP_POSE = 'scavenge',        -- optional, else PICKUP_POSE
        -- CARRY = { ... },              -- optional, else CARRY
        BLIP = { X = -1819.71, Y = -1970.77, Z = 52.50 },  -- optional map pin (blips module)
        POINTS = {                       -- one crate per point
            { X = -1816.63, Y = -1977.91, Z = 52.50, YAW = 248.1 },
            { X = -1815.79, Y = -1975.94, Z = 52.50, YAW = 246.9 },
        },
        SPAWN_PER_PASS = 1,              -- required, whole number above 0
        RESPAWN_MS = 120000,             -- optional, default 0
        -- PAY = 220,                    -- optional, whole number >= 0
        -- JOBS = { nomad = 0 }, ON_DUTY = true,   -- optional job gate
        DROPOFFS = {
            sale = { LABEL = 'Sale', X = -1819.13, Y = -1964.37, Z = 51.50, RADIUS = 6.0,
                NPC = { RECORD = 'Character.VendorMale', YAW = 254.0 } },
        },
    },
}

• X, Y, Z finite and within ±1,000,000 (the shared spot bound, see spot helpers).
• Every drop-off needs an NPC with a RECORD of the form Character.*.
• No JOBS = anyone may haul.
• The shipped sites also carry a TARGET block (label, description, icon); the code does not read it — row texts come from the locale keys hauling.row.*.

Refusal codes

Sent as reason on opx:net:hauling:answer and shown as the toast hauling.refused.<reason> (fallback hauling.refused.generic).