# Shop Metadata

:::hint{type="info" title="Premium"}
Editing shop metadata, the project's shop defaults and the shop export need Premium. On the free plan, shop metadata is shown read-only, so a teammate on the free plan still sees what a shared project carries.
:::

**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.

| Field | What it means |
| --- | --- |
| **Shop** | The shop or category id the item belongs to, for example `ponsonbys`. Empty means any shop. |
| **Price** | A whole number. Empty means no price of its own. |
| **Tags** | Restriction tags. `job:police`, `gang:ballas`, `ace:vip` and `citizenid:…` restrict who can use the item. Any other tag is a free label and restricts nothing. Press Enter to add a tag. |
| **Shop label** | The name the shop shows. Empty uses the item's name. |
| **Author**, **Author URL**, **Credit** | Credits for the garment. An empty author falls back to the project's author. |
| **Hidden from shop** | Keeps the item out of the shop. |
| **Allow in random outfits** | Whether scripts may use the item in random outfits. |

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

:::steps
### 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.

### Choose the scope

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

### 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**.

### 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

:::steps
### 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.

### 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).

### 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:

```json title="shop_export/kct_shop.json"
{
  "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.

```lua title="shop_export/kct_shop.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:

| Function | What it does |
| --- | --- |
| `KctShop.Apply(ped, item, textureIndex)` | Dresses the ped in a manifest item. `textureIndex` is 0-based and defaults to 0. |
| `KctShop.GlobalIndex(ped, item)` | Returns the item's global drawable (or prop) index on this ped, or -1 when the collection is not loaded. For scripts that only understand global indices. |
| `KctShop.FitsPed(ped, item)` | True when the item was made for this ped's freemode model. |

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`.

:::hint{type="warning" title="Beta"}
The runtime blacklist file has not been run in game yet. Check it on your server before relying on it.
:::

### 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](/cloth-tool/about-the-tool/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](/cloth-tool/about-the-tool/building)
- [Mass Edit](/cloth-tool/about-the-tool/mass-edit)
- [Tattoo Creator](/cloth-tool/about-the-tool/tattoo-creator)
- [Items and Textures](/cloth-tool/about-the-tool/items-and-textures)