# Installation

> Setup guide for ML Vehicle Crafting

Category: VEHICLE CRAFTING · Source: https://miciomods.it/docs/ml-vehiclecraft-installation · Last updated: 2026-08-18

## Overview

`ml_vehiclecraft` turns a chassis item into a drivable owned vehicle. A player places a bare shell in the world, installs its parts one at a time with a full carry and mount sequence, and finishes the project into a registered vehicle. It ships with a placement ghost, a holographic progress board over the shell, crew collaboration, an admin panel with a map view, wreck salvaging and an optional paid layer. Runs on ESX, QBCore, Qbox and standalone through `ml_bridge`.

## Quick Start

1. Download from [CFX Portal](https://portal.cfx.re)
2. Extract to your `resources` folder as `ml_vehiclecraft`
3. Add to `server.cfg`:

**server.cfg**

```cfg
ensure oxmysql
ensure ox_lib
ensure ml_bridge
ensure ml_vehiclecraft
```

> **WARNING:** Load Order
>
> `ml_vehiclecraft` must start AFTER `ml_bridge`, `ox_lib` and `oxmysql`. Starting earlier fails the schema install.

> **DANGER:** Do not rename the folder
>
> The resource folder must be named `ml_vehiclecraft`. Renaming it locks the script.

## Database

The schema installs automatically on first start. `_INSTALL/ml_vehiclecraft.sql` is provided for servers whose database user cannot run DDL at runtime.

`ml_vehiclecraft_builds`: Every project in the world: vehicle, owner, crew, coordinates, slot state, plate, shell colour

`ml_vehiclecraft_unlocks`: Permanent per-vehicle unlocks, only used by the paid layer

`ml_vehiclecraft_credits`: Per-player balance of paid uses, only used by the paid layer

All three use `CREATE TABLE IF NOT EXISTS`, so restarts never touch existing rows.

## Item Registration

Copy the entries in `_INSTALL/items.lua` into your inventory definition, and every file in `_INSTALL/images` into `ox_inventory/web/images`.

With the shipped defaults only these are needed:

- `vc_chassis`: the bare shell, stamped with the vehicle it builds
- `vc_engine`, `vc_transmission`, `vc_brakes`, `vc_wheel`, `vc_door`, `vc_seat`, `vc_bonnet`, `vc_boot`, `vc_exhaust`: the parts
- `vc_bp_rebel`, `vc_bp_bison`, `vc_bp_youga`, `vc_bp_dinghy`, `vc_bp_elegy2`, `vc_bp_sultan`, `vc_bp_futo`: blueprints for tier 2 and tier 3 vehicles

The per-vehicle `vc_chassis_<model>` entries in the same file belong to `Config.ChassisMode = 'items'` and can be skipped otherwise. `toolkit` is only needed if `Config.Tools.enabled` is turned on.

> **WARNING:** A plain giveitem produces a blank chassis
>
> With the default `Config.ChassisMode = 'metadata'`, a chassis or a part carries the vehicle it belongs to in its metadata. `/giveitem vc_chassis` hands out an unstamped item that does nothing. Use the admin panel, the console commands, or the exports on the Developer page.

## Where parts come from

The script builds vehicles. It deliberately does not sell, spawn or loot the parts, so it never fights with the shop, loot or crafting system already running on the server. Pick one source before going live, otherwise players have no way to start a project.

The admin panel covers testing on its own: open `/vehiclecraft`, pick a vehicle under **Spawn for testing** and press **Chassis** and **Parts**. The full loop is playable in under a minute without wiring anything.

For production, the Developer page has copy-paste snippets for a shop entry, a crafting recipe, a loot table reward and a generic give call.

## Verify

After starting, the server console prints the resource banner and the number of restored projects. Give yourself a chassis and use it:

```lua
/vc_givechassis <playerId> emperor
/vc_giveparts <playerId> emperor
```

Using the chassis opens placement. Set the shell down, walk up to it, and the build panel opens on the target option.

**Troubleshooting**

- **Nothing happens when the chassis is used**: the item was given without metadata. Use `/vc_givechassis` or the admin panel instead of `/giveitem`.
- **The console warns about metadata support**: the inventory does not carry metadata. Part quality and model lock switch themselves off, and chassis mode falls back to the per-vehicle items, which have to exist in the inventory.
- **`/vehiclecraft` says access denied**: the account has none of the aces in `Config.Permissions.Admin` and is not a framework admin.
- **The shell is invisible to other players**: expected. The shell is spawned client side by everyone within `Config.Carcass.streamDistance` and is never networked.
- **A project cannot be placed**: `Config.Build.maxNearby` refuses a new shell when too many already sit within `crowdRadius`, and `Config.Placement.zoneRestricted` limits placement to the listed zones.
- **The panel opens but the mount button is missing**: `Config.Collaboration.install` does not allow that player on that project.