🛍️Trader Shop System

Overview

hate-traders is a comprehensive trading system for FiveM servers that allows players to buy and sell items through various trading locations. The script supports different market types (traders, fence, black market) and includes features like stock management, multilingual support, and customizable NPCs.

Features

  • Multiple Market Types: Configure different types of markets (traders, fence, black market)

  • Stock Management: Each item has its own stock that replenishes over time

  • Infinity Stock Option: Special "-1" stock value for items with unlimited availability

  • Buy/Sell Permissions: Control which items can be bought or sold with individual flags

  • Item Metadata Support: Items can have metadata like durability, registration status, etc.

  • Multilingual Support: Built-in support for English, Turkish, and German languages

  • Dynamic UI: Modern and responsive NUI interface with dynamic content generation

  • Framework Support: Compatible with both QBCore and ESX frameworks

  • NPC & Blip Customization: Fully customizable NPCs and map blips

  • Category System: Items can be organized into categories for easy navigation

  • Customizable Markers: Full control over marker appearance, size, and colors

  • Extensible Market Types: Easily add new market types with custom marker colors

Installation

Requirements

  • QBCore or ESX Framework

  • oxmysql

Setup Instructions

  1. Download and Extract

    • Download the resource and extract it to your server's resources folder

    • Ensure the folder is named hate-traders

  2. Database Setup

    • The script will automatically create required database tables on first start

    • Required table: market_stocks

  3. Configure the Script

    • Open config.lua to customize market locations, items, and settings

    • Set Config.Framework to either "qbcore" or "esx" depending on your server

    • Set Config.Locale to your desired language ("en", "tr", or "de")

  4. Add to Server.cfg

    • Add ensure hate-traders to your server.cfg file

  5. Restart Your Server

    • Restart your server for the changes to take effect

Configuration

Main Configuration Options

Config = {}
Config.Framework = "qbcore" -- 'esx' or 'qbcore'
Config.Locale = "en" -- Language option: "en", "tr", "de"

-- Shop System Settings
Config.EnablePeds = true -- Set to false to disable all trader NPCs
Config.EnableBlips = true -- Set to false to disable map blips
Config.EnableMarkers = true -- Set to false to disable all markers

-- Marker configuration
Config.Marker = {
    type = 27, -- Marker type (https://docs.fivem.net/docs/game-references/markers/)
    scale = 1.5, -- Size of the marker
    bobUpAndDown = false,
    faceCamera = false,
    rotate = true,
    drawOnEnts = true,
    -- Default colors for different market types
    colors = {
        traders = {147, 136, 102, 155}, -- R, G, B, Alpha
        fence = {125, 145, 111, 155},
        black = {177, 95, 76, 155}
        -- Add more market types and colors as needed
    }
}

-- Stock replenishment interval in milliseconds
Config.StockUpdateInterval = 3600000 -- 1 hour

Market Location Setup

Each market location can be configured with these properties:

{
    coords = vector3(x, y, z), -- Location coordinates
    type = "traders", -- Market type: 'traders', 'fence', or 'black'
    blip = {
        sprite = 59, -- Blip sprite ID
        color = 2, -- Blip color
        scale = 0.7, -- Blip size
        label = "Market" -- Blip label
    },
    npc = {
        model = "s_m_m_ammucountry", -- NPC model
        heading = 266.74, -- NPC facing direction
        scenario = "WORLD_HUMAN_CLIPBOARD", -- NPC animation
        appearance = {
            variation = 0,
            texture = 0
        }
    }
}

Item Configuration

Items can be configured with these properties:

{
    name = "item_name", -- Item spawn name
    price = {
        item = "currency_item", -- Item used for payment
        amount = 100 -- Amount required
    },
    sellPrice = {
        item = "currency_item", -- Item received when selling
        amount = 50 -- Amount received
    },
    canBuy = true,  -- Whether the item can be purchased by players (Optional, defaults to true)
    canSell = true, -- Whether the item can be sold by players (Optional, defaults to true)
    type = "Category", -- Item category for UI organization
    level = 1, -- Item level requirement
    stock = 10, -- Initial stock amount (use -1 for infinity stock)
    metadata = { -- Optional metadata
        registered = true,
        serial = "SERIAL",
        durability = 100,
        -- Add any other metadata properties
    }
}

Exports

The script provides the following exports that can be used by other resources:

Client-side Exports

  1. OpenMarket Opens a specific market type

    -- Usage:
exports['hate-traders']:OpenMarket(marketType)

-- Example:
exports['hate-traders']:OpenMarket('traders') -- Opens the regular trader
exports['hate-traders']:OpenMarket('fence') -- Opens the fence market
exports['hate-traders']:OpenMarket('black') -- Opens the black market

  2. CloseMarket Closes the currently open market

    -- Usage:
exports['hate-traders']:CloseMarket()

Language Support

The script includes complete translations for English, Turkish, and German languages. You can change the active language by modifying the Config.Locale setting in the config.lua file.

To add a new language, you can create a new entry in the languages.lua file following the existing language structure.

Customization

Adding New Items

To add new items to the markets, add them to the respective market type in the Config.Items table.

Creating New Market Types

You can create new market types by adding a new key to the Config.Items table and then adding locations with that type.

Custom Currency System

The script uses item-based currency by default. The main currency item is defined in Config.MoneyItem.

Advanced Features

Stock System

Each item has its own stock that is tracked server-side and stored in the database. Stocks automatically replenish over time based on the Config.StockUpdateInterval setting.

Infinity Stock

Set an item's stock value to -1 to give it unlimited stock. Items with infinity stock:

  • Display an infinity symbol (∞) in the UI

  • Never run out of stock when purchased

  • Synchronize between database and config

Buy/Sell Permissions

Each item can have individual buy and sell permissions:

  • canBuy: Controls whether players can purchase the item (defaults to true)

  • canSell: Controls whether players can sell the item back (defaults to true)

The UI will automatically hide buy/sell tabs if no items are available for that mode in the current market.

Item Metadata

When configuring items, you can add metadata that will be transferred to the player's inventory when they purchase the item. This can include properties like:

  • Durability

  • Serial numbers

  • Registration status

  • Any other custom properties

Troubleshooting

Common Issues

  1. Items not appearing in the shop

    • Ensure the item exists in your server's shared items list

    • Check that the market type is correctly configured

    • Verify that the item's canBuy or canSell flags are not set to false

  2. NPCs not spawning

    • Verify that Config.EnablePeds is set to true

    • Check that the NPC models are valid and available on your server

  3. Translation issues

    • Make sure the language key in Config.Locale matches one of the available languages

    • Check if the translation key exists in the selected language

  4. Stock not synchronizing

    • If infinity stock (-1) is not working, verify your database supports negative values

    • Check server console for any SQL-related errors

Support

For additional support, please refer to the official documentation or contact the developer.

Note: This script has encrypted client and server files. The documentation only covers the available exports and configuration options.

PreviousGPS SystemNextCraft System