Ares Armory - Installation & Configuration Guide

Version: 1.5.0 Authors: KPG-TB, Roroleroh Framework Support: ESX, QB-Core, QBX Core

---

📋 Table of Contents

• Installation

• Dependencies

• Item Configuration

• Configuration Guide

• Custom Notifications

---

🚀 Installation

Important Notice

⚠️ Do not rename the resource folder. The script must be named weaponGame to function properly.

Setup Steps

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

2. Add items to your inventory system (see Item Configuration)

3. Add to server.cfg:

   ensure weaponGame

4. Restart your server

The script will automatically initialize its database tables on first startup if they don't exist.

---

📦 Dependencies

Required (Choose One Framework)

• ESX (any version)

• QB-Core (any version)

• QBX Core (any version)

Optional

• ox_lib - Enhanced UI features

• ox_target - Target system integration

• ox_inventory - Advanced inventory support

• oxmysql - MySQL database wrapper

The script automatically detects your framework and adapts accordingly. No manual configuration needed.

---

🎒 Item Configuration

For ox_inventory

ox_inventory

Add the following items to your ox_inventory/data/items.lua file:

-- Base Materials
["plastic"] = {
    label = "Plastic",
    weight = 1050,
    stack = true,
    close = true,
},

["metal_scrap"] = {
    label = "Metal Scrap",
    weight = 1050,
    stack = true,
    close = true,
},

-- AK-47 Parts
["ak47part1"] = {
    label = "AK-47 Top Cover",
    weight = 2800,
    stack = false,
    close = true,
},

["ak47part2"] = {
    label = "Receiver",
    weight = 2800,
    stack = false,
    close = true,
},

["ak47part3"] = {
    label = "AK-47 Buttstock",
    weight = 2800,
    stack = false,
    close = true,
},

["ak47part4"] = {
    label = "AK-47 Barrel",
    weight = 2800,
    stack = false,
    close = true,
},

-- Compact Rifle (AKU) Parts
["akupart1"] = {
    label = "AKU | Top Cover",
    weight = 2800,
    stack = false,
    close = true,
},

["akupart2"] = {
    label = "AKU | Receiver",
    weight = 2800,
    stack = false,
    close = true,
},

["akupart3"] = {
    label = "AKU | Barrel",
    weight = 2800,
    stack = false,
    close = true,
},

-- Beretta Parts
["berettapart1"] = {
    label = "Beretta Barrel",
    weight = 2800,
    stack = false,
    close = true,
},

["berettapart2"] = {
    label = "Beretta Trigger",
    weight = 2800,
    stack = false,
    close = true,
},

["berettapart3"] = {
    label = "Beretta Receiver",
    weight = 2800,
    stack = false,
    close = true,
},

["berettapart4"] = {
    label = "Beretta Slide",
    weight = 2800,
    stack = false,
    close = true,
},

-- MS 500 Shotgun Parts
["ms500part1"] = {
    label = "MS 500 Barrel",
    weight = 2800,
    stack = false,
    close = true,
},

["ms500part2"] = {
    label = "MS 500 Slide",
    weight = 2800,
    stack = false,
    close = true,
},

["ms500part3"] = {
    label = "MS 500 Grip",
    weight = 2800,
    stack = false,
    close = true,
},

["ms500part4"] = {
    label = "MS 500 Buttstock",
    weight = 2800,
    stack = false,
    close = true,
},

["ms500part5"] = {
    label = "MS 500 Receiver",
    weight = 2800,
    stack = false,
    close = true,
},

QB-Core Inventory

ESX Legacy

---

⚙️ Configuration Guide

All configuration is done in the config.lua file. Below is a comprehensive breakdown of each section.

General Settings

Locale

Config.Locale = 'en'

Description: Sets the default language for the script. Options: 'en', 'fr', 'de', 'es' (add custom locales in locales/ folder) Default: 'en'

---

Crafting Table Locations

