Configuration

All settings are defined in config.lua. Changes require a resource restart to take effect.

---

Core Settings

Config.Debug

Enables verbose debug printing in server and client logs. Useful for troubleshooting.

Config.Debug = true

Config.Framework

Framework your server runs on. Choose one:

• 'qb' — QBCore
• 'qbx' — QBX (QBCore fork, most compatible)
• 'esx' — ESX
• 'standalone' — No framework; relies only on weapon meta scanning

Config.Framework = 'qb'

Config.ToggleCommand

Client-side chat command that opens/closes the Weapon Meta Editor NUI. Users must still pass the server-side admin check.

Config.ToggleCommand = 'weaponmeta'

Config.DisableCriticalHits

Disables GTA V critical headshot damage during the live preview combat simulator. When true, random critical multiplier variance is suppressed for consistent damage testing.

Config.DisableCriticalHits = true

---

Admin Permissions

Config.AdminPermissions

Controls which players can open the editor UI and run admin actions.

Config.AdminPermissions = {
    Permissions = {
        'admin',  -- Standard FiveM admin ACE permission
        'god'     -- God mode ACE permission (common on many servers)
    },
    License = {
        -- Optional: license identifier whitelist (bypasses ACE check)
        -- ['license:12345678901234567890123456789012'] = true,
    }
}

How checks work:

• ACE groups in Permissions are checked via IsPlayerAceAllowed
• License identifiers in License are checked as a fallback

Tip: Use add_ace group.admin command allow and add 'admin' to the Permissions list for standard admin setup. If your server uses custom ACE groups, add them here.

---

Inventory Images (Optional)

Config.InventoryImages

Base NUI URL for displaying weapon/item icons inside the editor’s attachment tabs. Set this to match your inventory system’s image path:

Config.InventoryImages = 'nui://qb-inventory/html/images/'

Supported inventory systems:

Inventory	Example Value
qb-inventory	nui://qb-inventory/html/images/
ox_inventory	nui://ox_inventory/web/images/
qs-inventory	nui://qs-inventory/html/images/
ps-inventory	nui://ps-inventory/html/images/
ak47_inventory	nui://ak47_inventory/web/build/images/
ak47_qb_inventory	nui://ak47_qb_inventory/web/build/images/

Leave blank or at default if you do not use inventory icon display in the UI.

---

Component Write-Back

Config.OverwriteAddonComponentSource

Controls where add-on weapon component edits are written:

• false — Generate per-component override files inside ars_components_assets (default, safe)
• true — Write edited component data directly back into the owning source resource’s original .meta file

Config.OverwriteAddonComponentSource = false

Warning: When set to true, you must add add_filesystem_permission ars_weaponmeta write <resource_name> for each add-on resource that contains weapon components. The resource prints the required lines on startup.

---

AI Assistant (Optional)

Config.AI

Configuration for the built-in AI weapon-tuning assistant. Works with any OpenAI-compatible API (Kilo default, Groq, OpenRouter, etc.).

Config.AI = {
    Enabled = true,
    PromptMaxLength = 1000,       -- Maximum characters for user prompt
    HistoryMessages = 10,         -- Number of recent messages retained in context
    RequestCooldown = 3,          -- Seconds between requests per user (anti-spam)
    UseFullStatContext = false,   -- If true, sends all stats on every request; if false, sends a compact subset first
    MaxRetrievalRounds = 1,       -- How many times AI can request additional stat context before being forced to answer
    MaxRequestedKeys = 10,        -- Maximum stat keys AI may request per retrieval round
    MaxTokens = 8000,             -- Maximum response tokens allowed from the API
}

Enabling the AI:

Set these convars in server.cfg:

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

Provider	ai_url	ai_model examples	How to get key
Kilo (default)	https://api.kilo.ai/api/gateway/chat/completions	kilo-auto/free	Default provider
Groq (recommended)	https://api.groq.com/openai/v1/chat/completions	llama-3.3-70b-versatile, llama-3.1-8b-instant	console.groq.com/keys
OpenRouter	https://openrouter.ai/api/v1/chat/completions	openrouter/free, meta-llama/llama-3.3-70b-instruct	openrouter.ai/keys
Local/other	Your custom endpoint	Any OpenAI-compatible model ID	Provider-specific

---

Native Recoil Settings

Config.NativeRecoil

Configuration for runtime FiveM-native driven weapon recoil and player-specific overrides. When enabled, admins can toggle weapons into Native Recoil Mode in the NUI.

