Configuration

Editable Configuration Files

These files are open source and can be edited:

External Configuration

🔧 Main Configuration (config.lua)

Basic Settings

Shop Ownership Limits

Config.MaxShopsPerPlayer = 2

• Type: Integer

• Default: 2

• Description: Maximum number of shops one player can own

• Min: 1 (must own at least 1)

• Max: Unlimited (not recommended above 5 for economy balance)

• Example:

  LuaCopy

  Config.MaxShopsPerPlayer = 1  -- Only one shop per player
  Config.MaxShopsPerPlayer = 5  -- Allow wealthy players to own 5 shops

Language Selection

Config.Lang = 'en'

• Type: String

• Default: 'en'

• Options: 'en', 'fr', 'ar', or custom language code

• Description: Sets the language for all UI and notifications

• Notes:

  • Language file must exist in lang/ folder
  • Format: lang/{code}.lua

• Example:

  LuaCopy

  Config.Lang = 'fr'  -- French
  Config.Lang = 'ar'  -- Arabic
  Config.Lang = 'de'  -- German (requires creating lang/de.lua)

Owner/Employee Purchase Prevention

Config.OwnerPrevention = true

• Type: Boolean

• Default: true

• Description: Prevents shop owners and employees from buying items from their own shop

• Reason: They should use "Retrieve Stock" instead to avoid paying themselves

• Recommended: true (prevents economy exploits)

• Example:

  LuaCopy

  Config.OwnerPrevention = true   -- Enable prevention (recommended)
  Config.OwnerPrevention = false  -- Allow owners to buy from own shop

Rent System Configuration

Weekly Rent Amount

Config.WeeklyRent = 1000

• Type: Integer

• Default: 1000

• Description: Base rent amount due every 7 days

• Currency: Your server's currency (dollars, etc.)

• Notes: This is overridden by individual shop prices in Config.Shops[x].Price

• Economy Tips:

  • Low economy servers: 500-2000
  • Medium economy servers: 2000-5000
  • High economy servers: 5000-20000

• Example:

  LuaCopy

  Config.WeeklyRent = 500    -- Cheap rent for new players
  Config.WeeklyRent = 10000  -- Premium shop rent

Late Payment Fee

Config.LateFee = 500

• Type: Integer

• Default: 500

• Description: Additional fee added if rent is paid during grace period

• Added To: Base rent amount

• Example: If rent is $1000 and LateFee is $500, late payment costs $1500

• Recommended: 25-50% of base rent

• Example:

  LuaCopy

  Config.LateFee = 250   -- Low penalty
  Config.LateFee = 1000  -- High penalty to encourage timely payment

Grace Period Days

Config.GraceDays = 2

• Type: Integer

• Default: 2

• Description: Number of days after rent due date before shop is lost

• How It Works:

  • Day 0: Rent due
  • Days 1-2: Grace period (can pay with late fee)
  • Day 3: Shop automatically deleted

• Recommended: 1-3 days

• Example:

  LuaCopy

  Config.GraceDays = 1  -- Strict: 1 day grace period
  Config.GraceDays = 7  -- Lenient: 1 week grace period

Rent System Flow

Day 0 (Rent Due):
  ├─ Player pays on time → Rent = Base Amount
  └─ Player doesn't pay → Enter Grace Period

Grace Period (Days 1-2):
  ├─ Player pays → Rent = Base Amount + Late Fee
  └─ Player doesn't pay → Continue to next day

After Grace Period (Day 3+):
  └─ Shop automatically deleted (inventory cleared)

Interaction Configuration

Interaction Distance

Config.InteractionDistance = 3.0

• Type: Float

• Default: 3.0

• Description: Distance in GTA units for interaction zones

• Units: 1.0 ≈ 1 meter

• Affects:

  • Text-based interaction trigger range
  • Target box zone size

• Range: 1.0 - 10.0 (recommended: 2.0 - 5.0)

• Notes:

  • Too small: Players must be very precise
  • Too large: Zones may overlap

