🛒SHOPS CREATOR

Here check the installation guide

Forge Shops V2

Advanced shop system for FiveM servers.

Created by CodeForge Support Discord: https://discord.gg/UTVssdrXRV

Features

Normal shops with buy and sell modes.
Reusable item categories through ItemCategories.
Weapon shops with a dedicated NUI, stats, tints, components, license checks and optional 3D preview.
Illegal shops with configurable police alert chance, delay and cooldown.
Business shops with duty, management panel, stock, custom prices, employees, NPC income, invoices and worker deliveries.
Target and non-target interaction modes.
Proximity-based shop NPC spawning for better performance.
Model-based shops for vending machines, coffee machines and other props.
Multiple payment methods per shop.
Job-restricted shops.
Server-side validation for purchases, sales, jobs, distance, stock and inventory actions.
Server-side Discord webhook logging.
Full translation system in config/translations.lua.
Debug mode with startup hints and structured console logs.
Open configuration, bridge and hook files for easier server integration.

Requirements

Required:

A FiveM server using cerulean.
oxmysql.
ESX or QBCore/QBOX.
A supported inventory system, or the framework fallback.

Supported framework modes:

auto
esx
qb

Supported inventory aliases:

auto
ox / ox_inventory
qb / qb-inventory / qb_inventory
ps / ps-inventory / ps_inventory
qs / qs-inventory / qs_inventory / quasar
core / core_inventory / core-inventory
tgiann / tgiann-inventory / tgiann_inventory
jaksam / jaksam_inventory / jaksam-inventory
esx / esx_default / default

Optional:

ox_target or qb-target.
forge-notify.
neon-boss for the external boss menu option.
Society/banking resources depending on Config.Business.SocietyMethod.
Dispatch resources if you connect illegal shop alerts to your dispatch system.

Installation

Place the folder in your resources directory.
Recommended path:
```
resources/[forge]/forge-shops
```
Keep the resource name as forge-shops.
If you rename the resource, update paths that reference the resource name, especially:
```
Config.WeaponShop.WeaponImageBase = 'nui://forge-shops/html/public/weapons/'
```

Make sure your dependencies start before this resource.

Example server.cfg:

ensure oxmysql
ensure es_extended
# or: ensure qb-core

ensure ox_inventory
# optional target:
ensure ox_target

ensure forge-shops

Configure your database connection for oxmysql.
Install the database table.
By default this is automatic:
```
Config.Business.AutoInstallDB = true
```
If you prefer manual installation, run:
```
SQL/install.sql
```
Configure the script in:
- config/config.lua
- config/shops.lua
- config/weaponshops.lua
- config/illegalshops.lua
- config/translations.lua
- config/open_server.lua
- config/open_client.lua
Restart the server or restart the resource:
```
restart forge-shops
```

Main Configuration

Framework

Set your framework in config/config.lua:

Config.Framework = 'auto'

Use auto unless you need to force a framework:

Config.Framework = 'esx'
Config.Framework = 'qb'

For ESX, check:

Config.ESXExport = 'es_extended'
Config.Core = 'esx:getSharedObject'

Inventory

Set your inventory system:

Config.Inventory = 'auto'

If auto-detection does not match your server, force it:

Config.Inventory = 'ox'
Config.Inventory = 'qb'
Config.Inventory = 'qs'

Target Mode

Target disabled:

Config.UseTarget = { false, 'ox-target', 'target.open_shop' }

Target enabled with ox_target:

Config.UseTarget = { true, 'ox-target', 'target.open_shop' }

Target enabled with qb-target:

Config.UseTarget = { true, 'qb-target', 'target.open_shop' }

When target is enabled, it is used for shops, business duty, management, boss menu and worker delivery interactions.

Language

Set the active language:

Config.Locale = 'en'

Translations are stored in:

config/translations.lua

Discord webhook texts are configured separately in config/open_server.lua.

Debug

