Configuration

This page documents every configurable option in config.lua. The config file ships with factory defaults that are also editable at runtime via the in-game Admin Panel → Settings tab (stored in ars_cardealer_settings). When an admin override exists in the database, the DB value takes precedence over the value in this file until cleared.

General Settings

Config.Framework = 'auto'
Config.Debug = false
Config.Target = 'auto'

• Framework — 'auto' (detects QBCore/QBox/ESX), 'qb', 'qbx', or 'esx'. Must be resolved before framework bridge files load.
• Debug — when true, prints extra output to server/client consoles.
• Target — 'auto' (detects ox_target/qb-target/qtarget), 'ox', 'qb', or 'qtarget'. A target resource is required — the catalog opens only by targeting the salesman ped.

Admin

Controls shop creator / control panel authorization. A player is admin if they match any of the three allow-lists below. Console (src == 0) always passes.

Config.Admin = {
    openCommand = 'arscardealer',
    auditRetentionDays = 90,

    allow = {
        group = { ['admin'] = true, ['god'] = true },
        license = { -- ['license:xxx'] = true },
        identifier = { -- ['xxxxxxxx'] = true },
    },
}

Key	Description
openCommand	Chat command to open the admin panel. Must differ from any other registered command.
auditRetentionDays	Prunes audit log rows older than N days on startup. 0 = keep forever.
allow.group	Framework group/rank allow-list (resolved per-framework via Bridge.HasPermission).
allow.license	Rockstar license allow-list (format license:<hex>).
allow.identifier	Character identifier allow-list (citizenid for QBCore/QBox, identifier for ESX).

---

Dealership

Top-level physical shop behaviour: shop-wide defaults, stock cap, display floor, deliveries, test drives, creator options, and zone weapon rules.

Shop Defaults

Config.Dealership.Shop = {
    catalogPurchaseDefault = true,
    defaultRetailMarkupPct = 0.25,
}

Key	Description
catalogPurchaseDefault	Whether customers can buy from the catalog/tablet without a rep present.
defaultRetailMarkupPct	Auto-seeded retail markup on wholesale when a model has no explicit price.

Stock

Config.Dealership.Stock = {
    maxPrice = 100000000,
    maxStock = 500,
}

Key	Description
maxPrice	Hard cap on retail price — rejects absurd input.
maxStock	Hard cap on finite stock a single shop can hold for one model. Stock = -1 (unlimited) is unaffected.

Display

Config.Dealership.Display = {
    enabled = true,
    collision = true,
    sphereRadius = 3.0,
    defaultModel = 'adder',
    readjustCommand = 'readjustdisplay',
    maxDisplaysPerShop = 20,
    autoRotateSpeed = 30.0,
    outOfStockAlpha = 200,
    displayPanel = { enabled = true, corner = 'bottom-right' },
    placement = { rayFlags = 511, distance = 3.0, nudgeStep = 0.05, nudgeXYStep = 0.05, settle = true, maxAbovePlayer = 8.0, clearRadius = 3.0 },
}

Display vehicles are frozen showroom models spawned on zone enter and despawned on exit. Each is invincible and frozen.

Key	Description
enabled	Toggle display vehicles entirely.
collision	Physical collision on display vehicles.
sphereRadius	Proximity sphere for the floating stats panel.
defaultModel	Preview model for newly placed display slots.
readjustCommand	Command to reposition the nearest display vehicle (admin).
maxDisplaysPerShop	Bounds per-shop entity and render cost.
autoRotateSpeed	Turntable rotation in degrees/second.
outOfStockAlpha	Display opacity (0-255) when stock is 0.
displayPanel.enabled	Show the floating stats panel near display vehicles.
displayPanel.corner	Screen anchor: top-left, top-right, bottom-left, bottom-right.
placement.rayFlags	Shape test flags for in-world placement (511 = include all entity types).
placement.distance	How far ahead of the player (along the camera aim) the placement ghost anchors, in metres.
placement.nudgeStep	Meters per PageUp/PageDown press during placement.
placement.nudgeXYStep	Metres of horizontal movement per arrow-key press during fine-tuning.
placement.settle	Run settle-on-wheels at spawn.
placement.maxAbovePlayer	Reject placement more than this many meters above/below the placer.
placement.clearRadius	Metres around a pad; foreign vehicles parked inside are deleted before the display spawns (0 disables).

