Features

How each part of oxide-blackmarket works in game.

The Dealers

Several dealers exist at the same time, shared by the whole server. The server creates them, keeps track of each one, and syncs them to every player. By default there are three (Config.DealerCount), but you can set any number up to how many spawn locations you have listed.

Spawn and relocation

• Each dealer spawns at its own random spot from Config.Locations — no two dealers ever share a location.
• Every Config.RelocationInterval (45 minutes by default) a dealer packs up and moves to a new random spot. Each dealer runs its own timer and they are staggered, so they don't all move at the same moment.
• Relocating gives that dealer a fresh full stock.
• Players who arrive late, log in mid-session, or teleport in still see and can interact with every dealer — no special handling needed.

Day-to-day behavior

• A dealer wanders around near his spawn point when nobody's trading.
• Opening the shop stops him and he turns to face the player.
• If someone attacks a dealer, he stops trading, arms himself, and fights back — no more deals from that dealer until he next respawns.

Reputation and Tiers

Each character has a black market reputation, saved with their character data (blackmarket_rep via olink.character). Reputation is shared across all dealers — selling to any dealer builds the same reputation.

Tier thresholds

Earning and losing reputation

• Selling items listed in Config.SellableItems earns cash and reputation.
• Killing a dealer costs Config.KillPenalty reputation (500 by default).
• Moving up or down a tier plays a sound and shows a notification.

Turning tiers off

Set Config.EnableTiers = false and:

• every player sees the full shop, all tiers
• reputation is never gained or lost
• tier notifications never show
• the pager works for everyone (treated as top tier)

Shop and Dirty Money

The shop is a buy/sell window. Everything the player does in it is checked again by the server, so edited clients can't cheat prices, stock, or distance.

Category tabs and search

Both the buy list and the sell list are grouped under category headings (such as Weapons, Ammo, Medical, Tools, Drugs & Supplies, Armor, Blueprints on the buy side, and Weed, Meth, Misc on the sell side). A search box at the top filters the list by item name as the player types. The category each item falls under is set by its category field in shared/items.lua.

Buying

• The player must be standing near the dealer he opened.
• The buy list shows the player's tier and every tier below it.
• Each dealer carries its own stock — buying the last rifle from one dealer doesn't affect any other dealer. Find another dealer and he may still have one.
• A dealer's stock refills when he relocates or respawns, and tops up over time on its own (see Living Economy below).

Selling

• Only items in Config.SellableItems can be sold.
• The sell tab shows what's in the player's inventory that the dealer wants.
• Selling pays dirty money and earns reputation.
• The price shown is the current market price, which moves with how much of that item has been sold server-wide (see Living Economy).

Dirty money

Config.DirtyMoney decides what currency the shop uses (see the Installation Guide for per-framework setup):

• Account mode — money comes from a money account (regular cash, or ESX black money).
• Item mode — money is an inventory item, one item = $1.
• Item mode with metadata — each bill carries its own dollar value (e.g. a marked bill worth $5,000). Payments use the fewest bills possible and change comes back as a new bill.

This applies to purchases, sales, and the cash in loot bags.

Living Economy

Three optional systems make the market feel alive. All three run in memory only, so they reset when the resource or server restarts.

Market saturation (sell prices)

When players flood the market with an item, its sell price drops for everyone — at every dealer, since there's one shared market. The price then slowly climbs back toward normal over time. Buy prices are never affected. Configured under Config.Market:

• decayPerSale — how much the price drops per item sold (default 0.02, i.e. 2% per item)
• recoveryPerMinute — how fast the price recovers toward normal (default 0.01, i.e. 1% per minute)
• minSellMultiplier — the floor; the price never falls below this share of the base (default 0.4, i.e. 40%)

Set Config.Market.enabled = false to keep sell prices fixed.

Periodic restock

Separate from relocation, each active dealer tops his stock back up toward its maximum on a timer, so a single buyer can't drain a dealer for a whole spawn and leave everyone else with nothing.

• Config.RestockEnabled — turns restocking on or off (default true)
• Config.RestockInterval — how often each dealer restocks (default 10 minutes)
• Config.RestockPercent — how much of each item's maximum is added each time (default 0.25, i.e. +25% of max per tick, never above the maximum)

Daily sell caps (optional)

You can limit how much of an item each player is allowed to sell to dealers per real-world day. This is off by default. Configured under Config.DailySellCap:

• enabled — turn the caps on (default false)
• default — the cap applied to any sellable item without its own limit (0 means unlimited)
• perItem — per-item overrides, e.g. ['weed_brick'] = 50

A player who hits the cap is told how many more they can sell today. Counts reset at the start of each new day and when the resource restarts.

Police Gameplay

A player counts as police when their job name is listed in Config.PoliceJobs.

Surrender

• An officer aiming a weapon at a dealer from within Config.AimSurrenderDistance forces him to put his hands up.
• If nobody starts an arrest within about 15 seconds, the dealer breaks free, pulls his weapon, turns hostile — and calls in a hit squad.
• If the officer drifts too far from a surrendered dealer, the dealer may bolt.

The arrest is a transport job

Arresting a dealer is not instant. Once a dealer has surrendered, the arresting officer walks the whole process through:

