# Installation

## Step 1 — Download

After your purchase on [Tebex](https://hzscripts.com/shop), download the script from your **FiveM Keymaster**:

1. Log in to [keymaster.fivem.net](https://keymaster.fivem.net/)
2. Go to **Granted Assets**
3. Download `HZ-CarControl`

{% hint style="warning" %}
**Important:** Use the same FiveM account that is linked to your Tebex license. The script is escrow protected and requires a valid license.
{% endhint %}

## Step 2 — Dependencies

### Required

1. **HZ-Bridge** (free)
   * Download from [Hz-Scripts shop](https://hzscripts.com/shop) — free asset
   * See [HZ-Bridge Installation](https://hz-script.gitbook.io/hz-script-docs/free-tools/hz-bridge/installation) for setup
   * Must start **before** HZ-CarControl in `server.cfg`

### Optional

* **oxmysql**: Required only if you enable neon color persistence (`Config.Neons.SaveColor = true`)
* **qbx\_vehiclekeys / qb-vehiclekeys**: For door lock integration (auto-detected, or use native fallback)

{% hint style="info" %}
**HZ-Bridge** handles all framework and notification detection automatically. You only need to configure it once.
{% endhint %}

## Step 3 — Files

1. Extract the `HZ-CarControl.zip` archive
2. Place the `HZ-CarControl` folder in your `resources/` directory

```
server/
├── resources/
│   ├── [hz]/
│   │   ├── HZ-Bridge/
│   │   ├── HZ-CarControl/
│   │   │   ├── client/
│   │   │   ├── server/
│   │   │   ├── bridge/
│   │   │   ├── html/
│   │   │   ├── locales/
│   │   │   ├── shared/
│   │   │   ├── config.lua
│   │   │   └── fxmanifest.lua
```

## Step 4 — Database (optional)

{% hint style="info" %}
This step is **optional**. The database is only needed if you want to save neon colors per vehicle plate.
{% endhint %}

If you enable `Config.Neons.SaveColor = true`, the `hz_neon_colors` table will be created **automatically** on first startup (requires oxmysql).

Or import manually:

```sql
CREATE TABLE IF NOT EXISTS `hz_neon_colors` (
  `plate` VARCHAR(12) NOT NULL PRIMARY KEY,
  `r` TINYINT UNSIGNED NOT NULL DEFAULT 0,
  `g` TINYINT UNSIGNED NOT NULL DEFAULT 0,
  `b` TINYINT UNSIGNED NOT NULL DEFAULT 0
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

## Step 5 — server.cfg

Add the resources to your `server.cfg` in this order:

```cfg
# Framework (if applicable)
ensure es_extended
# ensure qb-core

# Optional dependency
ensure oxmysql

# HZ-Bridge (required — free asset, before all Hz-Scripts)
ensure HZ-Bridge

# Hz-Scripts
ensure HZ-CarControl
```

{% hint style="danger" %}
**Startup order is important!** Your framework and `HZ-Bridge` must start **before** HZ-CarControl.
{% endhint %}

## Step 6 — Configuration

Open `config.lua` and adapt the settings to your server. See the [Configuration](https://hz-script.gitbook.io/hz-script-docs/scripts/hz-carcontrol/configuration) page for details on each option.

**Essential settings to check:**

* `Config.Locale`: Language (14 languages available)
* `Config.Menu.Keybind`: Key to open the menu (default: `H`)
* `Config.Features`: Enable/disable individual features

## Step 7 — Verification

1. Start your server
2. Connect in-game
3. Get into a vehicle
4. Press `H` (default) or type `/carmenu`
5. The control panel should appear
6. Check the server console: `HZ-CarControl v3.0.0 — HZ Script`

{% hint style="success" %}
**Done!** If the menu opens and you can toggle features, the script is working. Move on to [Configuration](https://hz-script.gitbook.io/hz-script-docs/scripts/hz-carcontrol/configuration) to customize.
{% endhint %}

***

## Quick Troubleshooting

<details>

<summary>The script doesn't start</summary>

Check that:

* The folder is correctly named `HZ-CarControl` (case sensitive)
* `HZ-Bridge` is installed and started **before** HZ-CarControl
* Your FiveM license is valid on the Keymaster
* The `server.cfg` has `ensure HZ-CarControl`

</details>

<details>

<summary>Error "Framework not detected"</summary>

Framework detection is handled by **HZ-Bridge**. Make sure that:

* `es_extended` or `qb-core` is properly `ensure`d before `HZ-Bridge`
* `HZ-Bridge` is `ensure`d before `HZ-CarControl`
* Check the HZ-Bridge console line to verify detection is correct

</details>

<details>

<summary>Menu doesn't open</summary>

* Check that you are in a vehicle
* Check that `Config.Menu.Keybind` is not conflicting with another script
* Check the F8 console for errors
* Try the chat command: `/carmenu`
* If `Config.Permissions.Enabled = true`, check that you have the required ace permission

</details>

<details>

<summary>Neon colors not saving</summary>

* Enable `Config.Neons.SaveColor = true` in config.lua
* Make sure `oxmysql` is installed and started
* Check the server console for database errors
* The `hz_neon_colors` table is created automatically — if not, import the SQL manually

</details>