• Example:

  LuaCopy

  Config.InteractionDistance = 2.0   -- Tight range, precise
  Config.InteractionDistance = 5.0   -- Wide range, easier

Debug Mode

Config.Debug = false

• Type: Boolean

• Default: false

• Description: Shows visual PolyZone boxes for interaction zones

• Uses: Development, troubleshooting, positioning zones

• Performance: Disable in production (slight performance impact)

• Example:

  LuaCopy

  Config.Debug = true   -- Show zone boxes (red wireframes)
  Config.Debug = false  -- Hide zone boxes (production)

UI Theme Configuration

Theme Colors

Config.Theme = {
    Primary = "#FEDC2D",
    Bggradient = "#fedb2c1c",
    ButtonHover = "#CAAA00",
    ButtonText = "#000000"
}

Each theme property:

Primary Color

Primary = "#FEDC2D"

• Type: Hex color code

• Default: #FEDC2D (Yellow)

• Affects: Main UI accents, borders, highlights

• Format: #RRGGBB or #RRGGBBAA (with alpha)

• Examples:

  LuaCopy

  Primary = "#FF0000"  -- Red
  Primary = "#00FF00"  -- Green
  Primary = "#0099FF"  -- Blue
  Primary = "#9D4EDD"  -- Purple

Background Gradient

Bggradient = "#fedb2c1c"

• Type: Hex color code with alpha

• Default: #fedb2c1c (Transparent yellow)

• Affects: Background overlay, card backgrounds

• Format: #RRGGBBAA (alpha channel required)

• Alpha: Last 2 digits (00=transparent, FF=opaque)

• Examples:

  LuaCopy

  Bggradient = "#FF000020"  -- Light red tint
  Bggradient = "#0000FF40"  -- Medium blue tint

Button Hover Color

ButtonHover = "#CAAA00"

• Type: Hex color code

• Default: #CAAA00 (Dark yellow/gold)

• Affects: Button color when mouse hovers over it

• Recommendation: Slightly darker than Primary color

• Examples:

  LuaCopy

  ButtonHover = "#CC0000"  -- Dark red (if Primary is red)
  ButtonHover = "#0077CC"  -- Dark blue (if Primary is blue)

Button Text Color

ButtonText = "#000000"

• Type: Hex color code

• Default: #000000 (Black)

• Affects: Text color inside buttons

• Contrast: Must be readable against Primary color

• Examples:

  LuaCopy

  ButtonText = "#FFFFFF"  -- White text (for dark buttons)
  ButtonText = "#000000"  -- Black text (for light buttons)

Theme Examples

Dark Theme:

Config.Theme = {
    Primary = "#BB86FC",      -- Purple
    Bggradient = "#1E1E1E80", -- Dark grey transparent
    ButtonHover = "#9965F4",  -- Dark purple
    ButtonText = "#FFFFFF"    -- White text
}

Red Theme:

Config.Theme = {
    Primary = "#FF4444",      -- Red
    Bggradient = "#FF444420", -- Light red
    ButtonHover = "#CC0000",  -- Dark red
    ButtonText = "#FFFFFF"    -- White text
}

Blue Theme:

Config.Theme = {
    Primary = "#0099FF",      -- Blue
    Bggradient = "#0099FF20", -- Light blue
    ButtonHover = "#0077CC",  -- Dark blue
    ButtonText = "#FFFFFF"    -- White text
}

Green Theme:

Config.Theme = {
    Primary = "#00E676",      -- Green
    Bggradient = "#00E67620", -- Light green
    ButtonHover = "#00C853",  -- Dark green
    ButtonText = "#000000"    -- Black text
}

NPC & Blip Configuration

Seller NPC (Shop Manager)

Seller Ped Model

Config.SellerPed = 'cs_bankman'

• Type: String (ped model name)

• Default: 'cs_bankman'

• Description: NPC model for the shop rental manager

• Format: String with ped hash name