Enable debug mode while installing or diagnosing:

Config.Debug = true

Disable it in production:

Config.Debug = false

When enabled, the server prints startup hints, including the selected framework, inventory, target system, business status, weapon shop status and Discord logging status.

Payment Methods

Global payment methods are configured in:

Config.PaymentMethods
Config.DefaultPaymentMethods

Per-shop payment methods:

paymentMethods = { 'bank', 'cash' }

Examples:

paymentMethods = { 'cash', 'black_money' }
paymentMethods = { 'bank' }

Adding a Normal Shop

Add normal shops in:

config/shops.lua

Example:

Shops["Example Shop"] = {
    label        = "shop.example_shop",
    category     = "supermarket",
    sellCategory = "supermarket_sell",
    paymentMethods = { 'bank', 'cash' },

    ped    = { use = true, model = "mp_m_shopkeep_01", coords = vector4(25.0, -1345.0, 28.5, 180.0), useAnimations = true },
    coord  = vector3(25.0, -1345.0, 29.5),
    marker = { use = true, style = 23, r = 51, g = 175, b = 213 },
    blip   = { use = true, style = 52, color = 3, scale = 0.8, text = "blip.example_shop" },
}

Then add translations in config/translations.lua:

['shop.example_shop'] = 'Example Shop',
['blip.example_shop'] = 'Example Shop',

Adding Item Categories

Reusable buy categories are in config/shops.lua:

ItemCategories["example_category"] = {
    ["Water"] = {
        itemName  = "water",
        itemImage = "water.png",
        itemPrice = 10,
        special   = false
    },
}

Use the category in a shop:

category = "example_category"

Adding Sell Categories

Sell categories define what a shop buys from players:

SellCategories["example_sell"] = {
    ["Water"] = {
        itemName  = "water",
        itemImage = "water.png",
        itemPrice = 5
    },
}

Use the sell category in a shop:

sellCategory = "example_sell"

Restricting a Shop by Job

Add allowedJobs to the shop:

allowedJobs = { "police", "ambulance" }

Remove allowedJobs or leave it empty to allow everyone.

Access is validated server-side.

Adding a Weapon Shop

Weapon shops are configured in:

config/weaponshops.lua

Example:

Shops["Ammu-Nation Example"] = {
    label          = "shop.ammu_nation",
    shopType       = 'weapon',
    weaponCategory = { 'handguns', 'melee', 'ammo' },
    requireLicense = true,
    paymentMethods = { 'bank', 'cash' },

    ped    = { use = true, model = "s_m_y_ammucity_01", coords = vector4(22.0, -1107.0, 28.8, 160.0), useAnimations = false },
    coord  = vector3(22.0, -1107.0, 29.8),
    marker = { use = true, style = 23, r = 255, g = 120, b = 30 },
    blip   = { use = true, style = 110, color = 47, scale = 0.85, text = "blip.ammu_nation" },
}

Weapon shop settings are in:

Config.WeaponShop

Important options:

Enabled
LicenseCheckMode
LicenseItem
LicenseName
GiveMode
StackableWeaponItems
WeaponImageBase
Preview3D

If LicenseCheckMode = 'item', make sure the license item exists in your inventory.

Weapon Categories, Components and Tints

Weapon categories are in:

WeaponCategories

Each weapon can define:

weaponHash
itemName
image
price
description
tints
stats
components

Components can define:

name
hash
itemName
price
image
slot

Tint palettes are in:

WeaponTints

Adding an Illegal Shop

Illegal shops are configured in:

config/illegalshops.lua

Example:

Shops["Black Market Example"] = {
    label          = "shop.black_market",
    category       = "black_market",
    sellCategory   = "black_market_sell",
    illegal        = true,
    paymentMethods = { 'cash', 'black_money' },

    coord  = vector3(100.0, 100.0, 30.0),
    marker = { use = true, style = 23, r = 120, g = 0, b = 0 },
    blip   = { use = false, style = 0, color = 0, scale = 0.0, text = "blip.black_market" },
}

