🚿Spectro_grua

📘 Spectro Vehicle Management System - Complete Documentation

Advanced vehicle cleanup and management system for FiveM with automated scheduling, protected zones, and modern UI

---

📋 Table of Contents

1. Key Features

2. Requirements and Dependencies

3. Installation Guide

4. General Configuration

5. Admin Commands

6. Automatic Scheduling

7. Protected Zones

8. Notification System

9. UI Customization

10. Frequently Asked Questions

11. Troubleshooting

12. Advanced Settings

---

🌟 Key Features

🚀 Core Functionality

Feature	Description	Command
Mass Vehicle Cleanup	Remove all abandoned vehicles from server	/borrarcoches
Quick Cleanup	Remove specific or nearby vehicles	/bc or /bc [radius]
Automated Schedule	Clean vehicles at preset times	Automatic
Protected Zones	Safe areas where vehicles won't be removed	Config-based
Visual Notifications	Modern UI with countdown timers	Automatic
Sound Alerts	Audio warnings for players	Automatic

🛡️ Admin Features

Feature	Description	Access
ESX Integration	Permission-based access	Admin groups
Custom Admin List	Manual identifier-based access	Config file
Console Commands	Execute from server console	Console
Logging System	Track all cleanup actions	Server logs

🎨 Visual System

Component	Description	Customizable
Countdown UI	Interactive countdown timer	✅ Colors, position
Progress Bar	Visual cleanup progress	✅ Colors
Sound Effects	Alert sounds (1 & 2 minutes)	✅ Custom sounds
Zone Markers	Protected area indicators	✅ Colors, opacity

---

📋 Requirements and Dependencies

🚨 Mandatory Dependencies

Dependency	Description	Status
mysql-async	Database integration	✅ Required
ESX Framework	Player permissions (optional)	⚪ Optional

📊 Server Requirements

Requirement	Specification
FiveM Version	Latest stable
Script Name	Must be Spectro_grua
Lua Version	5.4 enabled
File Structure	All files intact

🔗 Framework Compatibility

Framework	Status	Notes
ESX	✅ Full support	Automatic permission detection
QBCore	⚠️ Partial	May require modifications
vRP	⚠️ Partial	May require modifications
Standalone	✅ Full support	Use admin identifier list

---

🔧 Installation Guide

Step 1: Download and Setup

1. Download the script files

2. IMPORTANT: Rename folder to exactly Spectro_grua

3. Place in your server's resources folder

Step 2: Database Setup

-- This script uses ESX tables if framework is enabled
-- No additional database setup required

Step 3: Server Configuration

-- Add to server.cfg
ensure Spectro_grua

Step 4: Initial Configuration

1. Open config.lua

2. Configure basic settings:

Config.locale = "en"          -- Language: "en" or "es"
Config.Cmd = "borrarcoches"   -- Main cleanup command
Config.DeleteVehicleTimer = 2  -- Minutes before cleanup

Step 5: Admin Setup

Choose one of two methods:

Option 1: ESX Integration

Config.ESX = true  -- Use ESX groups (admin, mod, superadmin)

Option 2: Manual Admin List

Config.ESX = false
Config.AdminList = {
    'license:your_license_here',
    'discord:your_discord_id',
    'steam:your_steam_hex'
}

---

⚙️ General Configuration

🎯 Core Settings

Config = {
    locale = "en",                -- Language (en/es)
    Cmd = "borrarcoches",        -- Main cleanup command
    ESX = true,                  -- Use ESX permissions
    NotificationColor = "#d4ff00", -- UI accent color
    DeleteVehicleTimer = 2,      -- Warning minutes
    EnableBcCommand = true,      -- Enable quick cleanup
    DefaultRadius = 50.0         -- Default cleanup radius
}

🌍 Language Settings

Language	Code	Status
English	en	✅ Full support
Spanish	es	✅ Full support

Add custom languages in locales.lua:

Locale["your_lang"] = {
    first_message = "Your translation here",
    deleted_vehicles = "Your translation here",
    -- ... more translations
}

🎨 Visual Customization

-- Notification color (hex format)
Config.NotificationColor = "#d4ff00"  -- Spectro yellow-green

