ESX FiveM Gang System Script Development (Lua) You are assisting in the development of a comprehensive FiveM Gang System script specifically for the **ESX framework**, written in **Lua**. The goal is to create a feature-rich, configurable, and robust script compatible with ESX, leveraging its core functionalities. The script should include all features outlined in the original resource description. Please help generate the Lua code for the following modules and features. Ensure the code is well-commented, optimized, and adheres to ESX scripting best practices. Prioritize a highly configurable system where nearly every aspect can be adjusted via a configuration file. Implement robust error handling and logging. ## I. Core ESX Setup & Compatibility 1. **Base Resource Structure:** * Standard resource file structure: * `client/` (client-side Lua scripts) * `server/` (server-side Lua scripts) * `shared/` (e.g., `config.lua`, shared utility functions) * `config.lua` (centralized configuration) * `locales/` (for language files, e.g., `en.lua`) * `fxmanifest.lua` * `your_sql_file.sql` (for database table creation) * Populate `fxmanifest.lua` with necessary directives: `fx_version`, `game`, `author`, `description`, `version`, `server_scripts`, `client_scripts`, `shared_scripts`. * Ensure `dependencies { 'es_extended' }` is present. Declare `onesync` as required. 2. **ESX Integration:** * Utilize `ESX.GetPlayerData()` for accessing player information (identifier, job, money, inventory, accounts). * Use `ESX.ShowNotification()` for client-side notifications. * For money: `xPlayer.addMoney()`, `xPlayer.removeMoney()`, `xPlayer.getMoney()`, `xPlayer.addAccountMoney('bank', amount)`, etc. * For inventory: `xPlayer.addInventoryItem()`, `xPlayer.removeInventoryItem()`, `xPlayer.getInventoryItem()`. The script should be configurable to work with common ESX inventories like `esx_addoninventory`, `ox_inventory` (if ESX bridge exists), or the default ESX inventory. * For dispatch: Integrate with specified dispatch systems by triggering their respective events. 3. **Configuration (`config.lua`):** * Define ALL configurable values here, grouped logically (e.g., `Config.Gangs`, `Config.TurfWars`, `Config.Drugs`, `Config.Racketeering`, `Config.Rivalries`, `Config.Checkpoints`, `Config.Debug`). * Set `Config.Framework = 'esx'`. * Include options for enabling/disabling major features. * List of gang colors, default rank permissions, business locations, item names (for drugs, zip ties, etc.). 4. **Database Integration (MySQL with `oxmysql` or `mysql-async`):** * Set up chosen MySQL library. * Create server-side functions for all database interactions. * SQL schemas should use ESX player `identifier` (from `users` table, which links to characters if multichar is used) for linking gang membership, leadership, etc. ## II. Gang Management 1. **Gang Data Structure:** * Schema: gang ID (unique), name, tag (3-5 chars), color, leader_identifier (ESX character identifier), bank balance (e.g., using ESX society accounts or a custom table), created date. 2. **Gang Creation & Initialization:** * Admin command (e.g., `/creategang <name> <tag> <color_id> [leader_target_player_id]`) for gang creation. Leader ID should be the target player's ESX identifier. * Server-side logic to store new gang data. 3. **Joining/Leaving Gangs:** * Invite system: members with permission can invite players (target their server ID, resolve to identifier). * Players can accept/decline invites. 4. **Ranks & Permissions System:** * Default ranks with configurable names and permissions. * Permissions: invite, kick, manage_ranks, manage_checkpoints, collect_protection_money, withdraw_gang_money (from gang account), deposit_gang_money, start_rivalry, manage_gang_vehicles. * Gang leaders (or permitted ranks) can manage ranks via a menu. 5. **Gang Menu (`/gangmenu` or keybind):** * NUI-based preferred. * View members (name, rank, online status from ESX player list). * Manage members (invite, kick, promote/demote). * Gang bank (view balance, deposit, withdraw - using ESX society account functions if possible). * View territory loyalty status. * Place/manage gang checkpoints. 6. **Admin Gang Management (`/managegang`):** * NUI-based for admins (check `xPlayer.getGroup() == 'admin'`). * View/edit/delete gangs, manage gang bank, force add/remove members. ## III. Turf Wars & Loyalty System 1. **Territory Definition:** * Configurable zones in `config.lua`. * Database table: `gang_territory_loyalty` (territory_id, gang_id, loyalty_points). 2. **Loyalty Mechanics:** * **Gaining Loyalty (configurable points):** * Presence: `Config.TurfWars.Loyalty.PointsPerPresence` per `Config.TurfWars.Loyalty.PresenceIntervalMinutes`. * Selling Drugs: `Config.TurfWars.Loyalty.PointsPerDrugSale`. * Spraying Gang Tags: `Config.TurfWars.Loyalty.PointsPerSpray`. (Requires external spray script integration point). * Limit: `Config.TurfWars.Spraying.MaxActiveTagsPerGang`. Cooldown: `Config.TurfWars.Spraying.CooldownBetweenSpraysHours`. * **Losing Loyalty:** Killing rival gang members, negative actions in territory (robbing stores, etc.). * **Loyalty Decay:** Passive decay. * **Dominance:** Gang with most loyalty owns territory. 3. **Map Visualization:** * Client-side: Display territory zones on map, colored by dominant gang. 4. **Notifications:** * Use `ESX.ShowNotification()` for gang members for territory events. 5. **Loyalty Spread:** * Percentage spread to neighboring zones. ## IV. Rivalries 1. **Initiation:** * Start rivalry in non-owned territory. Requires deposit from gang account. Anonymous attackers. 2. **Mechanics:** * Duration: `Config.Rivalries.DurationHours`. * During rivalry, involved gangs earn `Config.Rivalries.DrugSaleProfitPercentageDuringRivalry`. Remainder to shared pool. 3. **Resolution:** * Gang with most drug sales (configurable: quantity or value) wins pool. Optional loyalty boost. ## V. Drug Selling 1. **NPC Interaction:** * Client-side: Approach NPC, offer drugs (use `ESX.Game.GetClosestPed()`, integrate with target scripts if available). * NPC Responses: Accept, Decline, Call Police (trigger dispatch event). * NPCs buy once per player or until despawn. 2. **Dynamic System:** * Diminishing returns based on sales frequency. Lower price, higher risk. * Base drug prices in `config.lua`. Drug items defined by `Config.Drugs.Items` (e.g., `{ {name='weed', label='Weed', points=20}, ...}`). 3. **Animations & Items:** * Synchronized animations. Requires drug items in player's ESX inventory. ## VI. Racketeering 1. **Business Definition:** * `Config.Racketeering.Businesses`: Array {name, type, location, hourlyIncome}. 2. **Income Generation:** * Dominant gang collects protection money to gang account. 3. **Vulnerability:** * Loss on business robbery (integrate with robbery script events). ## VII. Player Interaction & Crime (Kidnap/Rob System) 1. **Actions (configurable keybinds, target script integration):** * Restrain: Requires item (e.g., `zipties` from `Config.Items.ZipTiesName`). * Blindfold: Requires item (e.g., `paperbag` from `Config.Items.BlindfoldName`). * Escort/Transport. * Rob Player: Use ESX functions to transfer money/items. 2. **Item Dependencies:** * Define item names in `config.lua`, ensure they exist in ESX `items` DB table. ## VIII. Gang Assets (Checkpoints) 1. **General Checkpoint Logic:** * Placement via gang menu. Cost from gang account. DB stored. 2. **Storage Checkpoint:** * Shared gang inventory. * Integrate with ESX inventory: * If using `esx_addoninventory`: create a society-type inventory (e.g., `society_gang_<gang_id>`). * If `ox_inventory`: use its stash system, linked to gang ID. * Default ESX: custom tables to store items, linked to gang ID. * Configurable size. Option to disable. 3. **Garage Checkpoint:** * Buy/Store/Retrieve gang vehicles. * Vehicles have gang colors. * `Config.Checkpoints.Garage.AllowedVehicles`. * Persistence: Store in `owned_vehicles` with gang identifier as owner, or a custom `gang_vehicles` table. * If custom: `gang_vehicles` (id, gang_id, model, plate, vehicle_props, stored_at). * Option to disable. ## IX. ESX Multi-Character Support * Crucial: All player-specific gang data (membership, rank, contributions) MUST be tied to the ESX character's `identifier` (e.g., `steam:xxxx_char1`). This is usually the primary key in the `users` table or a linked `characters` table in ESX. Do NOT use `source` or `license` alone for persistent storage of character-specific gang data. ## X. General ESX Scripting Guidelines * **Modularity:** Separate client/server files. * **Events:** Use `TriggerServerEvent`, `TriggerClientEvent`, `ESX.RegisterServerCallback`, `ESX.RegisterNetEvent`. Secure server events. * **Optimization:** Avoid heavy loops in ticks. Optimize DB queries. * **Error Handling & Logging:** Use `print()` for server logs, or a more advanced logger. * **Localization:** Use ESX's `Locales` system (`ESX.RegisterLocale`, `_U('key')`). --- **Initial Steps for Copilot (ESX Focus):** 1. Generate `fxmanifest.lua` with `es_extended` dependency. 2. Outline `config.lua` with ESX-specific considerations (e.g., item names, society account prefixes if used). 3. Set up server-side ESX object (`ESX = nil; TriggerEvent('esx:getSharedObject', function(obj) ESX = obj end)`). 4. SQL Schema (`your_sql_file.sql`): * `gangs` (id, name, tag, color, leader_identifier VARCHAR(255), bank_balance INT DEFAULT 0, created_at TIMESTAMP) * `gang_members` (id INT AUTO_INCREMENT PRIMARY KEY, gang_id INT, member_identifier VARCHAR(255), rank_name VARCHAR(50) DEFAULT 'Recruit', join_date TIMESTAMP, FOREIGN KEY (gang_id) REFERENCES gangs(id) ON DELETE CASCADE) * `gang_ranks` (id INT AUTO_INCREMENT PRIMARY KEY, gang_id INT, rank_name VARCHAR(50), permissions TEXT, FOREIGN KEY (gang_id) REFERENCES gangs(id) ON DELETE CASCADE) -- Permissions as JSON string * `gang_territory_loyalty` (id INT AUTO_INCREMENT PRIMARY KEY, territory_name VARCHAR(100), gang_id INT, loyalty_points INT DEFAULT 0, FOREIGN KEY (gang_id) REFERENCES gangs(id) ON DELETE CASCADE, UNIQUE KEY (territory_name, gang_id)) * `gang_checkpoints` (id INT AUTO_INCREMENT PRIMARY KEY, gang_id INT, type VARCHAR(50), location TEXT, created_at TIMESTAMP, FOREIGN KEY (gang_id) REFERENCES gangs(id) ON DELETE CASCADE) -- Location as JSON string * `gang_vehicles` (id INT AUTO_INCREMENT PRIMARY KEY, gang_id INT, model VARCHAR(50), plate VARCHAR(8) UNIQUE, props TEXT, stored_at TIMESTAMP, FOREIGN KEY (gang_id) REFERENCES gangs(id) ON DELETE CASCADE) -- Vehicle props as JSON * Consider a `gang_bank_transactions` table if not using ESX society accounts. 5. Begin with server-side ESX events/commands for gang creation, ensuring player data is fetched using `ESX.GetPlayerFromId(source)` to get `xPlayer`. Let's build this for ESX, focusing on robust integration with its systems. build this full system all the function shsoldi be working a to z all te menu etc