Config.Tables = {
    vec3(-151.23, -984.49, 114.12),
    { coords = vec3(145.8781, 142.4480, 111.9217), weapons = { 'ak47', 'beretta' } }
}

Description: Defines the physical locations of weapon crafting tables in the game world.

Formats:

• Simple format: vec3(x, y, z) — Shows all weapons at this location

• Advanced format: { coords = vec3(x, y, z), weapons = { 'ak47', 'beretta' } } — Only specific weapons

• Explicit all: { coords = vec3(x, y, z), weapons = 'all' } — Shows all weapons (explicit)

Example:

Config.Tables = {
    vec3(100.0, 200.0, 30.0),                                        -- All weapons available
    { coords = vec3(300.0, 400.0, 50.0), weapons = { 'ak47' } },     -- Only AK-47
    { coords = vec3(500.0, 600.0, 70.0), weapons = 'all' }           -- All weapons (explicit)
}

---

Weapon Item Mode

Config.IsWeaponAnItem = true

Description: Determines whether crafted weapons are treated as inventory items. Options: true (weapons as items), false (weapons as native GTA weapons) Default: true Note: Required for ox_inventory and modern inventory systems.

---

Client Options

Target System

Config.Options.Target = {
    enabled = false,
    system = 'ox_target',
    fallbackToPress = false,
    debug = false,
    options = {
        distance = 2.0,
        label = 'Use Weapon Table'
    }
}

Parameter	Type	Description	Default
enabled	boolean	Enable target system integration	false
system	string	Target system to use ('ox_target' or 'qb-target')	'ox_target'
fallbackToPress	boolean	Fall back to press "E" if target not available	false
debug	boolean	Show debug boxes around target zones	false
options.distance	number	Interaction distance in meters	2.0
options.label	string	Label shown in target menu	'Use Weapon Table'

QB-Target support is experimental. Use at your own risk.

---

Table Interaction

Config.Options.Table = {
    InteractionDistance = 1.0,
    NotificationCooldown = 15000,
    CheckFrequency = {
        Near = 1000
    }
}

Parameter	Type	Description	Default
InteractionDistance	number	How close player must be to interact (meters)	1.0
NotificationCooldown	number	Cooldown between notifications (milliseconds)	15000
CheckFrequency.Near	number	How often to check player proximity (milliseconds)	1000

---

Notifications

Config.Options.Notifications = {
    Enabled = true,
    type = 'default',
    Debug = false
}

Parameter	Type	Description	Options
Enabled	boolean	Enable/disable notifications	true/false
type	string	Notification system to use	'default', 'ox', 'custom'
Debug	boolean	Show debug notifications in console	true/false

Notification Types:

• 'default' — Native GTA notifications

• 'ox' — ox_lib notifications (requires ox_lib)

• 'custom' — User-defined system (see Custom Notifications)

---

Inventory & Progress

Config.Options.Inventory = 'auto'
Config.Options.Progress = {
    type = 'bar'
}

Parameter	Type	Description	Options
Inventory	string	Inventory system detection	'auto', 'ox'
Progress.type	string	Progress bar style	'bar', 'circle'

Recommended: Leave Inventory set to 'auto' for automatic framework detection. Note: Use 'circle' progress type for Qbox framework.

---

Leveling System

Config.Leveling = {
    Enabled = true,
    Levels = {
        [1] = 0, [2] = 100, [3] = 250, [4] = 500, [5] = 850,
        [6] = 1300, [7] = 1900, [8] = 2700, [9] = 3800, [10] = 5200,
    },
    MaxLevel = 10,
    DefaultWeaponXP = 50,
    DefaultPartXP = 10,
}

Parameter	Type	Description
Enabled	boolean	Enable/disable XP and leveling system
Levels	table	XP required for each level (key = level, value = XP needed)
MaxLevel	number	Maximum achievable level
DefaultWeaponXP	number	Default XP awarded for crafting a weapon
DefaultPartXP	number	Default XP awarded for crafting a part

How it works:

