Ares Core - Installation & Configuration Guide

Version: 1.0.0 Author: Roroleroh Purpose: Core dependency for multiplayer lobbies and licensing

---

📋 Table of Contents

• Overview

• Installation

• Dependencies

• Configuration Guide

• Garage System

• Job Vehicles

• API Reference

---

🎯 Overview

Ares Core is a required dependency for Ares Studio's multiplayer-enabled scripts. It provides:

• Multiplayer lobby system - Create and manage player lobbies for jobs and activities

• Licensing verification - Ensures legitimate script usage

• Vehicle management - Garage spawn/return system for job vehicles

• Player avatar system - Steam and Discord avatar integration

• Framework bridge - Universal compatibility layer for ESX, QB-Core, and QBX

• Language support - Multi-language UI system

Scripts that require Ares Core:

• Ares Electrician

• Future multiplayer-enabled Ares scripts

---

🚀 Installation

Important: Resource Start Order

Ares Core must be started after frameworks but before Ares scripts:

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

# 2. Start Ares Core
ensure ares-core

# 3. Start Ares scripts that depend on it
ensure ares_electrician
# ensure other ares scripts...

Setup Steps

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

2. Configure the script (see Configuration Guide)

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

4. Restart your server

No database setup or item configuration required - Ares Core handles infrastructure only.

---

📦 Dependencies

Required

• Framework: ESX, QB-Core, or QBX (auto-detected)

Optional

• Steam Web API Key - For player Steam avatars

• Discord Bot Token - For custom Discord avatars

Both are optional and can be configured later if needed.

---

⚙️ Configuration Guide

All configuration is done in shared/config.lua.

Framework Settings

Config.Framework = 'auto'
Config.Debug = false

Parameter	Type	Description	Options
Framework	string	Framework detection mode	'auto', 'esx', 'qb-core'
Debug	boolean	Enable debug logging	true/false

Recommended: Leave Framework set to 'auto' for automatic detection. Production: Set Debug = false to reduce console spam.

---

Lobby System Settings

Config.LobbyIdLength = 6
Config.LobbyTimeout = 120
Config.GarbageCollectorInterval = 121

Parameter	Type	Description	Default
LobbyIdLength	number	Character length of generated lobby IDs	6
LobbyTimeout	number	Seconds before empty lobbies are deleted	120
GarbageCollectorInterval	number	Seconds between cleanup cycles	121

How it works:

• When players create a lobby, a random ID is generated (e.g., AB12CD)

• Empty lobbies are automatically deleted after LobbyTimeout seconds

• The garbage collector runs every GarbageCollectorInterval seconds to clean up

Performance tuning:

• Higher LobbyTimeout = lobbies stay active longer (good for slow joiners)

• Lower GarbageCollectorInterval = more frequent cleanup (slightly more server load)

Example - Longer lobby lifetime:

Config.LobbyTimeout = 300  -- 5 minutes before deletion
Config.GarbageCollectorInterval = 180  -- Check every 3 minutes

---

Invite UI Settings

Config.InviteTimeout = 15

Description: Seconds before lobby invite popup auto-dismisses. Default: 15 seconds Range: 5-60 seconds recommended

Example:

Config.InviteTimeout = 30  -- Invites stay on screen for 30 seconds

---

Steam API Configuration

Config.SteamApiKey = ''

Description: Steam Web API key for fetching player Steam avatars.

Setup instructions:

1. Go to https://steamcommunity.com/dev/apikey

2. Sign in with your Steam account

3. Register a new domain (your server name/IP)

4. Copy your API key

5. Paste into config:

Config.SteamApiKey = 'YOUR_STEAM_API_KEY_HERE'

Without Steam API key:

• Player avatars will show initials instead (e.g., "JD" for John Doe)

• Functionality is not affected, only visual appearance

Example:

Config.SteamApiKey = 'ABCDEF1234567890ABCDEF1234567890'

---

Discord Bot Token

Config.DiscordBotToken = ''

Description: Discord Bot token for fetching custom Discord avatars.

Setup instructions:

1. Go to https://discord.com/developers/applications

2. Click New Application

3. Go to Bot section

4. Click Add Bot

5. Under Token, click Copy

6. Paste into config:

