esx_core icon indicating copy to clipboard operation
esx_core copied to clipboard

feat(es_extended): add Vehicle Identification Number (VIN) system

Open gtolontop opened this issue 4 months ago • 1 comments

Description

This PR implements a complete Vehicle Identification Number (VIN) system for ESX vehicles, as requested in issue #1638. Each vehicle now has a unique 17-character VIN that persists across plate changes and provides a permanent identifier for vehicles.


Motivation

Currently, vehicles are only identified by their license plate, which creates limitations for advanced roleplay mechanics. A VIN system enables:

  • Vehicle history tracking independent of plate changes
  • Plate swapping/changing mechanics
  • Law enforcement investigations
  • Insurance and ownership verification systems
  • Better vehicle persistence and tracking

Implementation Details

  • Database: Added vin column (VARCHAR(17) UNIQUE) to owned_vehicles table with index
  • Automatic Generation: Vehicles without VIN automatically receive a unique 17-character alphanumeric VIN
  • Vehicle Class Enhancement:
    • Added vin field to CVehicleData
    • Added getVin() method to retrieve VIN
    • VIN stored in entity state for network sync
  • Utility Functions:
    • ESX.GenerateVIN() - Generates unique VIN with database collision check
    • ESX.GetExtendedVehicleFromVIN(vin) - Find vehicle by VIN
  • Admin Command: /getvehiclevin [plate] for testing and debugging
  • Backward Compatibility: Existing vehicles receive VIN on first spawn

Usage Example

-- Get vehicle VIN
local xVehicle = ESX.GetExtendedVehicleFromPlate("ABC123")
if xVehicle then
    local vin = xVehicle:getVin()
    print("Vehicle VIN: " .. vin) -- Output: 1ES1234567890ABCD
end

-- Find vehicle by VIN
local xVehicle = ESX.GetExtendedVehicleFromVIN("1ES1234567890ABCD")
if xVehicle then
    local plate = xVehicle:getPlate()
    print("Vehicle with this VIN has plate: " .. plate)
end

Admin command usage: /getvehiclevin ABC123 Shows notification: Vehicle VIN: ~g~1ES1234567890ABCD~s~


PR Checklist

  • [x] My commit messages and PR title follow the Conventional Commits standard.
  • [x] My changes have been tested locally and function as expected.
  • [x] My PR does not introduce any breaking changes.
  • [x] I have provided a clear explanation of what my PR does, including the reasoning behind the changes and any relevant context.

gtolontop avatar Aug 21 '25 02:08 gtolontop

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

CLAassistant avatar Nov 16 '25 20:11 CLAassistant