-- UI positioning and styling
-- See style.css for advanced customization

---

👮‍♂️ Admin Commands

🚨 Primary Cleanup Command

# Default command
/borrarcoches

# Customizable in config
Config.Cmd = "your_command_here"

Functionality:

• Warns all players

• Starts countdown timer

• Removes all abandoned vehicles

• Respects protected zones

⚡ Quick Cleanup Command

# Remove specific vehicle (in or nearby)
/bc

# Remove vehicles in radius
/bc 50    # Remove within 50 meters
/bc 100   # Remove within 100 meters

Detection Priority:

1. Vehicle player is currently in

2. Vehicle directly in front of player

3. Vehicle below player

4. Nearest vehicle within range

💻 Console Access

All commands work from server console:

# Server console
borrarcoches
bc 100

---

⏰ Automatic Scheduling

📅 Scheduled Cleanups

Configure automatic cleanup times:

Config.DeleteVehiclesAt = {
    {['h'] = 01, ['m'] = 00},  -- 1:00 AM
    {['h'] = 03, ['m'] = 00},  -- 3:00 AM
    {['h'] = 05, ['m'] = 00},  -- 5:00 AM
    {['h'] = 07, ['m'] = 00},  -- 7:00 AM
    {['h'] = 09, ['m'] = 00},  -- 9:00 AM
    {['h'] = 11, ['m'] = 00},  -- 11:00 AM
    {['h'] = 13, ['m'] = 00},  -- 1:00 PM
    {['h'] = 15, ['m'] = 00},  -- 3:00 PM
    {['h'] = 17, ['m'] = 00},  -- 5:00 PM
    {['h'] = 19, ['m'] = 00},  -- 7:00 PM
    {['h'] = 21, ['m'] = 00},  -- 9:00 PM
    {['h'] = 23, ['m'] = 00},  -- 11:00 PM
}

⏱️ Countdown Timer

Config.DeleteVehicleTimer = 2  -- Minutes before cleanup

// Countdown stages:
// 2 minutes: Initial warning + UI
// 1 minute: Second warning + sound
// 30 seconds: Final countdown + sound
// 0 seconds: Cleanup executed

---

🛡️ Protected Zones

📍 Zone Configuration

Config.SafeZones = {
    {
        ['x'] = -44.155,      -- X coordinate
        ['y'] = -1100.155,    -- Y coordinate
        ['z'] = 26.267,       -- Z coordinate
        ['radius'] = 50.0,    -- Protection radius
        ['color'] = 2,        -- Blip color
        ['alpha'] = 150       -- Blip transparency
    },
    {
        ['x'] = -1688.438,
        ['y'] = -1073.625,
        ['z'] = 13.152,
        ['radius'] = 200.0,
        ['color'] = 2,
        ['alpha'] = 150
    }
}

🎨 Blip Colors

Color ID	Color Name	Hex Code
1	Red	#FF0000
2	Green	#00FF00
3	Blue	#0000FF
5	Yellow	#FFFF00
25	Pink	#FF00FF
47	Orange	#FFA500

⚙️ Zone Behavior

Config.DeleteVehiclesIfInSafeZone = false  -- Respect safe zones
Config.DeleteVehiclesIfInSafeZone = true   // Delete even in safe zones

---

📢 Notification System

🔔 Notification Types

Stage	Type	Duration	Sound
Initial	ESX + UI	Until next stage	None
2 minutes	ESX + UI	60 seconds	Custom
1 minute	ESX + UI	30 seconds	Custom
30 seconds	Countdown	30 seconds	Beeps

📱 ESX Notifications

// Built-in messages with emojis:
"The tow truck will impound all abandoned vehicles in 2 MINUTES🚨"
"The tow truck will impound all abandoned vehicles in 1 MINUTE🚨"
"All vehicles have been removed ♻️"

🎵 Custom Sounds

Place custom sound files in /sounds/ folder:

• oneminute.mp3 - Plays at 1-minute mark

• twominutes.mp3 - Plays at 2-minute mark

🖥️ Visual UI

Modern countdown interface with:

• Dynamic timer display

• Progress bar animation

• Color customization

• Shake effects for urgency

