ns-locksmith — Advanced Locksmith Job (FiveM)

by NullSect

A server-authoritative, roleplay-focused locksmith job for Qbox / QBCore / ESX. It covers:

• vehicle, house, business and safe locks with realistic lockpicking minigames;
• customer dialogue and price negotiation, fake owner detection and police interaction;
• levels, reputation and a skill tree, an equipment workshop, contracts and achievements;
• server events, a conduct record and career paths.

Everything is managed from a single NUI tablet.

• Version: 1.2.0
• Language: English / Turkish. One setting, Config.Locale, switches everything: UI, dialogue, notifications, command descriptions and config names. Adding a language is easy, see CONFIGURATION.md → Texts.
• Licence files: nui/fonts/*.txt (fonts are OFL / free licences, bundled offline)

Features

Access: by default there is no job requirement. Players buy a locksmith tablet at the HQ; while they carry it they receive calls, can use the job board and do lock work. Want a real job instead (or as well)? Set Config.RequireJob = true and/or Config.Items.RequireTablet = false.

Job flow

• Two ways to get work: automatic calls and a shared job board. A call arrives as a pager with a printed work order (address, lock, difficulty, live distance and direction, estimate, countdown); accept with Y while driving.
• Job types: vehicle, house, business, emergency, police callout, safe cracking and key making.
• NUI dialogue with the customer NPC:
  • talk and listen to their problem;
  • check ID and documents, run a registry lookup;
  • ask for the alarm code and negotiate the price.
• The customer NPC is networked: other players and the police see the same person.
• Fake owners exist. Catch them by comparing ID and registry; a justified cancellation is rewarded.
• Lock inspection before work. Some locks turn out harder than expected, and alarms are a risk.
• ox_doorlock integration: the recorded door really opens when the job succeeds.

Minigames (all validated server-side)

• Single pin picking (SPP), raking, wafer, UV keypad deduction, transponder signal, wiring, circuit, drilling, safe dial and key impressioning.
• 1–2 stages depending on the lock profile and tier. Tool efficiency widens the target zones.

Progression

• 10 levels, then mastery ranks with a cash reward per rank.
• Reputation 0–100 with 5 tiers. Tiers affect price, tips and the premium customer chance.
• Skill tree with 5 branches. Perfect job criteria and bonus.
• Career paths at level 10: Corporate, Emergency Responder, Independent Craftsman.

Economy & content

• HQ equipment workshop: buy, repair, 3 upgrade tiers, sell.
• Tools wear down with durability and can break.
• Daily contracts, business contracts (with client relationship points), a weekly master contract and 30+ achievements.
• Random job events: jammed lock, discount request, dropped tool, nosy neighbour.
• Server-wide events: double XP, lock crisis, premium week, tool sale. Started on a schedule or by an admin.

Service van

• Rent a company van at the HQ (level 2+, rent + refundable deposit, damage is deducted on return).
• Mobile workshop at the van: repair tools up to 50% and restock supplies anywhere.
• Key cutting machine: key making jobs get extra key blanks with the van nearby.
• Arriving at a job with the van impresses the customer.
• Tool fetching: basic tools are always on you. Advanced tools are taken from the van (or the HQ tool locker) with an animation and a held prop. The wrong tool in hand means the work can't start.

Black market

• A fence waits at night at a secret spot. After an introduction (level 4, cash fee) an encrypted Channel section opens in the tablet.
• Illegal jobs on the normal job engine: vehicle orders (open a parked car, drive it to a drop), break-ins (open a door, search inside, deliver the package), safe jobs and copy keys. Paid in cash at a drop point.
• Black market spots and drop points are recorded in-game with /lslocations (Black market tab).
• Heat grows with every job and cools down over time. Witnesses may call the real police; a reported job adds strikes to the licence record. Each job type needs enough officers online. High heat also brings more NPC police checks on legal jobs.

Companies

• Players found their own locksmith firm at the HQ (level 5, registration fee). Five ranks with permissions: Intern, Technician, Senior Locksmith, Manager, Owner.
• Every member job pays a commission (set by the owner, 0-30%) into the company bank; bonuses, deposits and withdrawals with a full bank history.
• Company levels and reputation (reputation raises members' prices), weekly company contracts, a shared tool depot borrowed from the tool cabinet, and a company van fleet (cheaper rent paid by the company, no deposit, company plates).
• Managed from the tablet's Company section: members, invitations, promotions, bank, depot and settings.

Apprentice training

• A guided first job at a training door next to the HQ. A checklist on screen and a mentor walk new locksmiths through the tablet, calls, ID and registry checks, pricing, inspection, the tool cabinet, the minigame and payment.
• Nothing can go wrong in it (no fake owner, alarm, police or random events). The reward is paid once. Offered automatically to new locksmiths, restart with /lstutorial or at the HQ.

Legality

• License system: expiry, renewal, suspension, revocation.
• Conduct record: strikes lead to a warning, then suspension, then revocation. A clean record adds a price bonus.
• Police side:
  • verify a license and ask for the work order,
  • suspend a license,
  • random NPC police checks,
  • request a locksmith (/lscallout),
  • dispatch through ps-dispatch, cd_dispatch or the built-in fallback.

Interface

• "Field terminal + work orders" themed NUI tablet. Sections:
  • home, job board, active job
  • skills, workshop, career
  • profile, leaderboard, settings
• HQ clerk NPC carries the HQ options; everything else is in the terminal.
• In-game location tool (/lslocations): map, list, ghost preview of where the car and customer appear, record / edit / test spots.
• Falls back to ox_lib menus when NUI is disabled.

Security & performance

• Every reward, price and position decision is made on the server.
• Callbacks are rate-limited. Job actions are checked for ownership, state and distance.
• Minigame results are checked against a minimum time with millisecond precision, using single-use tokens.
• Profiles are only loaded for players who carry the locksmith tablet (or hold the job, if required). Saving uses dirty flags. Indexes and daily cleanup are automatic.

Requirements

MySQL 5.7+ / MariaDB 10.3+ and OneSync are required. The resource folder is named ns-locksmith; it can be renamed, the code reads its name with GetCurrentResourceName() (exports then use the new name).

Quick start

ensure oxmysql
ensure ox_lib
ensure qbx_core
ensure ox_target
ensure ox_inventory
ensure ns-locksmith

add_ace group.admin locksmith.admin allow

1. Register the locksmith_tablet item in your inventory (anyone who buys it at the HQ becomes a locksmith; a framework job is optional).
2. Set Config.Locale ('en' or 'tr').
3. Set Config.Locations[1].coords to your HQ position.
4. Start the server. Tables and indexes are created automatically.
5. Record job spots in game with /lslocations.

Step-by-step guide and framework examples → INSTALLATION.md Every setting and balancing recipes → CONFIGURATION.md Architecture, trust boundary and development notes (Turkish) → ARCHITECTURE.md

Commands

Locksmith

Police

Admin (ACE locksmith.admin or a framework admin)

Exports

Server

exports['ns-locksmith']:GetPublicProfile(src)      -- { name, careerPath, progress = { level, xp, title, reputation, ... }, license, stats, equipment, skills, achievements, settings } | nil
exports['ns-locksmith']:GetLicense(src)            -- { id, status, issuedAt, expiresAt, company } | nil
exports['ns-locksmith']:GetLevel(src)              -- number | nil
exports['ns-locksmith']:CanWork(src)               -- bool, reason
exports['ns-locksmith']:AddXP(src, amount, reason)
exports['ns-locksmith']:AddReputation(src, amount, reason)

Client

exports['ns-locksmith']:GetProfile()               -- the local player's own profile view | nil

To read another player's locksmith info on the client, use the replicated state bag Player(serverId).state.nsLocksmith. It contains { level, title, licenseId, licenseStatus, company, onJob }. onJob means the player holds the locksmith job (and is on duty if required); it does not mean they are doing a job right now.

Updating

1. Copy over every file except data/locations.json. That file holds your recorded spots.
2. If you changed config.lua, move the new settings from the new version into your own file.
3. If files were added, type refresh and then restart ns-locksmith in the console. If only existing files changed, restart ns-locksmith is enough.
4. Schema changes (AutoMigrate = true) and new indexes are applied automatically on start.

If you see Modules not loaded: ... in the console on start, refresh was not run.