Agency-Repairkit: Simple Vehicle Repairs That Players Actually Use

The Field Repair Problem

Your vehicle gets damaged mid-mission. The mechanic shop is 10 minutes away. Sitting through that drive kills the pacing of whatever action sequence you were in. But instant self-repair feels unfair. Agency-Repairkit finds the middle ground with usable-but-limited field repair tools.

Three Tiers of Kits

Basic kits restore small damage quickly. Advanced kits restore medium damage more slowly. Professional kits handle major damage but take noticeably longer to apply. The tiering gives players meaningful choices based on their inventory and the situation they're in.

Animation Integrity

Every repair uses a visible animation at the vehicle's damaged area. Players can't quick-repair from the driver's seat — they have to step out, walk to the damage, and commit to the repair animation. This prevents field-repair abuse during combat and makes the action feel earned.

Interruption Matters

Taking damage or getting hit during a repair interrupts it and consumes the kit. Repairs happen outside combat, not in the middle of it. This protects chase sequences from becoming whack-a-mole where nothing sticks.

Economy Integration

Repair kits are craftable by mechanic NPCs or player mechanics via Agency-Minerjob's metal supply chain. The entire automotive economy — mining, crafting, field repairs, shop repairs — becomes a connected web. Kits aren't a one-off item; they're a node in a larger system.

Installation & Setup

Download Agency-Repairkit from your Tebex library and drop the folder into your resources directory. Add ensure agency-repairkit to server.cfg. The resource requires oxmysql if you want persistent kit tracking across restarts; without it, kit quantities are session-only and reset on server restart.

Kit items need to be registered in your framework's item list. The config ships with the correct item names for QBCore and ESX. For standalone setups, the item registration hook is a single function call in config.lua.

Configuration Options

The config.lua exposes full control over kit behavior:

• Kit tiers — define as many kit types as you want, each with a max repair amount, repair speed, and animation duration.
• Combat lock — whether repairs can be initiated while the player is flagged as in combat. Default: disabled during combat.
• Interruption damage threshold — how much incoming damage cancels an active repair. Set to 0 to make any hit cancel it.
• Animation per damage zone — different animations play for engine damage vs. body damage vs. tire damage.
• Economy integration — enable the crafting event hook so Agency-Minerjob metal output can feed kit crafting.

Framework Compatibility

Agency-Repairkit ships with built-in adapters for QBCore and ESX. Framework detection is automatic — drop the resource in, and it detects which you're running. For standalone servers:

• Implement Config.GetItem and Config.RemoveItem to connect your item system.
• Implement Config.GetVehicleHealth and Config.SetVehicleHealth for your vehicle damage layer.
• Everything else (animations, UI, interruption logic) works without changes.

Why This Matters for Roleplay

Vehicle damage is one of the most consistent sources of RP friction. When a mission goes sideways 15 minutes from the nearest mechanic shop, players face a choice: limp the car and ruin the pacing, call it and fast-travel, or have a viable field option. Repair kits give a third path that feels earned without being free.

The tiered kit system creates natural inventory economy decisions. Do you carry a professional kit "just in case" and pay the carrying cost? Or rely on basic kits and accept that serious damage will require a shop? These are the kind of meaningful micro-decisions that make inventory management feel real rather than arbitrary.

The combat interruption mechanic is particularly important for chase RP. Without it, a chased player could field-repair mid-pursuit, which completely deflates the tension. With it, repairs are a post-conflict or between-scene activity, not a panic button.

Frequently Asked Questions

Can mechanics sell repair kits from their menu?

Yes. Agency-Repairkit exports a server-side event agency-repairkit:giveKit that any mechanic script can call. Pass the player server ID, kit tier, and quantity. Your existing mechanic shop script just needs one event call added to its sell routine.

Does the kit work on boats and aircraft?

Yes. The damage system uses FiveM's native vehicle health properties which apply to all vehicle types. Aircraft use a simplified animation (players can't walk to a specific damage zone mid-flight), and boats repair from the dock position. Both behaviors are configurable.

Can I limit which kit tiers certain jobs can use?

Job-based kit access is supported in the item definition. Set requiredJob = 'mechanic' on a kit type and only players in that job can use it. This is useful if you want professional kits to be a mechanic-exclusive tool rather than a purchasable commodity.

How does the kit interact with vehicle respawn scripts?

Agency-Repairkit fires agency-repairkit:onRepairComplete with vehicle netId and repair amount when a kit is successfully used. Any script listening to this event can respond accordingly — your vehicle persistence script can flag the vehicle as field-repaired for logging purposes.

Requirements

• FiveM server (QBCore, ESX, or standalone)
• oxmysql (optional, for persistent kit tracking)
• cfx.re account with valid Agency-Repairkit license
• Framework item registration for kit items

Balancing Repair Kits in Your Server Economy

The economic question servers ask most about Agency-Repairkit is: how rare should the kits be? The answer depends on your server's existing economy balance.

If your server has active mechanic shops with good roleplay, make basic and advanced kits reasonably available but professional kits rare or mechanic-exclusive. This pushes major repairs back to shops while allowing minor field repairs, keeping mechanic RP viable.

If your server struggles with player engagement at mechanic jobs, reduce field kit availability and ensure mechanic-crafted kits are better than commercially available ones. The economic incentive to visit a player mechanic needs to be real, not just narrative.

If your server has a strong criminal economy, craft kit prices through Agency-Blackmarket or player crafting creates a parallel market. Military-grade repair kits as black market items generate interesting logistics RP without undermining the civilian mechanic market.

The key principle: field repair should feel like a useful option, not the optimal one. If players are never visiting mechanic shops, your kits are too powerful or too cheap. Adjust yield and price together rather than one at a time.