• Responsive design

---

🎨 UI Customization

🖌️ Style Configuration

/* Main notification container */
#countdown-container {
    left: 1.2vw;      /* Horizontal position */
    bottom: 27vh;     /* Vertical position */
    width: 15vw;      /* Responsive width */
    min-width: 240px; /* Minimum width */
    max-width: 300px; /* Maximum width */
}

/* Color customization */
.title {
    color: #FFC800; /* Title color */
}

.counter-circle {
    border-color: rgba(255, 196, 0, 0.7); /* Border color */
}

🎯 Position Adjustments

Screen Type	Bottom Position	Notes
HD (720p)	30vh	Above minimap
Full HD (1080p)	27vh	Centered
4K (2160p)	25vh	Proportional
Ultrawide	24vh	Adjusted for aspect

🌈 Color Schemes

// Predefined color schemes:
Config.NotificationColor = "#d4ff00"  // Spectro green-yellow
Config.NotificationColor = "#ff0000"  // Red (emergency)
Config.NotificationColor = "#00ff00"  // Green (success)
Config.NotificationColor = "#0080ff"  // Blue (info)

---

❓ Frequently Asked Questions

🔧 General Questions

❓ How do I change the cleanup timer?

// In config.lua:
Config.DeleteVehicleTimer = 2  // Default: 2 minutes
Config.DeleteVehicleTimer = 5  // Extended: 5 minutes
Config.DeleteVehicleTimer = 1  // Quick: 1 minute

❓ Can I disable automatic cleanup?

// Comment out all times in config.lua:
Config.DeleteVehiclesAt = {
    -- {['h'] = 01, ['m'] = 00},
    -- All times commented = no automation
}

❓ How do I add more admin identifiers?

Config.AdminList = {
    'license:abc123...',
    'discord:123456789',
    'steam:110000...',
    // Add as many as needed
}

🎮 Gameplay Questions

❓ Will my vehicle be deleted if I'm inside?

No, the script never deletes vehicles with players inside.

❓ What about player-owned vehicles?

The script only targets abandoned vehicles. Player ownership detection depends on your framework.

❓ Can I protect specific areas?

Yes, configure protected zones in Config.SafeZones:

{
    ['x'] = coordinate_x,
    ['y'] = coordinate_y,
    ['z'] = coordinate_z,
    ['radius'] = protection_radius,
    ['color'] = 2,
    ['alpha'] = 150
}

🔨 Technical Questions

❓ Why must the folder be named 'Spectro_grua'?

The script includes integrity checks to prevent unauthorized modifications:

-- Built-in validation
if resourceName ~= "Spectro_grua" then
    print("ERROR: Must run with name 'Spectro_grua'")
    return
end

❓ How do I customize the UI position?

Modify style.css:

#countdown-container {
    left: 1.2vw;    /* Horizontal */
    bottom: 27vh;   /* Vertical */
}

❓ Can I use custom sounds?

Yes, replace files in /sounds/ folder:

• oneminute.mp3

• twominutes.mp3

Same filenames, any audio format supported by browsers.

---

🔧 Troubleshooting

🚫 Common Issues

Command not working

1. Check permissions:

   // ESX enabled: Verify admin group
   // ESX disabled: Check AdminList

2. Verify command name:

   Config.Cmd = "borrarcoches"  // Check spelling

3. Console errors:

   # Look for errors in server console
   # Common: script disabled, permission issues

UI not showing

1. Check resource name:

   # Must be exactly: Spectro_grua
   # Refresh resources after renaming

2. Verify file paths:

   // Ensure all files are present:
   // - html/index.html
   // - html/script.js
   // - html/style.css

3. Browser compatibility:

   // Clear FiveM cache
   // %localappdata%\FiveM\FiveM.app\data\cache

Sounds not playing

1. Check file formats:

   # Supported: .mp3, .wav, .ogg
   # Location: /sounds/ folder

2. Volume settings:

   // In script.js:
   oneMinuteSound.volume = 1.0;
   twoMinutesSound.volume = 1.0;

3. Browser autoplay policies:

   // Sound may require user interaction first
   // This is handled automatically in the script

📊 Debug Mode

