Ares Electrician - Installation & Configuration Guide

Version: 1.2.0 Authors: RKY, Roro Framework Support: ESX, QB-Core, QBX Dependencies: ares-core (required)

---

📋 Table of Contents

• Overview

• Installation

• Dependencies

• Configuration Guide

• Job Sites

• Leveling System

• Customization

---

🎯 Overview

Ares Electrician is a multiplayer job system that allows players to work as electricians, completing electrical repairs across the map. Features include:

• Multiplayer lobbies - Team up with other players (powered by ares-core)

• Dynamic job dispatch - AI-generated job locations with varying difficulty

• XP & leveling system - Earn experience and unlock pay multipliers

• Mini-games - Interactive electrical repair challenges

• Customizable job sites - 20+ pre-configured locations

• Work vehicle system - Spawn and manage job vehicles

• Reroll system - Don't like the job? Reroll for a new one

---

🚀 Installation

⚠️ Important: Resource Name

The resource folder MUST be named exactly:

ares_electrician

Do not rename the folder. The script will not work correctly with any other name.

Resource Start Order

Ares Electrician requires ares-core to be started first:

# 1. Start your framework
ensure es_extended
# or
ensure qb-core

# 2. Start dependencies
ensure ox_lib
ensure ares-core

# 3. Start Ares Electrician
ensure ares_electrician

Setup Steps

1. Extract the resource to your server's resources folder

2. Ensure ares-core is installed (see ares-core documentation)

3. Add to server.cfg in the correct order (see above)

4. Configure job center and sites (see Configuration Guide)

5. Restart your server

No database setup or items required - the script handles everything.

---

📦 Dependencies

Required

• ox_lib - Core library for UI and menus

• ares-core - Lobby system and infrastructure

Framework (Choose One)

• ESX (es_extended)

• QB-Core (qb-core)

• QBX Core (qbx-core)

Optional

• ox_target or qb-target - Entity/zone targeting

• ox_inventory or qb-inventory - Enhanced inventory integration

The script automatically detects your framework, target system, and inventory.

---

⚙️ Configuration Guide

All configuration is done in config.lua.

Framework Settings

Config.Framework = 'auto'

Description: Framework detection mode. Options: 'auto', 'esx', 'qb-core' Recommended: Leave as 'auto' for automatic detection.

---

Language Settings

Config.Language = 'en'

