Apocalyptic Trader

One shared trader roams a configured route with a shopping cart. Players approach on foot and barter inventory goods for his rotating stock. Players can buy a basket of items, offer multiple inventory stacks, and earn extra barter value from the trader's preferred supply category.

{:links-list}

INSTALLATION

  1. Copy the complete BigDaddy-ApocalypticTrader folder from the downloaded package into your server's resources folder. This is the runtime name, even though the source project is named BigDaddy-Trader.
  2. Add your product key from your Big Daddy Scripts account to key1 under [licensing] in settings.ini.
  3. Enable OneSync. Install and start ox_inventory and its framework/dependencies before the trader.
  4. Configure [trader] in settings.ini, the item rules in trade-items.json, and the walking route in route.json.
  5. Add ensure BigDaddy-ApocalypticTrader to server.cfg after ensure ox_inventory.
  6. Grant administrators the management permission: add_ace group.admin bigdaddy.trader.admin allow, or your configured AdminPermission.
  7. Restart the resource after configuration edits. Use /traderadmin locate to find the trader and test a barter exchange.

Keep the resource folder named BigDaddy-ApocalypticTrader. Include the supplied client/server DLLs, runtime libraries, BigDaddy-NativeString.js, inventory_bridge.lua, configuration files, html folder, and complete stream folder, including the animation and minimap assets.

REQUIREMENTS

REQUIREMENT DETAILS
FiveM server GTA V server with OneSync enabled.
Licensing Valid Big Daddy Scripts product key. Gameplay starts after successful license synchronization.
Inventory ox_inventory with its own supported framework/setup and dependencies. No qb-inventory bridge is included.
Item definitions Exact ox_inventory item names for configured goods. Missing registered items are logged and skipped.
Route Connected, walkable points suitable for your map's navigation mesh and terrain.
Targeting Not required. Players use the nearby E prompt.

Payment uses inventory goods, with no framework cash-account integration. No trader-specific SQL import is required. Framework compatibility depends on your working ox_inventory installation; the trader does not supply framework bridges for that inventory.

CONFIGURATION

Restart the resource after changes. The tables show values in the supplied settings.ini; omitted-setting fallbacks can differ.

Licensing and diagnostics

SECTION SETTING SUPPLIED VALUE DESCRIPTION
[licensing] key1 Your product key Obtain your key from your Big Daddy Scripts account.
[settings] debug false Enables additional diagnostic logging.
[settings] DesyncKey Supplied value Leave the synchronization value unchanged.

The file also contains UseAcePermissions and AcePermission from the startup settings. Ordinary barter does not require an admin ACE. Trader management uses [trader] AdminPermission below.

Appearance and interaction

All settings in the following tables belong under [trader].

SETTING SUPPLIED VALUE DESCRIPTION
Name The Apocalyptic Trader Name in the barter panel and map blip.
PedModel ig_hunter Trader ped model.
CartModel prop_skid_trolley_1 Cart model. prop_skid_trolley_2 uses the same attachment setup.
AnimationDictionary amb@prop_human_bum_shopping_cart@male@idle_a Cart animation dictionary.
AnimationClip idle_a Animation clip.
CartOffset JSON shown below Fixed attachment offsets relative to the trader, with a separate heading. Z is used directly and is not terrain-adjusted.
WalkSpeed 0.5 Movement-rate multiplier: 0.5 is slower and 1.0 is normal. The current loader accepts 0.5 to 5; test changes in-game.
InteractionDistance 2.5 On-foot interaction distance in metres; 1 to 5.
SessionSeconds 240 Trade-session lifetime; whole number from 15 to 300 seconds.
AdminPermission bigdaddy.trader.admin ACE object for player use of /traderadmin.

The supplied cart attachment setting is one line:

CartOffset={"X":-0.021060294463155,"Y":0.92500375280317,"Z":-0.5,"Heading":175.01481191011}

Tune Z for hand alignment with your chosen models. The cart is reserved from player pushing/riding when using BigDaddy-ShoppingCart; that resource is not required to run the trader.

Stock and values

SETTING SUPPLIED VALUE DESCRIPTION
ItemsFile trade-items.json Item-rule file in the resource. A missing or malformed selected file prevents initialization.
StockVariety 8 Distinct sale items selected each restock; 1 to 100, limited by eligible rules.
RestockMinutes 60 Restock interval; 1 to 1440 minutes. Waits until active trade sessions finish.
Markup 1.20 Asking-value multiplier; 1 to 10. Asking value per unit is rounded up.
PreferenceBonus 1.15 Offered-value multiplier for the preferred category; at least 1 and no greater than Markup. Offered value per unit is rounded down.
Blacklist Array shown below Case-insensitive blacklist overriding both sale and payment rules. Keep the JSON array on one INI line.
Blacklist=["money","black_money","identification","phone","WEAPON_RPG","WEAPON_MINIGUN"]

