The Anti-Feature That Isn't
Requiring a key to start a vehicle sounds like an anti-feature. Who wants more steps before driving? But immersive RP is often built from exactly this kind of meaningful friction. Vehicle theft becomes thievery-with-stakes. Locking your car becomes a real action. Hotwiring becomes a learnable skill.
Key States That Matter
Agency-Vehiclekeys models three key states per vehicle: owned (you have a physical key item), shared (someone gave you a copy), hotwired (temporarily accessible with police trace risk). Each state has different sound cues, startup animations, and engine behavior. Players who borrow friends' cars feel different from thieves — as they should.
Lockpicking Mini-Game
We ship a simple 3-tier lockpicking mini-game that scales with vehicle class. A Sultan RS takes longer and fails more often than a Faggio. The mini-game is skill-based but non-punishing — failure costs time and tools, not character progress. This is the right difficulty curve for a mechanic that should be a tension tool, not a gatekeeper.
Framework Integrations
QBCore vehicle ownership, ESX garages, and standalone custom registries all plug in through a single set of hooks. Keys are stored as inventory items, so they interact with drops, trading, and inventory searches naturally. Nothing is special-cased.
Economic Impact
Key-based vehicle access creates realistic economic roles. Locksmiths become a viable job. Car thieves become a real threat. Insurance companies become useful. Emergent roleplay comes from systems that respond to each other — Agency-Vehiclekeys is one piece in that puzzle.
Installation & Setup
Agency-Vehiclekeys requires oxmysql to persist key ownership across server restarts. Import vehiclekeys.sql, drop the resource folder into your server, and add ensure agency-vehiclekeys to server.cfg. The resource reads vehicle ownership data from your framework's garage or vehicle registry — QBCore and ESX adapters ship in the package and auto-detect on startup.
Key items need to be registered in your framework's item system. The config ships with item names and metadata definitions for both QBCore and ESX. Standalone setups define item handling through config hooks.
Configuration Options
The config.lua gives fine-grained control over every key mechanic:
- Lockpick tiers — define success probability and failure behavior per vehicle class. Supercars are harder to hotwire than economy vehicles.
- Hotwire detection chance — probability that a successful hotwire sends a police ping per minute of active use.
- Key duplication cost — item and money cost to create a copy key at the locksmith bench.
- Locksmith job requirement — optionally restrict key cutting to players in the locksmith job role.
- Auto-lock on exit — whether vehicles lock automatically when the driver exits. Default: disabled (more realistic).
- Shared key expiry — temporary keys can have a real-world time limit before they automatically deactivate.
Framework Compatibility
Full QBCore and ESX adapters ship in the package. For standalone setups, implement four config functions: vehicle owner lookup, item give/remove, police ping trigger, and the optional locksmith job check. The core key state machine, animations, mini-game, and hotwire logic require no framework knowledge.
Why This Matters for Roleplay
Vehicle ownership without meaningful access control is just cosmetic. Agency-Vehiclekeys makes the gap between owning a vehicle and accessing one feel real. A locked car parked outside a bank isn't just scenery — it's a potential target or a safe asset depending on who's looking at it.
The locksmith economy is the biggest emergent benefit. Once keys are a physical item that can be duplicated, lost, or stolen, locksmith characters have a genuine service to offer. Players who lose their key need to either hotwire (risky) or find a locksmith (requires trust and negotiation). That interaction is pure RP that didn't exist before the script was installed.
The hotwire detection trace is what makes vehicle theft a calculated risk rather than a trivially easy action. Players who hotwire and drive for an hour are taking a meaningful gamble. Experienced thieves learn to swap vehicles frequently. Police learn to watch for hotwire pings. The script generates organic criminal and law enforcement roleplay without any scripted events.
Frequently Asked Questions
Can players give their key to another player?
Yes. Keys are inventory items and can be traded, dropped, or given via any standard inventory transfer. This includes giving a key through Agency-Phone's marketplace or dropping it at a location for someone to pick up — the full item economy applies.
What happens when a key item is lost or deleted?
The server-side key registry tracks ownership independently of the item. A player who loses their physical key item can get a replacement generated at a locksmith shop (costs time and money) or through admin commands. The vehicle doesn't become permanently inaccessible.
Can the mini-game be disabled for specific player roles?
Yes. The lockpick mini-game can be bypassed for players with specific job roles (master locksmith, for example) or specific items (professional lockpick kit vs. basic one). Configure the bypass conditions in Config.LockpickItems.
Does this conflict with existing garage scripts?
Agency-Vehiclekeys reads from garage ownership data but doesn't modify the garage system. Vehicles still spawn through your existing garage script. The key system layers on top — when you spawn a vehicle from the garage, a key item is generated in your inventory automatically.
Requirements
- FiveM server (QBCore, ESX, or standalone)
- oxmysql
- cfx.re account with valid Agency-Vehiclekeys license
- Compatible garage or vehicle ownership system
Running a Locksmith Character on a Keys Server
Agency-Vehiclekeys enables a genuine locksmith profession that doesn't exist on keyless servers. Here's what that character's gameplay looks like in practice:
A locksmith character who offers key cutting services needs a way for clients to reach them — Agency-Phone handles that. They need a workspace prop for the key cutting animation — coordinate your server's MLO team or use a vanilla workshop prop. They charge money for the service, which flows through your economy framework. They might carry higher-tier lockpick tools that can open vehicles other players' tools can't — requiring trust from criminal clients who need a specific vehicle accessed.
The trust dimension is particularly interesting. A locksmith who makes unauthorized copies of keys, or who reports key-cutting customers to the police, or who deliberately damages vehicles while "working on them" — that's a character with real moral complexity and real in-game consequences for their decisions. Agency-Vehiclekeys creates the conditions for that character to exist.