• Common Models:

  LuaCopy

  Config.SellerPed = 'cs_bankman'      -- Banker (suit)
  Config.SellerPed = 'cs_barry'        -- Casual guy
  Config.SellerPed = 'a_m_m_business_01' -- Business man
  Config.SellerPed = 's_m_m_highsec_01'  -- Security guard
  Config.SellerPed = 'ig_claypain'     -- Clay Payne

• Find More: https://docs.fivem.net/docs/game-references/ped-models/

Seller NPC Location

Config.Npc = vec4(-545.3527, -203.8803, 38.2151, 211.4138)

• Type: Vector4 (x, y, z, heading)
• Default: Legion Square area
• Format: vec4(x, y, z, heading)
• How to Get Coordinates:
  1. Stand at desired location in-game
  2. Use /getcoords or /getpos command
  3. Copy coordinates
  4. Replace in config

Example Custom Locations:

-- City Hall
Config.Npc = vec4(-551.18, -191.45, 38.22, 207.41)

-- Pillbox Hill
Config.Npc = vec4(314.50, -278.62, 54.17, 161.18)

-- Sandy Shores
Config.Npc = vec4(1961.11, 3740.48, 32.34, 301.07)

-- Paleto Bay
Config.Npc = vec4(-247.67, 6231.54, 31.49, 47.61)

Seller Blip Configuration

Config.SellerBlip = {
    Enabled = true,
    Sprite = 59,
    Color = 2,
    Scale = 0.7,
    Name = 'Shop Manager'
}

• Enabled: Show blip on map (true/false)
• Sprite: Blip icon ID
  • 52: Store icon
  • 59: Garage icon
  • 108: Shop icon
  • 272: Dollar sign
  • Full List
• Color: Blip color ID
  • 0: White
  • 1: Red
  • 2: Green
  • 3: Blue
  • 5: Yellow
  • Full List
• Scale: Blip size (0.1 - 2.0)
  • 0.5: Small
  • 0.7: Medium (default)
  • 1.0: Large
• Name: Text shown on map

Shop Counter NPC

Shop Ped Model

Config.ShopPed = `mp_m_shopkeep_01`

• Type: Hash (ped model)

• Default: mp_m_shopkeep_01

• Description: NPC at shop counters for customer purchases

• Format: Backticks for hash, or string

• Examples:

  LuaCopy

  Config.ShopPed = `mp_m_shopkeep_01`  -- Default shopkeeper
  Config.ShopPed = `s_m_m_lathandy_01` -- Latino handyman
  Config.ShopPed = `a_m_m_indian_01`   -- Indian male

Shop Blip Settings

Config.BlipSprite = 52  -- Big shop icon
Config.BlipColour = 2   -- Green

• BlipSprite: Icon for owned shops
• BlipColour: Color for owned shops
• Applied To: All player-owned shops on map

Blacklist Configuration

Blacklisted Items

Config.BlacklistItems = {
    'weapon_pistol',
    'weapon_smg',
    'meth',
    'money',
}

• Type: Table/Array of strings
• Description: Items that cannot be added to shop stock
• Format: Item spawn names (exact match)
• Case: Insensitive (automatically converted to lowercase for comparison)
• Uses: Prevent weapon/drug sales, protect economy items

Common Items to Blacklist:

Config.BlacklistItems = {
    -- Weapons
    'weapon_pistol',
    'weapon_pistol50',
    'weapon_combatpistol',
    'weapon_assaultrifle',
    'weapon_carbinerifle',
    'weapon_smg',
    'weapon_microsmg',
    
    -- Illegal Items
    'meth',
    'cocaine',
    'weed',
    'crack',
    'lsd',
    
    -- Money/Currency
    'money',
    'black_money',
    'cash',
    'markedbills',
    
    -- Special Items
    'id_card',
    'driver_license',
    'weaponlicense',
    'lockpick',
    
    -- High-value Items
    'goldbar',
    'diamond',
    'rolex',
}

