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
    }

---

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