Shop Metadata#

New in 2.0.8. Shop metadata is information a FiveM clothing-shop script needs about each garment: what it costs, which shop sells it, and who may buy it. The tool stores it per garment and writes it into config files when you build.

The fields#

Select an item and open its Shop & metadata section in the item panel.

The tool warns you about tags it cannot use: a prefix with no value (job: alone), a tag with two colons, or a prefix it does not know (exported as a free label). It also warns when an item is Hidden from shop and has job or gang tags: in illenium-appearance, hidden wins and the item is blocked for everyone.

Items that carry shop metadata are marked with a tag on the item list.

Editing many items at once#

1. Open the Shop metadata window#

   Click the tag button next to the item list's search box, or select several items, right-click them and choose Edit shop metadata in the selected items…. From one item's Shop & metadata section, Apply to selection (N)… opens the same window with that item's values filled in.

2. Choose the scope#

   Pick Selected, Filtered (the items the list currently shows) or All items.

3. Tick the fields to change#

   Every field has a tick box. Only ticked fields change; everything else on each item is left as it is, so forty jackets with forty different credits can all get one price without losing their credits. For tags, choose Add, Remove or Replace all.

4. Check the preview and apply#

   The window shows how many fields will change on how many items before anything is written. Click Apply to N item(s).

The whole edit is one save and one undo step. Use Undo in the window, or Ctrl+Z.

Project defaults#

Open Project settings → Shop export:

• Default price — written into the export as defaults.price. Items without a price of their own are exported with no price; your server script applies the default. The export never fills it in for you.
• Default shop — the shop items belong to when they name none. Empty means any shop.
• Currency label — shown next to prices in the manifest, for example $. It is a label only; your server's framework handles money.

Exporting for shop scripts#

1. Turn it on in the build window#

   Open Build project with FiveM or Both selected under Output. In the Shop export section, tick Write shop configs. The line under it shows how many items carry metadata, and your default price and shop.

2. Choose the targets#

   • KCT universal manifest — kct_shop.json and kct_shop.lua plus a client helper. Works with any shop script.
   • illenium-appearance blacklist — job, gang, ace and citizen ID restrictions and hidden items, for illenium-appearance (beta).

3. Build#

   The files go into a shop_export folder inside the built resource, with SHOP_INSTALL.txt explaining how to use them. They are not listed in fxmanifest.lua: they are for your server's scripts.

Collection and local index, never a global index#

Every garment in the export is addressed as collection + component (or prop) id + local index, never as a global drawable number. Global numbers change whenever the server's game build adds official DLC; the collection and local index do not. Resolve them at runtime with FiveM's collection-based natives. The client helper does this for you.

Example: kct_shop.json#

One jacket, shortened:

{
  "format": "kct-shop/1",
  "resource": "my_pack",
  "collection": "my_pack",
  "collections": [ "my_pack" ],
  "indexing": "collection-local",
  "author": "Koja",
  "version": "1.0.0",
  "currency": "$",
  "defaults": { "price": 250, "shop": "ponsonbys" },
  "itemCount": 1,
  "items": [
    {
      "name": "Police jacket",
      "label": "Police jacket",
      "gender": "male",
      "component": 11,
      "slot": "jbib",
      "isProp": false,
      "collection": "my_pack",
      "localIndex": 0,
      "authoredDrawable": 0,
      "textureCount": 2,
      "shop": "ponsonbys",
      "price": 450,
      "hiddenFromShop": false,
      "allowRandom": true,
      "tags": [ "job:police" ],
      "restrictions": { "jobs": [ "police" ], "gangs": [], "aces": [], "citizenids": [] },
      "creator": { "author": "Koja", "url": "", "credit": "" },
      "textures": [
        { "index": 0, "letter": "a", "price": null, "hidden": false },
        { "index": 1, "letter": "b", "price": null, "hidden": false }
      ]
    }
  ]
}

An item without any shop metadata is still listed, with "shop": null and no price, tags or credits.

Example: kct_shop.lua#

The same data as a Lua table, with the same keys. A null in the JSON is simply left out in Lua.

return {
  format = "kct-shop/1",
  resource = "my_pack",
  collections = { "my_pack" },
  currency = "$",
  defaults = {
    price = 250,
    shop = "ponsonbys",
  },
  items = {
    {
      name = "Police jacket",
      gender = "male",
      component = 11,
      collection = "my_pack",
      localIndex = 0,
      price = 450,
      tags = { "job:police" },
      restrictions = {
        jobs = { "police" },
        gangs = {},
        aces = {},
        citizenids = {},
      },
    },
  },
}

The client helper#

kct_shop_resolve.lua is a client script with three functions:

A global index is only valid for the ped model it was resolved on, and only until the server's game build changes.

The illenium-appearance blacklist (beta)#

illenium-appearance wants global drawable numbers, which do not exist at build time. The export writes two files:

• illenium_blacklist_runtime.lua resolves each garment on the client and adds it to illenium's own Config.Blacklist, so the entries survive a game build change. Add it to illenium-appearance's fxmanifest.lua client scripts, after shared/*.lua, and start your pack before illenium-appearance.
• illenium_blacklist.lua has the same entries in the static shape of illenium's shared/blacklist.lua, for servers with a pinned game build. Each KCT_GLOBAL("collection", localIndex) placeholder must be replaced with the real global number on your build, and redone whenever the build changes. A placeholder left in stops the resource with an error on purpose.

Restriction tags become illenium's jobs, gangs, aces and citizen IDs; Hidden from shop blocks the item for everyone. Prices are not part of illenium's blacklist and are not exported there. Garments in slots illenium has no category for are skipped and listed in SHOP_INSTALL.txt.

Tattoo prices#

When shop export is on, the illenium-appearance tattoo entries of the build carry each tattoo's In-game price from the Tattoo Creator as cost. Set Config.ChargePerTattoo = true in illenium-appearance's config to use it.

Limits#

• Shop export is for FiveM builds only. A singleplayer dlc.rpf has no server scripts to feed.
• A Replace build also has its own Write shop metadata option. That is the game's shop meta file, not this export.

Related pages#

• Building
• Mass Edit
• Tattoo Creator
• Items and Textures