Ares Armory - Adding Custom Weapons

Guide for creating and integrating custom weapons into Ares Armory

---

Step 1: Generate Anchor Data

Tool: Anchor Point Calculator

1. Open the Anchor Point Calculator (web tool)

2. Upload each weapon part image (PNG, JPG, GIF)

3. Click Place Anchor Mode to drop anchors on every merge point

4. Toggle Set Merge Pair, then click matching anchors on different parts

5. Rearrange parts with Drag, use Bring to Front / Send to Back for layering

6. Click Calculate Anchor Info and download myweapon-anchors.json

What this does: Defines exact pixel coordinates where weapon parts snap together during assembly.

---

Step 2: Build Your .js Configuration

Tool: Config Manager

1. Open the Config Manager (web tool)

2. Click Load Template → Empty Template

3. Paste your anchor JSON into the parts: [] section

4. Complete the Workbench Data section:

workbenchData: {
  name: "myweapon",                    // Internal ID (must match server config)
  displayName: "My Custom Gun",        // Shown in UI
  description: "A sleek custom weapon.",
  type: "rifle",                       // Options: pistol | rifle | shotgun
  totalCost: {                         // Total cost categories for the weapon
    Receiver: 1,
    Barrel: 1
  },
  parts: [                             // IDs must match your anchors output
    { 
      id: "myweaponpart1", 
      name: "Receiver", 
      description: "Main body.", 
      image: "./assets/mygun/receiver.blueprint.png", 
      category: "Receiver", 
      cost: { metal_scrap: 6 } 
    },
    { 
      id: "myweaponpart2", 
      name: "Barrel", 
      description: "High-precision barrel.", 
      image: "./assets/mygun/barrel.blueprint.png", 
      category: "Barrel", 
      cost: { metal_scrap: 4, plastic: 2 } 
    }
  ]
}

1. Click Validate to check for errors

2. Click Export Configuration → save as myweapon.js

---

Step 3: Deploy Client-Side Files

1. Copy your weapon config:

   myweapon.js → weaponGame/html/guns/myweapon.js

2. Register the weapon in the config loader:

   • Open weaponGame/html/workbenchconf.js

   • Add your weapon path to the weaponConfigPaths array:

   const weaponConfigPaths = [
       './guns/ak47.js',
       './guns/aku.js',
       './guns/beretta.js',
       './guns/ms500.js',
       './guns/myweapon.js',  // Add your weapon here
   ];

3. Ensure your HTML loads the script (usually automatic if added to weaponConfigPaths)

---

Step 4: Update Server Configuration

File: config.lua

Add Weapon Definition

Under Config.Weapons, add your weapon:

Config.Weapons['myweapon'] = {
    jsConfig = "myweapon",              -- Must match the name in your .js file
    model = "weapon_assaultrifle",      -- Native GTA weapon model
    parts = {                           -- List all part item names
        "myweaponpart1",
        "myweaponpart2",
        "myweaponpart3"
    },
    display = "My Custom Gun",          -- Display name in-game
    xp = 75,                           -- XP awarded when crafted
    level = 5,                         -- Minimum level required to craft
}

Add Materials (Parts) Definitions

Under Config.Materials, define each weapon part:

Config.Materials['myweaponpart1'] = {
    display = "Gun Receiver",
    craftTime = 8,                     -- Seconds to craft
    xp = 15,                          -- XP awarded when part is crafted
    costs = {
        ["metal_scrap"] = 6
    }
}

Config.Materials['myweaponpart2'] = {
    display = "Gun Barrel",
    craftTime = 10,
    xp = 15,
    costs = {
        ["metal_scrap"] = 4,
        ["plastic"] = 2
    }
}

Config.Materials['myweaponpart3'] = {
    display = "Gun Stock",
    craftTime = 6,
    xp = 10,
    costs = {
        ["plastic"] = 5
    }
}

Add Items to Inventory System

Don't forget to add the weapon parts to your inventory system (see main installation guide for ox_inventory, QB-Core, or ESX examples).

---

Step 5: Generate Blueprint Images

Tool: Blueprint Converter

1. Open the Blueprint Converter (web tool)

2. Upload your part PNGs or paste your blueprint config

3. Download the generated blueprint-style PNGs

4. Place them in weaponGame/html/assets/[yourweapon]/

5. Ensure filenames match exactly what you specified in workbenchData.parts[].image

Example structure:

weaponGame/html/assets/mygun/
├── receiver.blueprint.png
├── barrel.blueprint.png
└── stock.blueprint.png

---

Example Reference

For a complete working example, refer to the AK-47 implementation:

• Client config: weaponGame/html/guns/ak47.js

• Server config: config.lua → Config.Weapons['ak47']

• Materials: config.lua → Config.Materials['ak47part1'] through ['ak47part4']

• Assets: weaponGame/html/assets/ak47/

---

Testing Your Custom Weapon

1. Restart your server after making all configuration changes

2. Test the crafting table - your weapon should appear in the list (if you meet level requirements)

3. Verify parts appear in the crafting menu with correct costs

4. Test assembly - parts should snap together visually at your defined anchor points

5. Confirm XP awards are working correctly

---

Troubleshooting

Issue	Solution
Weapon doesn't appear	Check jsConfig matches between .js file and Config.Weapons
Parts don't snap together	Verify anchor coordinates in your .js config
Images not loading	Check file paths in workbenchData.parts[].image
Can't craft parts	Ensure items are added to your inventory system
Wrong weapon spawns	Verify model in Config.Weapons matches GTA weapon name

---

Important Notes

• Internal IDs (name in workbenchData) must be unique across all weapons

• Part item names must match exactly between client .js and server config.lua

• Image paths are relative to weaponGame/html/

• Weapon models must be valid GTA V weapon spawn names

• Anchor data must be precise for smooth part assembly visuals

---

Your custom weapon is now ready! It will appear in-game with full assembly mechanics, crafting requirements, and blueprint visuals.