# 1 · Getting Started

Install Nord Vehicle Keys, understand its core concepts and verify a clean first boot.

# Overview

Nord Vehicle Keys is a server-authoritative vehicle access system for FiveM. It combines physical vehicle keys, vehicle locking, theft gameplay, temporary stolen keys, recovery NPCs and a modular bridge layer for frameworks, inventories and UI providers.

## Main features

- Physical `vehicle_key` items with plate metadata.
- Server-authoritative lock state using entity state bags.
- Lock / unlock from keybind, commands or the physical-key remote.
- Permanent owner keys, shared keys, temporary keys and stolen/session keys.
- Carjacking of NPC drivers by aiming a valid firearm.
- Lockpick and hotwire flows with configurable difficulty and alarm chances.
- Stolen-key expiry when leaving the stolen vehicle plus a safety timeout.
- Persistent key-recovery NPCs for owned vehicles.
- In-game admin panel for recovery NPC management.
- Ghost NPC placement editor with movement, rotation, height and ground snapping.
- Framework, inventory, notification and Text UI bridges isolated from the core.
- Server exports for garages, dealerships, rentals and other trusted resources.

## Design principle

Normal access is intentionally strict when physical keys are enabled:

> If the player no longer has the matching physical key item, the resource does not silently recreate it during an access check.

A missing owner key must be deliberately reissued through the recovery NPC, an admin action or a trusted server export.


# Requirements & Installation

## Requirements

| Requirement | Status |
|---|---|
| FiveM server | Required |
| OneSync | Required for authoritative entity checks |
| `oxmysql` | Required when persistence/ownership tables are used |
| QBCore / QBX / ESX | Optional |
| `nord_inventory` | Recommended for native physical-key metadata |
| `ox_inventory` | Supported for generic item checks |
| `ox_lib` | Optional notification/Text UI provider |

## Resource installation

1. Copy the folder as `nord_vehiclekeys` into your resources directory.
2. Start the database resource first.
3. Start your framework and inventory before Nord Vehicle Keys.
4. Add the recovery admin ACE if staff will manage recovery NPCs.
5. Ensure the resource.

```cfg
ensure oxmysql
ensure qb-core          # or qbx_core / es_extended when used
ensure nord_inventory   # recommended for physical vehicle_key items
ensure nord_vehiclekeys
```

Recovery admin permission:

```cfg
add_ace group.admin nord.vehiclekeys.admin allow
```

## Database

Auto SQL is enabled by default. The resource creates and validates its own tables at startup.

For a manual install, import:

```text
sql/install.sql
```


# First Boot Checklist

After installation, verify these points before opening the server to players.

1. `oxmysql` is started before Nord Vehicle Keys.
2. The selected framework bridge is detected correctly.
3. The selected inventory bridge is available.
4. OneSync is enabled.
5. No SQL or Lua errors appear during resource startup.
6. The `vehicle_key` item is registered when Nord Inventory auto-registration is enabled.
7. `/vehiclekeysadmin` opens for an ACE-authorized admin.
8. Lock/unlock works on an owned test vehicle.
9. Removing the physical owner key removes normal access when strict physical-key mode is enabled.
10. Recovering that key through a recovery NPC reissues access correctly.

## Recommended start order

```cfg
ensure oxmysql
ensure your_framework
ensure nord_inventory
ensure nord_vehiclekeys
```

If you use another inventory, replace `nord_inventory` with that resource and configure the Inventory bridge accordingly.


# Resource Structure

The resource is intentionally split so integrations can be changed without editing the core logic.

```text
nord_vehiclekeys/
├─ config/
│  ├─ bridges.lua
│  └─ main.lua
├─ client/
│  ├─ bridge/
│  │  ├─ framework.lua
│  │  ├─ inventory.lua
│  │  ├─ notify.lua
│  │  ├─ textui.lua
│  │  └─ minigame.lua
│  ├─ main.lua
│  ├─ theft.lua
│  ├─ stolen.lua
│  ├─ placement.lua
│  └─ recovery.lua
├─ server/
│  ├─ bridge/
│  │  ├─ framework.lua
│  │  ├─ inventory.lua
│  │  ├─ notify.lua
│  │  ├─ textui.lua
│  │  ├─ ownership.lua
│  │  └─ nord_inventory_registration.lua
│  ├─ api.lua
│  ├─ main.lua
│  ├─ stolen.lua
│  ├─ recovery.lua
│  └─ storage.lua
├─ shared/
├─ locales/
├─ web/
└─ sql/
```

For normal compatibility work, edit the appropriate file under `client/bridge/` or `server/bridge/` instead of changing `main.lua`.