Administrator Guide

Complete admin workflow guide for the ARS Weapon Meta Editor. Covers UI navigation, stat editing, component management, persistence, scanning, live preview, AI assistance, and troubleshooting.

---

Table of Contents

1. Opening the Editor
2. Understanding the Weapon List
3. Editing Weapon Stats
4. Editing Component Stats
5. Saving Changes
6. Resetting Weapons
7. Running a Weapon Scan
8. Live Preview Mode
9. AI Weapon Tuning
10. Stat Presets
11. Native Recoil Mode & Spray Visualizer
12. Troubleshooting

---

1. Opening the Editor

Method 1: Command

Type /weaponmeta in chat as an admin user.

/weaponmeta

The UI opens only if your account passes the admin check (Config.AdminPermissions). The NUI is a React panel with tabs: Overview, Tuning, Attachments, Animations, Recoil, and AI.

Method 2: Server Command (Scan Only)

Admins can trigger a weapon scan from the server console without opening the UI:

weaponmeta_scan

---

2. Understanding the Weapon List

The main Overview tab displays all detected weapons in a sortable, searchable list.

Column	Description
Weapon Name	Human-readable label (e.g., Pistol, Assault Rifle) pulled from the game’s label text or the weapon hash
Category	Auto-detected weapon group: pistols, smgs, rifles, shotguns, snipers, heavy, melee, throwable, or unknown
Stats sidebar	Quick glance at current Damage, RPM, Range, Accuracy (varies by UI settings)
Actions	Edit button (pencil) opens the stat editor; Reset button (undo) reverts to defaults

Data sources (in order of precedence):

1. Saved overrides — your admin modifications
2. Scanned defaults — raw values extracted from .meta files
3. Config.StatLimits — used for validation, not display

Modified weapons show a MODIFIED badge in the list.

---

3. Editing Weapon Stats

Click Edit (pencil icon) on any weapon row to open the Tuning tab for that weapon.

Stat Tabs

• Damage — Damage, headshot multipliers, limb/vehicle/network modifiers, AI headshot distances
• Falloff — Damage range falloff curves
• Firing — RPM, reload time, clip size, burst/batch settings
• Accuracy — Spread, aiming modifiers, recoil buildup
• Ballistics — Bullet speed, penetration, force, bending, pitch offsets
• Camera — FOV, zoom, reticle size, aim probe, depth of field
• Rumble — Controller vibration settings (third person / first person)
• FX — Muzzle flash, tracers, smoke
• Misc — Melee multipliers, ammo diminishing, capsule radius
• AI Detection — AI hearing and blast reaction distances
• Range — Weapon range, lock-on range, aircraft lock-on multiplier
• Animation — Breathing, lean, IK settings

Stat Controls

• Sliders — Drag to adjust numeric values (clamped to allowed bounds)
• Number inputs — Type precise values
• Dropdowns — For string-enum stats (DamageType, FireType, EffectGroup, etc.)
• Tooltips — Hover over any stat name for an explanation

All changes are client-side until you click Save.

---

4. Editing Component Stats

Switch to the Attachments tab to edit weapon component metadata (scopes, suppressors, magazines, flashlights, etc.).

The component panel lists all components attached to the currently selected weapon. Each component has its own stat subset:

Component Stat	Description
ClipSize	Magazine capacity override
AccuracyModifier	Accuracy multiplier when equipped
DamageModifier	Damage multiplier
HudDamage / HudSpeed / HudCapacity / HudAccuracy / HudRange	HUD bar values
RecoilShakeAmplitude	Recoil effect modifier
ExtraZoomFactorForAccurateMode	Additional zoom level when aiming
FallOffRangeModifier / FallOffDamageModifier	Damage falloff adjustment
CameraHash	Camera behavior override
ReticuleHash	Crosshair style
SpecialScopeType	Night vision / thermal scope
AmmoInfo	Ammo type (AP, explosive, incendiary, tracer, etc.)
ReloadData	Reload animation variant
bShownOnWheel	Show in weapon wheel
ShouldSilence	Suppressor effect flag
ApplyWeaponTint	Enable tint customization

Note: If Config.OverwriteAddonComponentSource is true, component edits write directly back to the source resource. Otherwise, overrides are generated inside ars_components_assets.

Changes here are client-side until saved.

---

5. Saving Changes

Single Weapon Save

1. Edit stats in the Tuning tab
2. Click Save at the bottom of the panel
3. Server validates all values and persists the changes
4. Companion asset resources are restarted to apply changes in-game
5. Component changes (if any) are saved alongside weapon stats

The UI shows a “Saved” toast and refreshes the badge/stat display.

Bulk Save All

Click Save All at the top of the Overview list. Sends every modified weapon in one batch and performs a single asset resource restart.

Tip: Use Save All to batch multiple edits before restarting — minimizes server interruption.