Police alert settings are in:

Config.IllegalShops

The open server-side hook is:

IllegalShopPoliceAlert(src, shop, action, coords)

You can integrate dispatch systems in:

config/open_server.lua

Business Shops

Business shops are normal or weapon shops with:

isBusiness = true

Business settings are in:

Config.Business

Main features:

Worker duty.
Management panel.
Stock and restock system.
Custom item and weapon prices.
NPC employee hiring and firing.
NPC salaries.
Passive NPC income.
Invoice sales.
Worker order deliveries.
Company and worker revenue split.
External society/banking integration or built-in balance.

Example:

Shops["My Business Shop"] = {
    label        = "shop.business_store",
    category     = "supermarket",
    sellCategory = "supermarket_sell",

    isBusiness  = true,
    assignedJob = "shopkeeper",
    societyKey  = "society_shopkeeper",
    workerRanks = { 0, 1 },
    ownerRanks  = { 2, 3 },

    dutyPoint = vector4(25.0, -1345.0, 29.49, 180.0),
    adminPanel = {
        targetCoords = vector4(23.0, -1344.0, 29.49, 90.0),
        targetExtent = vector3(1.5, 1.0, 1.5),
    },
    bossMenuPoint = vector4(22.0, -1343.0, 29.49, 90.0),

    ped    = { use = true, model = "CS_Josh", coords = vector4(24.5, -1346.19, 28.5, 266.78), useAnimations = true },
    coord  = vector3(25.3555, -1346.1746, 29.4876),
    marker = { use = true, style = 23, r = 51, g = 175, b = 213 },
    blip   = { use = true, style = 52, color = 2, scale = 0.8, text = "blip.business_store" },
}

Business Society Money

Use built-in business balance:

Config.Business.UseBuiltinBalance = true

Use external society/banking:

Config.Business.UseBuiltinBalance = false
Config.Business.SocietyMethod = 'QB'

Supported society methods:

FORGE
QB
OKOK
ESX
FD
TGG
WASABI
CODEM
JUSTBANKING

Make sure the required banking/society resource is installed and started.

To use neon-boss:

Config.Business.UseNeonBossMenu = true

Then configure bossMenuPoint in each business shop.

Model-Based Shops

Model shops are configured with:

Config.ModelScan
Config.ModelShops

Example:

Config.ModelShops = {
    { model = 'prop_vend_soda_01', shop = 'Vending Machines', distance = 1.2, label = 'target.open_vending' },
}

The referenced shop should use:

openByModelOnly = true

Discord Webhook Logs

Discord logs are configured server-side only in:

config/open_server.lua

Do not place webhook URLs in client or shared files.

Enable logs:

Config.DiscordLogs.Enabled = true

Use one default webhook:

Config.DiscordLogs.DefaultWebhook = 'https://discord.com/api/webhooks/...'

Or use a different webhook per category:

Config.DiscordLogs.Categories.purchases.Webhook = 'https://discord.com/api/webhooks/...'
Config.DiscordLogs.Categories.sells.Webhook = 'https://discord.com/api/webhooks/...'
Config.DiscordLogs.Categories.weapons.Webhook = 'https://discord.com/api/webhooks/...'
Config.DiscordLogs.Categories.business.Webhook = 'https://discord.com/api/webhooks/...'
Config.DiscordLogs.Categories.illegal.Webhook = 'https://discord.com/api/webhooks/...'

You can also store webhook URLs in server.cfg using convars:

set forge_shops_purchases_webhook "https://discord.com/api/webhooks/..."

Then point the category to that convar:

Config.DiscordLogs.Categories.purchases.Convar = 'forge_shops_purchases_webhook'

Default categories:

purchases
sells
weapons
business
illegal

Default log actions:

