⚙️Concepts & How It Works

This guide shows how to create and reuse shop themes in MarketV2. Define visuals (NPC/blip/marker/UI), payments, access rules, and full item catalogs, then style the UI via CSS theme tokens

📚 RISK MARKET V2 — SHOPS & THEMES

Note: This script receives regular updates with new features and improvements. This documentation may not reflect the latest version. Always refer to the most recent configuration files, example configs, and release notes included with your script version for accurate and up-to-date information.

---

1) Overview

• Shops are world instances you place (in Config.MarketShops, WeaponShops, BlackMarkets, JobShops).

• Each shop points to a theme: Config.MarketThemes[THEME_KEY].

• A theme defines visuals (NPC/blip/marker/UI colors), economy (payments), access, and the catalog (categories + items).

---

2) Theme Anatomy

Define under Config.MarketThemes:

Config.MarketThemes = Config.MarketThemes or {}

Config.MarketThemes.mytheme = {
  distance = 3.0,
  npc   = { enabled = true, model = 'a_m_y_business_01' },
  blip  = { enabled = true, sprite = 52, color = 48, scale = 0.8, name = 'My Themed Shop' },
  marker= { enabled = true, type = 29, scale = 0.5, color = { r=255,g=255,b=0,a=150 } },

  ui = {
    title = 'MY THEME',
    description = 'Welcome!',
    showStock = true  -- show stock to customers on owned shops
  },

  payment = {
    cash = true, 
    bank = true, 
    blackmoney = false
    -- itemCurrency = { enabled = true, item = 'gold_token', per = 100 }
  },

  -- Optional access control (jobs/grades):
  access = {
    jobs = 'all',  -- or { 'police','ambulance' }
    minGrade = 0,
    minGrades = { police = 3 }
  },

  weaponsAsItems = false, -- false=give to loadout, true=inventory item

  -- Optional per-job category gates:
  -- categoryAccess = {
  --   police = { { minGrade = 2, categories = { 'Restricted' } } }
  -- },

  categories = {
    { name = 'Snacks', icon = 'img/items/hamburger.png' },
    -- { name = 'Restricted', icon = 'img/categories/crown.png' }
  },

  items = {
    Snacks = {
      { name='bread',     label='Bread',     price={min=10,max=15}, image='img/items/bread.png',     description='Fresh loaf.' },
      { name='hamburger', label='Hamburger', price={min=25,max=25}, image='img/items/hamburger.png', description='Juicy & quick.' }
    }
    -- Restricted = { ... }
  }
}

Rules

• Category names in items must match categories.

• price can be a number (price=100) or {min,max}.

• image can be img/... (NUI) or https://....

---

3) Attach Theme to a Shop

Config.MarketShops = Config.MarketShops or {}
table.insert(Config.MarketShops, {
  coords = {
    {
      id='myshop_1', 
      theme='mytheme',
      pos=vector4(24.50,-1347.06,29.50,264.45),
      ownable=true,
      mgmt=vector4(30.03,-1339.62,29.49,7.72),
      price=200000,
      
      -- ✅ NEW: Per-shop license configuration
      license = {
        required = false,           -- Set to true to require a license
        mode = 'item',              -- 'item', 'esx', or 'tkmdt'
        itemName = 'weapon_license', -- For mode='item'
        esxType = 'weapon',         -- For mode='esx'
        tkmdtType = 'weapon'        -- For mode='tkmdt' (weapon/pistol/rifle)
      }
    }
  }
})

• IDs must be unique across all shops.

• Switch look/catalog by changing theme.

• NEW: Each shop can have its own license requirements via the license table.

---

4) License System (NEW)

Per-Shop License Configuration

Each shop can require a license. Configure in the shop's coords:

license = {
  required = true,              -- true = license required, false = no license
  mode = 'item',                -- 'item', 'esx', or 'tkmdt'
  itemName = 'weapon_license',  -- Required item (mode='item')
  esxType = 'weapon',           -- ESX license type (mode='esx')
  tkmdtType = 'weapon'          -- TK-MDT license type (mode='tkmdt')
}

License Modes

Mode	Description	Required Config
'item'	Player must have item in inventory	itemName = 'weapon_license'
'esx'	ESX license system check	esxType = 'weapon'
'tkmdt'	TK-MDT license system	tkmdtType = 'weapon' / 'pistol' / 'rifle'

Example: Weapon Shop with License

