> For the complete documentation index, see [llms.txt](https://atiysus-organization.gitbook.io/aty-scripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atiysus-organization.gitbook.io/aty-scripts/weapon-editor/reference/troubleshooting.md). # Troubleshooting ## Troubleshooting Run this first. It answers most of what follows: ``` /gunsmith:doctor ``` ### Access #### I have no permission, but I granted it ``` /gunsmith:whoami ``` Not permission-gated, deliberately. It prints every scope, every group and ACE object tested, the result of each, and which path granted access if any did. The two usual answers: the grant went to the framework and the framework's own check is failing (add the ACE as well — either path is enough), or the ACE went to a principal the player is not actually in. Full detail on Permissions. #### `/gunsmith` does nothing It is disabled by default. `Config.Access.workshop.command = false` means the command is **not registered at all** — which is better than registering one that refuses, because an unregistered command does not appear in chat suggestions and nobody hunts for it. The intended way into the workshop is a workbench. #### Nothing at all starts Check the start order. `aty_lib` must come before `aty_gunsmith`, and the framework before both. Check the server console on boot for a Lua error. ### Weapons and skins #### A weapon is missing from the editor The catalogue is a fixed list of 42 vanilla weapons and addon weapons are not supported out of the box. You can extend it yourself: from 1.0.3 the catalogue file stays readable on the escrow build too. Read Adding weapons first — a guessed texture name produces a weapon that silently never takes a skin. See Adding weapons and Weapon catalogue. #### Nothing happens on a melee weapon Six melee weapons cannot be skinned: Baseball Bat, Golf Club, Hammer, Nightstick, Pool Cue and Pipe Wrench. Their real texture name is not known, so there is nothing to write a design into. They are refused openly rather than accepting a design and doing nothing. If one of them is *accepting* a design and doing nothing, that is a different problem — report it. #### Mk II weapons will not take a skin SMG Mk II and Assault Rifle Mk II are locked. The other three Mk II weapons (Pistol, Carbine Rifle, Marksman Rifle) work through their camo slots. See Weapon catalogue. Mk II weapons being blocked *outright* was the behaviour before 1.0.2. Update. #### Other players do not see my skin Check which lane covers the weapon — Who sees your skin has the table. Then: * Is the weapon **in the player's hands**? A skinned weapon in a pocket shows nothing * Is the other player within `Config.Sync.radius` (25 m)? * Is `aty_gunsmith_assets` installed, started, and on a matching version? Without its model copies the prop lane cannot run * Run `/gunsmithpropverify` — every model must load ``` /gunsmithsync /gunsmithpool ``` #### My design appeared on someone else's gun Expected, on any weapon outside the prop and camo lanes. The game replaces weapon textures at model level, not per entity — one texture slot per weapon model per client. `Config.Sync.conflict = 'vanilla'` trades your own design away to stop it happening; the prop lane avoids the problem entirely. Full explanation on Who sees your skin. #### A player appears unarmed The prop lane hides the real weapon before overlaying its copy. If a copy will not load, nothing replaces the hidden weapon. ``` /gunsmithpropverify ``` Every model must report loaded. If any do not, either ship the missing files or remove that weapon from `Config.Lanes.prop.weapons` until you can. #### A saved skin looks different from the preview Fixed in 1.0.1 — the base colour was dropped on save, so the design was redrawn on a transparent canvas. Skins saved before that version keep their missing base; re-save them once. #### A design will not save The server validates every field and rejects the **whole** design if any of them is out of range, so trim before saving. The limits are 14 layers, 24 characters of text, 240 points per stroke, 48 characters of name — Design format. If it is an image layer, the host has to be on `Config.Lanes.composite.images.whitelist`, https, matched exactly, and the URL has to point at the image rather than at a share page. #### Pasted AI JSON is rejected Almost always a wrapper the model added — a markdown fence, a `"design":` wrapper, or a sentence before the JSON. The design must be the bare object. See AI designs. #### The art or template gallery is empty `aty_gunsmith_assets` did not start. It is not declared as a hard dependency, so the script runs happily without it and simply has no artwork. ### Workbenches #### A new workbench only appears after a restart Fixed in 1.0.1. Bench access depends on job and citizen identity, which is not resolved at the moment a player joins; the scan now re-runs when the player loads and whenever their job changes. #### A workbench appears two or three times over Fixed. Two refreshes arriving at once could each spawn the prop. The symptom looks like it depends on player count; the cause was concurrent refreshes. #### The object failed to load The placement flow says so and lets you continue. The workbench works; it just has no prop. ### Serial numbers and inventory #### Modifying a weapon creates a new serial Fixed in 1.0.1, and confirmed on a live server. The stored record was being rejected whenever its owner field did not match, and a fresh serial minted instead. The serial is now treated as the weapon's identity, and an unowned record is claimed rather than replaced. Verify on your own database: ``` /gunsmithverify ``` Run from the server console. Duplicate `(owner, weapon)` pairs from *before* the fix may still exist; the measure is that no new ones appear. #### Attachments show as `undefined`, or the weapon will not come back out of a pocket This is a metadata write problem, not a display one. From the server console: ``` /gunsmithslots [WEAPON_X] ``` It shows how many copies of that weapon the inventory holds and which serial each one carries. Two slots and one write means one of them is blank — which is the state that produces both symptoms. Please include that output in a ticket, taken **before and after** putting the weapon away. #### Metadata was wiped Fixed. Weapon metadata is no longer overwritten when the inventory cannot be read; ammo, durability and your framework's own serial field used to be lost in that case. ### Balance #### I changed a stat and nothing happened in game Read the note under the slider. Deploy-class fields — clip size, range, spread, reload, falloff, force, penetration — take effect **after a server restart**, and no setting changes that. Live and scripted fields are immediate. Also check `Config.Balance.metaEmitFields` is not `false`, which saves values without writing them anywhere. #### A deploy says it will apply on the next start That is `Config.Balance.applyMode = 'safe'` working correctly. Restarting the weapon meta resource with players connected crashes them — Balance lab explains why. #### Players crashed after a deploy Check `applyMode`. If it is `'force'`, that is the cause: FiveM cannot hot-unmount a weapon meta `data_file`. Set it back to `'safe'`. #### I raised a limb multiplier and limb shots do not hurt more `Config.Authority.action = 'correct'` can only claw back over-claimed damage. It cannot increase damage — the game already deals less than expected, so there is no excess to correct. Multipliers only take effect downward through that path. Use the instant fields in the lab for balance. ### Anything else Turn on `Config.Debug = true`, reproduce the problem, and send the server console output with your report — plus `/gunsmith:doctor`. Turn it back off afterwards; it is verbose.