item_purchase
item_sell
weapon_purchase
accessory_purchase
invoice_sale
worker_sale
worker_weapon_sale
business_management
illegal_alert

Translations

All player-facing and admin-facing text is in:

config/translations.lua

Set the active language in:

Config.Locale = 'en'

To add a language:

Copy the English language table.
Rename it to your locale code, for example es.
Translate the values, not the keys.
Set Config.Locale to your locale code.

Do not translate:

Event names.
Export names.
Function names.
Item names.
Weapon hashes.
Job names.
Permission names.
Internal identifiers.

Discord log texts are intentionally configured in config/open_server.lua.

Images

Item images use:

Config.ItemImageBaseURL
Config.ItemImageExtension

Examples:

Config.ItemImageBaseURL = 'nui://ox_inventory/web/images/'
Config.ItemImageBaseURL = 'nui://qb-inventory/html/images/'
Config.ItemImageBaseURL = 'public/items/'

Weapon images use:

Config.WeaponShop.WeaponImageBase
Config.WeaponShop.WeaponImageExt

Image filenames must match the configured item or weapon image names.

Editable Integration Files

These files are intended for configuration and integration:

config/config.lua
config/translations.lua
config/shops.lua
config/weaponshops.lua
config/illegalshops.lua
config/bridge_client.lua
config/bridge_server.lua
config/open_client.lua
config/open_server.lua

Use config/open_server.lua for protected server-side hooks such as:

Inventory carry checks.
Discord webhook configuration.
Illegal shop police alerts.

Troubleshooting

The shop does not open

Check that your framework is started before forge-shops.
Check Config.Framework.
Check that your inventory resource is started.
Check Config.Inventory.
If using target, check Config.UseTarget and make sure ox_target or qb-target is started.
Check allowedJobs on the shop.
Check that the player is close enough to the configured coordinates.

Items are not added or removed

Check that the item exists in your inventory system.
Check Config.Inventory.
Enable Config.Debug = true and read the server console.
Check inventory weight/capacity rules.

Weapon purchases fail

Check Config.WeaponShop.Enabled.
Check Config.WeaponShop.GiveMode.
If using GiveMode = 'item', make sure weapon items exist in your inventory.
If using licenses, make sure the configured license item or framework license exists.
Check that weapon components and ammo item names match your inventory.

Business money does not update

Check Config.Business.Enabled.
Check Config.Business.UseBuiltinBalance.
If using external society money, check Config.Business.SocietyMethod.
Make sure the society/banking resource required by your selected method is started.
Make sure the shop has a valid societyKey.

NPCs appear only nearby

Shop NPCs are spawned by proximity for performance.

Adjust:

Config.PedSpawnRadius = 50

Higher values keep NPCs spawned from farther away, but may cost more performance on servers with many shops.

Images are missing

Check Config.ItemImageBaseURL.
Check Config.WeaponShop.WeaponImageBase.
Check that filenames include the configured extension.
If you renamed the resource, update NUI paths that contain forge-shops.

Text is missing or shows a translation key

Check config/translations.lua.
Make sure the key exists in the active language.
English is used as fallback when possible.

Support

For support, updates and questions, join:

https://discord.gg/UTVssdrXRV

PreviousTriggers and Exports NextSLEEK MULTIJOB

Last updated 3 months ago

Forge Shops V2

Features

Requirements

Installation

Main Configuration

Framework

Inventory

Target Mode

Language

Debug

Payment Methods

Adding a Normal Shop

Adding Item Categories

Adding Sell Categories

Restricting a Shop by Job

Adding a Weapon Shop

Weapon Categories, Components and Tints

Adding an Illegal Shop

Business Shops

Business Society Money

External Boss Menu

Model-Based Shops

Discord Webhook Logs

Translations

Images

Editable Integration Files

Troubleshooting

The shop does not open

Items are not added or removed

Weapon purchases fail

Business money does not update

NPCs appear only nearby

Images are missing

Text is missing or shows a translation key

Support