Config

⚙️ Configuration

The alpha-NailBox script offers extensive customization options through the Shared/Config.lua file. This page provides detailed explanations for each configuration option to help you tailor the script to your server's needs.

🔧 General Settings

Debug Mode

Debug = false

• Type: boolean

• Default: false

• Description: Enable debug mode to see detailed console messages and access debug commands

• Production Note: Always set to false for production servers to hide debug information

Language Configuration

Locale = "En"

• Type: string

• Options: "En" | "Tr"

• Default: "En"

• Description: Language setting for all script messages and notifications

• Supported Languages:

  • "En" - English

  • "Tr" - Turkish

• Expandable: Add more languages by creating new files in the Locales/ folder

Interaction System

InteractType = "Target"

• Type: string

• Options: "Target" | "Default"

• Default: "Target"

• Description: How players interact with objects and NPCs

  • "Target" - Use target systems (ox_target/qb-target) for interactions (recommended)

  • "Default" - Use key press interactions with on-screen text

🛠️ Required Items

Items = {
    ScrewdriverSet = "screwdriverset",
    ElectronicKit = "electronickit"
}

Configure the required items for nail box operations:

Item	Config Key	Default Value	Purpose
Screwdriver Set	ScrewdriverSet	"screwdriverset"	Needed to drill holes in nail boxes
Electronic Kit	ElectronicKit	"electronickit"	Needed to install electronic activation system

⚠️ Important: Ensure these items exist in your server's item database

🚫 Vehicle Restrictions

Model Blacklist

Blacklist = {
    Models = {
        "police", "police2", "police3", "police4", "police5", "ambulance", "firetruck"
    }
}

• Type: table

• Description: Specific vehicle model names to restrict (case sensitive)

• Default: Emergency vehicles are blacklisted

• Reference: Find vehicle names at FiveM Vehicle Models

• Empty Table: Use {} to allow all models

Class Blacklist

Classes = {
    8, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22
}

Vehicle classes restricted by default:

Class ID	Category	Reason
8	Motorcycles	Too small for nail boxes
10	Industrial	Work vehicles
11	Utility	Service vehicles
13	Cycles	Bicycles
14	Boats	Water vehicles
15	Helicopters	Air vehicles
16	Planes	Air vehicles
17	Service	Service vehicles
18	Emergency	Emergency vehicles
19	Military	Military vehicles
20	Commercial	Commercial vehicles
21	Trains	Rail vehicles
22	Open Wheel	Racing cars

Allowed Classes Reference:

• 0: Compacts

• 1: Sedans

• 2: SUVs

• 3: Coupes

• 4: Muscle

• 5: Sports Classics

• 6: Sports

• 7: Super

• 9: Off-road

• 12: Vans

📦 Nail Box System

Economic Settings

NailBox = {
    Price = 100000,
    Currency = "$"
}

