DocsBusinessesPlayer Shops

Player Owned Shops

Allow players to purchase, stock, and manage their own retail stores. Features a complete supply chain system, dynamic pricing, and optional logistics integration.

1

Database Installation

Run the following SQL query to create the necessary tables for shops, transaction logs, and supply orders.

MySQL / MariaDB

-- 1. Main Shop Data
CREATE TABLE IF NOT EXISTS `xada_shops` (
  `id` int(11) NOT NULL,
  `owner` varchar(50) DEFAULT NULL,
  `name` varchar(50) DEFAULT 'Store',
  `funds` int(11) DEFAULT 0,
  `stock` longtext DEFAULT '[]',
  `prices` longtext DEFAULT '{}',
  `discounts` longtext DEFAULT '{}',
  `blip_sprite` int(11) DEFAULT 52,
  `for_sale` tinyint(1) DEFAULT 0,
  `sale_price` int(11) DEFAULT 0,
  `total_sold` int(11) DEFAULT 0,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 2. Transaction History
CREATE TABLE IF NOT EXISTS `xada_shop_logs` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `shop_id` int(11) NOT NULL,
  `price` int(11) NOT NULL,
  `created_at` timestamp DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 3. Logistics Integration (Active Supply Orders)
CREATE TABLE IF NOT EXISTS `xada_shop_orders` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `shop_id` int(11) NOT NULL,
  `shop_label` varchar(255) DEFAULT 'Store',
  `items` longtext NOT NULL,
  `coords` text NOT NULL,
  `payout` int(11) DEFAULT 0,
  `status` varchar(50) DEFAULT 'pending',
  `created_at` timestamp DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
2

System & Inventory

Configure the script to match your specific framework and inventory system.

Config.Debug = false 
Config.Locale = 'en' 

Config.System = {
    Framework = 'qb-core',      -- Options: 'qb-core', 'esx'
    
    -- INVENTORY SELECTION
    -- 'ox_inventory': Uses exports (Recommended)
    -- 'qb': Uses standard QBCore inventory (qb/lj/ps)
    -- 'esx': Uses ESX limit/weight system
    -- 'qs': Uses Quasar Inventory
    Inventory = 'ox_inventory', 
    
    Notify = 'qb',              -- Options: 'xada', 'ox_lib', 'qb', 'esx'
    Interaction = 'target',     -- Options: 'textui', 'target'
    
    -- Dependencies for UI/Interaction
    TextUI = 'ox_lib',          
    Target = 'ox_target',       
}
3

Gameplay & Logistics

Logistics Integration

If enabled, shop owners cannot restock instantly. They must place an order, which creates a job in xada_logistics for truckers to deliver.

Config.UseLogistics = false -- Set to true to force delivery via trucks

Discord Webhooks

Config.Webhooks = {
    Enable = true,
    Url = "https://discord.com/api/webhooks/...", 
    Name = "XADA Shops",
    Colors = {
        Success = 65280,    -- Green (Customer Purchases)
        Business = 3447003, -- Blue (Owner Management)
        Money = 15548997,   -- Red (Withdrawals)
        Logistics = 16776960 -- Yellow (Supply Orders)
    }
}
4

Shop Locations

Define the physical store locations purchasable by players.

Config.Shops = {
    [1] = {
        label = "Davis 24/7",
        coords = vec4(-48.0, -1757.0, 28.0, 45.0), -- x, y, z, heading
        pedModel = 'mp_m_shopkeep_01',             -- The cashier NPC
        interactionDist = 2.0,                     -- Distance to open menu
        price = 50000,                             -- Cost to buy the business
        blip = { sprite = 52, color = 2, scale = 0.8, display = 4 }
    },
    [2] = {
        label = "Rob's Liquor",
        coords = vec4(1135.0, -982.0, 46.0, 280.0),
        pedModel = 'mp_m_shopkeep_01',
        interactionDist = 2.0,
        price = 75000,
        blip = { sprite = 52, color = 2, scale = 0.8, display = 4 }
    },
}
5

Items & Suppliers

Items must be defined in the global list before they can be assigned to a Supplier.

1. Global Item Registry

Defines valid items and images.

Config.Items = {
    { 
        name = "testburger", 
        label = "Test Burger", 
        price = 15, -- Recommended Retail Price
        category = "general", 
        image = "nui://ox_inventory/web/images/testburger.png" 
    },
    { 
        name = "repairkit", 
        label = "Repair Kit", 
        price = 300, 
        category = "tools", 
        image = "nui://ox_inventory/web/images/repairkit.png" 
    },
}

2. Wholesale Suppliers

Where owners buy stock.

Config.Suppliers = {
    {
        label = "Los Santos Provisions",
        description = "Food & Meds",
        icon = "fa-solid fa-box-open",
        color = "text-green-500",
        items = {
            -- 'cost' is the price the Shop Owner pays
            { name = "testburger", label = "Test Burger", cost = 5 },
            { name = "medkit", label = "Medkit", cost = 250 },
        }
    },
    {
        label = "Industrial Supply Co.",
        description = "Tools & Mining",
        icon = "fa-solid fa-hammer",
        items = {
            { name = "repairkit", label = "Repair Kit", cost = 120 },
        }
    }
}