Configuration Guide

A beginner-friendly guide to creating and configuring shops.

---

Quick Start

Open configs/shops.lua and copy this template:

['my_shop'] = {
    name = 'My Shop Name',
    subtitle = 'My Shop Subtitle',
    shopType = '247store',
    location = vector3(0.0, 0.0, 0.0),
    blip = {
        sprite = 52,
        color = 2,
        scale = 0.7,
        display = 4
    },
    ped = {
        enabled = true,
        model = 'mp_m_shopkeep_01',
        coords = vector3(0.0, 0.0, 0.0),
        heading = 0.0,
        scenario = 'WORLD_HUMAN_STAND_MOBILE'
    },
    registers = {
        enabled = false,
        coords = {}
    },
    items = {},
    ownership = {
        enabled = false,
        coords = vector3(0.0, 0.0, 0.0),
        price = 0
    }
}

Then just:

1. Change 'my_shop' to a unique name

2. Fill in your coordinates

3. Pick a shopType from the list below (configure anything else you'd want to change)

4. Done!

---

Shop Types

Pick one of these for your shopType:

Type	What it sells
247store	Food, drinks, basic supplies
liquorstore	Alcohol, snacks
hardware	Tools, materials, repair kits
pharmacy	Medical supplies
gunstore	Weapons, ammo, attachments
pawn	Sell your Items

Brief Note: the pawn type is a hardcoded value. If used the shop turns into a shop where you SELL items. Example:

shopType = 'hardware',

---

Adding a New Shop Type

If the existing shop types don't fit your needs:

Step 1: Add display settings in configs/config.lua:

ShopTypeDisplay = {
    -- ... existing types ...
    ['petstore'] = {
        icon = 'paw-print',    -- From https://lucide.dev/icons
        color = 'cyan'
    }
}

Step 2: Add base products (if using BaseProducts):

BaseProducts = {
    -- ... existing types ...
    ['petstore'] = {
        items = {
            { item = 'dogfood', price = 15 },
            { item = 'leash', price = 25 },
        }
    }
}

Step 3: Add categories for your items:

Categories = {
    -- ... existing categories ...
    ['petfood'] = {
        title = 'Pet Food',
        color = 'yellow',
        types = {'petstore'},
        items = {'dogfood', 'catfood'}
    }
}

Step 4: Add to product whitelist in configs/management.lua (for owned shops):

ProductWhitelist = {
    -- ... existing types ...
    ['petstore'] = {
        { item = 'dogfood', canOrder = true, orderPrice = 10 },
        { item = 'leash', canOrder = true, orderPrice = 15 },
    }
}

---

Categories Explained

Categories group items together in the shop UI. They're configured in configs/config.lua.

Each category has:

• title - Display name

• color - Badge color

• types - Which shop types use it (empty = all shops)

• items - Which items belong to it

['food'] = {
    title = 'Food & Drinks',
    color = 'green',
    types = {'247store', 'liquorstore'},
    items = {'water', 'sandwich', 'coffee', 'burger', 'cola'}
},

Available colors: emerald, purple, orange, red, slate, blue, green, yellow, pink, indigo, cyan, teal, lime, amber, rose, fuchsia, violet, sky, gray

---

Configuration Explained

Basic Info

['shop_id'] = {                    -- Unique ID (no spaces, no duplicates)
    name = 'Shop Name',            -- Displayed to players
    subtitle = 'Shop Description', -- Shown under the name
    shopType = '247store',         -- What products it sells (see list above)
    location = vector3(x, y, z),   -- Where the blip appears on the map

Map Blip

    blip = {
        sprite = 52,     -- Icon type (set to 0 to hide from map)
        color = 2,       -- Icon color
        scale = 0.7,     -- Icon size
        display = 4      -- Keep at 4
    },

Common blip sprites:

• 52 = Shopping cart (convenience stores)

• 93 = Goblet (liquor stores)

• 402 = Wrench (hardware)

• 110 = Gun (weapon shops)

Shop Ped (The Clerk)

    ped = {
        enabled = true,                        -- true = spawn a ped, false = no ped
        model = 'mp_m_shopkeep_01',            -- Ped appearance
        coords = vector3(x, y, z),             -- Where the ped stands
        heading = 180.0,                       -- Direction they face (0-360)
        scenario = 'WORLD_HUMAN_STAND_MOBILE'  -- What they're doing
    },

Common ped models:

• mp_m_shopkeep_01 = Standard shopkeeper

• s_m_y_ammucity_01 = Gun store clerk

• a_m_m_eastsa_02 = Casual male

• s_m_m_cntrybar_01 = Country/hardware store worker

Common scenarios:

• WORLD_HUMAN_STAND_MOBILE = Standing with phone

• WORLD_HUMAN_CLIPBOARD = Holding clipboard

• WORLD_HUMAN_STAND_IMPATIENT = Standing, looking around

Cash Registers (Optional)

    registers = {
        enabled = true,              -- true = players can interact with registers
        coords = {
            vector3(x, y, z),        -- Position of register 1
            vector3(x, y, z),        -- Position of register 2 (optional)
        }
    },

If your shop doesn't have physical registers, just use:

    registers = {
        enabled = false,
        coords = {}
    },

Shop Items

    items = {
        { item = 'water', price = 5 },
        { item = 'sandwich', price = 10 },
        { item = 'WEAPON_PISTOL', price = 5000, license = 'weapon' },
    },

Note: This is ignored if BaseProducts is enabled in config.lua (it is by default). When enabled, all shops of the same type share the same items.

Player Ownership

    ownership = {
        enabled = true,              -- Can players buy this shop?
        coords = vector3(x, y, z),   -- Where they access the management menu
        price = 50000                -- How much to buy it
    }

If you don't want players to own this shop:

    ownership = {
        enabled = false,
        coords = vector3(0.0, 0.0, 0.0),
        price = 0
    }

---

Item Display Overrides

Any item can override its display name, description, and image in the shop UI. These work in BaseProducts, individual shop items (configs/shops.lua), and ProductWhitelist entries (configs/management.lua).

Field	Description
label	Custom display name (overrides the auto-fetched inventory label)
description	Custom description text (overrides the auto-fetched inventory description)
image	Custom image — either a filename (e.g., 'lockpick_gold.png') resolved via your inventory's image directory, or a full path (e.g., 'nui://my_resource/images/custom.png' or a URL)

In BaseProducts or shop items:

{ item = 'water', price = 5, label = 'Spring Water', description = 'Freshly sourced spring water.' },
{ item = 'lockpick', price = 50, image = 'lockpick_gold.png' },
{ item = 'radio', price = 250, image = 'nui://my_resource/radio.png' },

In ProductWhitelist:

{ item = 'water', canOrder = true, orderPrice = 5, label = 'Spring Water', description = 'Freshly sourced spring water.', image = 'water_spring.png' },

These overrides apply across the entire UI — shop display, management menu, stock ordering, analytics, and transaction history.

Item Metadata

You can assign metadata to any item sold through shops (owned and unowned). Metadata is passed to the inventory system when a player purchases the item — this is useful for things like durability, quality, or any custom field your server uses.

In BaseProducts or shop items:

{ item = 'bandage', price = 15, metadata = { durability = 100 } },
{ item = 'lockpick', price = 50, metadata = { durability = 50 } },

In ProductWhitelist:

{ item = 'bandage', canOrder = true, orderPrice = 10, metadata = { durability = 100 } },

For weapons, configured metadata is merged with weapon serial metadata (weapon fields take priority on conflict).

Display Metadata (ox_inventory only)

If you're using ox_inventory, you can register custom metadata keys so they appear in the item tooltip. Add a displayMetadata table to any item.

There are two formats:

String format — the key is shown with a simple label (booleans display as "Yes"/"No", numbers display as-is):

{ item = 'water', price = 5, metadata = { quality = 100 }, 
displayMetadata = { quality = 'Quality' }
-- Tooltip shows: "Quality: 100"

Table format — for booleans, you can customize what "true" and "false" display as:

{ item = 'bandage', price = 15,
  metadata = { sterile = true },
  displayMetadata = { sterile = { label = 'Sterile', trueValue = 'Sanitized', falseValue = 'Contaminated' } }
}
-- Tooltip shows: "Sterile: Sanitized" (when true) or "Sterile: Contaminated" (when false)

You can combine both formats on the same item:

{ item = 'water', price = 8,
  label = 'Premium Spring Water',
  metadata = { quality = 100, purified = true },
  displayMetadata = {
      quality = 'Quality',
      purified = { label = 'Purified', trueValue = 'Yes', falseValue = 'No' }
  }
}
-- Tooltip shows: "Quality: 100" and "Purified: Yes"

Note: Do NOT add ox_inventory built-in keys like durability, description, ammo, serial, components, weapontint, type, or label to the displayMetadata table — ox_inventory handles those already and they will be ignored.

ApplyMetadata Groups

Instead of adding metadata to every item individually, you can define global metadata groups in configs/config.lua that automatically apply metadata to purchased items based on rules.

ApplyMetadata = {
    enabled = true,
    groups = {
        { applyTo = 'all', metadata = { durability = 100 } },                          -- Every item gets durability
        { applyTo = { 'lockpick', 'screwdriver' }, metadata = { durability = 50 } },   -- These get lower durability
        { applyTo = { 'bandage', 'firstaid' }, metadata = { sterile = true } },         -- Medical items get sterile flag
    },
    displayMetadata = {
        sterile = 'Sterile',
        -- Or with custom boolean display:
        -- sterile = { label = 'Sterile', trueValue = 'Sanitized', falseValue = 'Contaminated' },
    },
},

How priority works:

1. Groups are applied in order (top to bottom) — later groups override earlier ones for the same key

2. Per-item metadata (from BaseProducts/shop items/ProductWhitelist) overrides group values

3. Weapon serial metadata (serial, registered) always takes highest priority

So if a lockpick is purchased: it first gets durability = 100 from the 'all' group, then that's overridden to durability = 50 by the specific group. If the lockpick also had metadata = { durability = 75 } in its item config, that would win over both groups.

Item Variants

You can sell multiple variants of the same item, each as a completely separate product. Items with different metadata are treated as entirely separate items by the resource — they have their own stock, their own sales tracking, and their own display.

For example, if you have a single water item in your inventory system, you can sell a regular version and a premium version side by side, each with different prices, labels, images, and metadata.

In BaseProducts or shop items:

['247store'] = {
    items = {
        { item = 'water', price = 2 },                    -- Regular water, no metadata
        { item = 'water', price = 8,                       -- Premium variant
          label = 'Premium Spring Water',
          description = 'Imported artisan spring water.',
          image = 'water_premium.png',
          metadata = { quality = 100, purified = true },
          displayMetadata = {
              quality = 'Quality',
              purified = { label = 'Purified', trueValue = 'Yes', falseValue = 'No' }
          }
        },
    }
}

In ProductWhitelist (for owned shops):

ProductWhitelist = {
    ['247store'] = {
        { item = 'water', canOrder = true, orderPrice = 2 },
        { item = 'water', canOrder = true, orderPrice = 5,
          label = 'Premium Spring Water',
          description = 'Imported artisan spring water.',
          image = 'water_premium.png',
          metadata = { quality = 100, purified = true },
          displayMetadata = {
              quality = 'Quality',
              purified = { label = 'Purified', trueValue = 'Yes', falseValue = 'No' }
          }
        },
    }
}

For owned shops, each variant gets its own independent stock — ordering, withdrawing, and transferring from inventory all respect variant boundaries. In the management UI, variants display as water: Premium Spring Water so you can easily tell them apart.

Another example — a weed shop selling different strains, all using the same base weed item:

['dispensary'] = {
    items = {
        { item = 'weed', price = 20, label = 'Standard Bud', metadata = { quality = 50 } },
        { item = 'weed', price = 50, label = 'OG Kush', image = 'og_kush_weed.png', metadata = { quality = 100, strain = 'og_kush' } },
        { item = 'weed', price = 40, label = 'Blue Dream', image = 'blue_dream_weed.png', metadata = { quality = 85, strain = 'blue_dream' } },
    }
}

Each strain shows up as its own product with its own price, image, and metadata — but they all use the same weed item in the inventory system.

Common Examples

Example 1: Basic 24/7 Store

['my_247'] = {
    name = '24/7 Store',
    subtitle = 'Open 24/7',
    shopType = '247store',
    location = vector3(373.55, 325.56, 103.56),
    blip = {
        sprite = 52,
        color = 2,
        scale = 0.7,
        display = 4
    },
    ped = {
        enabled = true,
        model = 'mp_m_shopkeep_01',
        coords = vector3(372.97, 327.88, 103.57),
        heading = 256.84,
        scenario = 'WORLD_HUMAN_STAND_MOBILE'
    },
    registers = {
        enabled = true,
        coords = {
            vector3(373.3, 325.2, 103.56)
        }
    },
    items = {},
    ownership = {
        enabled = true,
        coords = vector3(379.49, 333.46, 103.40),
        price = 60000
    }
}

Example 2: Hidden Illegal Shop (Dirty Money Only)

['black_market'] = {
    name = 'Black Market',
    subtitle = 'No Questions Asked',
    shopType = '247store',
    location = vector3(100.0, 200.0, 30.0),
    illegal = true,                          -- ONLY accepts dirty money
    blip = {
        sprite = 0,                          -- Hidden from map
        color = 0,
        scale = 0.0,
        display = 0
    },
    ped = {
        enabled = true,
        model = 'g_m_m_chicold_01',
        coords = vector3(100.0, 200.0, 30.0),
        heading = 180.0,
        scenario = 'WORLD_HUMAN_DRUG_DEALER'
    },
    registers = {
        enabled = false,
        coords = {}
    },
    items = {
        { item = 'lockpick', price = 500 },
    },
    ownership = {
        enabled = false,
        coords = vector3(0.0, 0.0, 0.0),
        price = 0
    }
}

Example 3: Gun Store with License Requirements

['my_gunstore'] = {
    name = 'Ammu-Nation',
    subtitle = 'Firearms & Ammunition',
    shopType = 'gunstore',
    location = vector3(250.0, -50.0, 70.0),
    blip = {
        sprite = 110,
        color = 1,
        scale = 0.7,
        display = 4
    },
    ped = {
        enabled = true,
        model = 's_m_y_ammucity_01',
        coords = vector3(250.5, -50.5, 70.0),
        heading = 90.0,
        scenario = 'WORLD_HUMAN_CLIPBOARD'
    },
    registers = {
        enabled = true,
        coords = {
            vector3(250.0, -51.0, 70.1)
        }
    },
    items = {
        { item = 'WEAPON_PISTOL', price = 5000, license = 'weapon' },
        { item = 'ammo-9', price = 25 },
    },
    ownership = {
        enabled = false,
        coords = vector3(0.0, 0.0, 0.0),
        price = 0
    }
}