Configuration

All settings live in config.lua. Customer personalities and dialogue lines are in shared/customers.lua, and texts are in shared/locale.lua. After making changes, a restart ns-locksmith is all you need.

Rule: all money, XP and pricing decisions are calculated on the server from these values. The client can never set any amount.

Table of Contents

• General & bridges
• Job & feature toggles
• Database
• Admin & security
• License
• Progression: levels, reputation, perfect jobs
• Skill tree
• Tools, durability, workshop
• Contracts & achievements
• Events
• Conduct record
• Career paths & mastery
• Items, locations, blips
• Service van
• Jobs
• Vehicles & doors
• Economy
• Difficulty & minigames
• Police
• User interface
• Customers (shared/customers.lua)
• Texts (shared/locale.lua)
• Balance presets

General & bridges

Job & feature toggles

Feature toggles:

Database

Cleanup runs on startup and then every 24 hours.

Admin & security

Config.Admin:

Config.Cooldowns (ms):

Setting these values too low opens the door to spam.

Config.Security:

License

Renewal, reinstatement and career change fees are always charged to the bank account (not Shop.Account).

Progression: levels, reputation, perfect jobs

Config.Progression

Config.Levels: total XP required per level, the title, and the "unlocks" list shown on the tablet. The unlocks list is informational only. The actual locks come from the related settings:

• job type → Jobs.Types[x].level
• tool → Tools[x].level
• lock tier → Jobs.MaxTierByLevel

Config.Reputation

• Tiers defines tiers by reputation. Each tier has:
  • priceMult price multiplier
  • tipMult tip multiplier
  • friendly: half of this value is added to the customer's starting satisfaction
  • premium premium customer chance
• EmergencyMinRep, BusinessMinRep and PremiumMinRep are job type gates.
• Premium customer settings:
  • PremiumPriceMult price multiplier (×1.5)
  • PremiumXPMult XP multiplier (×1.25)
  • PremiumSatisfaction satisfaction penalty (-10)
  • BoardPremiumChance premium chance on the job board

Config.PerfectJob

• All criteria must be met for a perfect job:
  • fast: OnSceneTime.base + perTier × (tier-1) seconds from arrival to unlock
  • no mistakes
  • with the correct tool
  • inspected, if the tier is ≥ RequireInspectionFromTier
  • satisfaction ≥ MinSatisfaction
  • legal (not a fake owner or a late emergency job)
• Reward: XP, a company bonus equal to the MoneyBonus share of the payment, and Rep.

Skill tree

Config.Skills.Branches contains 5 branches with 3 skills per branch. Each skill has:

• maxRank number of ranks
• level unlock level
• requires prerequisite skill

Effects holds the per-rank effect values; the total effect is rank × value. ResetPrice is the fee for refunding all points at HQ.

Tools, durability, workshop

Config.StarterEquipment: tools given to a new profile.

Config.Tools: fields per tool.

When adding a new tool, its category must appear in the tools list of the relevant lock types. The label comes from the label field.

Config.Durability: wear amounts.

• PerUse: successful use
• MinorFailure: minor mistake
• CriticalFailure: critical mistake
• Only the mech_durability skill reduces wear. Upgrades increase maximum durability.

Config.Shop

Contracts & achievements

Daily (Config.Contracts.Daily)

• General settings:
  • Count: number of daily contracts
  • FreeRerolls: free rerolls
  • LevelScale: reward increase per level (+8%)
  • Rep: reputation for each claimed contract
• Pool is the contract pool. Each entry has:
  • goal and the target range target = {min, max}
  • level unlock level
  • reward, the reward per unit of the target. For earnings ($) goals, the reward is calculated per $1000
• Goal types:

The day rolls over at midnight, server local time. Rewards that are completed but not yet claimed are paid out automatically at rollover.

Weekly master (Master)

• From level Level onward, a goal is drawn from the pool every Monday (server time).
• Reward scales with the lower bound of the goal.

Business (Business)

Config.Achievements

• Achievement types:

• Available counters: fakeCaught, policeApproved, dailyContracts, dailySweeps, businessContracts, safeJobs, keymakeJobs, masterContracts.
• For a new achievement, add the ach_<key> and ach_<key>_desc texts to shared/locale.lua.

Events

Random (Config.Events.Random): rolled at most once per job.

• LockJam: with probability chance, the lock becomes 1 tier harder and the payment increases by bonus.
• Discount: the customer asks for a percent discount. Accepting or refusing changes satisfaction by sat.
• ToolDrop: a tool takes wear damage.
• Neighbor: on a night arrival, NPC police show up after delay seconds.

Server-wide (Config.Events.Special)

Multipliers in Types:

Schedule defines automatic windows. weekday: 1 = Sunday … 7 = Saturday, server time; the hour range is [from, to). Admin control: /locksmithevent (list), /locksmithevent <key> [minutes] (default 60) and /locksmithevent stop [key]. A stopped scheduled event does not restart for the rest of that window.

For a new event, add a key to the Types table and add the event_<key> and event_<key>_desc texts to the locale.