Config.DiscordBotToken = 'YOUR_DISCORD_BOT_TOKEN_HERE'

Without Discord Bot token:

• Default Discord avatars will be used as fallback

• Functionality is not affected

Example:

Config.DiscordBotToken = 'MTIzNDU2Nzg5MDEyMzQ1Njc4.ABCDEF.1234567890abcdefghijklmnopqrstuv'

---

Language Settings

Config.Language = 'en'

Description: Language code for lobby UI translations. Default: 'en' (English) Available languages: Check shared/lang/*.json for available language files

Supported languages:

• 'en' - English

• 'fr' - French

• Add custom languages by creating JSON files in shared/lang/

Example:

Config.Language = 'fr'  -- French UI

---

🚗 Garage System

The garage system manages vehicle spawning and return for multiplayer jobs.

Garage Configuration

Config.Garages = {
    ["canal_way"] = {
        label = "Default Garage",
        center = vector3(282.3517, -336.7103, 44.9198),
        dropoff = {
            pos = vector3(297.6721, -338.1398, 44.9199),
            radius = 10.0
        },
        spawn = {
            pos = vector4(275.2115, -329.1011, 44.9203, 300.1234),
            radius = 5.0
        }
    }
}

Garage Parameters

Parameter	Type	Description
label	string	Display name of the garage
center	vector3	Center point for proximity detection
dropoff.pos	vector3	Where players return vehicles
dropoff.radius	number	Radius for valid drop-off zone (meters)
spawn.pos	vector4	Where vehicles spawn (x, y, z, heading)
spawn.radius	number	Check radius for occupied space (meters)

How Garages Work

1. Vehicle Request - Player requests vehicle from nearest garage (based on center)

2. Spawn Check - System verifies spawn area is clear within spawn.radius

3. Vehicle Spawn - Vehicle spawns at spawn.pos with specified heading

4. Drop-off - Player returns vehicle within dropoff.radius of dropoff.pos

Adding Custom Garages

Config.Garages = {
    ["canal_way"] = {
        -- Default garage...
    },
    ["sandy_shores"] = {
        label = "Sandy Shores Garage",
        center = vector3(1737.59, 3710.2, 34.14),
        dropoff = {
            pos = vector3(1740.0, 3715.0, 34.0),
            radius = 15.0
        },
        spawn = {
            pos = vector4(1730.0, 3705.0, 34.0, 210.0),
            radius = 7.0
        }
    },
    ["paleto_bay"] = {
        label = "Paleto Bay Depot",
        center = vector3(-378.86, 6062.08, 31.5),
        dropoff = {
            pos = vector3(-375.0, 6065.0, 31.5),
            radius = 12.0
        },
        spawn = {
            pos = vector4(-382.0, 6058.0, 31.5, 45.0),
            radius = 6.0
        }
    }
}

Finding Coordinates

In-game method:

1. Stand at desired location

2. Open F8 console

3. Type /getcoords (if available) or use:

local coords = GetEntityCoords(PlayerPedId())
local heading = GetEntityHeading(PlayerPedId())
print(string.format("vector4(%.4f, %.4f, %.4f, %.4f)", coords.x, coords.y, coords.z, heading))

---

🚙 Job Vehicles

Configure default vehicles for each Ares script that uses the lobby system.

Job Vehicle Configuration

Config.JobVehicles = {
    ["ares_electrician"] = {
        default = "burrito",
        maxVehicles = 2,
        customVehicles = {
            -- Custom vehicles per phase
        }
    }
}

Parameters

Parameter	Type	Description
default	string	Default vehicle model for this job
maxVehicles	number	Maximum vehicles per lobby
customVehicles	table	Phase-specific vehicle overrides

Adding Job Vehicles

For new Ares scripts:

Config.JobVehicles = {
    ["ares_electrician"] = {
        default = "burrito",
        maxVehicles = 2,
    },
    ["ares_delivery"] = {
        default = "boxville",
        maxVehicles = 3,
        customVehicles = {
            ["phase_1"] = "mule",      -- Use mule truck for phase 1
            ["phase_3"] = "benson"     -- Use benson for phase 3
        }
    },
    ["ares_mining"] = {
        default = "flatbed",
        maxVehicles = 1,
    }
}

Custom Vehicles Per Phase

Use case: Different job phases need different vehicles.

Example:

["ares_electrician"] = {
    default = "burrito",
    maxVehicles = 2,
    customVehicles = {
        ["setup_phase"] = "utillitruck",  -- Utility truck for setup
        ["repair_phase"] = "burrito",     -- Van for repairs
        ["cleanup_phase"] = "tiptruck"    -- Truck for cleanup
    }
}

How it works:

• If phase has a customVehicles entry, that vehicle is used

• Otherwise, default vehicle is spawned

• Vehicle is selected automatically when phase changes

---

🔌 API Reference

Ares Core exports the following functions for use by other scripts:

Server-Side Exports

-- Create a new lobby
exports['ares-core']:CreateLobby(hostId, jobType, maxPlayers)

-- Player joins a lobby
exports['ares-core']:JoinLobby(playerId, lobbyId)

-- Player leaves their current lobby
exports['ares-core']:LeaveLobby(playerId)

-- Get player's current lobby
exports['ares-core']:GetPlayerLobby(playerId)

-- Request a vehicle for a lobby
exports['ares-core']:RequestVehicle(playerId, garageId, vehicleModel)

-- Execute vehicle swap (return old, spawn new)
exports['ares-core']:ExecuteSwap(playerId, oldVehicle, newVehicleModel)

-- Update lobby activity timestamp
exports['ares-core']:UpdateLobbyActivity(lobbyId)

-- Get all players in a lobby
exports['ares-core']:GetLobbyPlayers(lobbyId)

-- Get specific player data from lobby
exports['ares-core']:GetLobbyPlayerData(lobbyId, playerId)

-- Get player's lobby data
exports['ares-core']:GetPlayerLobbyData(playerId)

-- Get host level/rank
exports['ares-core']:getHostLevel(playerId)

Example Usage in Other Scripts

-- Create a lobby when job starts
local lobbyId = exports['ares-core']:CreateLobby(source, 'ares_electrician', 4)

-- Check if player is in a lobby
local playerLobby = exports['ares-core']:GetPlayerLobby(source)
if playerLobby then
    print('Player is in lobby: ' .. playerLobby)
end

-- Request a job vehicle
exports['ares-core']:RequestVehicle(source, 'canal_way', 'burrito')

-- Get all lobby members
local players = exports['ares-core']:GetLobbyPlayers(lobbyId)
for _, playerId in ipairs(players) do
    print('Lobby member: ' .. playerId)
end

---

📝 Quick Reference

Essential Configuration Checklist

• ✅ Set resource start order in server.cfg

• ✅ Configure framework detection (or leave as 'auto')

• ✅ Set Config.Debug = false in production

• ✅ Add garage locations for your map

• ✅ Configure job vehicles for installed Ares scripts

• ⚙️ Optional: Add Steam API key for avatars

• ⚙️ Optional: Add Discord Bot token for avatars

When to Configure Garages

• ✅ Adding new job locations to your server

• ✅ Spreading jobs across different areas of the map

• ✅ Customizing vehicle spawn/return locations

• ❌ Not needed if using default locations

When to Configure Job Vehicles

• ✅ Installing new Ares multiplayer scripts

• ✅ Customizing vehicles per job type

• ✅ Adding phase-specific vehicles

• ✅ Changing maximum vehicles per lobby

---

🔧 Troubleshooting

Issue	Solution
"Ares Core not found" error	Check resource start order in server.cfg
Lobbies not working	Verify framework is detected (check F8 console)
Vehicle won't spawn	Check spawn.pos coordinates and spawn.radius
Can't return vehicle	Verify player is within dropoff.radius
No player avatars	Add Steam API key or Discord Bot token
Lobby immediately deleted	Increase Config.LobbyTimeout value

---

🎯 Important Notes

• Required for: All Ares multiplayer scripts (Electrician, future releases)

• Start order matters: Framework → Ares Core → Ares Scripts

• No items needed: This is pure infrastructure, no inventory items

• Framework agnostic: Works with ESX, QB-Core, QBX, or standalone

• Licensing handled automatically: No manual activation required

---

Support: For issues or questions, please contact Ares Studio. License: This script is protected and should not be redistributed without permission.