Config.NativeRecoil = {
    Enabled = true,               -- Enables the entire native recoil NUI panel and runtime application
    AutoDetectJobs = true,        -- Automatically queries and lists jobs from QBCore/QBX/ESX in dropdown menus
    ManualJobs = {},              -- Custom job list to append to the auto-detected list (strings)
    GangResource = '',            -- Custom gang resource if using an external gang script
    GangField = 'gang',           -- Data field in framework player metadata containing gang information
    DefaultAnimOverrides = {      -- Animation options displayed in the NUI dropdown for native recoil overrides
        'Default', 'Gang1H', 'Gang2H', 'Fat',
        'FirstPerson', 'Ballistic', 'Hillbilly',
    },
}

How Native Recoil works:

• When a weapon is switched to Native mode, the client runs a fast polling loop to apply custom recoil parameters live via FiveM natives.
• Recoil-related XML metadata overrides for that weapon are automatically restored to their defaults during saving to avoid engine conflicts.
• Supports a mandatory Global baseline for all users, plus an ordered list of overrides targeting job, gang, or identifier matches.
• Dynamic updates occur immediately at runtime when a player changes their job, gang, or swaps weapons.

---

Stat Limits

All numeric weapon stats are validated server-side against min/max bounds before saving. There are 154 stat limit entries in Config.StatLimits.

Config.StatLimits

Bounds for each editable weapon stat key. Values outside these ranges are rejected or clamped.