{
  id = 'ammu_1',
  theme = 'weapon',
  pos = vector4(817.60, -2157.69, 29.59, 83.88),
  ownable = true,
  mgmt = vector4(812.80, -2155.10, 29.62, 270.0),
  price = 450000,
  license = {
    required = true,
    mode = 'item',
    itemName = 'weapon_license'
  }
}

Example: TK-MDT Pistol Shop

{
  id = 'ammu_pistol',
  theme = 'weapon_pistol',
  pos = vector4(253.89, -50.48, 69.94, 72.98),
  license = {
    required = true,
    mode = 'tkmdt',
    tkmdtType = 'pistol'  -- Requires TK-MDT pistol license
  }
}

TK-MDT Configuration

Enable/disable TK-MDT weapon registration globally:

Config.TKMDT = {
  debug = false,
  weaponRegistration = {
    autoRegister = false,  -- Set to true to auto-register weapons in TK-MDT
    creator = 'Risk-MarketV2',
    addNotes = true,
    noteTemplate = 'Purchased at shop %s on %s'
  }
}

License Notifications

When a player lacks a license, they receive a notification:

• ❌ You need a valid license

---

5) UI Styling (CSS)

Frontend adds theme-<key> on <body>. Define colors in html/css/config.css:

:root { 
  --main-color:#FDFF18; 
  --main-color-2:#FDFF1836; 
}

.theme-market { 
  --main-color:#FDFF18; 
  --main-color-2:#FDFF1836; 
}

/* Your custom theme */
.theme-mytheme { 
  --main-color:#2EE6A8; 
  --main-color-2:#2EE6A836; 
}

---

6) Payments

Toggle cash, bank, blackmoney in payment.

Item Currency

payment = { 
  itemCurrency = { 
    enabled=true, 
    item='gold_token', 
    per=100  -- each token = $100
  } 
}

QBCore Black Money as Item

Config.BlackMoneyAsItem = { 
  name='black_money', 
  per=1 
}

---

7) Ownership, Pricing & Stock

Unowned Shops

• Prices read from theme each open (min..max random if range).

• No DB stock tracking.

Owned Shops

• Prices freeze to DB on purchase (owner can edit).

• Stock tracked per item (show in UI if ui.showStock=true).

• Sales credit shop balance; purchases decrement stock.

---

8) Access Control & Weapons

Restrict by job/grade via access (and optionally categoryAccess).

Job/Grade Access (Theme Level)

access = {
  jobs = 'all',  -- or { 'police', 'ambulance' }
  minGrade = 0,
  minGrades = { police = 3 }  -- Police need grade 3+
}

Weapons

• weaponsAsItems=false → given to loadout (duplicates blocked).

• weaponsAsItems=true → added as inventory items.

---

9) Delivery Missions (Owner Restock)

Start from owner UI → server calls:

exports['risk-marketv2']:StartDelivery(source, shopId)

Flow

1. Truck spawns at Config.Delivery.Spawns[shopId].spawn.

2. Load at loadMarker (progress bar).

3. Return to shop and unload → stock increases.

Configuration

Config.Delivery.Spawns = {
  ['247_1']   = { 
    spawn = vector4(...), 
    loadMarker = vector3(...) 
  },
  ['myshop_1'] = { 
    spawn = vector4(...), 
    loadMarker = vector3(...) 
  }
}

---

10) Owner Flow (Bank & Procurement)

• Buy: Charge bank; create risk_mv2_balances row; freeze prices; init stock rows.

• Fund/Withdraw: Bank ↔ shop balance (fee via Config.FundFeePercent).

• Set Price: DB update + live NUI refresh.

• Procure: Buy stock from balance at wholesale = min(price) * (1 - Discount%).

---

11) Exports & Events

Server Exports

exports('StartDelivery', function(src, shopId) end)
exports('GetShopSnapshot', function(shopId) -> table end)
exports('CanManage', function(src, shopId) -> bool end)

Core Events

• risk_markets:open → Open UI for shop id (server).

• risk_markets:purchase → Process cart/payment (server).

Owner Actions

• risk-mv2a:setItemPrice

• risk-mv2a:fundAccount

• risk-mv2a:withdrawAccount

• risk-mv2a:procureItem

Delivery Flow

• risk-markets:delivery:* (spawn/load/unload/done)

---

12) Images & Paths

• Prefer local img/... under the resource's html folder.

• Remote images: full https://....

