Installation Guide

Installation guide for server owners and administrators. No database setup required — weapon meta overrides are persisted in data/weapon_meta_state.json and native recoil configurations are persisted in data/native_recoil_state.json.

Prerequisites

• ox_lib — Installed and started before this resource
• QBCore / QBX / ESX / Standalone — One framework must be present on your server
• Resource files — Downloaded from portal.cfx.re

Installation Steps

1. Download and Place Resources

Place all three resources in your server’s resources/ directory:

server-data/resources/[weaponmeta]/
  ├── ars_weaponmeta/
  ├── ars_weaponmeta_assets/
  └── ars_components_assets/

---

2. Configure Filesystem Permissions

Add these lines to your server.cfg:

add_ace resource.ars_weaponmeta command allow
add_filesystem_permission ars_weaponmeta write ars_weaponmeta_assets
add_filesystem_permission ars_weaponmeta write ars_components_assets
add_ace resource.ars_weaponmeta command.add_ace allow

Important: These permissions are mandatory. Without them, saving will fail.

---

3. Configure Framework

Open ars_weaponmeta/config.lua and set Config.Framework to match your server:

Config.Framework = 'qb'         -- QBCore
Config.Framework = 'qbx'        -- QBX
Config.Framework = 'esx'        -- ESX
Config.Framework = 'standalone' -- No framework

---

4. Set Admin Permissions

By default, only accounts with ACE groups admin or god can use the editor. Adjust Config.AdminPermissions to match your server’s admin groups.

Config.AdminPermissions = {
    Permissions = {
        'admin',
        'god'
    },
    License = {
        -- Optional: license identifier whitelist
    }
}

---

5. Add Resources to Server Config

Add these lines at the end of your server.cfg:

ensure ars_weaponmeta_assets
ensure ars_components_assets
ensure ars_weaponmeta

Note: ox_lib must be started somewhere in your server.cfg before these resources.

---

6. (Optional) Configure AI Assistant

The built-in AI assistant requires an OpenAI-compatible chat completion API endpoint.

Add these convars to your server.cfg:

set ars_weaponmeta:ai_key "<your-api-key>"
set ars_weaponmeta:ai_model "<model-name>"
set ars_weaponmeta:ai_url "<api-endpoint>"

Supported providers:

Provider	ai_url	ai_model examples	Notes
Groq	https://api.groq.com/openai/v1/chat/completions	llama-3.3-70b-versatile, llama-3.1-8b-instant	Free tier: 30 req/min; fastest inference
OpenRouter	https://openrouter.ai/api/v1/chat/completions	openrouter/free, meta-llama/llama-3.3-70b-instruct	300+ models; free tier available
Local/other	Your custom endpoint	Any OpenAI-compatible model ID	Must support /chat/completions

Note: The AI runs entirely server-side — keys are never sent to clients.

---

7. (Optional) Configure Add-on Component Write-Back

By default, Config.OverwriteAddonComponentSource is false, meaning add-on component edits generate override files inside ars_components_assets. If set to true, edits are written directly back to the source resource’s original .meta file.

When enabled, you must add filesystem permissions for each add-on resource that contains weapon components. The resource prints the required add_filesystem_permission lines on startup.

---

8. Start the Server

Start or restart your server. Look for [ars_weaponmeta] Ready in the console.

---

Verification

1. Console output — Look for [ars_weaponmeta] Ready.
2. Run /weaponmeta as an admin in-game. The NUI panel should open without a “No permission” error.
3. Click Scan (or run /weaponmeta_scan from server console) and verify weapons populate the list.
4. Edit a weapon stat — Change Damage or TimeBetweenShots, click Save, then test the weapon in-game.
5. Test Native Recoil — Select a weapon, switch to the Recoil tab, toggle its mode to Native, adjust the global baseline RecoilShakeAmplitude, and check that the shooting behavior applies in-game and mirrors the canvas-based spray pattern visualizer.

---

Updating

1. Replace the resource files with the new version.
2. Compare the new config.lua with your customized version and merge any new options.
3. Restart the server.

---

Troubleshooting

“No permission to use this” when opening UI

• Ensure your account has an ACE group listed in Config.AdminPermissions.Permissions
• Verify Config.Framework matches your server’s framework
• Restart the resource after changing config.lua

Weapons list is empty or incomplete

• Run /weaponmeta_scan from the server console to force a full scan
• Ensure your framework resources are started before this resource
• If using a custom weapon mod, verify it includes .meta files

Save fails or shows filesystem error

• Verify the add_ace / add_filesystem_permission lines in server.cfg are present
• Check that ars_weaponmeta_assets is running
• If using OverwriteAddonComponentSource, ensure filesystem permissions are set for the add-on resource

AI assistant returns errors

• Confirm ars_weaponmeta:ai_key, ars_weaponmeta:ai_model, and ars_weaponmeta:ai_url convars are set in server.cfg
• Check that the API key is valid and has quota remaining

Weapon changes do not apply in-game

• Confirm the console shows a resource restart message after saving (for Meta mode meta-XML files)
• If changes seem to revert after a full server restart, check write permissions on the resource folder
• For Native Recoil mode, verify changes are saved to the server and synchronized (Native mode does not trigger a resource restart on save because values are updated dynamically at runtime)

Native recoil overrides are not resolving

• Ensure data/native_recoil_state.json exists in your data/ folder and is writable by the resource
• Verify Config.Framework matches your actual running framework
• Enable Config.Debug to inspect job, gang, and identifier runtime matching in your server logs

---

Note: AI convars (set ars_weaponmeta:ai_*) can go anywhere in server.cfg.

---

Note: This guide is written by a third party. If you find any incorrect or outdated information, please contact us on Discord so we can update it for you.