Config.StatLimits = {
    -- ═══ Damage ═══
    Damage = { min = 0, max = 500 },
    DamageTime = { min = 0, max = 10 },
    DamageTimeInVehicle = { min = 0, max = 10 },
    DamageTimeInVehicleHeadShot = { min = 0, max = 10 },
    EnduranceDamage = { min = 0, max = 500 },
    HeadshotDamageModifier = { min = 0, max = 5 },
    HeadShotDamageModifierAI = { min = 0, max = 1000 },
    RecoilAccuracyToAllowHeadShotAI = { min = 0, max = 1000 },
    RecoilAccuracyToAllowHeadShotPlayer = { min = 0, max = 1000 },
    NetworkHeadShotPlayerDamageModifier = { min = 0, max = 5 },
    HitLimbsDamageModifier = { min = 0, max = 2 },
    NetworkHitLimbsDamageModifier = { min = 0, max = 2 },
    LightlyArmouredDamageModifier = { min = 0, max = 2 },
    VehicleDamageModifier = { min = 0, max = 5 },
    ArmouredVehicleGlassDamageOverride = { min = -1, max = 500 },
    NetworkPlayerDamageModifier = { min = 0, max = 5 },
    NetworkPedDamageModifier = { min = 0, max = 5 },
    MinHeadShotDistancePlayer = { min = 0, max = 200 },
    MaxHeadShotDistancePlayer = { min = 0, max = 200 },
    MinHeadShotDistanceAI = { min = 0, max = 1000 },
    MaxHeadShotDistanceAI = { min = 0, max = 1000 },

    -- ═══ Falloff ═══
    DamageFallOffRangeMin = { min = 0, max = 1500 },
    DamageFallOffRangeMax = { min = 0, max = 1500 },
    DamageFallOffModifier = { min = 0, max = 1 },

    -- ═══ Firing ═══
    TimeBetweenShots = { min = 0, max = 5 },
    AmmoMaxClip = { min = 1, max = 9999 },
    ReloadTimeMP = { min = 0, max = 5 },
    ReloadTimeSP = { min = -1, max = 5 },
    VehicleReloadTime = { min = 0, max = 5 },
    TimeLeftBetweenShotsWhereShouldFireIsCached = { min = -1, max = 5 },
    BulletsInBatch = { min = 1, max = 50 },
    BatchSpread = { min = 0, max = 0.5 },
    AnimReloadRate = { min = 0, max = 5 },
    BulletsPerAnimLoop = { min = 1, max = 100 },
    SpinUpTime = { min = 0, max = 5 },
    SpinTime = { min = 0, max = 30 },
    SpinDownTime = { min = 0, max = 5 },
    AlternateWaitTime = { min = -1, max = 5 },

    -- ═══ Accuracy ═══
    AccuracySpread = { min = 0, max = 10 },
    AccurateModeAccuracyModifier = { min = 0, max = 2 },
    RunAndGunAccuracyModifier = { min = 0, max = 3 },
    RunAndGunAccuracyMaxModifier = { min = 0, max = 3 },
    RunAndGunAccuracyMinOverride = { min = -1, max = 3 },
    RecoilErrorTime = { min = 0, max = 10 },

    -- ═══ Recoil ═══
    RecoilShakeAmplitude = { min = 0, max = 2.5 },
    ExplosionShakeAmplitude = { min = -1, max = 2.5 },
    RecoilRecoveryRate = { min = 0, max = 2 },
    RecoilAccuracyMax = { min = 0, max = 2 },
    IkRecoilDisplacement = { min = 0, max = 1 },
    IkRecoilDisplacementScope = { min = 0, max = 1 },
    IkRecoilDisplacementScaleBackward = { min = 0, max = 2 },
    IkRecoilDisplacementScaleVertical = { min = 0, max = 2 },
    MinTimeBetweenRecoilShakes = { min = 0, max = 1000 },

    -- ═══ Bullet Physics ═══
    Speed = { min = 0, max = 5000 },
    Penetration = { min = 0, max = 1 },
    ProjectileForce = { min = 0, max = 500 },
    FragImpulse = { min = 0, max = 1000 },
    VerticalLaunchAdjustment = { min = -10, max = 10 },
    BulletBendingFarRadius = { min = 0, max = 5 },
    BulletBendingNearRadius = { min = 0, max = 5 },
    BulletBendingZoomedRadius = { min = 0, max = 5 },
    FirstPersonBulletBendingNearRadius = { min = 0, max = 5 },
    FirstPersonBulletBendingFarRadius = { min = 0, max = 5 },
    FirstPersonBulletBendingZoomedRadius = { min = 0, max = 5 },
    BulletDirectionOffsetInDegrees = { min = 0, max = 10 },
    BulletDirectionPitchOffset = { min = -10, max = 10 },
    BulletDirectionPitchHomingOffset = { min = -10, max = 10 },

    -- ═══ Force ═══
    Force = { min = 0, max = 500 },
    ForceHitPed = { min = 0, max = 2000 },
    ForceHitVehicle = { min = 0, max = 2000 },
    ForceHitFlyingHeli = { min = 0, max = 2000 },
    ForceMaxStrengthMult = { min = 0, max = 5 },
    ForceFalloffRangeStart = { min = 0, max = 500 },
    ForceFalloffRangeEnd = { min = 0, max = 500 },
    ForceFalloffMin = { min = 0, max = 5 },
    KillshotImpulseScale = { min = 0, max = 2 },
    KnockdownCount = { min = 0, max = 10 },

    -- ═══ Camera ═══
    CameraFov = { min = 10, max = 120 },
    FirstPersonAimFovMin = { min = 10, max = 120 },
    FirstPersonAimFovMax = { min = 10, max = 120 },
    FirstPersonScopeFov = { min = 0, max = 120 },
    FirstPersonScopeAttachmentFov = { min = 0, max = 120 },
    ZoomFactorForAccurateMode = { min = 0, max = 5 },
    VehicleAttackAngle = { min = 0, max = 90 },
    ReticuleMinSizeStanding = { min = 0, max = 1 },
    ReticuleMinSizeCrouched = { min = 0, max = 1 },
    ReticuleScale = { min = 0, max = 1 },
    AimProbeLengthMin = { min = 0, max = 5 },
    AimProbeLengthMax = { min = 0, max = 5 },
    AimProbeRadiusOverrideFPSIdle = { min = 0, max = 5 },
    AimProbeRadiusOverrideFPSIdleStealth = { min = 0, max = 5 },
    AimProbeRadiusOverrideFPSLT = { min = 0, max = 5 },
    AimProbeRadiusOverrideFPSRNG = { min = 0, max = 5 },
    AimProbeRadiusOverrideFPSScope = { min = 0, max = 5 },
    FirstPersonDofMaxNearInFocusDistance = { min = 0, max = 10 },
    FirstPersonDofMaxNearInFocusDistanceBlendLevel = { min = 0, max = 1 },
    FirstPersonDofSubjectMagnificationPowerFactorNear = { min = 0, max = 10 },

    -- ═══ HUD ═══
    HudDamage = { min = 0, max = 100 },
    HudSpeed = { min = 0, max = 100 },
    HudCapacity = { min = 0, max = 100 },
    HudAccuracy = { min = 0, max = 100 },
    HudRange = { min = 0, max = 100 },

    -- ═══ Rumble ═══
    InitialRumbleDuration = { min = 0, max = 500 },
    InitialRumbleIntensity = { min = 0, max = 2 },
    InitialRumbleIntensityTrigger = { min = 0, max = 2 },
    RumbleDuration = { min = 0, max = 500 },
    RumbleIntensity = { min = 0, max = 2 },
    RumbleDamageIntensity = { min = 0, max = 2 },
    RumbleIntensityTrigger = { min = 0, max = 2 },
    InitialRumbleDurationFps = { min = 0, max = 500 },
    InitialRumbleIntensityFps = { min = 0, max = 2 },
    RumbleDurationFps = { min = 0, max = 500 },
    RumbleIntensityFps = { min = 0, max = 2 },

    -- ═══ FX ═══
    MuzzleSmokeFxMinLevel = { min = 0, max = 1 },
    MuzzleSmokeFxIncPerShot = { min = 0, max = 1 },
    MuzzleSmokeFxDecPerSec = { min = 0, max = 1 },
    TracerFxChanceMP = { min = 0, max = 1 },
    TracerFxChanceSP = { min = 0, max = 1 },
    FlashFxScale = { min = 0, max = 5 },
    FlashFxChanceMP = { min = 0, max = 1 },
    FlashFxChanceSP = { min = 0, max = 1 },
    FlashFxAltChance = { min = 0, max = 1 },

    -- ═══ Misc ═══
    AmmoDiminishingRate = { min = 0, max = 100 },
    ExpandPedCapsuleRadius = { min = 0, max = 1 },
    DropForwardVelocity = { min = 0, max = 100 },
    MeleeDamageMultiplier = { min = -1, max = 10 },
    MeleeRightFistTargetHealthDamageScaler = { min = -1, max = 10 },

    -- ═══ AI ═══
    AiSoundRange = { min = -1, max = 500 },
    AiPotentialBlastEventRange = { min = -1, max = 500 },

    -- ═══ Range ═══
    WeaponRange = { min = 0, max = 1500 },
    LockOnRange = { min = 0, max = 200 },
    AirborneAircraftLockOnMultiplier = { min = 0, max = 10 },

    -- ═══ Animation Breathing ═══
    AimingBreathingAdditiveWeight = { min = 0, max = 1 },
    FiringBreathingAdditiveWeight = { min = 0, max = 1 },
    StealthAimingBreathingAdditiveWeight = { min = 0, max = 1 },
    StealthFiringBreathingAdditiveWeight = { min = 0, max = 1 },

    -- ═══ Animation Lean ═══
    AimingLeanAdditiveWeight = { min = 0, max = 1 },
    FiringLeanAdditiveWeight = { min = 0, max = 1 },
    StealthAimingLeanAdditiveWeight = { min = 0, max = 1 },
    StealthFiringLeanAdditiveWeight = { min = 0, max = 1 },

    -- ═══ Animation IK ═══
    TorsoIKAngleLimit = { min = -1, max = 360 },
}

