How to Add a Mechanic Job to Your QBCore FiveM Server

A practical guide to how to add a mechanic job to your qbcore fivem server, with implementation decisions, validation steps, and security considerations for a production-minded project.

Summary: This guide walks you through adding a robust, secure mechanic job to a QBCore FiveM server. It covers architecture, data model, server/client responsibilities, common implementation choices (ox_lib, qb-bossmenu, inventory integrations), security and validation patterns, testing strategies, and deployment/maintenance best practices. Follow the server-first patterns: never trust client input for critical state changes such as job assignment, billing, or inventory transactions.

1 — High-level architecture and responsibilities

Design the mechanic job using a clear separation of responsibilities. Use the server to own authoritative state (player job, money, database updates) and the client to provide presentation and local interactions (animations, UI). Typical components:

Core: QBCore job definition and any required shared configuration (shared/jobs.lua).
Server: job handlers, billing, inventory checks, job promotions, database persistence, RPC endpoints and callbacks.
Client: targeting UI (ox_target/3dtext), animations, progress bars, local vehicle repairs, and hit detection.
Optional: third-party libraries like ox_lib for UI utilities, qb-bossmenu for job management, qb-phone for billing notifications.

Stellar AI can help generate and revise the project files for this workflow. Describe your framework, existing dependencies, and one testable feature, then bring back errors for a focused revision. You remain responsible for running the tests and managing deployment in your own development environment.

2 — Database and job configuration

Add a job entry in your QB core configuration so players can be assigned the mechanic job and grades. Edit qb-core/shared/jobs.lua and add a new table entry like this:

["mechanic"] = {
  label = "Mechanic",
  defaultDuty = true,
  grades = {
    ["0"] = { name = "Trainee", payment = 20 },
    ["1"] = { name = "Mechanic", payment = 40 },
    ["2"] = { name = "Supervisor", payment = 70 }
  }
}

QBCore uses the player job saved field to persist job state. If you plan to allow recruitment via a boss menu, ensure your job supports grade permissions and that you wire qb-bossmenu or a custom admin UI to call the server-side API to set a player's job.

Schema guidance

Keep persistent job fields in the player table managed by QBCore. Avoid adding duplicate job columns.
If you store owned vehicles or mechanic invoices, use dedicated tables: mechanic_invoices (id, sender, receiver, amount, paid, createdAt) and vehicle_maintenance (vehicle_plate, last_service, notes).
Index frequently queried columns (player identifier, plate, paid flag) for performance.

3 — Server-side design and API surface

All authoritative actions must be executed on the server. Implement clear event and callback names and minimize arguments from the client. Example server API responsibilities:

Assign/remove job: only by staff or boss menu; validate caller permissions server-side.
Create and charge invoices: validate sender job, ensure target exists, store invoice row, notify via qb-phone/server event.
Approve repairs: server checks player's job, funds or item ownership, then instruct the client to perform local repairs.

Example server-side pattern (pseudocode):

local QBCore = exports['qb-core']:GetCoreObject()

RegisterNetEvent('mechanic:server:attemptRepair', function(vehiclePlate, estimate)
  local src = source
  local Player = QBCore.Functions.GetPlayer(src)
  if not Player or Player.PlayerData.job.name ~= 'mechanic' then
    TriggerClientEvent('QBCore:Notify', src, 'You are not a mechanic', 'error')
    return
  end

  -- validate funds server-side
  if Player.Functions.RemoveMoney('cash', estimate) then
    -- safe: server authorizes action, client only performs visual and local entity modifications
    TriggerClientEvent('mechanic:client:performRepair', src, vehiclePlate)
  else
    TriggerClientEvent('QBCore:Notify', src, 'Insufficient funds', 'error')
  end
end)

Notes:

Do not trust vehiclePlate or entity IDs sent from the client for authorization — use server-side ownership checks where possible.
Prefer calling Player.Functions.RemoveMoney/Payment APIs provided by QBCore to maintain atomicity and avoid race conditions.

4 — Client-side roles and safe interactions

The client should be responsible for UX: showing menus, targeting vehicles, playing animations, and applying the local repair effect when the server authorizes it. Keep these rules:

The client triggers minimal events like "request repair" but does not directly change money or job data.
When the server authorizes an action, the server triggers a client event with a minimal payload. To limit abuse, do not include sensitive arguments like payment outcomes or server-side identifiers.
For vehicle repair visuals, the client can repair the local vehicle entity after server authorization. The actual record of the repair should be stored on the server (invoice/maintenance log).

Example client flow:

