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:

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:

--   name                   label            class     mk2    texture dictionary
{ 'WEAPON_COMBATPISTOL',  'Combat Pistol',  'pistol',  false, 'w_pi_combatpistol' },

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.

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:

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

{ '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.

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:

Config.Lanes.composite.classes = {
    'pistol', 'smg', 'rifle', 'shotgun', 'sniper', 'mg', 'heavy', 'melee',
    'throwable',
}

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:

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 <model>_s<slot> — 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

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.

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