pls_mechanic – Realistic Mechanic Job
Every kilometre counts.
Realistic vehicle wear, true-to-life OBD diagnostics and fully animated workshop work – free & open source.
Download on GitHub
Most mechanic scripts are a progress bar and a repaired car. pls_mechanic turns the mechanic job into actual work.
Every car on your server ages with its kilometres. Oil runs out, brake pads wear down, a timing belt snaps, a neglected engine starts to misfire – and the driver feels it on the road. The mechanic finds the problem with an OBD scanner and fixes it part by part. He opens the hood, slides under the car, drains the oil into a pan and carries the old part out.
Full preview (16 min) – everything the script does, in one video:
At a glance
 Realistic vehicle model |
Mileage, 11 service parts, 13 core parts, collisions by impact zone, engine temperature, EV support |
 OBD diagnostics |
Scanner under the dashboard, React report with part states, next service and real fault codes |
 Animated repairs |
40+ step-by-step scenes – hood, wheels, lying under the car, drain pan, test run |
 Parts logistics |
A missing part pauses the job, a route leads to the storage, you carry the box back |
 Lifts & jacks |
Smooth synced car lifts, a jack that tilts one corner of the car |
 Tuning |
Performance stages + full Benny’s-style catalogue, live preview, animated installation |
 Customer catalog |
Customers pick their own tuning with live preview and prices, the mechanic gets the order |
 Economy |
Supplier with supply runs, itemized bills, commission, crafting from salvage |
 Field work |
Push, flip, slim jim, impound, flatbed winch, jump start, 5 NPC mission types |
 In-game creator |
Unlimited workshops, 11 point types, permission matrix per job grade |
 Secure |
Server-authoritative, secure events, rate limits, mileage and plate-spoof protection |
Realistic vehicle model
Mileage for every vehicle – saved for owned cars, optional odometer above the minimap.
11 service parts with km intervals – oil, air / fuel filter, spark plugs, coolant, brake fluid, transmission fluid, brake pads, tyres, timing belt, EV battery coolant.
13 core parts – engine, transmission, clutch, radiator, alternator, battery, fuel pump, brakes, suspension, alignment, turbo, EV battery, EV motor.
Neglect has consequences – an overdue service starts damaging the linked core parts, a worn-out timing belt snaps.
Collisions by impact zone – a frontal crash hits the radiator and engine, a side hit the suspension and alignment.
Engine temperature – warning, power cut, then the engine shuts down until it cools.
Electric vehicles – own parts, no oil or timing belt, extra drain from a worn battery.
NPC & stolen cars come with a random history (20 000–250 000 km). Cars bought in a vehicle shop start brand new.
The driver feels it
| Part | Symptoms |
|---|---|
| Engine | power loss · misfires · stalling · smoke · won’t start |
| Transmission / clutch | slow shifts · limp mode · clutch slip under throttle |
| Battery / alternator | slow cranking · flickering lights · dead battery |
| Brakes / pads / fluid | longer braking distance |
| Suspension / alignment | wobble · pulling to one side · lower top speed |
| Tyres | less grip · blowouts at high speed |
| Radiator / coolant | overheating · steam from the engine bay |
Smoke and steam are networked – everyone around sees a dying car.
OBD diagnostics
- Plug the OBD scanner in under the dashboard and read the car on a tablet.
- The diagnostics report shows every part with its state, the next service in km, damaged body parts, real fault codes (
P0300,P0520,P0217…) and installed tuning. - Tick the jobs, press Start repair – the whole job runs as one workflow.
The last report can be reopened for 10 minutes without a new scan.
Animated repair workflow
Checked before it starts – permission, location (bay, lift, jack) and tools. No clicking through ten steps to fail on the last one.
Every repair is its own scene – oil change with a drain pan, gearbox swap lying under the car, brakes at each wheel, battery swap with sparks, engine test run afterwards. 40+ scenes built from editable presets.- Body damage part by part – doors, hood, trunk, windows, bumpers, headlights, tyres, wheels and bodywork. Everything else stays damaged.
- Parts logistics – heavy parts don’t have to be in your pockets. A missing part pauses the job, Take parts for the job at the storage gives you exactly what’s missing, you carry the box back and continue.
- Car lifts rise smoothly and are synced for everyone. Car jacks lift one corner. Some jobs need a lift, a bay or a jack.
Cancel anytime with X or the target on the car.
Tuning
 Performance |
 Visual (Benny’s style) |