---

6. Resetting Weapons

Per-Weapon Reset

Click the Reset button (undo/rotate icon) on a weapon row. This:

1. Removes the override for that weapon
2. Restores the weapon to its scanned default
3. Resets all component stats for that weapon back to defaults
4. Restarts companion resources to apply changes

You will be prompted to confirm the action.

Reset All (Console Only)

Run from the server console or RCON:

weaponmeta_resetall

This clears all overrides and resets everything to vanilla defaults. Use with caution — this action cannot be undone.

---

7. Running a Weapon Scan

Click Scan in the top-right of the UI or run the command:

weaponmeta_scan

What Scanning Does

1. Iterates all started resources looking for weapon meta files (vanilla + custom)
2. Extracts weapon hashes, human-readable names, and categories
3. Builds a complete map of every editable stat value for every weapon
4. Populates the UI weapon list if it was empty

When to Scan

• After adding a new weapon mod or custom weapon resource
• If your weapon list is empty or missing entries
• To refresh default values after a framework update

---

8. Live Preview Mode

The Live Preview mode opens an in-game combat simulator so you can test weapon changes in real-time without leaving the game.

How to Use

1. Open /weaponmeta UI and select a weapon to tune
2. In the top header, click Live Preview
3. Spawns 5 target peds in front of you at 10 meters distance, spaced 2 meters apart
4. Shoot the targets to gather live DPS, accuracy, TTK, and hit pattern data
5. Changes to weapon stats apply live to your currently equipped weapon without a restart
6. Press F5 (control 166) to exit live preview and return to the editor
7. Press Alt (control 19) to toggle cursor mode between free-aim and UI interaction

Live Preview Features

• Auto respawn toggle — targets respawn 3 seconds after being destroyed
• Reset stats — revert the weapon to scanned defaults on-the-fly
• Combat stats — shots fired, damage dealt, headshot count, kills
• Hit visualization — 3D damage numbers at impact point (gold = head, red = body, blue = limbs)
• Kill markers — “KILL” text appears above killed peds
• Component support — weapon attachments are applied and testable in the preview

Note: Live Preview uses a separate runtime override that does not persist to the weapons.meta file until you click Save in the editor.

Note: If Config.DisableCriticalHits is true, random GTA V critical headshot multipliers are suppressed during live preview for consistent damage testing.

---

9. AI Weapon Tuning

The built-in AI assistant helps you balance weapons by suggesting stat changes in a one-click apply format.

Starting a Conversation

1. In the UI, click the AI tab (assistant icon)
2. Type a natural-language request in the chat input
   • Examples: “Increase fire rate by 20% and reduce recoil”
   • “Make this a 2-tap headshot weapon at close range”
   • “Balanced for PvP, not too OP”

The AI responds with advice and, if tuning is requested, a suggestions list with stat keys, labels, and new numeric values. Each suggestion has an Apply button that updates the Tuning tab sliders instantly.

AI Flow

• First prompt → AI receives a compact context of key stats first
• If more data needed → AI asks for specific keys; the client fetches additional stats and retries automatically (up to MaxRetrievalRounds)
• Clarification mode → If the prompt is vague, the AI returns multiple-choice questions (up to 3 questions, 6 options each) to narrow the intent
• Final response → Explanation + suggestions array or plain text

Token Cost

Each round consumes LLM tokens. The panel displays [X tok] after each exchange. Costs are tracked server-side but not billed per-user.

Requirements

• ars_weaponmeta:ai_key set in server.cfg
• API endpoint supports OpenAI chat completions format
• Config.AI.Enabled = true

---

10. Stat Presets

The Presets panel lets you save and load weapon stat configurations for quick switching between tuning profiles.

Using Presets

1. Tune a weapon to your desired settings
2. Open the Presets panel and enter a name
3. Click Save to store the current stat configuration
4. Load any saved preset from the list to apply it to the current weapon
5. Use Quick Templates for common tuning profiles

Presets are stored client-side and persist across sessions.

---

11. Native Recoil Mode & Spray Visualizer

The Recoil tab hosts the most advanced feature set in the editor, providing a complete canvas-based spray simulation and support for runtime-driven native recoil.

11.1 Meta Recoil vs. Native Recoil

You can toggle each weapon’s recoil system between two mutually exclusive modes:

1. Meta Recoil Mode (XML-driven): Standard mode. Recoil is driven by the weapon’s .meta XML files. The editor writes metadata overrides that apply upon resource restart.
2. Native Recoil Mode (FiveM runtime-driven): Advanced mode. Recoil is driven live at runtime by the client using FiveM native calls (SetWeaponRecoilShakeAmplitude, SetWeaponWeaponSpread, and SetWeaponAnimationOverride).