Stock quantities and the preferred category rotate at restock. Sold-out goods disappear on the next menu opening. All players share stock; availability is checked again on confirmation.

trade-items.json

This file is an object keyed by exact ox_inventory item names. Unlisted and blacklisted items cannot be traded. The supplied catalog includes custom items; adjust it for your server.

FIELD DESCRIPTION
Value Base barter value per unit; whole number from 1 to 1000000. Configured balance value, not a cash price imported from ox_inventory.
Category Nonempty category used to select the preferred category at restock.
MinStock Minimum stock when selected for sale; at least 1.
MaxStock Maximum stock; at least MinStock and no greater than 10000.
Sell true allows selection for trader stock.
Accept true allows eligible player stacks as payment.

This complete example uses two custom items from the supplied catalog. Both must be registered in your inventory:

{
  "bzzz_bigdaddy_prop_cola": {
    "Value": 10,
    "Category": "drinks",
    "MinStock": 3,
    "MaxStock": 10,
    "Sell": true,
    "Accept": true
  },
  "bzzz_prop_shop_paper": {
    "Value": 6,
    "Category": "medicine",
    "MinStock": 3,
    "MaxStock": 8,
    "Sell": true,
    "Accept": true
  }
}

With Markup=1.20, one cola costs ceil(10 × 1.20) = 12 in barter value. With medicine preferred and PreferenceBonus=1.15, each paper item contributes floor(6 × 1.15) = 6. Two cover the asking value. Excess payment is not returned.

Only metadata-free stacks can be offered. Serialized weapons, worn tools, containers, personalized items, and expiring goods with metadata are excluded. Configured weapons can be sold as fresh inventory-generated goods; metadata-bearing weapons cannot be offered back as generic payment. An item in your basket cannot also be payment in the same exchange.

Older settings without ItemsFile support inline [trader] Items JSON. New installations should use the separate file.

Route and navigation

SETTING SUPPLIED VALUE DESCRIPTION
RouteFile route.json File containing 2 to 500 route points. A missing or invalid selected file prevents initialization.
StopSeconds 0 Pause on arrival; whole number from 0 to 600 seconds.
RouteArrivalDistance 5 Arrival tolerance including height; 2.5 to 25 metres.
RouteStuckSeconds 20 Time without movement before a nearby destination retry; 10 to 600 seconds. Excludes pauses, ownerless periods, and active obstacle recovery.
RouteRetryRadius 15 Retry distance limit from the original route coordinate; 3 to 50 metres.
RecoverySearchRadius 48 Connected obstacle-detour search radius; 12 to 100 metres. Larger searches take longer.

route.json is an array of world coordinates with separate headings. This example uses the first two supplied Sandy Shores points:

[
  { "X": 1963.6313, "Y": 3751.8188, "Z": 32.2503, "Heading": 301.2525 },
  { "X": 1945.4188, "Y": 3729.6467, "Z": 32.3528, "Heading": 50.1672 }
]

Each spawn randomly selects a starting point, then walks through following points in order and loops. Restarts and death respawns can select the same point again. Older settings without RouteFile support inline Route JSON.

The trader exists in routing bucket 0. He stops when a living player in the same bucket is within 5 metres, including players in vehicles. He also stops during barter and configured waypoint pauses. Walking resumes when those conditions end. A nearby client must stream the trader to control navigation.

Blocked navigation retries nearby destinations without changing the route or teleporting. Physical obstacle recovery searches connected ground positions and holds the current route point. If no exit is found, it checks again after 15 seconds. Failed destinations do not advance the route. Test connected, walkable points on your actual map; missing collision and large obstacles can still prevent movement.

Map blip

SETTING SUPPLIED VALUE DESCRIPTION
BlipEnabled true Show the trader blip.
BlipSprite 76 Bundled custom cart icon; setting accepts 1 to 2000.
BlipColour 17 Orange colour; setting accepts 0 to 85.
BlipScale 0.8 Scale; 0.1 to 3.
BlipShortRange true Controls distant visibility. Set to false for visibility from farther away.

The blip follows the live trader nearby and receives server position updates every 10 seconds outside entity streaming range. The bundled icon reserves sprite 76; other resources using that sprite also show the cart. Store sprite 52 is unchanged.

The resource streams minimap.gfx. If your server already streams a custom minimap, merge the cart into that asset using the supplied build-cart-blip.js tool and instructions in blip/README.md. Only one resource should stream the final merged asset; start order does not merge competing files. Reconnect clients after asset changes.

If merging is unavailable, remove the trader's bundled minimap.gfx and its explicit manifest entry, then set BlipSprite=52 for the standard store icon.