|---|---|
| Engine, brakes, transmission, suspension, armor, turbo | Paint (160 colours + RGB), every body mod, all wheel types |
| Installed with stage items, dependencies checked | Interior, xenon, neon, tyre smoke, window tint, plate style, horns |
| A removed part goes back to the mechanic | Prices with a per-workshop markup |
Live preview with an orbit camera and a cart – drafts survive closing the menu.
Step-by-step installation – the mechanic carries the parts crate, fits each part where it belongs, calibrates on a laptop and tests the result.
Customer catalog – the customer picks, the mechanic builds
No more “a bit more to the left… no, the other spoiler”. The customer drives into the tuning bay and opens the Tuning catalog on their own car.
- The customer browses – same menu, live preview on the car, prices with the workshop markup.
Send order – the preview is reverted and mechanics on duty get a notification with the plate, item count and total.- The mechanic opens tuning – the cart is already filled from the order, with the customer’s name and every item tagged Ordered.
Anything extra needs the customer’s OK – parts the mechanic adds on top are sent to the customer’s screen as a quote with prices and a countdown. Accept or Decline.
Installation and the bill work as usual. The customer is notified when the order is done.
The server refuses any installed part that isn’t in the order or approved by the customer – even step by step.
Economy
-
Supplier with three delivery modes:
Mode Price Delivery Instant 100 % straight into the storage Delayed 85 % after 15 minutes Supply run 65 % mechanics drive a van to the port and load the crates by hand Daily limits, grade-restricted items – and crates can be stolen from an unlocked van.
-
Itemized bills prefilled from the work actually done (labor + parts with markup), mechanic commission, pay by cash or bank. Unpaid bills survive a reconnect (
/mechbills). -
Crafting – replaced parts give salvage (scrap metal, aluminium, rubber, plastic, electronics, used oil). 26 recipes, each with an animated bench scene. -
Public repair stations – paid self-service repair, optionally only when no mechanic is on duty.
Field work – F6 / radial menu
Push, 
flip and 
unlock with a slim jim (fail chance + car alarm)
Impound with photos
Flatbed towing with a real winch – lower the bed, hook the cable, the car slides up, strap the wheels
Jump start with visible jumper cables
5 NPC mission types – towing, dead battery, flat tyre, out of fuel, scrapping a wreck. The customer waits by the car, watches you work and pays you in hand.
Placeable props – traffic cones, road barriers, work signs, toolbox
Workshops built in game
- Unlimited workshops, several jobs can share one.
- Admin creator
/mechanicadminwith a live ghost preview – place duty, boss menu, storage, supply delivery, computer, workbench, payment terminal, service vehicles, bays, car lifts and public repair stations. No coordinates in config files. 
Permission matrix per job grade – 17 permissions edited by the boss in a clean UI.- Duty system, workshop account through your framework’s society, deposits at the computer.
📦 All 86 items (images included)
All items use the mech_ prefix and are mapped in the config, so you can rename them.
- Service: engine oil, oil filter, air filter, fuel filter, spark plugs, coolant, brake fluid, transmission fluid, brake pads, tyre, timing belt
- Core parts: engine parts, transmission parts, clutch kit, radiator, alternator, car battery, fuel pump, brake discs, shock absorber, turbocharger, EV battery module, EV motor, EV coolant
- Body: door, hood, trunk lid, bumper, glass, headlight, wheel, body panel
- Tools: OBD scanner, toolbox, impact wrench, car jack, jump starter, slim jim, tuning laptop, spray gun
- Kits: repair kit, advanced repair kit, emergency patch kit, cleaning kit
- Materials: scrap metal, aluminium, rubber, plastic, electronics, used oil
- Tuning: engine, brake, transmission, suspension and armor stages, turbo kit, paint, vinyl, body kit parts, rims, tyre smoke kit, xenon kit, neon kit, window tint, interior parts, horn, plate kit
- Other: service book, supply crate, traffic cone, road barrier, work sign
Requirements
| Resource | |
|---|---|
| ox_lib |  required |
| oxmysql | required |
| ESX Legacy / QBCore | required (auto-detected) · OX Core partially, the bridge is open |
| Inventory | ox_inventory · qb-inventory · qs-inventory · codem-inventory · core_inventory |
| Target | ox_target · qb-target · built-in marker mode |
| LegacyFuel / ox_fuel, boss menu, keys, dispatch |  optional – simple hooks in configs/client.lua |
Installation
Installation tutorial
- Download the latest release from GitHub and put
pls_mechanicinto your resources. - Add the items from
INSTALL/items.luato your inventory and copyINSTALL/images/*.pnginto your inventory image folder. - Set your inventory and target in
BRIDGE/config.lua– the framework is detected automatically. - Start it after its dependencies – the database tables are created automatically:
ensure ox_lib ensure oxmysql ensure es_extended # or qb-core ensure ox_inventory # your inventory ensure pls_mechanic - Make sure the mechanic job has a society account (ESX:
society_<job>). - Join as an admin, run
/mechanicadmin, create a workshop and place the points. Done.
Full documentation – every config option, all exports, hooks and FAQ: README on GitHub
For developers
-- vehicle shop: a freshly bought car starts brand new
exports.pls_mechanic:SetVehicleNew(plate)
-- read the condition of a vehicle (mileage, service and core parts)
local data = exports.pls_mechanic:GetVehicleData(vehicle)
🔌 All exports
Server – vehicles: SetVehicleNew · GetVehicleMileage · AddVehicleMileage · GetVehicleData · SetVehiclePart · SetPartOrigin · SetVehicleModifiers · SetPlateAlias · ClearPlateAlias · GetRealPlate · GetEntityPlate · SetTrustedPlate · GetInstalledTuning · IsVehicleBusy
Server – workshops: GetItems · GetShop · GetShops · GetCurrentShopId · HasShopPermission · IsNearShopPoint · GetStashId · RegisterPointType · RefreshShopAccess
Client: GetVehicleMileage · GetVehicleData · GetItems · GetShop · GetCurrentShopId · HasPermission · IsBusy · RegisterPointType · RegisterPointAction · SetExternalPower
Hooks for boss menu, fuel, keys, dispatch, impound and logs live in configs/client.lua and server/open.lua. Bridge, configs and locales are plain Lua / JSON and the NUI source (React + Vite) is included.
Download
GitHub – pls_mechanic
Bugs & suggestions: GitHub Issues
| Code is accessible | Yes |
| Subscription-based | No |
| Lines (approximately) | ~42 000 (Lua + React NUI) |
| Requirements & dependencies | ox_lib, oxmysql, ESX / QBCore |
| Support | Yes |