X3D DeveloperX3D Developer
Contact on Discord
Docs

X3D Weapon Skins

Free collectible ESX weapon skins: each skin is an add-on weapon tied to its base gun. Unlock with an item, same damage, tradable, held-weapon effects.

Buy / Get freeConfig builder

Installation

  1. Drop x3d_weaponskins into resources/ and run install.sql (creates the x3d_weaponskins table).
  2. Add ensure x3d_weaponskins after es_extended (and after your inventory).
  3. Add your skins (below) and restart the server. Players reconnect once to load new weapon models.

Keys and commands
/skins Open the skin collection (Config.Command, empty = off)
Config.Key Optional default key for the same command (players can rebind)
Config.OpenItem Item that opens the collection when used (not consumed). Works with any inventory that supports ESX usable items (NC, ox, qs…)
Config.Radial true = "Weapon skins" entry in the ox_lib radial menu
Skin item Use it from the bag: the skin unlocks and the unlock card shows

Config (config.lua)

Option What it does
Config.Locale th or en
Config.ImagePath Skin picture path, %s = lowercase weapon name. With X3D Inventory: nui://x3d_inventory/web/build/img/items/%s.png
Config.WeaponNames Optional names for base weapons (else the ESX label)
Config.SweepIntervalMs How often skins held without an unlock turn back into the base weapon (0 = on join only)
Config.CloseEvents / Config.RestartLockState Close the screen on your events / block actions during a restart lock

Skins (config/skins.lua, key = UPPERCASE ESX weapon name)

Each skin is an add-on weapon (not a replace) tied to its base weapon through base. The original gun is never overwritten. No models ship with the script; stream your own add-on weapon models.

Field What it does
base Base weapon: damage, weight and ammo come from it
item Unlock item
label { th = ..., en = ... }
rarity 0-5 frame colour
tradable false = bound forever once used
vfx Effect while held (omit = none): dict, name, color, scale, alpha, viewDistance, points

New skin: stream the add-on weapon model yourself (weapons.meta etc.), add the weapon to es_extended Config.Weapons (copy the base's components/tints, or a weapon with attachments cannot take the skin), add the item to the items table, put a picture weapon_<name>.png where Config.ImagePath points, add a row in config/skins.lua, restart the server.

config/skins.lua ships one live example entry, WEAPON_GOLDPOOLCUE (Gold Pool Cue), as a template. If your server does not have that model and item yet, delete or comment the entry out.

Open from your own menu

Any menu can open the screen (F-menu, esx_context, ox_lib context, radial):

exports.x3d_weaponskins:Open()                  -- all weapons
exports.x3d_weaponskins:Open('WEAPON_POOLCUE')  -- straight to one weapon
-- or: TriggerEvent('x3d_weaponskins:open')

ox_lib context example:

{ title = 'Weapon skins', icon = 'gun', onSelect = function() exports.x3d_weaponskins:Open() end }

Hooks (addons/hooks/)

Hooks.BeforeFocus() (client): runs before the collection or unlock card takes the mouse. Close your inventory or menu here (X3D Inventory closes itself), e.g. TriggerEvent('your_inventory:close').

Server: Hooks.CanCarry(xPlayer, item, count): can the bag take the skin item back. Default: ESX canCarryItem. With X3D Inventory: return exports.x3d_inventory:CanCarryItemSrc(xPlayer.source, item, count).

For other scripts

  • GlobalState.x3dWeaponBase = { [SKIN] = BASE }: treat a skin as its base (X3D Damage does this automatically).
  • GlobalState.x3dWeaponSkins = { [SKIN] = { base, label, rarity } }: for inventories to show skins.
  • Client events: TriggerEvent('x3d_weaponskins:open', base) opens the screen; x3d_weaponskins:focus fires before it takes focus (close your panel); x3d_weaponskins:swapped (from, to) after a swap.
  • Client export: exports.x3d_weaponskins:Open(base).
View product page