Enable detailed logging:

// Add to config.lua:
Config.Debug = true

// Check console for detailed logs:
// - Command executions
// - UI events
// - Permission checks

---

🚀 Advanced Settings

🛠️ Advanced Configuration

// Extended configuration options
Config.Advanced = {
    -- Vehicle detection settings
    MaxDetectionRange = 500.0,    -- Max vehicle scan distance
    MinPlayerDistance = 5.0,      -- Min distance for player detection
    
    -- Performance settings
    CleanupThreadDelay = 100,     -- Milliseconds between checks
    MaxVehiclesPerTick = 5,       -- Vehicles processed per tick
    
    -- Safety settings
    RequireGroundContact = true,  -- Only delete grounded vehicles
    IgnoreEmergencyVehicles = true, -- Skip police/ambulance
    
    -- Notification settings
    DisableESXNotifications = false, -- Use only custom UI
    CustomSoundVolume = 0.8,      -- Sound effect volume
    UIFadeTime = 500,             -- UI transition time (ms)
    
    -- Zone settings
    AutoGenerateZoneBlips = true, -- Show zone boundaries
    ZoneCheckFrequency = 1000,    -- Zone check interval (ms)
}

📡 Custom Events

// Custom event triggers for integration
TriggerEvent('spectro:vehicleCleanup:started')
TriggerEvent('spectro:vehicleCleanup:warning', minutesLeft)
TriggerEvent('spectro:vehicleCleanup:completed', vehicleCount)

// Listen for custom events
AddEventHandler('spectro:vehicleCleanup:started', function()
    // Custom actions when cleanup starts
end)

🔌 API Integration

// Server-side exports
exports['Spectro_grua']:StartCleanup()
exports['Spectro_grua']:QuickCleanup(playerId, radius)
exports['Spectro_grua']:AddProtectedZone(coords, radius)
exports['Spectro_grua']:RemoveProtectedZone(coords)

// Usage example:
local success = exports['Spectro_grua']:StartCleanup()
if success then
    print("Cleanup initiated successfully")
end

🎨 Theme Presets

// Predefined UI themes
Config.UIThemes = {
    default = {
        primaryColor = "#d4ff00",
        backgroundColor = "rgba(12, 12, 12, 0.95)",
        borderColor = "rgba(255, 196, 0, 0.3)"
    },
    
    emergency = {
        primaryColor = "#ff0000",
        backgroundColor = "rgba(20, 0, 0, 0.95)",
        borderColor = "rgba(255, 0, 0, 0.5)"
    },
    
    police = {
        primaryColor = "#0080ff",
        backgroundColor = "rgba(0, 10, 20, 0.95)",
        borderColor = "rgba(0, 128, 255, 0.4)"
    }
}

// Apply theme
Config.ActiveTheme = "default"

---

📞 Support Information

📋 Required Support Data

When requesting support, provide:

1. Server Information:

   • FiveM version

   • Script version

   • Framework (ESX/standalone)

   • Resource name confirmation

2. Error Details:

   • Exact error messages

   • Console logs (client & server)

   • Steps to reproduce

3. Configuration:

   • Config.lua settings

   • Admin list setup

   • Any custom modifications

🔍 Self-Diagnosis Checklist

# Pre-support checklist:
[ ] Resource name is exactly 'Spectro_grua'
[ ] All files are present and unmodified
[ ] ESX permissions are correctly set
[ ] Admin identifiers are properly formatted
[ ] No conflicting resources are running
[ ] Console shows no red errors
[ ] UI files (HTML/CSS/JS) are intact

---

📄 Final Notes

🔄 Update Process

1. Backup current configuration

2. Replace script files (keep config.lua)

3. Check version notes for changes

4. Test in development server first

5. Apply to production server

📋 License Information

This script is copyrighted material:

• Licensed for single-server use

• Modification of core files prohibited

• Resource name change prohibited

• Redistribution prohibited

🛡️ Security Notice

The script includes integrity checks:

• Resource name validation

• Author verification

• File structure validation

These protect against unauthorized modifications and ensure proper functionality.

---

Documentation for Spectro Vehicle Management System v1.2.0 Last updated: 2025