nCore Vehicle Inspection – walk-around checks, mechanic diagnostics with fault codes documentation

nCore Development · intelnpc.com · Resource: ncore_vehicle_inspection · Version: see fxmanifest.lua

What it is#

Anyone can walk around a parked vehicle with /vinspect and get a plain verdict on each part. A mechanic runs a timed scan with /vdiag and gets a report with fault codes, a repair estimate and a pass or fail. A passing scan issues a certificate tied to the plate, and police read that certificate on a roadside check with /vroadside.

It needs OneSync and nothing else. With ESX, QBCore or QBox it reads jobs, grades and character names. Without a framework, access works through ACE permissions.

Features#

Civilian walk-around#

• /vinspect works for everyone, no job or item needed. It picks the nearest vehicle within 8 m, and the one you sit in wins.
• Up to 22 point types per vehicle: wheels, doors, hood, trunk, headlights, windshield, bumpers, underside and more. Positions come from the bones of the real vehicle.
• A colored marker on each point, and a bracket with a label and an "n/m" counter on the one you have selected. A light shows on the selected point at night.
• Point selection by aim, by distance or a mix of both (mixed is the default). The mouse wheel cycles between close points.
• E inspects a point. Your ped turns to it, plays a pose and an idle clip, and the server sends back a verdict.
• Verdicts are plain language in six bands, from excellent to critical, with a little random fuzz. There are 162 hand-written lines, three phrasings for every group and band.
• Extra alerts for burst tires, rim damage, broken windows, damaged doors, broken headlights, low oil, overheating, a very dirty car and an engine that is off. The vehicle-wide ones (low oil, overheating, dirty, engine off) show once per walk-around.
• Open and close the hood and trunk with E. Engine bay, fluids and cargo area stay blocked until the lid is open.
• Locked cars stay locked. The doors are refused, and the hood and trunk only open for the player driving the car, a player who drove it in the last 5 minutes, or whoever your keys hook allows. Config.Interaction.RespectVehicleLocks = false turns the lock check off.
• Kick the tire on a wheel you already inspected.
• A cinematic close-up camera on the point, during the inspection or after a poor result.
• Doors the tool opened are closed again when you finish.
• An overall summary after enough points are checked (4 by default).
• A log at the end: a full screen sheet, an ncore_hud card, an in-world tablet, or nothing.
• Vehicle class filter (boats, planes, helicopters, trains and bicycles are ignored by default), and moving vehicles are refused.
• X stops. It also ends on its own if the vehicle is gone or you walk more than 7.5 m away.
• Attacking, aiming and the weapon wheel are blocked while you walk around.
• Roleplay /me lines at the main steps.

Mechanic diagnostic scan#

• /vdiag for mechanics. The hood opens, a tablet comes out, the scanner beeps and a 16 second scan runs through six named stages.
• 19 readings per scan: engine, body, fuel tank, fuel, oil, temperature, rpm, gear, turbo, dirt, worst and average wheel, burst tires, damaged doors, broken windows, broken headlights and deformation.
• 23 fault codes ship ready to use, such as ENG, OIL, TYR and SUS codes. Each has a severity: critical, major, advisory or info. Edit them or add your own in config/config.lua.
• Pass or fail rules: a limit of faults per severity, hard minimums (engine, body, fuel tank, worst wheel, burst tires, headlights) and an optional fail on handling tamper.
• A condition score from 0 to 100, weighted over 10 readings.
• A repair estimate with a call-out fee, per-part counts and per-severity charges. You set the currency and the rates.
• Deformation heatmap: 30 samples over the vehicle in nine zones. The dents show as colored spheres on the car for 9 seconds, and the sheet lists the zones.
• Scanner beeps and a chime when the scan ends.
• The result opens as a full screen sheet, on the tablet prop, as one notification, or not at all.
• X aborts the scan.

Certificates#

• A passing scan issues a certificate tied to the plate. It is valid for 30 days by default (1 to 3650 days).
• A certificate with more than 7 days left is returned unchanged, so it can't be renewed early.
• A failed scan revokes a certificate that is still valid. An unverified scan does not revoke it.
• /vcert shows the status of the nearest vehicle to anyone: valid, expired, revoked or missing.
• An expiry watcher fires the certificateExpired event once per certificate and deletes records that expired more than 90 days ago.
• Revoke from the server console with lrvi_revoke <plate>, or with the revokeCertificate export.

Handling tamper detection#

• The scan reads 13 handling values and never changes them.
• Each value is compared against a baseline for the model, with its own tolerance.
• The result is stock, tampered, learning or unknown.
• A tampered car gets the fault HND-001 and fails the scan. Police see the flag on a roadside check.
• No baselines ship. You add them in Config.Handling.Baselines, or you turn on learning with AllowLearningInRelease. Until then every model reads as unknown.
• lrvi_resetbaseline <model> clears a baseline.

