> 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/adding-weapons.md). # Adding weapons ## Adding weapons This is the page for *"how do I add more weapons to the skin creator?"* The answer depends on which of three things you actually want, and they are separate mechanisms in separate files: | What you want | Where it is done | Difficulty | | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------- | | A weapon that is **not in the editor at all** should appear | `shared/weapons.lua` | Hard — needs a measurement, see below | | A weapon that **is** in the editor should get **full-body sync** (everyone sees your design on the whole gun) | `Config.Lanes.prop.weapons` + model files | Easy config, large file work | | A whole **class** of weapon should be allowed to take designs | `Config.Lanes.composite.classes` | One config line | {% hint style="info" %} **Everything on this page works on both the escrow and the open build.** From 1.0.3 the weapon catalogue (`shared/weapons.lua`) is left readable inside the escrowed resource, so you can edit it yourself. On 1.0.2 and earlier it shipped encrypted. If you are on an older version and want a weapon added, update first — or open a ticket with the weapon name. {% endhint %} ### The catalogue The editor does not scan your server for weapons. It reads a fixed catalogue of **42 vanilla GTA V weapons** defined in `shared/weapons.lua`. Adding an entry to that list is what puts a weapon in the selector. One entry looks like this: ```lua -- name label class mk2 texture dictionary { 'WEAPON_COMBATPISTOL', 'Combat Pistol', 'pistol', false, 'w_pi_combatpistol' }, ``` | Field | Meaning | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **name** | The game's weapon name. No hash — the script converts it at runtime | | **label** | What the player sees in the selector | | **class** | One of `pistol` `smg` `rifle` `shotgun` `sniper` `mg` `heavy` `melee` `throwable`. Decides the order in the UI, and whether the class is allowed to be skinned at all | | **mk2** | `true` for Mk II weapons — they take a different path entirely | | **txd** | The weapon's **model name**. This is also its texture dictionary | | *camoBase* | Mk II only — the base used to build the camo component names | | *txnOverride* | The texture name, **when it is not the model name**. See below | ### The one thing that makes this hard A design is applied with `AddReplaceTexture(dictionary, texture, ...)`. That native **returns nothing at all** — no success value, no error. Give it a texture name that does not exist and the call still succeeds, the script still reports the design as applied, and the weapon stays vanilla. So a wrong guess does not produce an error. It produces a weapon that silently never takes a skin, and a player who reports the script as broken. {% hint style="danger" %} **Do not add a weapon by guessing its texture name.** Every entry in the shipped catalogue was measured in game before it was added. A guessed entry is worse than a missing one: a missing weapon is simply absent from the selector, while a guessed one appears, accepts a design, and does nothing. {% endhint %} ### The measured rules Three rules came out of measuring the catalogue. They are not conventions — the first two were tested in game, and the third disproved an earlier assumption. **The dictionary is always the model name.** There is no shared texture dictionary. Treating `w_camo_1` as one was tried and failed on every weapon: the dictionary is the model's own name, every time. Only the *texture* name varies. **On firearms, the texture name is also the model name.** Measured on `WEAPON_PISTOL`: `w_pi_pistol` / `w_pi_pistol` paints. The `_diff` suffix that looks plausible does nothing at all. **Melee and Mk II break that rule.** They need `txnOverride`: | Group | Texture name | Example | | -------------------- | ------------------------------------------------------------------ | ------------------------------------------ | | Firearms | same as the model | `w_pi_pistol` / `w_pi_pistol` | | Most skinnable melee | `w_camo_1`, inside the model's *own* dictionary | `w_me_knife_01` / `w_camo_1` | | Some melee | their own diffuse name | `w_me_flashlight` / `w_me_flashlight_body` | | Mk II | livery 1 (`_L1`), in a dictionary that is **not reachable** | — | Mk II weapons therefore never take a design on their base model. They are skinned through the camo slots or the prop copies instead, and both of those sidestep the base texture completely. ### Adding a weapon to the catalogue **1. Find the model name** ``` /gunsmithprobe verify ``` This audits the whole catalogue against `GetWeapontypeModel` and lists any entry whose `txd` does not match the weapon's real model. Run it first — it gives you the model name with no guessing involved. **2. Find the texture name** If you have a CodeWalker or OpenIV dump of the model's `.ytd`, you already have the name. Test it directly: ``` /gunsmithtry WEAPON_KNIFE w_me_knife_01 w_camo_1 ``` The weapon turns **red** if the pair is correct. Nothing happens if it is wrong. That red is the entire test. If you do not have a dump, search for it: ``` /gunsmithhunt WEAPON_KNIFE list the candidate rounds /gunsmithhunt WEAPON_KNIFE 1 apply round 1 /gunsmithhunt WEAPON_KNIFE off clear ``` Each round applies several candidates **at once**, each in a different colour. Only the correct pair binds, so the colour the weapon takes tells you which candidate it was — one look per round instead of one look per candidate. For melee specifically: ``` /gunsmithmeleetest dump what the catalogue currently holds /gunsmithmeleeshow walk the melee weapons one at a time, one mapping at a time ``` **3. Add the line** ```lua { 'WEAPON_MYWEAPON', 'My Weapon', 'pistol', false, 'w_pi_myweapon' }, ``` Add `txnOverride` as a seventh field only if step 2 showed the texture name differs from the model name. **4. Restart and confirm** ``` refresh restart aty_gunsmith ``` Then open the workshop, pick the weapon, apply any design, and **look at it**. If it stays vanilla, step 2 was wrong — go back to it. Do not ship an entry you have not seen take a colour. ### Which weapons are skinnable today Of the 42 in the catalogue, **32** can take a custom design. | Excluded | Count | Why | | ------------------------------------------------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SMG Mk II, Assault Rifle Mk II | 2 | Their camo slot names do not follow the pattern the other Mk II weapons use. Around thirty naming variants were tried without a match, so they stay locked rather than silently doing nothing | | Baseball Bat, Golf Club, Hammer, Nightstick, Pool Cue, Pipe Wrench | 6 | Their real diffuse texture name is not known. They use a plain `normal_spec` shader and neither `w_camo_1` nor their own model name paints them | | Grenade, Molotov | 2 | The `throwable` class is not in `Config.Lanes.composite.classes` | The full per-weapon breakdown is on Weapon catalogue. Excluded weapons are marked `noSkin` and the studio **refuses them out loud**. That is deliberate: accepting a design and changing nothing is what players read as a broken script. ### Adding a class If you want the two throwables to become skinnable, that is a config line — no catalogue edit, and it works on the escrow build: ```lua Config.Lanes.composite.classes = { 'pistol', 'smg', 'rifle', 'shotgun', 'sniper', 'mg', 'heavy', 'melee', 'throwable', } ``` {% hint style="info" %} This lifts the *class* gate only. Grenade and Molotov have never been measured, so they may well accept a design and show nothing — the same silent failure this page is about. Test them with `/gunsmithtry` before you leave the class enabled. {% endhint %} ### Adding a weapon to full-body sync Full-body sync — where every nearby player sees your actual design on the whole weapon rather than only on camo surfaces — is the **prop lane**. It covers ten weapons out of the box: ```lua Config.Lanes.prop = { enabled = true, slots = 4, weapons = { 'WEAPON_PISTOL', 'WEAPON_COMBATPISTOL', 'WEAPON_APPISTOL', 'WEAPON_PISTOL_MK2', 'WEAPON_SMG', 'WEAPON_MICROSMG', 'WEAPON_ASSAULTRIFLE', 'WEAPON_CARBINERIFLE', 'WEAPON_SPECIALCARBINE', 'WEAPON_PUMPSHOTGUN', }, } ``` It works by hiding the real weapon and overlaying a **per-slot copy of its model**, so each player gets an independent texture target. That means every weapon on the list needs `slots` copies of its model shipped in `aty_gunsmith_assets/stream/` — ten weapons at four slots is forty model pairs, which is most of that resource's \~96 MB. **1. Produce the model copies** For each weapon and each slot `1..4`, a `.ydr` and a `.ytd` named `_s` — for example `w_pi_pistol_s1.ydr` and `w_pi_pistol_s1.ytd`. **2. Register the archetypes** A raw `.ydr` is not enough. A custom prop needs an archetype definition or `CreateObject` cannot spawn it — measured: without the `.ytyp` entry the model is not registered at all. Add the new archetypes to `aty_gunsmith_assets/stream/aty_gunsmith_props.ytyp`. **3. Add the config line** ```lua weapons = { ..., 'WEAPON_HEAVYPISTOL' }, ``` **4. Verify before anyone plays** ``` refresh restart aty_gunsmith_assets restart aty_gunsmith ``` then, in game: ``` /gunsmithpropverify ``` It requests every model the lane needs and reports how many loaded. {% hint style="danger" %} **Never leave the lane enabled with a missing file.** The lane hides the real weapon *before* it overlays the copy. If the copy will not load, the player is left holding nothing and appears unarmed. `/gunsmithpropverify` must report every model loaded before you go live. {% endhint %} Lowering `slots` or shortening `weapons` reduces the asset size proportionally. ### Addon weapons Not supported out of the box. The catalogue is a fixed list of vanilla weapons and there is no runtime discovery sweep. An addon weapon can in principle be added the same way a vanilla one is — you need its model name and its texture name, and both come from whoever built it. ### See also * Weapon catalogue — every weapon and what it supports * Who sees your skin — what the lanes actually do * Commands — the diagnostic commands used above