Player targets vehicle and selects "Repair".
Client sends TriggerServerEvent('mechanic:server:attemptRepair', plate, estimate).
Server checks job and charges, then sends TriggerClientEvent('mechanic:client:performRepair', src).
Client plays animation, progress bar, and repairs local vehicle entity.

5 — Integration choices: ox_lib, ox_target, qb-bossmenu, ox_inventory

Depending on your server, integrate with quality-of-life libraries:

ox_target or qb-target: Use these for contextual target interactions on vehicles and NPCs.
ox_lib: Provides common UI components, notifications, and liberation from boilerplate.
qb-bossmenu: Use for hiring, promoting, and firing mechanics through a UI that performs server-side authorization.
ox_inventory/qb-inventory: Ensure any item consumption (repair kits) is performed atomically on the server.

Integration best practice: wrap library calls in your own server endpoints so you can swap out implementations later without changing business logic.

6 — Security and server validation checklist

Security is critical. Use the checklist below during development and code review.

Area	Action	Why it matters
Job assignment	Only allow server-side changes via authenticated admin or boss routes	Prevents client spoofing of job privileges
Billing & Payments	Validate and remove funds on server, persist invoices in DB	Keeps monetary state authoritative and auditable
Vehicle ownership	Verify plate/owner server-side before granting free repairs	Prevents griefing or unauthorized repairs
Item consumption	Consume items only via server APIs; return failure state if missing	Prevents duplication exploits
Events	Named and namespaced events; rate-limit high-frequency actions	Reduces accidental collisions and DoS surface

7 — Testing strategy and QA

Test the mechanic job across the following dimensions:

Functional: recruit/promote, repair flow, invoice creation and payment, item usage.
Security: attempt client-side spoofing (fake job, fake server events) — server should reject.
Edge cases: unexpected disconnect during repair, simultaneous payments, DataStore or MySQL failures.
Performance: measure server CPU during job-heavy scenarios (multiple simultaneous repairs) and tune queries.

Automated tests:

Unit test database queries where possible.
Write integration tests that simulate job assignment and payment flows using tools that can call server events.
Use staging servers and player testing sessions to validate UI/UX and concurrency.

8 — Deployment and maintenance

Deploy using a staged pipeline: local development → staging → production. Key items:

Version control all resources. Tag releases and maintain changelogs for server admins.
Apply database migrations in a controlled manner. Backup before running migrations.
Monitor server logs for suspicious events tied to job APIs and billing endpoints.
Provide admin commands to roll back invoices or revert job changes in emergencies.

9 — Maintenance: monitoring and telemetry

Routine maintenance tasks:

Review server logs weekly for errors tied to mechanic job events.
Audit job grade permissions if new grades are added.
Reconcile invoices and payments daily — add automated alerts for payment failures.
Update third-party libraries and test integrations (ox_lib, qb-bossmenu) in a staging environment.

10 — Roblox considerations (if you map similar concepts)

If you run a Roblox game with mechanic-like roles, follow these server-authority best practices:

Use RemoteEvents/RemoteFunctions with server validation: client requests should always be validated on the server before making state changes.
Gracefully handle DataStore failures: implement exponential backoff and retries, and show safe fallback UI when saves fail.
Use BindableEvents within server-only logic to decouple modules rather than broadcasting to clients directly.

Even though mechanics differ across platforms, the same principle applies: server owns the truth, clients present results.

Practical implementation checklist

Create job entry in qb-core/shared/jobs.lua and define grades.
Implement server endpoints for: hire/fire, create invoice, attempt repair, confirm payment.
Integrate with inventory system for repair kits and ensure server-side consumption.
Wire ox_target or qb-target to provide client interaction points.
Add client handlers that only act after server authorization events.
Implement persistence: invoice and maintenance tables; add backups and migrations.
Test security by attempting to call events directly; fix any paths where client can mutate authoritative state.
Deploy to staging and validate concurrency and rollback paths.

Files and responsibilities (quick reference)

File/Resource	Responsibility
shared/jobs.lua	Declare job, labels, and grade config
server/main.lua	Server event handlers, billing, DB writes
client/main.lua	UI, targeting, animations, local repair effects
sql/migrations	Schema for invoices and maintenance logs

Troubleshooting common issues

Players appear with incorrect jobs: ensure job is saved correctly and that you don’t have conflicting custom resources overriding player load handlers.
Repairs not applying: confirm client receives the server authorization event and that local entity mapping of plates/netIDs is correct.
Duplicate items after repair: make sure item consumption happens server-side and confirm returns are atomic.
Boss menu no-op: verify qb-bossmenu events trigger server functions that authorize job changes.