Custom framework: DashKart docs

DashKart supports QBox, QBCore and ESX Legacy out of the box. For any other framework you fill in one file: bridge/framework/custom.lua. It is not escrowed, and it is the only place where DashKart talks to your framework.

1. Select the custom adapter

config/main.lua:

Config.Bridge = {
    framework = 'custom',
    -- inventory, target, vehiclekeys, fuel, notify as before
}

The custom adapter is also picked automatically when none of qbx_core, qb-core or es_extended is running. Make sure your framework starts before DashKart in server.cfg either way.

2. Fill in the functions

Every function in the file is marked >>> FILL IN <<< and documented with its parameters and return type. Out of the box the template runs “standalone”: license identifiers, FiveM player names, and money functions that log a warning and refuse (so nobody is paid or charged until you wire them up).

Server functions (all required)

#	Function	Returns	Notes
1	`GetPlayer(src)`	player object or `nil`	`nil` = character not loaded; DashKart then refuses that player’s actions
2	`GetIdentifier(src)`	string (max 64 chars)	persistent character id (citizenid / charid). Key for rider stats, store ownership and staff
3	`GetCharName(src)`	string	“Firstname Lastname”, shown to owners, admins and in logs
4	`GetJob(src)`	`{ name, label, grade, gradeLabel, onDuty }`
5	`SetJob(src, name, grade)`	boolean	only called when `Config.Rider.useFrameworkJob = true`
6	`GetMoney(src, account)`	integer	`account` is `'cash'` or `'bank'`
7	`AddMoney(src, account, amount, reason)`	boolean	rider pay, tips, deposit refunds, store withdrawals and sales. `amount` is always a positive integer
8	`RemoveMoney(src, account, amount, reason)`	boolean	rental deposits, fines, store purchases and deposits. Must return `false` and change nothing when the balance is too low
9	`RegisterUsableItem(name, cb)`	-	call `cb(src)` when the item is used (the tablet). Can stay empty if your inventory calls the `dashkart.useTablet` export instead
10	`OnPlayerLoaded(cb)`	-	call `cb(src)` when a character has loaded
11	`OnPlayerUnloaded(cb)`	-	call `cb(src)` on logout and on drop. Firing twice for the same player is fine
12	`IsAdmin(src)`	boolean	gate for `/dashkart admin`, the admin panel and debug commands
13	`GetPlayers()`	integer[]	server ids with a loaded character. The default (native player list) is usually fine

IsAdmin: the template checks the ace in Config.Admin.ace (dashkart.admin). If you replace the body with your own staff check, keep that line so add_ace group.admin dashkart.admin allow keeps working:

if IsPlayerAceAllowed(src, Config.Admin.ace) then return true end

ServerNotify(src, msg, type) is only used when Config.Bridge.notify = 'framework'; with the default 'ox' notifications go through ox_lib.

Client functions

Function	Required	Notes
`IsLoaded()`	yes	is the local character loaded?
`GetJob()`	yes	same shape as the server
`OnPlayerLoaded(cb)`	yes	call `cb()` when the local character loads. DashKart uses it to restore an ongoing shift after a relog or resource restart
`OnPlayerUnloaded(cb)`	yes	call `cb()` on logout (ends the local shift state). Can stay empty if your framework has no logout
`ClientNotify(msg, type)`	only with `notify = 'framework'`

Optional: framework inventory

If your server runs one of the supported inventories (ox_inventory, qs-inventory, codem-inventory, core_inventory, qb-inventory), leave Framework.NativeInventory = nil. Otherwise fill it in so DashKart can give and check the tablet item:

Framework.NativeInventory = {
    AddItem = function(src, item, count, metadata) return true end,   -- true only if added
    RemoveItem = function(src, item, count) return true end,          -- false if not enough
    GetItemCount = function(src, item) return 0 end,
    CanCarry = function(src, item, count) return true end,
    GetItemLabel = function(item) return item end,
}

Without any inventory, set Config.Tablet.requireItem = false so the tablet opens with F6 without an item.

Framework job (optional)

With Config.Rider.useFrameworkJob = true, clocking in sets the job in Config.Rider.job (default dashkart, grade 0) and restores the previous job on clock-out. That job must exist in your framework. With the default false, DashKart keeps its own duty state and never touches jobs.

3. Verify

Restart the server. The console should show:

[DashKart] INFO Bridge framework   -> custom (config)
[DashKart] INFO DashKart v1.0.1 by MBTH Studios ready (NPC customers: true, player customers: false)

A missing function is reported as Bridge Framework adapter "custom" is missing X() and DashKart will not start until it is fixed. Unimplemented functions that still have the template body log custom framework: X is not implemented the first time they are used.

Then turn on debug mode with setr dashkart:debug "true" in server.cfg (before ensure dashkart), restart, and run /dk_bridgetest in game as an admin. It calls every function live on your character and prints PASS/FAIL for each one, then SUMMARY X/Y passed, in the server console and your F8 console. The money test adds 1 to the bank and removes it again; the item test adds and removes one Config.DebugTest.item. Fix every FAIL, then remove the dashkart:debug line (or set it to "false") again.

Other integrations

Only the framework has an open template. For the other categories DashKart falls back to a safe default when it finds none of the supported resources:

Category	Fallback	What you lose
Inventory	framework inventory (`NativeInventory` above, or the built-in one of ESX / QBCore)	nothing, if the framework inventory works
Target	ox_lib TextUI, press `E`	nothing; prompts look different
Vehicle keys	none: rentals are left unlocked	key items / key UI
Fuel	GTA native fuel level	your fuel script’s display may not match

If your inventory, target, key or fuel script exposes the same exports as one of the supported resources (many do, e.g. qb-target or qb-inventory compatible APIs), force that adapter in Config.Bridge, for example target = 'qb'.

Rules

DashKart calls these functions only on the server side with server-computed amounts; never pass client values into them from elsewhere.
Do not rename functions or change their return shapes.
Keep money functions strict: return true only when the money really moved.