Conduct record

Career paths & mastery

Config.Career:

• Level: level at which paths unlock.
• ChangeFee: fee for changing path. The first choice is free.
• ChangeCooldown: waiting period between two changes (days).
• Paths defines the bonuses per path:

For a new path, add a key to the Paths table and add the path_<key> and path_<key>_desc texts to the locale. The tablet list comes from the ORDER table in server/career.lua.

Config.Mastery.Reward: money paid for each mastery rank after level 10.

Items, locations, blips

Config.Items

Config.Locations

• The first entry is HQ. Skill resets, career selection and license reinstatement happen here.
• The features field on entries: terminal, board, license, shop, repair.
• If jobOnly = true, the target options are only visible to locksmiths.
• ped = { model, coords = vector4, scenario }: an HQ clerk NPC that carries all HQ options (stand there and use /lscoords). Without ped, a plain target box at coords is used.

Config.Blips

• LocksmithHQ and ActiveJob turn the blips on or off.
• HQ and Job hold the sprite, color and scale settings. route = true draws a GPS route to the job spot.

Config.LocationTool (admin /lslocations world view)

Black market

Config.BlackMarket – a fence and an encrypted channel in the tablet.

Flow: take an offer on the channel → go to the spot (nobody waits there) → take the right tool and open the lock → door / safe: search inside → drive or walk to the drop point marked on the map and hand over → cash. A stolen car must be parked at the drop and left. When the lock opens (and again, at half the chance, while searching) a witness may call the police: a dispatch is sent to real officers and Config.Record.Strikes.blackmarket (2) strikes are added. Black market jobs are not in the job history, stats, contracts or company commission. Burning the contact removes the channel until you meet the fence again.

Companies

Config.Company – player-founded firms, managed in the tablet's Company section.

Rules: only lower ranks can be promoted, demoted or removed. The owner cannot leave; they transfer the company or close it (the remaining bank is paid to them). Depot tools are borrowed from the tool cabinet (HQ or service van) by members with borrow; one person holds a depot tool at a time and wear is shared. The license card shows the company name. Admins: /locksmithcompany list | bank <id> <±amount> | delete <id>. Tables (locksmith_companies, _company_members, _company_tools, _company_ledger) are created automatically.

Apprentice tutorial

Config.Tutorial – a guided first job at an HQ entry's tutorial = vector4(...) door (stand in front of a door facing it and use /lscoords). HQs without it offer no training.

Offered when a new locksmith (no jobs yet) loads in; skipping is remembered. /lstutorial or the HQ option restarts it (no reward the second time), /lstutorial stop ends it. The training job has no fake owner, alarm, police check, random event or restricted zone; the customer never leaves and an overpriced offer is countered with the fair price. Work only starts after the inspection and a look into the HQ tool locker (tool fetching on). It does not count towards history, stats or contracts. No automatic calls arrive while the training runs.

Service van

Config.ServiceVan – rented at an HQ entry that has a van = vector4(...) spot (spawn and return bay).

Tool fetching. Basic tools (Config.StarterEquipment) and supplies (drill bits) are always on the player. Every other tool stays in the service van or the HQ tool locker: use Take tools on your van (or Tool locker at the HQ) to open the tool cabinet: a pegboard of your tools with the work order, the tool in hand and the basic tools you carry. Tools that fit the current lock are marked (before the inspection, against the estimated tier). Without NUI (Config.UI.UseNui = false) an ox_lib menu is used instead. One tool in hand at a time; picking another swaps it. The tool goes back automatically when the job ends or is cancelled.

• Wrong tool in hand: the work cannot start (tool_wrong).
• Empty hand and no basic tool fits, but you own one that does: the work cannot start (tool_in_van).
• You own nothing that fits: bare-handed work, as before (slow).
• The diagnostic device only helps the inspection while it is in hand. The inspection report shows "in the van" next to a tool that must be taken first.

A van that disappears (deleted / despawned) is lost and its deposit is kept. If the player leaves the server, the van is returned automatically (deposit minus damage). Keys are given through qbx_vehiclekeys or qb-vehiclekeys when running.

Jobs

Config.Jobs

Config.Jobs.Types: job type definitions.

Example, a new job type:

garage_door = { level = 4, weight = 8, kind = 'house', doorType = 'modern_residential', reward = 260,
                problems = { 'problem_garage_1' } },

Add type_garage_door to the locale for the label; otherwise the kind label (type_house) is used. Add problem_garage_1 for the problem text.

Config.Keys

• AcceptCall: key to accept a call, default Y.
• DeclineCall: unbound by default.
• Players can change these keys in the FiveM key bindings.

Vehicles & doors

• Config.JobVehicles: models and GTA classes used in vehicle jobs.
• Vehicle lock tier is determined from two places: VehicleModelTierOverrides[model], otherwise VehicleClassTiers[class].
• Config.Vehicles

Config.DoorTypes: fields per door and lock type.

Config.BusinessTypes: business type names. Business contracts and the location-recording tool use them.

Config.Houses

