OrigenNetwork
Docs

Custom · origen_dealerships

The custom/ folder contains all integration points between origen_dealerships and the rest of your server stack. These files are not escrowed and must be adapted to your specific setup.

text
custom/
├── client/
│   ├── framework.lua   — player identifier, vehicle props, NPC interaction
│   ├── keys.lua        — vehicle key assignment on purchase
│   └── notify.lua      — notifications and text UI
└── server/
    ├── framework.lua   — admin check, payments, vehicle DB insertion
    ├── financing.lua   — financing eligibility hook
    └── plate.lua       — plate generation and uniqueness check

custom/client/framework.lua

Custom.GetPlayerIdentifier()string

Returns the local player's unique identifier (citizenid or identifier depending on framework).

lua
Custom.GetPlayerIdentifier = function()
    local identifier = nil
    if Config.Framework == 'qb-core' then
        identifier = Framework.Functions.GetPlayerData().citizenid
    elseif Config.Framework == 'esx' then
        identifier = Framework.GetPlayerData().identifier
    end
    return identifier
end

Custom.HandleInteraction(interactionData)boolean

Hook called when a player attempts to interact with a dealership NPC. Return true to override the default interaction flow, false to let the resource handle it normally.

ParameterTypeDescription
interactionData.typestringInteraction type. Currently: 'npc'
interactionData.onInteractfunctionCall this to trigger the default interaction from within the hook
lua
Custom.HandleInteraction = function(interactionData)
    if interactionData.type == 'npc' then
        -- interactionData.onInteract() -- uncomment to delegate back
        return true -- return true to fully take over
    end
    return false
end

NPC interaction override is disabled by default (return false). Enable it if you want to use a custom ox_lib context menu or a third-party interaction resource.


Custom.GetVehicleProps(vehicle)table

Returns the properties of the given vehicle entity. Uses lib.getVehicleProperties when Config.VehiclePurchase.useOxLibProps is true.

ParameterTypeDescription
vehicleentityThe vehicle entity handle
lua
Custom.GetVehicleProps = function(vehicle)
    if Config.VehiclePurchase.useOxLibProps and lib and lib.getVehicleProperties then
        return lib.getVehicleProperties(vehicle)
    end
    -- fallback: returns basic props table
end

Custom.SetVehicleProps(vehicle, props)boolean

Applies a properties table to a vehicle entity. Uses lib.setVehicleProperties when available.

ParameterTypeDescription
vehicleentityThe vehicle entity handle
propstableProperties table (same format as GetVehicleProps)

custom/client/keys.lua

Custom.GiveKeys(vehicle, plate)boolean

Grants the local player ownership keys for the specified vehicle. Called automatically after purchase when Config.VehiclePurchase.giveKeysOnPurchase is true.

ParameterTypeDescription
vehicleentity | nilVehicle entity. If nil, plate is used
platestring | nilLicense plate. Used as fallback if entity is not available
lua
Custom.GiveKeys = function(vehicle, plate)
    local plateToUse = plate or (DoesEntityExist(vehicle) and GetVehicleNumberPlateText(vehicle) or nil)
    TriggerEvent("vehiclekeys:client:SetOwner", plateToUse)
    return true
end

The default implementation fires the vehiclekeys:client:SetOwner event (compatible with qb-vehiclekeys). Replace this function if your server uses a different key system such as qs-vehiclekeys or vehicles_keys.


custom/client/notify.lua

Custom.Notify(text, type, length)

Displays a notification to the local player using lib.notify.

ParameterTypeDescription
textstringAlready-translated message
typestringNotification type: 'success', 'error', 'warning', 'info'
lengthnumberDuration in milliseconds
lua
Custom.Notify = function(text, type, length)
    lib.notify({
        title       = 'Origen Dealerships',
        description = text,
        type        = type,
        duration    = length
    })
end

Custom.DrawText(text, key)

Shows the ox_lib text UI with a key hint.

ParameterTypeDescription
textstringLabel text
keystringKey label shown in brackets

Custom.HideText()

Hides the active ox_lib text UI.


custom/server/framework.lua

Custom.isAdmin(source)boolean

Checks whether the given player source has admin permissions according to Config.AdminGroups.

ParameterTypeDescription
sourcenumberPlayer server ID

Custom.getPlayerIdentifier(source)string | nil

Returns the player's unique identifier (citizenid for QB/QBX, identifier for ESX).

ParameterTypeDescription
sourcenumberPlayer server ID

Custom.doPayment(source, paymentData)boolean

Processes a payment from a player's account. Supports cash, bank, and xp methods.

ParameterTypeDescription
sourcenumberPlayer server ID
paymentData.methodstringPayment method: 'cash', 'bank', 'xp'
paymentData.amountnumberAmount to deduct
lua
Custom.doPayment = function(source, paymentData)
    -- Handles cash/bank via framework, XP via exports['origen_xp']
end

The 'xp' payment method requires origen_xp to be running. It calls exports['origen_xp']:RemoveXPFromLicense(license, amount).


Custom.removeFinanceMoney(source, amount)boolean

Deducts a financing installment payment from the player's bank account.

ParameterTypeDescription
sourcenumberPlayer server ID
amountnumberAmount to deduct from bank

Custom.addVehicleToDatabase(source, vehicleModel, plate, props, callback)

Inserts a purchased vehicle into the appropriate vehicles table for the active framework.

ParameterTypeDescription
sourcenumberPlayer server ID
vehicleModelstringVehicle model name (spawn name)
platestringLicense plate string
propstable | nilVehicle properties. If nil, defaults are used
callbackfunction(success, message)Called after the DB insert completes

Target tables:

FrameworkTable
QBCore / QBXplayer_vehicles
ESXowned_vehicles

Custom.GetPlayerSourceByIdentifier(identifier)number | nil

Finds an online player's server source ID by their unique identifier. Used for financing payment notifications.

ParameterTypeDescription
identifierstringcitizenid (QB/QBX) or identifier (ESX)

Custom.canBuyCategory(source, categoryKey, vehicleModel){ cant: boolean, msg: string }

Hook to add custom restrictions on vehicle category purchases. Return cant = false with a message to block the purchase.

ParameterTypeDescription
sourcenumberPlayer server ID
categoryKeystringThe dealership category identifier
vehicleModelstringVehicle model being purchased
lua
Custom.canBuyCategory = function(source, categoryKey, vehicleModel)
    -- Example: block category for players without a license
    return { cant = true, msg = "" }
end

custom/server/financing.lua

Custom.canFinanceVehicle(source, model, price, period){ success: boolean, message: string }

Hook called before creating a financing contract. Return success = false with a message to block the operation.

ParameterTypeDescription
sourcenumberPlayer server ID
modelstringVehicle model
pricenumberTotal vehicle price
periodnumberRequested number of payment periods
lua
Custom.canFinanceVehicle = function(source, model, price, period)
    return { success = true, message = '' }
end

custom/server/plate.lua

Custom.GeneratePlate()string | nil

Generates a unique 8-character license plate (4 letters + 4 digits). Retries up to 100 times to avoid collisions. Returns nil if no unique plate is found after max attempts.


Custom.PlateExists(plate)boolean

Checks whether a given plate is already registered in the vehicles table.

ParameterTypeDescription
platestringLicense plate to check

Queries player_vehicles for QBCore/QBX and owned_vehicles for ESX.