Config.StringStatLimits

Enumerated string values allowed for specific weapon stat keys. Out-of-list strings are rejected.

Config.StringStatLimits = {
    DamageType = { 'BULLET', 'MELEE', 'EXPLOSIVE', 'NONE', 'ELECTRIC', 'FIRE', 'SMASH' },
    FireType = { 'INSTANT_HIT', 'DELAYED_HIT', 'PROJECTILE', 'MELEE', 'NONE' },
    EffectGroup = {
        'WEAPON_EFFECT_GROUP_PISTOL_SMALL',
        'WEAPON_EFFECT_GROUP_PISTOL_LARGE',
        'WEAPON_EFFECT_GROUP_SMG',
        'WEAPON_EFFECT_GROUP_RIFLE_ASSAULT',
        'WEAPON_EFFECT_GROUP_RIFLE_SNIPER',
        'WEAPON_EFFECT_GROUP_SHOTGUN',
        'WEAPON_EFFECT_GROUP_ROCKET',
        'WEAPON_EFFECT_GROUP_GRENADE',
        'WEAPON_EFFECT_GROUP_MELEE_SHARP',
        'WEAPON_EFFECT_GROUP_MELEE_WOOD',
        'WEAPON_EFFECT_GROUP_MELEE_GENERIC',
    },
    NmShotTuningSet = { 'Automatic', 'Mini', 'Shotgun', 'Sniper', 'Normal', 'normal', 'Pistol', 'Rifle', 'Heavy', 'Melee' },
    AimingInfo = {
        'PISTOL_2H_BASE_STRAFE', 'RIFLE_HI_BASE_STRAFE', 'RIFLE_LO_BASE_STRAFE',
        'SMG_2H_BASE_STRAFE', 'MG_LOW_BASE_STRAFE', 'UNARMED_TARGETING_RESTRAINTS',
        'FLASHLIGHT_TARGETING_RESTRAINTS', 'PISTOL_FLAREGUN_BASE_STRAFE',
        'RIFLE_LO_DBSHOT_STRAFE', 'HOMING_RPG', 'GRENADELAUNCHER', 'RPG',
    },
    MovementModeConditionalIdle = { '', 'MMI_1Handed', 'MMI_2Handed', 'MMI_2Handed_Short' },
}