• Players earn XP by crafting weapons and parts

• Higher-level weapons require more XP to unlock

• Individual weapons and parts can have custom XP values (see Weapons/Materials config)

Example progression:

• Level 1 → 0 XP (start)

• Level 2 → 100 XP

• Level 5 → 850 XP

• Level 10 → 5200 XP

---

Weapons Configuration

Config.Weapons = {
    ['ak47'] = {
        jsConfig = "ak47",
        model = "weapon_assaultrifle",
        parts = { "ak47part1", "ak47part2", "ak47part3", "ak47part4" },
        display = "AK 47",
        xp = 60,
        level = 1,
    }
}

Parameter	Type	Description
jsConfig	string	JavaScript configuration identifier (don't change)
model	string	Native GTA weapon spawn name
parts	table	Array of part item names required to craft
display	string	Display name shown in UI
xp	number	XP awarded when weapon is crafted
level	number	Minimum level required to craft this weapon

Adding custom weapons:

Please see our Custom weapons page

['custom_rifle'] = {
    jsConfig = "custom_rifle",
    model = "weapon_specialcarbine",
    parts = { "custompart1", "custompart2", "custompart3" },
    display = "Custom Rifle",
    xp = 80,
    level = 5,
}

Pre-configured weapons:

• AK-47 — Level 1, 60 XP (4 parts)

• Compact Rifle — Level 3, 45 XP (3 parts)

• Beretta — Level 1, 40 XP (4 parts)

• MS 500 Shotgun — Level 5, 75 XP (5 parts)

---

Materials Configuration

Config.Materials = {
    ['ak47part1'] = {
        display = "AK-47 Top Cover",
        craftTime = 8,
        xp = 15,
        costs = {
            ["metal_scrap"] = 3
        }
    }
}

Parameter	Type	Description
display	string	Display name shown in crafting UI
craftTime	number	Time in seconds to craft this part
xp	number	XP awarded when part is crafted
costs	table	Materials required (item name = quantity)

Example material costs:

costs = {
    ["metal_scrap"] = 5,
    ["plastic"] = 3,
    ["steel"] = 2
}

Crafting times by complexity:

• Simple parts (triggers, grips): 4-5 seconds

• Medium parts (receivers, slides): 8-10 seconds

• Complex parts (barrels, stocks): 15-20 seconds

---

🔔 Custom Notifications

The script supports custom notification systems. Modify client/custom_notifications.lua to integrate your preferred notification resource.

File Location

weaponGame/client/custom_notifications.lua

File Structure

CustomNotifications = {
    debug = false,

    -- Help notification (top-right corner)
    notify = function(text)
        -- Your custom notification code here
        return false  -- Return false to use default fallback
    end,

    -- Info notification (above minimap)
    info = function(text)
        -- Your custom notification code here
        return false  -- Return false to use default fallback
    end
}

Integration Examples

Mythic Notify

notify = function(text)
    exports['mythic_notify']:SendAlert('inform', text)
    return true  -- Return true to prevent default notification
end

okokNotify

info = function(text)
    exports['okokNotify']:Alert("Weapon Crafting", text, 3000, 'info')
    return true
end

QBCore Notify

notify = function(text)
    QBCore.Functions.Notify(text, 'primary', 5000)
    return true
end

ESX Notify

info = function(text)
    ESX.ShowNotification(text)
    return true
end

Debug Mode

Enable debug mode to test your custom notifications:

CustomNotifications = {
    debug = true,  -- Prints notifications to F8 console
    -- ...
}

Return values:

• return true — Notification handled by custom system

• return false — Fall back to default notification system

---

📝 Quick Reference

Essential Configuration Checklist

• ✅ Set crafting table locations in Config.Tables

• ✅ Configure interaction distance in Config.Options.Table

• ✅ Choose notification system in Config.Options.Notifications

• ✅ Adjust leveling progression in Config.Leveling

• ✅ Customize weapon XP and requirements

• ✅ Set material costs for economic balance