Trader death

SETTING SUPPLIED VALUE DESCRIPTION
DeathBlastRadius 8 Lethal radius around the cart; 1 to 50 metres. Includes players in vehicles and behind cover in bucket 0. Normal grenade damage can also affect surrounding entities.
DeathExplosionDelaySeconds 3 Fuse after confirmed death; whole number from 1 to 60 seconds.
DeathRespawnSeconds 60 Respawn delay from detonation; whole number from 5 to 3600 seconds.

Killing the trader closes trades and arms the cart. An identified player killer receives a warning. The cart explodes after the fuse; the dead trader/cart are removed and replaced after the respawn delay. Confirmed death remains armed if another resource revives or replaces the corpse. A knockdown or missing entity alone does not trigger it. Resource shutdown or inventory suspension cancels a pending fuse.

HOW TO PLAY

  1. Approach the trader alive and on foot within the interaction distance, then press E.
  2. Under HIS WARES, set quantities to build your basket. Set a quantity to zero to remove it, or use CLEAR BASKET.
  3. Under YOUR OFFER, select eligible supply stacks and payment quantities. Search either list to find items.
  4. Compare the asking value, offered value, preferred category, and excess payment shown in the panel.
  5. Make room for the entire basket, then click ACCEPT TRADE when your offer covers the asking value.

Up to 40 distinct basket items and 40 payment stacks are supported, with up to 1,000 units per line subject to stock and inventory availability. Every selected payment quantity is used; excess value is not refunded. Basket goods cannot also be payment.

Close with the close button or Escape. Moving out of range, death, session expiry, and shutdown end sessions. Check your inventory before retrying after a response timeout.

Inventory exchange and resets

You need enough slots and carrying capacity for all purchased goods before payment is removed. The exchange adds and verifies the basket, then removes payment. Failed exchanges attempt to reverse changes; stock decreases only on success.

If recovery itself fails, trading stops and the server logs original/current inventory details and the owner. An administrator must reconcile that information before restoring service. Test custom ox_inventory item-creation hooks with the exchange flow.

Stock, preferences, and the received-goods ledger are held in memory and reset on resource/server restart. Received goods are not resold. Player inventory persistence remains with ox_inventory. An inventory-provider restart suspends the trader; recovery reloads stock and recreates one trader/cart pair.

ADMINISTRATION

Grant your chosen group the configured AdminPermission:

add_ace group.admin bigdaddy.trader.admin allow
COMMAND DESCRIPTION
/traderadmin status Availability, route point, movement state, distance, stock, sessions, and received-goods ledger. Default when no subcommand is supplied.
/traderadmin locate Sets an authorized player's waypoint. Console use prints coordinates.
/traderadmin restock Refreshes stock/preferences when no trade session or exchange is active.
/traderadmin catalog Prints item names, labels, and configured status to the server console.

The server console runs these without /. Player administration requires the configured ACE; ordinary barter does not.

TROUBLESHOOTING

No trader or interaction prompt

  • Check licensing and startup errors. Confirm OneSync and ox_inventory are running and the complete resource is named BigDaddy-ApocalypticTrader.
  • Check that route/catalog files exist and contain valid JSON.
  • Use /traderadmin status and /traderadmin locate. Approach in bucket 0, alive, on foot, and within InteractionDistance.
  • Allow your inventory to load. A distant trader needs a streaming client before navigation and trading become active.

The trader stands still

  • Move living players more than 5 metres away, including vehicle occupants. Close trade sessions and let waypoint pauses finish.
  • Use /traderadmin status to identify pauses, missing streaming clients, and obstacle recovery.
  • Check route heights, walkable navmesh, collision, and barriers. Adjust problematic points and restart.
  • Compare speeds outside the proximity-pause radius. Tune CartOffset.Z for cart height.

Missing items or rejected payment

  • Match catalog keys to registered ox_inventory names. Check skipped-item logs and /traderadmin catalog.
  • Check Sell, Accept, and Blacklist. Only a random selection of eligible goods is stocked each cycle.
  • Metadata-bearing stacks are excluded from payment. A basket item cannot also be payment.
  • Cover the full asking value and make room for the entire basket before payment is removed.

Stock will not restock

Close all trade sessions or let them expire before /traderadmin restock. Restocking waits for sessions and exchanges to finish. Restarting resets stock and the received-goods ledger.

Missing or incorrect map icon

Check BlipEnabled, BlipShortRange, and BlipSprite. Deploy stream assets and reconnect. Merge competing minimap.gfx files as described above, or use the standard store icon option.

Inventory recovery errors

Preserve logs and reconcile the logged owner and original/current inventory contents before restoring trading. Check custom inventory hooks and provider errors. A restart alone does not resolve missing or duplicated goods.