---

Component Limits

Weapon attachment components (scopes, suppressors, magazines, etc.) have their own stat limits.

Config.ComponentStatLimits

Numeric stat limits for weapon components.

Config.ComponentStatLimits = {
    ClipSize = { min = 1, max = 9999 },
    AccuracyModifier = { min = 0, max = 5 },
    DamageModifier = { min = 0, max = 5 },
    HudDamage = { min = -10, max = 100 },
    HudSpeed = { min = -10, max = 100 },
    HudCapacity = { min = -10, max = 300 },
    HudAccuracy = { min = -10, max = 100 },
    HudRange = { min = -10, max = 100 },
    RecoilShakeAmplitude = { min = 0, max = 2.5 },
    ExtraZoomFactorForAccurateMode = { min = 0, max = 5 },
    RecoilShakeAmplitudeModifier = { min = 0, max = 2 },
    FallOffRangeModifier = { min = 0, max = 5 },
    FallOffDamageModifier = { min = 0, max = 5 },
}

Config.ComponentStringLimits

String enum limits for component-specific settings.

Config.ComponentStringLimits = {
    CameraHash = {
        '', 'DEFAULT_THIRD_PERSON_PED_AIM_CAMERA', 'PISTOL_AIM_CAMERA',
        'PISTOL_2H_AIM_CAMERA', 'SMG_AIM_CAMERA', 'RIFLE_AIM_CAMERA',
        'RIFLE_HI_AIM_CAMERA', 'RIFLE_LO_AIM_CAMERA', 'MG_AIM_CAMERA',
        'SHOTGUN_AIM_CAMERA', 'SNIPER_AIM_CAMERA', 'SNIPER_LOW_ZOOM_AIM_CAMERA',
        'SNIPER_MED_ZOOM_AIM_CAMERA', 'SNIPER_HI_ZOOM_AIM_CAMERA',
        'SNIPER_MAX', 'THROW_CAMERA',
    },
    ReticuleHash = {
        '', 'SNIPER_SMALL', 'SNIPER_MEDIUM', 'SNIPER_LARGE', 'SNIPER_MAX',
        'PISTOL_RETICLE', 'RIFLE_RETICLE', 'SHOTGUN_RETICLE',
    },
    SpecialScopeType = { '', 'NightVision', 'ThermalVision' },
    AmmoInfo = {
        '', 'AMMO_RIFLE_ARMORPIERCING', 'AMMO_RIFLE_EXPLOSIVE',
        'AMMO_RIFLE_FMJ', 'AMMO_RIFLE_HOLLOWPOINT', 'AMMO_RIFLE_INCENDIARY',
        'AMMO_RIFLE_TRACER', 'AMMO_PISTOL_ARMORPIERCING', 'AMMO_PISTOL_FMJ',
        'AMMO_PISTOL_HOLLOWPOINT', 'AMMO_PISTOL_INCENDIARY', 'AMMO_PISTOL_TRACER',
        'AMMO_SHOTGUN_ARMORPIERCING', 'AMMO_SHOTGUN_EXPLOSIVE',
        'AMMO_SHOTGUN_HOLLOWPOINT', 'AMMO_SHOTGUN_INCENDIARY',
    },
    ReloadData = {
        '', 'RELOAD_DEFAULT', 'RELOAD_LARGE', 'RELOAD_DEFAULT_WITH_EMPTIES',
        'RELOAD_LARGE_WITH_EMPTIES', 'RELOAD_ONLY_AIM', 'RELOAD_LARGE_ONLY_AIM',
        'RELOAD_DEFAULT_BOTH_SIDES', 'RELOAD_EXTRA_LARGE',
    },
}

---

Tip: Changing any of these limit tables requires careful understanding of GTA V’s weapon meta schema. Do not adjust min/max values unless you know the engine’s internal constraints.

---

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.