🚘Spectro_WelcomeCar

Documentation: Welcome Car Script for FiveM

Index

1. Introduction

2. Requirements

3. Installation

4. Configuration

5. Operation

6. Admin Commands

7. Troubleshooting

8. Garage System Compatibility

Introduction

Welcome Car is a script for FiveM servers that use the ESX framework. Its main function is to provide new players with a welcome vehicle, allowing them to choose from several configurable models through an interactive graphical interface. The script includes an NPC that manages the vehicle delivery and automatically registers the vehicle in the database, making it compatible with various garage systems.

Main Features

• NPC system for vehicle delivery

• NUI interface for vehicle selection

• Eligibility verification (only new players can claim)

• Automatic database registration

• Compatibility with multiple garage systems (ESX, cd_garage, and others)

• Administration commands to manage claimed vehicles

• Anti-duplication vehicle system

• Configurable map markers (blips)

Requirements

Component	Requirement
Framework	ESX Legacy or higher
Database	MySQL 5.7+ or MariaDB 10.4+
ESX Resources	es_extended, mysql-async or oxmysql
FiveM Server	Build 2372+

Installation

1. Resource Download:

   • Download the resource files

   • Extract them into a folder named welcome_car within your server's resources directory

2. Database Import:

   • The script will automatically create the necessary welcome_cars_claimed table on startup

3. Server Configuration:

   • Add the following code to your server.cfg file:

   ensure welcome_car

4. Vehicle Images:

   • Make sure the vehicle images are in the nui/images/ folder

   • Recommended format: Transparent PNG (500x300px)

Configuration

The main configuration file is config.lua. The main sections are detailed below:

NPC Configuration

Config.NPC = {
    model = "a_m_y_business_01", -- NPC model
    coords = vector3(-516.4926, -252.2754, 34.6973), -- NPC coordinates
    heading = 380.0, -- NPC orientation
    scenario = "WORLD_HUMAN_CLIPBOARD" -- NPC animation
}

Vehicle Configuration

Config.WelcomeCars = {
    {
        label = "Sultan",
        model = "sultan",
        image = "./images/sultan.png",
        description = "A sporty sedan with good acceleration and handling. Perfect for beginners."
    },
    {
        label = "Blista",
        model = "blista",
        image = "./images/blista.png",
        description = "The legendary Skyline GTR R33. A Japanese icon with all-wheel drive and a powerful turbo engine."
    },
    {
        label = "Warrener",
        model = "warrener",
        image = "./images/warrener.png",
        description = "The Mitsubishi Lancer Evolution IX. A rally vehicle for the street with exceptional traction."
    }
}

Vehicle Spawn Configuration

Config.SpawnLocation = {
    coords = vector3(-503.4279, -259.4641, 35.5401),
    heading = 320.0
}

Other Configurations

Config.OnlyNewPlayers = true -- If true, only new players can claim

Config.Blip = {
    enable = true,
    sprite = 227, -- Blip icon
    color = 3, -- Blip color
    scale = 0.5, -- Blip size
    label = "Welcome Car" -- Blip text
}

Text Configuration

Config.Texts = {
    menuTitle = "Select your Welcome Vehicle",
    buttonSelect = "Select",
    buttonClose = "Close",
    processing = "Processing your request...",
    cooldown = "Wait a moment before interacting again...",
    interact = "Press ~INPUT_CONTEXT~ to claim your welcome vehicle",
    alreadyClaimed = "You have already claimed your welcome vehicle.",
    received = "You have received your welcome vehicle! It's parked nearby.",
    registered = "Vehicle registered to your name!"
}

Operation

Claim Process

1. The player approaches the NPC located at the configured coordinates

2. The system verifies if the player is eligible to claim a vehicle

3. Upon interacting with the NPC (E key by default), the selection menu opens

4. The player selects one of the available vehicles

5. After confirming, the vehicle is created near the NPC and registered in the database

6. The vehicle appears with a temporary blip to facilitate location

7. The vehicle is registered in the player's garage (compatible with multiple systems)

Eligibility System

• The script checks the database if the player has already claimed a vehicle previously

• It uses a combination of identifiers (ESX identifier and Steam ID) to prevent abuse

• If Config.OnlyNewPlayers is activated, only new players will be able to claim a vehicle

Vehicle Registration

The script registers the vehicle in the following tables:

• welcome_cars_claimed (script's own table)

• owned_vehicles (standard ESX table)

• Automatically detected garage system tables (cd_garage, etc.)

Admin Commands

Command	Description	Permissions
/resetwelcomecar [ID]	Resets the claimed vehicle status for a specific player	admin, superadmin
/resetallwelcomecars	Resets all claimed vehicles on the server	admin, superadmin
/welcomecarstats	Shows statistics about claimed vehicles	admin, superadmin
/fixwelcomecars	Fixes issues with the system (pending claims, cache, etc.)	admin, superadmin
/fixduplicates	Removes duplicate vehicles from the database	admin, superadmin
/checkgaragetables	Verifies compatible garage tables in the database	admin, superadmin

Troubleshooting

Common Issues

Problem	Solution
The NPC doesn't appear	Check the coordinates in Config.NPC.coords and make sure the model is available on your server
I can't claim the vehicle	Use the /fixwelcomecars command as an admin to reset the system status
The vehicle doesn't appear in my garage	Check compatibility with your garage system using /checkgaragetables
Duplicate vehicles	Use the /fixduplicates command to remove duplicates from the database
Vehicle model doesn't load	Make sure the model is available on your server. If it's an add-on, verify it's correctly installed

Logs and Debugging

To activate debug mode, set Config.Debug = true in the config.lua file. This will generate more information in the server console.

Garage System Compatibility

The script is compatible with the following garage systems:

• ESX native garage system

• cd_garage (automatic detection)

• Other systems that use the standard owned_vehicles table

Automatic Detection

The script tries to automatically detect the garage system used on the server and adapts the vehicle registration accordingly. It also searches for common tables such as:

• player_vehicles

• owned_cars

• vehicles

• user_vehicles

• character_vehicles

To verify compatibility, use the /checkgaragetables command.

Frequently Asked Questions

1: Can a player claim more than one vehicle? A: No, each player can only claim one vehicle. Administrators can reset this status with the /resetwelcomecar [ID] command.

2: How do I change the available vehicles? A: Edit the Config.WelcomeCars table in the config.lua file.

3: Can I change the NPC location? A: Yes, modify Config.NPC.coords in the config.lua file.

4: How do I add more vehicles to the list? A: Add new entries to the Config.WelcomeCars table and make sure the corresponding images are in the nui/images/ folder.

5: Does the script work with OneSync? A: Yes, the script is compatible with OneSync.

6: How can I prevent a player from claiming a vehicle after resetting their character? A: The system uses the player's unique identifier, so even after resetting their character, they won't be able to claim another vehicle unless an administrator uses /resetwelcomecar [ID].

7: Can I limit claims to new players only? A: Yes, make sure Config.OnlyNewPlayers = true in the config.lua file.