Delivery

Config.Dealership.Delivery = {
    enabled           = true,
    defaultMode       = 'instant',
    wholesalePct      = 0.60,
    supplier          = vector4(1000.0, -3000.0, 5.9, 90.0),
    supplierBlip      = { sprite = 477, color = 5, scale = 0.9 },
    trailerDocks      = {
        vector4(986.84, -2974.08, 5.9, 360.0),
        vector4(1020.24, -3001.02, 5.9, 90.0),
        vector4(954.54, -3053.41, 5.9, 268.81),
        vector4(1014.0, -3000.0, 5.9, 90.0),
    },
    dockCount         = 8,
    dockRadius        = 14.0,
    autoDelay         = 300,
    autoFeePct        = 0.05,
    truckModel        = 'packer',
    trailerModel      = 'docktrailer',
    maxUnitsPerRun    = 10,
    deliverRadius     = 8.0,
    abandonMinutes    = 15,
    maxConcurrentRuns = 3,
    driverPayPerUnit  = 200,
    driverPayFlat     = 500,
}

Key	Description
defaultMode	Default restock mode for new shops: instant, auto, or trucking.
wholesalePct	Cost to shop balance per unit, as fraction of retail.
supplier	Map coordinates for the stock supplier (vehicle import depot).
trailerDocks	Hand-placed vector4(x, y, z, heading) trailer spawn points. Each run uses trailerDocks[(runId % #trailerDocks) + 1]. Empty list falls back to the automatic ring around supplier.
dockCount / dockRadius	Fallback ring around the supplier when trailerDocks is empty.
autoDelay	Seconds before an auto-ordered car arrives.
autoFeePct	Surcharge on top of wholesale for auto mode.
truckModel / trailerModel	Vehicles used for trucking runs.
maxUnitsPerRun	Maximum units per delivery run.
abandonMinutes	Auto-cancel stalled runs. In-transit runs are timed from pickup; unclaimed orders from placement.
maxConcurrentRuns	Best-effort cap on in-transit runs per shop.
driverPayPerUnit	Driver pay per unit delivered (from new money, not shop balance).
driverPayFlat	Flat bonus per completed trucking run.

Test Drive

Config.Dealership.TestDrive = {
    enabled = true,
    mode = 'both',
    routingBucket = 0,
    duration = 60,
    maxDistance = 800,
    deposit = 0,
    refundOnExpiry = true,
    forfeitOnAbuse = false,
    cooldown = 30,
    plateFormat = 'TESTNNNN',
    auto = { exitGrace = 5, returnOnEnd = true },
    assisted = { duration = 120, disabledTimeout = 120, plateFormat = 'ASSISTNN' },
    sweepInterval = 10,
}

Key	Description
enabled	Master toggle for the test-drive flow.
mode	self, assisted, or both.
routingBucket	Base routing bucket (0 = shared world; >0 for isolation).
duration	Seconds the player may keep the vehicle (self mode).
maxDistance	Metres from the dealership (self mode).
deposit	Optional refundable deposit charged on start.
refundOnExpiry	Refund deposit on time-expiry sweep.
forfeitOnAbuse	Forfeit deposit on abuse exits (distance breach / destroyed).
cooldown	Seconds between test drives per player.
plateFormat	Plate pattern for self-mode test drives.
auto.exitGrace	Seconds outside the car before the drive ends.
auto.returnOnEnd	Teleport player back to their menu position on end.
assisted.duration	Seconds the customer may keep the vehicle (assisted mode).
assisted.disabledTimeout	Seconds the disabled car sits before force-delete.
assisted.plateFormat	Plate pattern for assisted-mode test drives.
sweepInterval	Server sweep cadence in seconds for expiry/disable/force-end.

Creator

Config.Dealership.Creator = {
    pedModels = {
        { model = 's_m_m_highsec_01',  label = 'Security Guard (default)' },
        { model = 'ig_siemonyetarian', label = 'Car Salesman' },
        { model = 's_m_m_autoshop_01', label = 'Mechanic' },
        { model = 'cs_siemonyetarian', label = 'Suit Salesman' },
        { model = 'a_m_m_business_01', label = 'Business Ped' },
    },
    defaultPedModel = 's_m_m_highsec_01',
}

Ped models available in the shop creator’s picker.

Weapons

Config.Dealership.Weapons = {
    lockInZone = true,
}

Disables firing and drive-by inside any dealership zone (anti-RDM).

---

Purchase

Payment

Config.Purchase.Payment = {
    currency = '$',
    methods = { 'cash', 'bank' },
    plateFormat = 'ARS XNXN',
    defaultGarage = 'pillboxhill',
    currencies = {},
}

Key	Description
currency	Symbol prefixed to amounts in the UI.
methods	Money types players may pay with (mapped via Bridge).
plateFormat	Vehicle plate format. X = random letter, N = random digit, other chars are literal.
defaultGarage	Garage label the purchased vehicle is sent to.
currencies	Custom currency definitions (framework account or external adapter). Leave {} to disable.

Financing

Config.Purchase.Financing = {
    command = 'myfinance',
    enabled = true,
    minPrice = 10000,
    downPaymentPct = 0.10,
    interestRate = 0.08,
    plans = { 12, 24, 36, 48 },
    intervalHours = 2,
    missedLimit = 3,
    repoFee = 5000,
    repossess = true,
    graceHours = 12,
    warnThresholds = { 0.5, 0.9 },
}

Installments are auto-charged from the bank account while the player is online. After missedLimit consecutive missed auto-charges, the vehicle is repossessed.

Key	Description
command	Chat command that opens the financing panel (/myfinance by default).
enabled	Master toggle for the financing flow.
minPrice	Minimum financed amount.
downPaymentPct	Fraction of price charged up front.
interestRate	APR (0.08 = 8%).
plans	Available installment counts.
intervalHours	Play-time hours between installments (counts down only while online).
missedLimit	Consecutive missed auto-charges before repossession.
repoFee	Flat fee added on top of outstanding balance for recovery.
repossess	Impound the vehicle after missedLimit consecutive misses.
graceHours	Play-time hours of grace before repossession (after missedLimit is reached).
warnThresholds	Escalating warning points during grace (0.5 = halfway, 0.9 = last-chance).

Coupons

Config.Purchase.Coupons = {
    enabled = true,
    codeLength = 8,
    maxDiscountPct = 50,
    maxFixedDiscount = 50000,
    maxUsesPerPlayer = 1,
}

Key	Description
enabled	Master toggle for coupons.
codeLength	Length of generated coupon codes.
maxDiscountPct	Maximum discount percentage.
maxFixedDiscount	Maximum flat discount amount (when a coupon uses a fixed value).
maxUsesPerPlayer	Per-player redemption limit (0 or nil = no limit).

Trade-In

Config.Purchase.TradeIn = {
    enabled = true,
    baseValuePct = 0.50,
    conditionFactor = 0.10,
    minValue = 500,
    detectRadius = 18.0,
}

A customer trades in an owned vehicle for credit against a purchase. Ownership is always re-validated server-side.

Sell

Config.Purchase.Sell = {
    enabled = true,
    payoutPct = 0.45,
    conditionFactor = 0.15,
    minValue = 500,
    balancePayout = true,
}

A player drives their owned vehicle onto the dealer’s sell zone and sells it for an instant bank payout. The acquired car enters the dealer’s used-vehicle inventory.

Transfer Vehicle

Config.Purchase.TransferVehicle = {
    enabled = true,
    command = 'transfervehicle',
    description = 'Transfer vehicle ownership to a nearby player',
    maxDistance = 10.0,
    blockIfFinanced = true,
    requireConsent = true,
    consentTimeout = 30,
}

Key	Description
blockIfFinanced	Block transfer of vehicles with an active loan.
requireConsent	When true, the recipient must accept the transfer.
consentTimeout	Seconds the recipient has to respond.
maxDistance	Server-authoritative max metres between giver and recipient.
blockedModels	Model spawn codes that can never change hands (transfer, sell-to-dealer, trade-in are all refused). Managed live in the admin panel; this list is the first-boot seed.

Security

Config.Purchase.Security = {
    purchaseCooldown = 5,
    maxDistance = 12.0,
}

Key	Description
purchaseCooldown	Seconds between purchase attempts per player.
maxDistance	Max metres from the browse zone when buying.

---

Vehicles

Colors

Config.Vehicles.Colors = {
    mode = 'palette',
    allowColors = true,
    allowSecondary = true,
    allowPearlescent = false,
    allowChameleon = false,
    palette = {
        { id = 0,   name = 'Black',    hex = '#0d1116' },
        { id = 111, name = 'White',    hex = '#fffff6' },
        -- ... more colours
    },
}

Key	Description
allowColors	Master switch for customer colour selection at purchase time.
mode	palette (palette only), ids (raw GTA IDs 0-160), or rgb (free-form wheel).
allowSecondary	Enable two-tone paint.
allowPearlescent	Enable third colour picker (pearlescent).
allowChameleon	Enable colour-cycling paint.
palette	List of { id, name, hex } entries. Hex values must match the actual in-game RGB for each GTA ID.

Appearance

Config.Vehicles.Appearance = {
    allowExtras = true,
    allowLiveries = true,
}

false hides the picker entirely; true (default) shows it only when the spawned vehicle actually exposes extras or liveries.

Preview

Config.Vehicles.Preview = {
    dragSensitivity = 0.005,
}

Mouse-drag sensitivity for orbiting the 3D showroom preview camera. Camera framing and lighting are hard-coded internally.

Fuel

Config.Vehicles.Fuel = {
    defaultLevel = 100.0,
}

Fuel level applied to every vehicle this resource spawns (purchase delivery, test drives, trucking cab). The running fuel resource is auto-detected at runtime — 19 fuel scripts are supported with no manual wiring.

---

Business

Player-owned dealership businesses. A shop becomes ownable when ownable = true.

Config.Business = {
    managementMode = 'business',
    ownerRole = 'owner',
    roles = { ... },
    roleOrder = { 'intern', 'sales', 'senior_sales', 'supervisor', 'manager', 'owner' },
    salesRadius = 5.0,
    salesDistanceNag = true,
    jobMode = { ... },
    shopCreditPct = 0.10,
    repCommissionPct = 0.05,
    salaries = { ... },
    commission = { ... },
}

Management Modes

Mode	Description
business (default)	Self-contained ownership with employees, balance, and payroll. Framework used only for money and identity.
job	Lean on the framework job system. No ownership, no balance, no in-game payroll. Framework society/boss menu handles all payouts.

Roles

Roles are ranked low to high in roleOrder. A lower rank cannot hire or promote above its own. Financing and test-drive access are governed globally, not by role keys. See the Owner Guide for the full role hierarchy and permission matrix.

Commission

Config.Business.commission = {
    enabled = true,
    rates = {
        intern       = 0.00,
        sales        = 0.05,
        senior_sales = 0.07,
        supervisor   = 0.08,
        manager      = 0.10,
    },
    selfServeMultiplier = 0.5,
    creditHouseOnNoStaff = true,
    requireOnSite = true,
    onSiteRadius = 60.0,
}

Per-role sales commission paid instantly to the rep’s bank on every sale.

Key	Description
rates	Per-role fraction of base sale price.
selfServeMultiplier	Applied to each rep’s cut on self-serve sales.
creditHouseOnNoStaff	Credit the pool to the shop balance if no reps are online.
requireOnSite	Only employees physically present at the dealership earn commission.
onSiteRadius	Metres from any shop point that counts as “on-site”.

Salaries (Business Mode Only)

Config.Business.salaries = {
    enabled = true,
    intervalHours = 24,
    minBalanceBuffer = 0,
    maxSalary = 50000,
}

Hiring Consent

Config.Business.hireConsent = {
    enabled = true,
    timeout = 60,
}

Key	Description
enabled	When enabled, hiring sends a confirmation prompt the candidate must accept.
timeout	Seconds before the job offer expires.

Sales Floor

Key	Description
salesRadius	Metres; rep and customer must be within this distance for an assisted sale.
salesDistanceNag	Notify the customer when a rep starts a sale for them.

---

Integrations

Config.Integrations = {
    okokContract = { enabled = false, resource = 'okokContract', event = 'okokContract:CreateContract' },
    qbVehicleSales = { enabled = false, resource = 'qb-vehiclesales', table = 'vehiclesales' },
    forceSaleAllowList = {},
    discordWebhook = { enabled = false, ... },
    Hooks = { enabled = true },
}

Key	Description
okokContract	Generate a purchase contract per sale via okokContract.
qbVehicleSales	Mirror each sale into the qb-vehiclesales listings table.
forceSaleAllowList	Restricts mutating exports (forceSale, addVehicle) to listed resources. Empty = open by default.
discordWebhook	Discord rich embeds for sales, repossessions, and coupon redemptions.
Hooks.enabled	Toggles the prePurchase and postSale hook events.

---

Contract

Config.Contract = {
    enabled = true,
    timeoutSec = 120,
    selfServeTimeoutSec = 300,
    requireNameMatch = true,
    showForSelfServe = true,
    offerSound = true,
    terms = { cash = 'contract_terms_cash', finance = 'contract_terms_finance' },
}

Purchase agreement shown before payment is taken. The buyer must type their full name to sign (when requireNameMatch is true). timeoutSec expires assisted offers; selfServeTimeoutSec releases pending self-serve offers.

---

Image Capture

Config.ImageCapture = {
    enabled = true,
    studio = { coords = vector3(0.0, 0.0, -150.0), heading = 80.0, routingBucket = 900,
               size = { w = 30.0, d = 30.0, h = 15.0 }, chroma = { r = 0, g = 177, b = 64 } },
    camera = { fov = 40.0, angleH = 315.0, elevation = 14.0, ... },
    output = { width = 512, height = 512 },
}

Note: The image capture upload provider config (webhook URL / API keys) lives in server/utils.lua via Server.GetUploadConfig — not in config.lua — because config.lua ships to every client and secrets must stay server-side. Set uploadProvider (discord | fivemanage | fivemerr | wew | custom) and fill in the matching webhook/apiKey in the uploadProviders table; Discord needs your channel webhook URL, Fivemanage/Fivemerr need your API key, wew needs nothing. See Installation.

---

Admin-Editable Live Settings

Several config values are marked [Admin-editable] in config.lua. These load their factory default from config.lua on first boot, but can be overridden at runtime via the Admin Panel → Settings tab. Overrides are stored in ars_cardealer_settings and take precedence over config.lua until cleared.

To clear a live override and revert to the config.lua default:

DELETE FROM ars_cardealer_settings WHERE `key` = 'your_setting_key';

---

Note: This guide is written by a third party. If you find any incorrect or outdated information, please contact us on Discord so we can update it for you.