Framework-Specific Items:

-- QB-Core
Config.BlacklistItems = {
    'weapon_pistol',
    'lockpick',
    'trojan_usb',
}

-- ESX
Config.BlacklistItems = {
    'bread',  -- If you want to prevent basic items
    'black_money',
}

Shop Locations Configuration

Shop Structure

Config.Shops = {
    [index] = {
        Image = 'url',
        Name = 'Shop Name',
        Price = 1000,
        Location = "Location Name",
        Street = "Street Name",
        Manage = vec4(x, y, z, heading),
        Counter = vec4(x, y, z, heading)
    }
}

Shop Properties Explained

Index

• Type: Integer
• Unique: Must be unique for each shop
• Sequential: Recommended to use 1, 2, 3, etc.
• Database: Stored in database to identify shop

Image

• Type: URL string

• Description: Preview image shown in shop browser UI

• Format: Full HTTP/HTTPS URL

• Recommended Size: 800x600px or similar

• Examples:

  LuaCopy

  Image = 'https://i.imgur.com/abc123.jpg'
  Image = 'https://r2.fivemanage.com/your-image.png'

• Tips: Use image hosting services like Imgur, FiveManage R2

Name

• Type: String
• Description: Shop type/brand name
• Examples: '24/7 Supermarket', 'LTD Gasoline', 'Rob Liquor'
• Note: Owners can set custom names after renting

Price

• Type: Integer

• Description: Weekly rent amount for this specific shop

• Override: Overrides Config.WeeklyRent

• Differentiation: Price different shops based on location value

• Examples:

  LuaCopy

  Price = 500,   -- Cheap location (rural)
  Price = 1500,  -- Medium location (suburban)
  Price = 5000,  -- Expensive location (city center)

Location

• Type: String
• Description: General area name
• Examples: "Innocence Blvd", "Sandy Shores", "Paleto Bay"

Street

• Type: String
• Description: Specific street or area descriptor
• Examples: "Elgin Ave, Strawberry", "Mount Chiliad", "Downtown"

Manage

• Type: Vector4 (x, y, z, heading)
• Description: Coordinates for shop management zone
• Who Can Access: Shop owner and employees only
• Purpose: Access management menu (add stock, hire employees, etc.)
• Positioning: Usually behind counter or in office area

Counter

• Type: Vector4 (x, y, z, heading)
• Description: Coordinates for customer counter
• Who Can Access: All players (customers)
• Purpose: Buy items from shop
• Positioning: Front counter where customers interact

Adding New Shop Locations

Step 1: Get Coordinates

1. Go to desired location in-game
2. Stand at customer counter position
3. Use /getcoords → save as Counter
4. Stand at management position (behind counter/in office)
5. Use /getcoords → save as Manage

Step 2: Find Image

1. Take screenshot of shop exterior
2. Upload to image host (Imgur, R2, etc.)
3. Get direct image URL

Step 3: Add to Config

Config.Shops = {
    -- Existing shops...
    
    [20] = {  -- New shop, increment index
        Image = 'https://i.imgur.com/yourimage.jpg',
        Name = 'Convenience Store',
        Price = 2000,  -- Set rent price
        Location = "Vinewood Hills",
        Street = "Mad Wayne Thunder Dr",
        Manage = vec4(1, 2, 3, 90.0),  -- Your coordinates
        Counter = vec4(4, 5, 6, 180.0)  -- Your coordinates
    },
}

Example: Adding a Custom Shop

-- Adding a new shop at the Vanilla Unicorn
[20] = {
    Image = 'https://i.imgur.com/vuclub.jpg',
    Name = 'Vanilla Unicorn Store',
    Price = 3000,  -- Premium location
    Location = "Elysian Island",
    Street = "Strawberry Ave",
    Manage = vec4(129.12, -1283.74, 29.27, 210.45),
    Counter = vec4(127.56, -1285.32, 29.27, 303.17)
},

🌐 PF_LIB Configuration