Police roadside check#

• /vroadside (alias /vcertcheck) for police.
• The officer inspects checkpoints with E. The server counts the distinct points it accepted and needs at least 3.
• A clipboard animation closes the check.
• The server checks the certificate, tires, headlights, body, glass and handling tamper. Taillights show as not checked.
• Result: PASS, WARNING or FAIL, a defect count, and a chip per check: within legal limits, borderline, outside legal limits or could not be checked.
• Defaults: no certificate, expired or revoked is a FAIL. A certificate that expires within 3 days is a WARNING. A burst tire is a FAIL. One broken headlight or window is a WARNING, two are a FAIL. Tampered is a FAIL.
• Exact numbers and fault codes on the sheet are opt-in. The tamper flag is on by default.
• The roadsideCompleted event and the lrvi:roadside state bag carry the result.

Road test#

• /vroadtest for mechanics. A timed drive, 45 seconds by default, in the driver seat.
• It records acceleration, braking, straight-line stability, wheel slip events, top speed and distance.
• The server gives each measure a score from 0 to 100 and an overall score. The verdict is good, pulls, loose, soft or inconclusive.
• Runs that are too short or have too few samples come back inconclusive.
• A live panel on ncore_hud, or a built-in panel if you don't run it.
• The roadTestCompleted event fires for every accepted run.

Pre-purchase inspection#

• /vprepurchase for mechanics, for the buyer's side of a sale.
• The owner (the current driver, or a driver from the last 5 minutes) gets a Y/N prompt that lasts 20 seconds.
• On Y the mechanic's scan runs, and the owner gets a copy of the report.

Reports and screens#

• Full screen report sheets for the mechanic scan, pre-purchase, police roadside check, road test and walk-around. Score ring, reading cards, fault list, handling table, and the roadworthy result.
• Mechanic sheets use a purple and orange theme, police sheets pink and blue.
• Blur behind the sheet. Close it with Escape, Backspace or the Close button.
• An in-world tablet that shows the report on the prop screen. It is off by default.
• Everything runs offline: no CDN, no remote fonts, no remote images.
• With ncore_hud: a walk-around tracker, a police checkpoint tracker, a scan stepper, a road-test card, a PASS/FAIL title card and a repair receipt.
• Notifications go through ncore_hud, ox_lib, qbx_core, qb-core or es_extended, whichever starts first. You can pick one, set a fallback (GTA feed, built-in toasts or chat) or use your own function.

Permissions and roles#

• Mechanic and police access by job and minimum grade, by ACE, or both. Admin access is by ACE only.
• Mechanic jobs by default: mechanic, bennys, lscustoms (grade 0) and cardealer (grade 2). Police jobs by default: police, sheriff, bcso, sast, lspd and state (grade 0).
• An optional on-duty rule for each list.
• The roles are separate. A mechanic permission never opens police tools.
• /vrole <police|mechanic|civil> gives an admin a role for this resource only.
• ACEs: ncore_vehicle_inspection.mechanic, ncore_vehicle_inspection.police, ncore_vehicle_inspection.admin.
• An optional keys or ownership hook (an export or a callback) decides who may scan a vehicle. It is off by default. Turn it on in ConfigServer.Authorization. Your function gets (src, netId, plate, action), where action is tier1, tier2, roadtest, roadside or owner, and returns true to allow. With the hook on, a mechanic can still scan a car through /vprepurchase once its owner pressed Y.

Server checks#

• The server builds every verdict, report and certificate itself, from the readings your client sends.
• On scans and roadside checks the server reads engine, body and tank health and burst tires itself. If all three health reads come back at zero, the scan counts as unverified and can't pass.
• Each scan uses a single-use token, a minimum time (90% of the scan), a 5 minute session life, and checks for distance (12 m), speed and a living player.
• A per-player rate limit on every action.
• Sessions that go quiet are aborted after 5 minutes, and everything is cleaned up when a player drops or the resource stops.

Setup#

• Framework detected at start: QBox, then QBCore, then ESX, otherwise standalone. You can force one with Config.Framework.
• Saves with oxmysql when it's running, otherwise to JSON files in data/. The tables are created for you, and sql/ncore_vehicle_inspection.sql is included.
• Eight module switches: cinematic camera, emotes, kick the tire, road test, deformation heatmap, tablet, pre-purchase and scanner sound.
• Command names, aliases and the /vi words can be renamed. Set a direct command to '' to drop it.
• Key mappings in the FiveM key settings: interact E, stop X, accept Y, refuse N.
• A startup check that clamps and warns about bad config values.
• Optional webhook logging for certificates, roadside checks and tamper. It needs ConfigServer.Logging.Enabled = true as well as a webhook URL.

Language#