Description: Language code for UI and notifications. Default: 'en' (English) Location: Language files are in shared/lang/*.json

Adding custom languages:

1. Duplicate shared/lang/en.json

2. Rename to your language code (e.g., fr.json)

3. Translate all values (keep keys unchanged)

4. Set Config.Language = 'fr'

---

Lobby Settings

Config.MaxPlayers = 2

Description: Maximum players allowed in a job lobby. Range: 1-4 recommended Note: Other lobby settings (timeout, ID length, etc.) are configured in ares-core

---

Target & Inventory Systems

Config.Target = 'auto'
Config.Inventory = 'auto'

Parameter	Type	Description	Options
Target	string	Target system detection	'auto', 'ox_target', 'qb-target'
Inventory	string	Inventory system detection	'auto', 'ox_inventory', 'qb-inventory'

Recommended: Leave both as 'auto'.

---

Menu & UI Settings

Config.menu = 'custom'
Config.Notification = 'ox_lib'

Parameter	Type	Description	Options
menu	string	Menu system to use	'custom', 'ox_lib'
Notification	string	Notification system	'ox_lib', 'custom'

Menu types:

• 'custom' - Ares custom UI (recommended)

• 'ox_lib' - ox_lib menus

Notification types:

• 'ox_lib' - ox_lib notifications (recommended)

• 'custom' - Your own system (edit client/framework/notify.lua)

---

Job Site Interaction

Config.JobSiteInteraction = 'default'

Description: How players interact with job sites. Options: 'default' (E key interaction with text notification) Note: More interaction systems may be added in future updates.

---

Animation Settings

Config.Animation = {}
Config.Animation.Dict = "anim@amb@trailer@touch_screen@"
Config.Animation.Anim = "idle_a"

Description: Animation played when interacting with electrical panels. Customization: Change to any valid GTA V animation dictionary and name.

---

Inventory Item Aliases

Config.InventoryAliases = {
    water = {
        ['qb-inventory'] = 'water_bottle',
        ['ox_inventory'] = 'water'
    },
    sandwich = {
        ['qb-inventory'] = 'sandwich',
        ['ox_inventory'] = 'sandwich'
    },
    lockpick = {
        ['qb-inventory'] = 'lockpick',
        ['ox_inventory'] = 'lockpick'
    }
}

Description: Maps logical item names to inventory-specific item IDs. Use case: If your QB and OX inventories use different item names.

---

Dispatch Settings

Config.Dispatch = {
    maxDistance = 10000.0,
    minPay = 500,
    maxPay = 2500,
    difficultyMultipliers = {
        easy = 1.0,
        medium = 1.5,
        hard = 2.0,
        expert = 2.5
    },
    rerollCooldown = 5000,
    maxRerolls = 10,
    defaultMinPlayers = 1,
    defaultMaxPlayers = 1
}

Parameter	Type	Description	Default
maxDistance	number	Maximum job distance from player (meters)	10000.0
minPay	number	Minimum base payout	500
maxPay	number	Maximum base payout	2500
difficultyMultipliers	table	Payout multipliers by difficulty	See config
rerollCooldown	number	Cooldown between rerolls (ms)	5000
maxRerolls	number	Maximum rerolls allowed	10

How dispatch works:

1. Player starts job at job center

2. System randomly selects a job site within maxDistance

3. Payout is calculated: basePay * difficultyMultiplier * levelMultiplier

4. Player can reroll job (with cooldown) up to maxRerolls times

Example - Higher payouts:

Config.Dispatch = {
    maxDistance = 15000.0,  -- Allow further jobs
    minPay = 750,           -- Higher minimum
    maxPay = 3500,          -- Higher maximum
    difficultyMultipliers = {
        easy = 1.2,
        medium = 1.8,
        hard = 2.5,
        expert = 3.5
    },
    rerollCooldown = 3000,  -- Faster rerolls
    maxRerolls = 15
}

---

📍 Job Center

Config.JobCenter = {
    coords = vector3(233.048279, -411.346802, 48.111935),
    radius = 2.0,
    blip = {
        sprite = 408,
        color = 3,
        scale = 0.8,
        name = "Electrician Job Center"
    }
}

Parameter	Type	Description
coords	vector3	Job center location
radius	number	Interaction radius (meters)
blip.sprite	number	Blip icon ID
blip.color	number	Blip color ID
blip.scale	number	Blip size
blip.name	string	Blip label

Finding coordinates:

1. Go to desired location in-game

2. Use /getcoords or F8 console with:

local coords = GetEntityCoords(PlayerPedId())
print(string.format("vector3(%.6f, %.6f, %.6f)", coords.x, coords.y, coords.z))

---

🎯 Markers

Config.Markers = {
    enabled = true,
    default = {
        type = 20,
        size = vector3(0.50, 0.50, 0.50),
        color = {r = 37, g = 87, b = 35, a = 0.8},
        bobUpAndDown = true,
        faceCamera = false,
        rotate = false,
        drawDistance = 15.0,
        heightOffset = 0.50
    }
}

Description: 3D markers shown at job sites to help players locate interaction points.

Parameter	Type	Description
enabled	boolean	Enable/disable markers globally
type	number	Marker type ID (reference)
size	vector3	Marker dimensions (width, height, depth in meters)
color	table	RGBA color values (0-255, alpha 0.0-1.0)
bobUpAndDown	boolean	Animate up/down movement
faceCamera	boolean	Always face player camera
rotate	boolean	Continuously rotate
drawDistance	number	Maximum render distance (meters)
heightOffset	number	Height above ground (meters)

Common marker types:

• 0 - Cylinder

• 1 - Arrow

• 20 - Chevron Up (recommended)

• 28 - Vertical Cylinder

Custom marker colors: Use RGBA Color Picker to find colors.

Example - Red pulsing marker:

default = {
    type = 1,  -- Arrow
    size = vector3(1.0, 1.0, 2.0),
    color = {r = 255, g = 0, b = 0, a = 0.9},  -- Bright red
    bobUpAndDown = true,
    rotate = true,
    drawDistance = 20.0,
    heightOffset = 1.0
}

---

🚐 Work Van Settings

Config.WorkVan = {
    model = 'boxville',
    spawnCoords = { 
        vector4(269.815582, -325.662537, 44.657276, 0.0),
        vector4(265.815582, -325.662537, 44.657276, 0.0),
        vector4(273.815582, -325.662537, 44.657276, 0.0),
        vector4(269.815582, -330.662537, 44.657276, 0.0),
    },
    spawnRadius = 1.0,
    plate = 'ELECTRIC',
    useRandomPlate = true,
    fuel = 100,
    requiredItems = {},
    giveKeys = {
        enabled = true,
        qbcoreOnly = true,
        event = 'vehiclekeys:client:SetOwner'
    }
}

Parameter	Type	Description
model	string	Vehicle model name
spawnCoords	table	Array of possible spawn locations (vector4)
spawnRadius	number	Radius to check if spot is occupied (meters)
plate	string	License plate text
useRandomPlate	boolean	Generate random plate instead
fuel	number	Initial fuel level (0-100)
requiredItems	table	Items player must have to spawn vehicle
giveKeys.enabled	boolean	Give vehicle keys to player
giveKeys.qbcoreOnly	boolean	Only give keys on QB-Core
giveKeys.event	string	Event to trigger for key distribution

Spawn Coordinate System

The script cycles through spawnCoords to find a free spot:

1. Checks first coordinate

2. If occupied within spawnRadius, tries next

3. Repeats until free spot found or all checked

Adding more spawn points:

spawnCoords = { 
    vector4(269.8, -325.7, 44.7, 90.0),   -- Heading 90°
    vector4(265.8, -325.7, 44.7, 90.0),
    vector4(273.8, -325.7, 44.7, 90.0),
    vector4(269.8, -330.7, 44.7, 180.0),  -- Different heading
    vector4(275.0, -335.0, 44.7, 270.0),  -- Additional spot
},

Vehicle Keys Integration

For QB-Core:

giveKeys = {
    enabled = true,
    qbcoreOnly = true,
    event = 'vehiclekeys:client:SetOwner'
}

For other key systems:

giveKeys = {
    enabled = true,
    qbcoreOnly = false,
    event = 'your_key_system:giveKeys'  -- Your event name
}

Disable vehicle keys:

giveKeys = {
    enabled = false
}

Required Items

Enable item requirements:

requiredItems = {
    'water',
    'sandwich',
    'lockpick'
}

Disable item requirements:

requiredItems = {}

---

🗺️ Job Sites

Job sites are the core of the electrician system. Each site represents a location where players perform electrical repairs.

Job Site Structure

{
    id = 4,
    name = "Gas Station - Route 68",
    coords = vector3(1701.2, 6425.8, 32.8),
    difficulty = "hard",
    basePay = 550,
    blip = {
        sprite = 354,
        color = 5,
        scale = 1.0,
        name = "Electrical Repair Site"
    },
    marker = {
        type = 1,
        color = {r = 0, g = 255, b = 255, a = 220},
    },
    minigame = "terminal",
    heading = 90.8585,
    description = "Fix fuel pump electrical systems"
}

Parameter	Type	Description
id	number	Unique identifier
name	string	Job site name
coords	vector3	Location coordinates
difficulty	string	Difficulty level ('easy', 'medium', 'hard', 'expert')
basePay	number	Base payout before multipliers
blip	table	Map blip configuration
marker	table	Custom marker overrides (optional)
minigame	string	Mini-game type
heading	number	Player/prop heading (degrees)
description	string	Job description

Available Mini-games

Config.Minigames = {
    wiring = {},                     -- Wire connection puzzle
    circuit_panel = {                -- 3D fuse placement
        description = '3D fuse placement puzzle'
    },
    terminal = {                     -- Terminal hacking
        description = 'terminal minigame'
    }
}

Mini-game types:

• "wiring" - Connect wires in correct order

• "circuit_panel" - Place fuses in 3D panel

• "terminal" - Terminal-style interface

---

Pre-configured Job Sites

The script includes 20+ pre-configured locations:

ID	Name	Difficulty	Mini-game
4	Gas Station - Route 68	Hard	Terminal
5	Hospital - Pillbox Hill	Hard	Terminal
6	Power Substation - Mirror Park	Hard	Terminal
7	Fleeca Bank West Coast	Hard	Terminal
8	Lumber Jack	Medium	Wiring
9	Caravan Electrical Panel	Medium	Circuit Panel
10	Arcade AC Unit	Hard	Terminal
11	Ice Cabinets	Medium	Wiring
12	LS Port Electrical Box	Medium	Circuit Panel
13	Cypress Warehouse	Hard	Terminal
14	Vinewood Sign Maintenance	Medium	Wiring
15	Rebel Radio Power Unit	Medium	Circuit Panel
16	Wind Farm Generator	Hard	Terminal
17	Lamp Replacement	Medium	Wiring
18	Dam AC Unit	Medium	Circuit Panel
19	Postal Service Power Unit	Hard	Terminal
20	Warehouse Maintenance	Medium	Wiring
21	Mining Site Maintenance	Medium	Circuit Panel
22	Gas Pump Electrical Box	Hard	Terminal
23	Farm Lamp Maintenance	Medium	Wiring
24	Construction Generator	Medium	Circuit Panel
25	Airport Power Box	Hard	Terminal

---

Adding Custom Job Sites

Config.JobSites = {
    -- Existing sites...
    
    {
        id = 26,                                    -- Unique ID
        name = "Custom Location",
        coords = vector3(100.0, 200.0, 30.0),     -- Your coordinates
        difficulty = "medium",                      -- easy/medium/hard/expert
        basePay = 750,
        blip = {
            sprite = 354,
            color = 5,
            scale = 1.0,
            name = "Electrical Repair Site"
        },
        marker = {
            type = 20,
            color = {r = 255, g = 165, b = 0, a = 200},  -- Orange
        },
        minigame = "wiring",                       -- wiring/circuit_panel/terminal
        heading = 180.0,
        description = "Your custom job description"
    }
}

---

📊 Leveling System

The XP and leveling system rewards players for completing jobs.

Config.leveling = {
    defaultLevelForJobs = 1,
    defaultXPPerJob = 100,
    
    notification = {
        theme = 'emerald',
        xpDuration = 2500,
        levelUpDuration = 6000,
        xpToLevelDelay = 300,
        animationDelay = 80,
        soundEnabled = true,
    },
    
    levels = { ... }
}

Notification Settings

Parameter	Type	Description	Default
theme	string	UI color theme	'emerald'
xpDuration	number	XP notification duration (ms)	2500
levelUpDuration	number	Level up notification duration (ms)	6000
xpToLevelDelay	number	Delay between XP and level up (ms)	300
animationDelay	number	Delay between perk animations (ms)	80
soundEnabled	boolean	Enable notification sounds	true

Available themes:

• 'emerald' (default green)

• 'blue'

• 'violet'

• 'amber'

• 'rose'

---

Level Configuration

levels = {
    {
        level = 1,
        multiplier = 1.0,
        xpRequired = 0
    },
    {
        level = 2,
        multiplier = 1.1,
        xpRequired = 100,
        UnlockedRewards = {
            {text = "Raise of 10% per job!", icon = "fa-solid fa-money-bill-trend-up"}
        }
    },
    -- ... more levels
}

Parameter	Type	Description
level	number	Level number
multiplier	number	Pay multiplier at this level
xpRequired	number	Cumulative XP needed to reach level
UnlockedRewards	table	Rewards shown when leveling up

Pre-configured levels:

Level	XP Required	Multiplier	Bonus
1	0	1.0x	Base pay
2	100	1.1x	+10%
3	1,500	1.15x	+15%
4	4,000	1.20x	+20%
5	8,000	1.35x	+35%
6	15,000	1.50x	+50%

How Leveling Works

XP Calculation:

XP Earned = Config.leveling.defaultXPPerJob

Payout Calculation:

Final Payout = basePay × difficultyMultiplier × levelMultiplier

Example:

• Base Pay: $800

• Difficulty: Hard (2.0x)

• Player Level: 5 (1.35x)

• Final Payout: $800 × 2.0 × 1.35 = $2,160

---

Adding More Levels

{
    level = 7,
    multiplier = 1.75,
    xpRequired = 25000,
    UnlockedRewards = {
        {text = "Raise of 75% per job!", icon = "fa-solid fa-money-bill-trend-up"},
        {text = "New tool unlocked", icon = "fa-solid fa-wrench"}
    }
},
{
    level = 8,
    multiplier = 2.0,
    xpRequired = 40000,
    UnlockedRewards = {
        {text = "Double pay unlocked!", icon = "fa-solid fa-trophy"}
    }
}

---

🎨 Customization

Editable Files

These files are not protected by escrow and can be customized:

File	Purpose
config.lua	Main configuration
shared/lang/*.json	Language files
shared/framework.lua	Framework adapter
client/framework/notify.lua	Notification system

---

Custom Notifications

File: client/framework/notify.lua

Default system (ox_lib):

Config.Notification = 'ox_lib'

Custom system:

Config.Notification = 'custom'

Then edit notify function in client/framework/notify.lua:

function notify(title, message, type)
    if Config.Notification == 'custom' then
        -- Your custom notification code
        exports['your_notify']:Show(title, message, type)
    else
        -- Default ox_lib
        lib.notify({
            title = title,
            description = message,
            type = type
        })
    end
end

---

Custom Language Files

Create new language:

1. Copy shared/lang/en.json to shared/lang/fr.json (example)

2. Translate all values (keep keys unchanged)

3. Set in config:

Config.Language = 'fr'

Language file structure:

{
    "job_started": "Job started!",
    "job_completed": "Job completed!",
    "difficulty_easy": "Easy",
    "difficulty_medium": "Medium",
    "difficulty_hard": "Hard",
    ...
}

Do not change:

• Key names (left side)

• JSON structure

Only translate:

• Values (right side)

---

📝 Quick Reference

Essential Configuration Checklist

• ✅ Install ares-core first

• ✅ Set resource start order in server.cfg

• ✅ Configure Config.JobCenter location

• ✅ Adjust Config.WorkVan.spawnCoords for your map

• ✅ Review and customize Config.JobSites

• ✅ Tune Config.Dispatch payouts

• ✅ Configure Config.leveling progression

• ✅ Test job flow and mini-games

Performance Tips

• Keep Config.Markers.drawDistance reasonable (10-20m)

• Disable markers if using target system

• Optimize job site count for server population

• Use reasonable maxDistance in dispatch settings

Common Customizations

Higher payouts:

Config.Dispatch = {
    minPay = 1000,
    maxPay = 4000,
    difficultyMultipliers = {
        easy = 1.5,
        medium = 2.0,
        hard = 2.5,
        expert = 3.5
    }
}

Faster leveling:

Config.leveling = {
    defaultXPPerJob = 200,  -- Double XP
    levels = {
        {level = 1, multiplier = 1.0, xpRequired = 0},
        {level = 2, multiplier = 1.2, xpRequired = 50},  -- Halved requirements
        {level = 3, multiplier = 1.4, xpRequired = 750},
        -- ...
    }
}

Disable vehicle keys:

Config.WorkVan = {
    -- ... other settings
    giveKeys = {
        enabled = false
    }
}

---

🔧 Troubleshooting

Issue	Solution
"ares-core not found"	Ensure ares-core is started before ares_electrician
No jobs appearing	Check Config.Dispatch.maxDistance and job site coordinates
Vehicle won't spawn	Verify spawn coordinates aren't occupied/invalid
Markers not showing	Enable Config.Markers.enabled = true
Wrong language	Check Config.Language matches file in shared/lang/
No XP gained	Verify Config.leveling.defaultXPPerJob is set
Lobby not working	Check ares-core configuration

---

Need Help? Join our Discord: https://discord.gg/eDEJUawmMh