• If you rename the resource, update any nui://<resource>/... paths used elsewhere.

---

13) ox_target vs. Markers

• If Config.UseOxTarget = true and ox_target is running → NPC/box-zone context options.

• Otherwise → 3D marker + "E" prompt.

---

14) Best Practices

✅ Keep catalog & visuals in themes; reuse themes across many shops. ✅ Ensure unique shop IDs. ✅ Show stock to players only where meaningful (ui.showStock=true). ✅ Start access simple (jobs='all'), add minGrade/categoryAccess later. ✅ Use per-shop license config for flexible access control. ✅ Test license modes thoroughly before production.

---

15) Gotchas & Troubleshooting

❌ Duplicate IDs: Don't reuse (e.g., 247_2 twice) — rename one (e.g., 247_4). ❌ UI won't open: Check ox_target state or stand in marker and press E. ❌ Images missing: Bad path; verify relative to html or use https://. ❌ Prices not persistent: Only persist after ownership (unowned uses theme config). ❌ Stock not changing: Tracked only for owned shops. ❌ License not working: Verify license.required = true and correct mode settings. ❌ No license notification: Check server console for errors in license checks.

---

16) Minimal Example Theme + Shop

Theme

Config.MarketThemes.neon = {
  distance = 3.0,
  npc = { enabled = true, model = 'a_f_y_hipster_02' },
  blip = { enabled = true, sprite = 52, color = 27, scale = 0.8, name = 'Neon Store' },
  marker = { enabled = true, type = 29, scale = 0.5, color = { r=0,g=200,b=255,a=140 } },

  ui = { 
    title = 'NEON MART', 
    description = 'Open late. Shine bright.', 
    showStock = true 
  },
  
  payment = { 
    cash = true, 
    bank = true, 
    blackmoney = false 
  },
  
  access = {
    jobs = 'all'
  },
  
  weaponsAsItems = false,

  categories = {
    { name='Drinks',  icon='img/items/water.png' },
    { name='Gadgets', icon='img/items/usb.png' }
  },

  items = {
    Drinks = {
      { name='water',        label='Water Bottle', price={min=5,max=5},   image='img/items/water.png',  description='Stay hydrated.' },
      { name='energy_drink', label='Energy Drink', price={min=18,max=22}, image='img/items/energy.png', description='Quick boost.' }
    },
    Gadgets = {
      { name='usb_stick', label='USB Stick', price={min=18,max=22}, image='img/items/usb.png', description='Portable storage.' },
      { name='radio',     label='Radio',     price={min=95,max=110},image='img/items/radio.png', description='Stay connected.' }
    }
  }
}

CSS

.theme-neon { 
  --main-color:#00E5FF; 
  --main-color-2:#00E5FF36; 
}

Shop

table.insert(Config.MarketShops, {
  coords = {
    {
      id='neon_1', 
      theme='neon',
      pos=vector4(1160.0, -324.0, 69.2, 90.0),
      ownable=true, 
      mgmt=vector4(1159.2, -319.7, 69.2, 178.0), 
      price=240000,
      license = {
        required = false  -- No license needed for this shop
      }
    }
  }
})

---

17) Weapon Shop License Examples

Example 1: Basic Weapon Shop (Item License)

{
  id = 'ammu_1',
  theme = 'weapon',
  pos = vector4(817.60, -2157.69, 29.59, 83.88),
  ownable = true,
  mgmt = vector4(812.80, -2155.10, 29.62, 270.0),
  price = 450000,
  license = {
    required = true,
    mode = 'item',
    itemName = 'weapon_license'
  }
}

Example 2: Pistol Shop (TK-MDT)

{
  id = 'ammu_pistol',
  theme = 'weapon_pistol',
  pos = vector4(253.89, -50.48, 69.94, 72.98),
  license = {
    required = true,
    mode = 'tkmdt',
    tkmdtType = 'pistol'
  }
}

Example 3: Rifle Shop (ESX)

{
  id = 'ammu_rifle',
  theme = 'weapon_rifle',
  pos = vector4(-662.88, -933.52, 21.83, 178.96),
  license = {
    required = true,
    mode = 'esx',
    esxType = 'rifle'
  }
}

Example 4: No License Shop

{
  id = 'ammu_public',
  theme = 'weapon',
  pos = vector4(842.40, -1033.40, 28.19, 0.0),
  license = {
    required = false
  }
}

---