The whole transport has a safety timer (Config.EscortMaxDuration, 3 minutes by default) — if it runs too long, the dealer slips away.

What can go wrong mid-transport

The dealer re-arms himself and the hit squad spawns if:

• the officer strays past Config.EscortBreakFreeDistance during the on-foot escort
• the transport exceeds Config.EscortMaxDuration
• the dealer is pulled out of the vehicle, or the vehicle is lost

Arrest rewards

The reward is paid only when the dealer is delivered to a drop-off, never before. Who gets paid is set by Config.ArrestRewardRecipient:

• 'officer' — the arresting officer receives Config.ArrestReward in personal cash
• 'society' — the police department account receives Config.DepartmentCut
• 'both' (default) — both of the above

A new dealer spawns after Config.ArrestRespawnDelay.

Optional oxide-police integration

If you run oxide-police and set Config.ArrestPoliceIntegration = true, the department cut is paid directly into the arresting officer's real oxide-police department treasury on delivery, instead of the generic society deposit. The officer still gets his personal cash portion if Config.ArrestRewardRecipient includes the officer.

This does not create an NPC arrest record, charge, or custody booking — an NPC can't be booked into a player-custody system. It only moves the money into the correct department. If oxide-police isn't installed (or the officer's department can't be found), the arrest quietly falls back to the standalone society deposit, so nothing breaks.

Dispatch alerts

Config.DispatchAlerts gives police two ways to find out about a dealer:

• transaction — a chance to alert dispatch whenever someone buys or sells
• proximity — a chance to alert dispatch when an officer gets close to a dealer

Alerts go through o-link, so they work with ps-dispatch, cd_dispatch, and other dispatch systems without extra setup.

Dealer Death and Hit Squad

Killing a dealer is always an option — but it has consequences.

How a death is handled

• The death is detected in game and confirmed by the server, which checks the report came from a player actually near the dealer.
• Duplicate reports are ignored, so the loot and hit squad only happen once.
• The server works out who the killer was from damage tracking; if the kill didn't involve a tracked weapon (vehicle, fire, melee), it falls back to the player who reported the death.

What happens next

• The killer loses reputation (when tiers are on).
• Players within Config.DeathNotifyRadius whose tier is at or above Config.DeathNotifyMinTier hear that a dealer is down (when tiers are off, everyone in range hears it).
• The body stays for Config.BodyFadeDelay, then fades away.
• That dealer respawns after Config.DeathRespawnDelay.
• If the dealer was killed while surrendered (hands up), the police account gets a smaller Config.SubduedDeathPayout instead of the full arrest reward.

The hit squad

The dealer's associates don't take a murder lying down. Four armed NPCs spawn in a car a few hundred meters away and come after the killer.

• Weapons and accuracy come from Config.HitSquadDifficulty (easy/medium/hard).
• They drive to the player, then get out and fight on foot once they're close.
• The spawn spot is picked carefully — on a road, at the configured distance, with a drivable route to the player — so the squad actually arrives instead of getting stuck.
• Escape by getting Config.HitSquadEscapeDistance away (500 m by default), or kill them all.
• If bad roads keep them from ever reaching the player, they give up after Config.HitSquadMaxChaseDuration.
• Only one hit squad exists at a time.

Loot Bags

A killed dealer can drop a bag at the spot where he died.

What's inside

• Cash between Config.LootCashMin and Config.LootCashMax.
• A cut of whatever stock that dealer hadn't sold yet (Config.LootStockPercent), up to Config.LootMaxItems different items.

Why it can't be exploited

• The bag's contents live on the server — the player's game only knows where the bag is.
• Collecting requires actually standing at the bag (checked server-side, 5 meters).
• First come, first served — once collected, it's gone for everyone.
• Uncollected bags disappear after Config.LootBagDespawnTime.

Finding a Dealer

Flash blips

Walking within Config.BlipDetectionRange of the nearest dealer flashes a "Suspicious Activity" blip on the player's map. Higher reputation keeps the blip visible longer (Config.BlipDuration), and it won't flash again for the same player until Config.BlipCooldown passes.

The pager

Using the blackmarket_pager item asks the player's contacts where the nearest dealer is. It only works if:

• at least one dealer is currently active
• the player is Tier 2 or above
• the pager isn't on cooldown (Config.PagerCooldown, 5 minutes by default)

Chance of getting an answer:

Because dealers roam during the short wait for a reply, the pager re-checks which dealer is nearest at the moment the reply comes in. What the answer looks like:

• Tier 2 — the general area the nearest dealer set up in, as an anonymous email ("working somewhere out in Davis")
• Tier 3 — the street and district in the email, still no map pin ("set up around Alta Street, out in Downtown")
• Tier 4 — the street and district plus a GPS waypoint dropped on the map

The intel arrives as an in-game phone email when your phone system is connected through o-link. A notification always confirms it, and Tier 4 always drops the waypoint even if the email can't be delivered.

Startup Config Check

When the resource starts, it reads through your buy and sell catalogs (Config.ShopInventory, Config.SellableItems, and your dirty-money item if you use item mode) and checks each item name against your inventory system. Any name your inventory doesn't recognize is flagged as a warning, so a typo shows up right away instead of silently failing at the counter later. The warnings go to oxide-logger if you run it, and also print to the server console when Config.Debug = true.

Next Steps