• Price: Cost to purchase a nail box (in your server's currency)

• Currency: Symbol displayed in messages and Discord logs

Auto-Hide Feature

AutoHide = true

• Type: boolean

• Default: true

• Description: Automatically hide nail box object when vehicle trunk is closed

• Alternative: Set to false to keep nail boxes always visible

Purchase System

Buy = {
    Distance = 3.0,
    PoliceAlertChance = 50,
    AlertJobs = { "police", "sheriff" },
    BlipSettings = {
        Sprite = 415,
        Scale = 0.5,
        Colour = 1,
        Flashes = false,
        Time = 5,
        Radius = 0
    },
    Ped = {
        Coords = vector3(-508.17, -1630.36, 17.8),
        Heading = 106.8,
        Model = `s_m_m_gaffer_01`
    }
}

Setting	Type	Default	Description
Distance	number	3.0	Maximum distance from NPC to purchase (game units)
PoliceAlertChance	number	50	Chance police get alerted (0-100%)
AlertJobs	table	{"police", "sheriff"}	List of job names to alert when nail box is purchased
BlipSettings.Sprite	number	415	Blip icon ID for police alert on map
BlipSettings.Scale	number	0.5	Size of the blip on map (0.0-2.0)
BlipSettings.Colour	number	1	Color ID of the blip
BlipSettings.Flashes	boolean	false	Whether the blip flashes on map
BlipSettings.Time	number	5	How long blip stays on map (seconds)
BlipSettings.Radius	number	0	Radius blip size (0 for normal blip)
Ped.Coords	vector3	Salvage yard area	World coordinates where NPC spawns
Ped.Heading	number	106.8	Direction NPC faces (0-360 degrees)
Ped.Model	hash	Gaffer worker	NPC model for vendor

Removal System

Remove = {
    Access = "Job",
    Jobs = {
        ["police"] = 1,
        ["mechanic"] = 2
    },
    Items = {
        [1] = {
            Item = "screwdriverset",
            Quantity = 1,
            Remove = true
        },
        [2] = {
            Item = "electronickit",
            Quantity = 1,
            Remove = false
        }
    }
}

Access Control:

• "Everyone" - Any player can remove nail boxes

• "Job" - Only specific jobs with minimum grades can remove

Job Requirements Format:

["jobname"] = minimum_grade_required

Item Requirements:

• Item - Item name from your database

• Quantity - How many items needed

• Remove - Whether to consume the item after use

🔩 Nails Effects

Nails = {
    Radius = 2.5,
    ExplodeBulletproofTiresChance = 50,
    ExplodeTiresChance = 50,
    ExplodeTiresAfterSeconds = 3,
    TireExplosionDelay = 1
}

Setting	Type	Default	Description
Radius	number	2.5	Distance from nails center that affects vehicles (game units)
ExplodeBulletproofTiresChance	number	50	Percentage chance of bulletproof tires exploding (0-100%)
ExplodeTiresChance	number	50	Percentage chance of regular tires exploding (0-100%)
ExplodeTiresAfterSeconds	number	3	Delay before tire explosion after contact (seconds)
TireExplosionDelay	number	1	Delay between each tire explosion (seconds)

Special Vehicles

SpecialVehicles = {
    Enabled = true,
    Models = {
        `riot`,
        `riot2`
    },
    ExplodeChance = 25
}

Configure special explosion chances for armored vehicles:

Setting	Description
Enabled	Enable/disable special vehicle handling
Models	Array of vehicle model hashes for special treatment
ExplodeChance	Custom explosion chance for these vehicles (0-100%)

⏱️ Timing Configuration

Nail Box Operations

Times = {
    NailBox = {
        Buy = 10000,     -- 10 seconds
        Drill = 30000,   -- 30 seconds
        Kit = 30000,     -- 30 seconds
        Pour = 10000,    -- 10 seconds
        Hold = 3000,     -- 3 seconds
        Remove = 30000   -- 30 seconds
    }
}

Setting	Default	Description
Buy	10 seconds	Time to complete nail box purchase
Drill	30 seconds	Time to drill hole in nail box
Kit	30 seconds	Time to install electronic kit
Pour	10 seconds	How long nail dropping lasts after activation
Hold	3 seconds	How long to hold activation key before nails start dropping
Remove	30 seconds	Time to remove nail box from vehicle

Nail's Timings

Nails = {
    Rate = 250,      -- Every 250ms
    Control = 500,   -- Every 500ms
    Clear = 100000   -- 100 seconds
}

Setting	Default	Description
Rate	250ms	How often new nails are created while dropping
Control	500ms	How often to check if vehicles are on nails
Clear	100 seconds	How long nails stay on road before cleanup

📱 Discord Logging

Basic Configuration

DiscordLog = {
    Enable = false,
    WebhookURL = "https://discord.com/api/webhooks/.../...",
    AvatarURL = "https://cdn.discordapp.com/...",
    DateFormat = "%H:%M:%S | %d/%m/%Y"
}

Setting	Description
Enable	Set to true to enable Discord logging
WebhookURL	Your Discord webhook URL from server settings
AvatarURL	Avatar image URL for Discord bot messages
DateFormat	Date/time format for timestamps (Lua format guide)

Event Colors

Colors = {
    Bought = 4286945,   -- Green
    Remove = 14165544,  -- Red
    Pour = 3207208      -- Blue
}

Use Hex to Decimal Converter for custom colors.

Custom Vehicle Images

CustomVehicles = {
    ["m3g80"] = "https://img.gta5-mods.com/q95/images/...",
    -- Add more vehicles:
    -- ["your_vehicle_name"] = "https://your-image-url.com/image.png"
}

Add custom vehicle images for enhanced Discord logs by mapping vehicle names to image URLs.

🚗 Custom Vehicle Positioning

CustomPositions = {
    ["issi7"] = {
        X = 0,      -- Left/right adjustment
        Y = 0.05,   -- Forward/backward adjustment
        Z = -0.35   -- Up/down adjustment
    },
    ["issi8"] = {
        X = 0,
        Y = 0.05,
        Z = -0.35
    }
}

Some vehicles may need special nail box positioning to look natural. Add entries for specific vehicle models with X, Y, Z offset adjustments.

📄 Full Config File

Languages = {} -- Don't remove

Config = {
    -- Enable debug mode to see detailed console messages and access debug commands
    -- Set to false for production servers to hide debug information
    Debug = false,

    ---@type "En" | "Tr"
    -- Language setting for all script messages and notifications
    -- "En" = English, "Tr" = Turkish
    -- You can add more languages by creating new files in Locales/ folder
    Locale = "En",

    ---@type "Target" | "Default"
    -- How players interact with objects and NPCs
    -- "Target" = Use target (ox_target/qb-target/...) for interactions (recommended)
    -- "Default" = Use key press interactions with on-screen text
    InteractType = "Target",

    -- Required items for nail box operations
    -- Make sure these items exist in your server's item database
    Items = {
        ScrewdriverSet = "screwdriverset", -- Item needed to drill hole in nail box
        ElectronicKit = "electronickit",   -- Item needed to install electronic activation system
    },

    -- Vehicle restrictions - prevent certain vehicles from using nail box
    Blacklist = {
        -- Specific vehicle model names to restrict (case sensitive)
        -- Find vehicle names at: https://docs.fivem.net/docs/game-references/vehicle-models/
        -- Leave empty {} to allow all models
        Models = {
            "police",     -- Police cruiser
            "police2",    -- Police cruiser 2
            "police3",    -- Police cruiser 3
            "police4",    -- Police cruiser 4
            "police5",    -- Police cruiser 5
            "ambulance",  -- Ambulance
            "firetruck"   -- Fire truck
        },

        -- Vehicle classes to restrict by category
        -- Leave empty {} to allow all classes
        Classes = {
            8,  -- Motorcycles - too small for nail box
            10, -- Industrial  - work vehicles
            11, -- Utility     - service vehicles
            13, -- Cycles      - bicycles
            14, -- Boats       - water vehicles
            15, -- Helicopters - air vehicles
            16, -- Planes      - air vehicles
            17, -- Service     - service vehicles
            18, -- Emergency   - emergency vehicles
            19, -- Military    - military vehicles
            20, -- Commercial  - commercial vehicles
            21, -- Trains      - rail vehicles
            22  -- Open Wheel  - racing cars

            -- Available classes for reference:
            -- 0: Compacts        - small cars
            -- 1: Sedans          - regular cars
            -- 2: SUVs            - sport utility vehicles
            -- 3: Coupes          - two-door cars
            -- 4: Muscle          - muscle cars
            -- 5: Sports Classics - classic sports cars
            -- 6: Sports          - modern sports cars
            -- 7: Super           - supercars
            -- 9: Off-road        - off-road vehicles
            -- 12: Vans           - cargo vans
        }
    },

    -- Main nail box system configuration
    NailBox = {
        Price = 100000,        -- Cost to purchase an nail box (in your server's currency)
        Currency = "$",        -- Currency symbol to display in messages and Discord logs

        -- Automatically hide nail box object when vehicle trunk is closed
        -- Set to false if you want nail box always visible
        AutoHide = true,

        -- Nail box purchase system settings
        Buy = {
            Distance = 3.0,    -- Maximum distance from NPC to purchase nail box (in game units)

            -- Chance that police will be alerted when someone buys an nail box
            -- 0 = never alert police, 100 = always alert police
            PoliceAlertChance = 50,
            -- Jobs to alert when nail box is purchased
            AlertJobs = { "police", "sheriff" },
            -- Blip settings for police alert on map
            BlipSettings = {
                Sprite = 402,
                Scale = 0.5,
                Colour = 1,
                Flashes = false,
                Time = 5,
                Radius = 0
            },

            -- NPC vendor configuration who sells nail box
            Ped = {
                Coords = vector3(-508.17, -1630.36, 17.8), -- World coordinates where NPC spawns
                Heading = 106.8,                                   -- Direction NPC faces (0-360 degrees)
                Model = `s_m_m_gaffer_01`                          -- NPC model
            }
        },

        -- Nail box removal system
        Remove = {
            ---@type "Everyone" | "Job"
            -- Who can remove nail box from vehicles
            -- "Everyone" = any player can remove nail box
            -- "Job" = only specific jobs with minimum grades can remove
            Access = "Job",

            Jobs = {
                ["police"] = 1,    -- Police officers grade 1 and above can remove nail box
                ["mechanic"] = 2,  -- Mechanics grade 2 and above can remove nail box
            },

            -- Items required to remove nail box from vehicles
            -- Leave empty {} if no items are needed
            Items = { -- Leave it empty if no item requirement is needed
                [1] = {
                    Item = "screwdriverset",  -- Item name from your database
                    Quantity = 1,            -- How many of this item needed
                    Remove = true            -- Whether to consume/remove the item after use
                },
                [2] = {
                    Item = "electronickit",  -- Item name from your database
                    Quantity = 1,            -- How many of this item needed
                    Remove = false           -- Keep the item after use (don't consume)
                },
                -- Add more items if needed:
                -- [3] = {
                --     Item = "lockpick",
                --     Quantity = 1,
                --     Remove = true
                -- }
            }
        }
    },

    Nails = {
        Radius = 2.5,    -- Distance from nails center that affects vehicles (in game units)

        SpecialVehicles = { -- Vehicles that have special explode chances for tires
            Enabled = true,
            Models = {
                `riot`,
                `riot2`
            },
            ExplodeChance = 25
        },
        ExplodeBulletproofTiresChance = 50, -- Percentage chance of bulletproof tires exploding when a vehicle drives over the nails
        ExplodeTiresChance = 50, -- Percentage chance of tires exploding when a vehicle drives over the nails
        ExplodeTiresAfterSeconds = 3, -- After how many seconds the tires will explode when a vehicle drives over the nails
        TireExplosionDelay = 1 -- Delay between each tire explosion in seconds
    },

    -- Timing configuration for all script operations (in milliseconds)
    Times = {
        -- Nail box operation timings
        NailBox = {
            Buy = 10000,     -- Time to complete nail box purchase (10 seconds)
            Drill = 30000,   -- Time to drill hole in nail box (30 seconds)
            Kit = 30000,     -- Time to install electronic kit (30 seconds)
            Pour = 10000,    -- How long nail pouring lasts after activation (10 seconds)
            Hold = 3000,     -- How long to hold activation key before nail pouring starts (3 seconds)
            Remove = 30000   -- Time to remove nail box from vehicle (30 seconds)
        },

        -- Nails effect timings
        Nails = {
            Rate = 250,      -- How often new nails are created while pouring (every 250ms)
            Control = 500,   -- How often to check if vehicles are on nails (every 500ms)
            Clear = 100000   -- How long nails stay on road before cleanup (100 seconds)
        }
    },

    -- Discord webhook logging system
    DiscordLog = {
        Enable = false,   -- Enable/disable Discord logging (set to true to enable)

        -- Your Discord webhook URL for sending logs
        -- Get this from your Discord server settings > Integrations > Webhooks
        WebhookURL = "https://discord.com/api/webhooks/.../...",

        -- Avatar image URL for Discord bot messages
        AvatarURL = "https://cdn.discordapp.com/attachments/1337137211056980019/1425764091896528906/Profile_Photo.png?ex=68e8c5c8&is=68e77448&hm=d2e081191d830bdae539e8d3bbe16cac7edf9fc6116230f70bb6af65b75ac154&",

        -- Discord embed colors for different events (decimal color values)
        -- Use https://www.mathsisfun.com/hexadecimal-decimal-colors.html to convert colors
        Colors = {
            Bought = 4286945,   -- Green color for purchase logs
            Remove = 14165544,  -- Red color for removal logs
            Pour = 3207208      -- Blue color for nail pouring logs
        },

        -- Date/time format for Discord log timestamps
        -- Format guide: https://www.lua.org/pil/22.1.html
        DateFormat = "%H:%M:%S | %d/%m/%Y", -- https://www.lua.org/pil/22.1.html

        -- Custom vehicle images for Discord logs
        -- Add your custom vehicles here with their image URLs
        CustomVehicles = {
            ["m3g80"] = "https://img.gta5-mods.com/q95/images/bmw-m3-g80-2022-add-on-tuning-lods-fivem-debadged-replace-eliominati/75d33a-10.png",
            -- Add more custom vehicles:
            -- ["your_vehicle_name"] = "https://your-image-url.com/image.png",
        }
    },

    -- Custom nail box positioning for specific vehicles
    -- Some vehicles need special positioning to look natural
    CustomPositions = {
        -- Position adjustments for specific vehicle models (X, Y, Z offsets)
        ["issi7"] = {
            X = 0,      -- Left/right adjustment
            Y = 0.05,   -- Forward/backward adjustment
            Z = -0.35   -- Up/down adjustment
        },
        ["issi8"] = {
            X = 0,
            Y = 0.05,
            Z = -0.35
        },
        -- Add more vehicles as needed:
        -- ["vehicle_name"] = {
        --     X = 0.0,
        --     Y = 0.0,
        --     Z = 0.0
        -- },
    }
}

💥 Tire Damage System Features

Realistic Explosion Mechanics

• Sequential Tire Bursts: Multiple tires explode with realistic delays for maximum impact

• Bulletproof Tire Support: Separate explosion chances for armored vehicle tires

• Special Vehicle Handling: Custom settings for riot vans and other armored vehicles

• Configurable Timing: Adjustable delays between tire contact and explosion

Damage Calculation

1. Vehicle drives over nails

2. System checks tire type (regular vs bulletproof)

3. Applies appropriate explosion chance

4. Triggers delayed explosion sequence

5. Each tire explodes with configured delay between them

🎯 Quick Setup Guide

1. Set your server's economy: Adjust Price and Currency

2. Configure NPC location: Set Buy.Ped.Coords to your preferred location (default: salvage yard)

3. Customize tire damage: Modify explosion chances and timing in Nails section

4. Setup special vehicles: Configure armored vehicle handling

5. Customize timings: Modify Times values for your server's pace

6. Setup Discord logging: Enable and configure webhook URL

7. Adjust restrictions: Modify Blacklist for your server's vehicles

8. Test and fine-tune: Use debug mode for testing, then disable for production

⚠️ Important Notes

• Always backup your config before making changes

• Restart the resource after configuration changes

• Test thoroughly with debug mode before production

• Ensure required items exist in your item database

• Some anti-cheat systems may interfere with client-side object creation

• Tire explosion effects are permanent until vehicle repair

• Special vehicles may require custom explosion chance tuning