Economy

• Config.PaymentAccount: account the payment goes to, 'bank' or 'cash'.
• Config.Rewards: base pay used when a job type does not set reward.
  • For vehicles, VehicleBasic for tiers 1–2 and VehicleAdvanced for tier 3 and above.
  • For houses, HouseBasic for tiers 1–2 and HouseAdvanced for tier 3 and above.
  • Also the Business, Emergency and Police base pay values.
• Config.PriceModifiers

Quote order:

1. The base pay and the modifiers above are summed.
2. For premium customers, the extra share is added.
3. The reputation multiplier, business skill, career path, clean record and event multiplier are applied to this subtotal. Each is added separately from the same subtotal (they do not compound). This step is skipped for contracted jobs such as police callouts.

Each appears as a separate line on the receipt.

• Config.XP
  • Base XP by lock tier: Easy, Medium, Hard, Expert.
  • Bonuses: EmergencyBonus, PerfectMinigame, CustomerSatisfaction (satisfaction 80 and above).
  • On door jobs only, the door type's xpMult value multiplies the sum of base + emergency + satisfaction.
  • Premium, career path, perfect job and event XP are added as separate lines.

Difficulty & minigames

Config.Difficulty

• Lock tiers map to difficulty as follows: 1 → Easy, 2 → Medium, 3–4 → Hard, 5 → Expert.
• Parameters:
  • pins, pinSpeed, pinZone: pin count, speed and correct zone width
  • tensionZone, tensionTime: tension zone and time
  • sequence, showTime, fakeInputs: keypad and signal
  • grid, wires: circuit and wiring
  • drillDepth, heatRate: drill
  • timeLimit: time limit
• Tool efficiency (efficiency) and skills scale these values in the player's favor.

Config.Minigames

Setting MinTime values too low opens the door to bots. If legitimate players get the minigame_too_fast warning, lower only the value for that particular game slightly.

Police

Config.Police

Callouts (police calling a locksmith):

User interface

Config.UI

• UseNui: if false, ox_lib menus are used.
• CompactHQ (default true): the HQ shows only the terminal and the physical actions (buy tablet, tool locker, service van, training). The job board, skills, career, workshop and licence open from the terminal. false shows every option separately.
• DefaultVolume: default volume. Players can change it with /lsvolume or from the tablet's Settings.

The NUI theme can be changed through the :root color variables in nui/theme.css (--yellow, --paper, --ink, --stamp-red, etc.). Per FiveM NUI rules, do not use backdrop-filter or blur.

Customers (shared/customers.lua)

• Personalities: values per personality.

• Name pools (FirstNames, LastNames) and ped models (PedModels) are language-independent.
• Language-dependent texts are in the Customers.Text.tr and Customers.Text.en blocks: Problems, BusinessProblems, Default, Dialogue (lines per personality) and PersonalityLabels. Config.Locale selects which block is used; if the block is missing, English is used.
• Dialogue placeholders: {name}, {price}, {counter}, {locksmith}.

Texts (shared/locale.lua)

Config.Locale accepts 'en' or 'tr' (English is the recommended default for new installs). Setting it switches everything to that language:

• notifications, menus, the tablet, minigames and receipts;
• customer and NPC police dialogue;
• chat command descriptions and key binding names;
• names in the config (tools, door types, locks, level titles, business types, police callout types, blips).

Every text exists under the same key in both the tr and en blocks. Do not change the number of %d and %s placeholders.

Config names. config.lua ships with English names. If a translation key exists in the active language, the name is replaced at load time (shared/constants.lua). Entries you add later without a key keep the text from the config.

Adding a new language (e.g. German):

1. Add extend('de', { ... }) blocks to shared/locale.lua. The easiest way is to copy the English blocks and translate them; missing keys fall back to English.
2. Add Customers.Text.de = { ... } to shared/customers.lua (copy the English block).
3. For NUI texts, add de: { ... } to the window.I18N table in nui/locales.js.
4. Set Config.Locale = 'de'.

NPC police dialogue lines are in the LINES_BY_LANG table in server/police.lua.

Balance presets

Slower progression (hardcore RP)

• Multiply the Config.Levels XP thresholds by 1.5.
• Lower the Config.XP values by 20%.
• Set Config.Contracts.Daily.Count = 2.
• Set Config.Jobs.DispatchInterval = { min = 150, max = 300 }.

Higher earnings (low-population server)

• Multiply the Config.Rewards values by 1.3.
• Set PriceModifiers.PerKilometer = 40.
• Set Shop.SellRate = 0.5.

More risk of illegality

• Set Jobs.WrongOwnerChance = 0.15.
• Set Police.NpcCheckChancePerMinute = 0.08.
• Set Record.Revoke = 4.

Easier minigames

• Increase the pinZone, tensionZone and timeLimit values in Config.Difficulty by 15%.
• Set Config.Minigames.StagesByTier[3] = 1.

Use only your own locations

1. Save at least 5–10 spots of each type with /lslocations.
2. Set Config.Jobs.UseDefaultLocations = false.