[!WARNING] When you toggle a weapon to Native Recoil Mode, the editor automatically resets its 16 recoil and accuracy XML meta parameters back to defaults during save. This is a critical safety feature to prevent FiveM natives from conflicting with game-engine XML overrides.

The 16 reset meta parameters are:

• Recoil: RecoilShakeAmplitude, RecoilErrorTime, RecoilRecoveryRate, RecoilAccuracyMax, IkRecoilDisplacement, IkRecoilDisplacementScope, IkRecoilDisplacementScaleBackward, IkRecoilDisplacementScaleVertical, MinTimeBetweenRecoilShakes, ExplosionShakeAmplitude.
• Accuracy: AccuracySpread, AccurateModeAccuracyModifier, RunAndGunAccuracyModifier, RunAndGunAccuracyMaxModifier, RunAndGunAccuracyMinOverride.

---

11.2 Overrides & Priority Resolution

In Native Recoil Mode, you can customize weapon recoil on a per-player basis:

1. Global Recoil Baseline (Mandatory): The default recoil shake amplitude, weapon spread, and animation override applied to all players.
2. Dynamic Overrides: Flat overrides matching players by:
   • job (player’s current framework job, e.g., police)
   • gang (player’s current framework gang, e.g., ballas)
   • identifier (license/steam/discord identifier, e.g., license:abcdef...)

Resolution Rules

• Overrides are sorted in ascending order of their Priority integer.
• The system evaluates overrides from top to bottom (highest priority/lowest number first).
• First match wins: The first override where the player meets the match condition is applied.
• Fallback: If no override matches, the player falls back to the Global baseline.
• Live switching: Updates are processed instantly. When a player’s job or gang changes via a framework event, or when they swap weapons, their recoil values re-evaluate and apply immediately without restarting any resources.

---

11.3 Recoil Spray Pattern Visualizer

The interactive canvas simulated in the NUI provides a deterministic preview of your weapon’s firing characteristics:

• Simulation Engine: Simulates up to 30 consecutive shots using a seedable PRNG (pseudo-random number generator) and custom weapon-category recoil models (pistols, SMGs, rifles, shotguns, snipers, heavy).
• Early/Mid/Late Gradients: The spray path changes color to show recoil phases (blue for early shots, green for mid-recoil, and red/orange for late-stage maximum vertical climb and horizontal drift).
• First-Person & Third-Person Support: Selects appropriate camera shake hashes based on camera mode and simulates the visual drift.
• Simulation Metrics: Instantly calculates and displays:
  • Peak Climb: Total vertical rise of the spray.
  • Horizontal Span: Total side-to-side recoil variance.
  • Camera Drift: Average and maximum camera shift.
  • Spread Growth: Buildup of weapon spread over sustained fire.
  • Largest Jump: The single biggest jump between consecutive shots.

---

11.4 Tuning Modes & Presets

• Simple Mode: Exposes a single Intensity slider. Dragging this slider proportionally scales all underlying native recoil metrics for quick, intuitive balancing.
• Advanced Mode: Exposes fine-grained control sliders for every metric, including shake amplitude, error recovery, dispersion limits, and custom animations.
• Built-in & Custom Presets: Choose from built-in templates (Pistol, Rifle, SMG, Shotgun, Sniper, Revolver) or export/import your custom setups via JSON to share configurations across servers.

---

12. Troubleshooting

UI says “No permission to use this”

• Verify Config.AdminPermissions.Permissions includes your ACE group name (admin, god, etc.)
• Confirm Config.Framework matches your server’s actual framework
• If using license whitelist, ensure your license identifier is in Config.AdminPermissions.License
• Restart ars_weaponmeta after config changes

Weapons list is empty

• Run /weaponmeta_scan in the server console
• Ensure relevant framework resources are started (qb-core, es_extended, etc.)
• Check that your weapon mod resources have started — they must load before scanning
• Confirm Config.Framework matches the running framework’s identifier

Save fails or shows an error

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

Live Preview stats do not update smoothly

• Some GTA V weapon stats only parse on weapon pickup/swaps
• Drop and re-pick up your current weapon after editing to force a refresh
• Enter/leave a vehicle or respawn as a last resort

AI says “API key is missing”

• Confirm the three set ars_weaponmeta:ai_* convars are in server.cfg
• Restart the server or run ensure ars_weaponmeta after adding convars
• Verify the API key is valid and not expired or out of quota

Resource restarts repeatedly

• Stop the resource, delete data/weapon_meta_state.json (it will regenerate), and restart

---

Quick Reference

Command / Action	Side	Description
/weaponmeta	client	Open UI (admin check required)
/weaponmeta_scan	server	Scan all resources for weapon .meta files
weaponmeta_resetall	server console	Clear all overrides and reset to vanilla
Live Preview F5	client	Exit combat test mode
Live Preview Alt	client	Toggle cursor mode (free-aim / UI)

---

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.