• English ships. Every text is in locales/en.lua, including all 162 verdict lines.
• With Config.Locale = 'auto' the resource takes the first of the lr:locale, locale, ox:locale, esx:locale and txAdmin-locale convars that has a matching file, then the player's GTA language, then English. Set Config.Locale = 'en' (or your code) to pick one yourself. The client only sees convars set with setr.
• To add a language, copy locales/en.lua to a new file in locales/ (for example de.lua), change Locales['en'] and the meta block at the top to the new code, and translate the texts. The manifest loads every file in locales/.

Admin and test tools#

• /vdemo (alias /vinspectdemo) spawns a sultan with random damage and wear, one per player. Admin, mechanic and police can use it.
• /vtow and /vpatrol give an admin a role kit: a role, a ped and a vehicle.
• Dev mode (Config.Dev) is off by default. Keep it off on a live server.
• /videbug prints what the resource detected to the F8 console.

For developers#

• Client exports: startWalkaround, startDiagnostics, startRoadsideCheck, startRoadTest, requestPrePurchase, isInspecting. Use them from ox_target, a radial menu or an item. They go through the same permission checks as the commands.
• 16 server exports, among them getCertificate, isRoadworthy, issueCertificate, revokeCertificate, getLastInspection, getInspectionHistory, getHandlingBaseline, resetHandlingBaseline, migratePlate, isMechanic, isPolice, canRunTier2 and syncVehicleState.
• Server events, all prefixed ncore_vehicle_inspection:: certificateIssued, certificateExpired, certificateRevoked, inspectionCompleted, roadsideCompleted and roadTestCompleted.
• Vehicle state bags: lrvi:inspection, lrvi:certificate and lrvi:roadside. They are written after a scan, /vcert or a roadside check, and again when a certificate is issued, revoked or expires. syncVehicleState writes them on demand.
• Inspection history keeps the last 25 mechanic scans per plate by default.
• getHandlingBaseline and resetHandlingBaseline take the model hash, for example GetHashKey('sultan').

-- client, for example from an ox_target option: start the mechanic scan on the nearest vehicle
exports.ncore_vehicle_inspection:startDiagnostics()

-- server: true while the plate has a valid certificate
local roadworthy = exports.ncore_vehicle_inspection:isRoadworthy(plate)

-- server: certificate state for a plate: valid, expired, revoked or missing
local cert = exports.ncore_vehicle_inspection:getCertificate(plate)
print(cert.state, cert.expiresLabel)

-- server: the events are local server events
AddEventHandler('ncore_vehicle_inspection:certificateIssued', function(plate, status)
    print(('%s is roadworthy until %s'):format(plate, status.expiresLabel))
end)

Event arguments: certificateIssued and certificateExpired get (plate, status), certificateRevoked gets (plate, reason), inspectionCompleted gets (plate, report, src), and roadsideCompleted and roadTestCompleted get (plate, result, src). src is the player who ran the check.

Commands and keys#

Server console: lrvi_resetbaseline <model> and lrvi_revoke <plate>.

Keys (rebind them in the FiveM key settings): E interact, X stop, Y accept and N refuse on the pre-purchase prompt.

Config files#

• config/config.lua for everything the client and server share: permissions, markers, interaction, faults, pass/fail rules, repair rates, certificates, road test, commands.
• config/config_server.lua for rate limits, validation, storage, logging and the keys hook.
• locales/en.lua for every text, including all 162 verdict lines.
• bridge/client.lua and bridge/server.lua for the framework code, if you need to adapt it.
• data/ and sql/ for the saved data and the table file.

Requirements#

• FXServer with OneSync on.
• Optional: ESX, QBCore or QBox for jobs, grades, duty and character names. Without one, access is by ACE.
• Optional: oxmysql for saving to a database. Without it the resource saves to JSON files in data/.
• Optional: ncore_hud for trackers, cards and the repair receipt.
• Optional: ncore_chat for the roleplay lines. It is the only chat picked up automatically. With another chat resource that has a /me command, set Config.Emotes.Mode = 'command'. The stock chat has no /me.
• Not needed: ox_lib, ox_target, a progress bar or an inventory resource. If ox_lib runs, it is one of the notification handlers.

See INSTALLATION.md for the steps.

FAQ and troubleshooting#

Editions#

Escrow and Full source have the same features and the same updates. In the Escrow edition the Lua code is protected by Cfx.re asset escrow, and the config, locale and bridge files stay editable. In the Full source edition every file is readable and editable.

Every update is listed in CHANGELOG.md.

Support#

Support is on intelnpc.com and I reply within 72 hours. It covers installing, configuring and bugs in the script as shipped. Refunds follow the Tebex terms.

nCore Vehicle Inspection is made by nCore Development. It is not approved, sponsored or endorsed by Rockstar Games.