Location: pf_lib/config.lua or pf_lib/shared/config.lua

Framework Selection

Config.Framework = 'qb-core'

Options:

• 'qb-core' - QBCore Framework
• 'esx' - ES Extended (ESX Legacy/New)
• 'nd_core' - ND Core Framework
• 'vrp' - vRP Framework
• 'mythic' - Mythic Framework
• 'ox_core' - Overextended Core
• 'custom' - Custom framework (requires bridge setup)

Inventory Selection

Config.Inventory = 'ox_inventory'

Options:

• 'ox_inventory' - Overextended Inventory
• 'qb-inventory' - QB-Core Inventory
• 'qs-inventory' - Quasar Inventory
• 'ps-inventory' - Project Sloth Inventory
• 'custom' - Custom inventory (requires bridge)

Notification Selection

Config.Notification = 'ox_lib'

Options:

• 'ox_lib' - ox_lib notifications (modern)
• 'okokNotify' - okokNotify system
• 'framework' - Use framework's native notifications
• 'custom' - Custom notification system

Interaction Selection

Config.Interaction = 'ox_target'

Options:

• 'ox_target' - ox_target (requires ox_target resource)
• 'qb-target' - qb-target (requires qb-target resource)
• 'qtarget' - qtarget (requires qtarget resource)
• 'ox_lib' - ox_lib text UI (requires PolyZone)
• 'qb-drawtext' - QB-Core drawtext (requires PolyZone)
• 'finals-drawtext' - Finals custom drawtext (requires PolyZone)
• 'custom' - Custom interaction system

📝 Language Configuration

Creating Custom Language

Step 1: Copy Template

cp lang/en.lua lang/yourlang.lua

Step 2: Edit Translations

local Translations = {
  BuyShop = {
    close = "Schließen",  -- German example
    business_title = "Mini Märkte",
    -- ... translate all strings
  },
  -- ... all sections
}
return Translations

Step 3: Activate

Config.Lang = 'yourlang'

Language Structure

All text in the script is in lang/ files:

• BuyShop: Shop rental UI
• NameUI: Name input dialog
• ConfirmMsg: Confirmation popups
• Menu: Generic menu strings
• AddStock: Add stock dialog
• RetrieveStock: Retrieve stock dialog
• Hire: Hire employee dialog
• Fire: Fire employee dialog
• ManageShop: Management UI
• HomeTab: Home tab strings
• StockManage: Stock management tab
• Staff: Staff management tab
• ShopUI: Customer shopping UI
• Notify: All notification messages

🎯 Configuration Best Practices

Economy Balance

1. Rent Pricing: Base on shop location value
   • City center: Higher rent
   • Rural areas: Lower rent
2. Late Fees: 25-50% of rent to encourage timely payment
3. Grace Period: 1-3 days is reasonable
4. Max Shops: Don't allow too many per player (2-3 recommended)

Performance

1. Interaction Distance: Keep at 2.0-5.0 for best performance
2. Debug Mode: Always disable in production
3. Shop Count: 20-30 shops is optimal, more may impact performance

User Experience

1. Theme: Choose high-contrast colors for readability
2. NPC Locations: Place seller NPC in accessible, visible area
3. Shop Locations: Spread across map for accessibility
4. Blacklist: Only blacklist items that would break economy/rules

Security

1. OwnerPrevention: Keep enabled to prevent exploits
2. Blacklist: Include all weapons, illegal items, currency items
3. Rent System: Use to prevent abandoned shops

📋 Configuration Checklist

Before going live:

• Configured PF_LIB framework settings
• Set appropriate rent prices for economy
• Configured late fees and grace period
• Set max shops per player
• Customized UI theme colors
• Placed seller NPC in good location
• Added/removed shop locations as needed
• Updated blacklist for your server
• Tested all shops are accessible
• Verified coordinates are correct
• Set appropriate interaction distance
• Disabled debug mode
• Tested rent payment system
• Tested with all player roles
• Translated to server's language (if needed)