Features

🏪 Shop Management System

Shop Rental

Browse Available Shops

• 19 Pre-configured Locations across the map
  • 9x 24/7 Supermarkets
  • 5x LTD Gasoline stations
  • 5x Rob's Liquor stores
• Visual Shop Browser with images
• Location Information:
  • Shop name and type
  • Area name (e.g., "Strawberry", "Sandy Shores")
  • Street address
  • Weekly rent price
  • Ownership status (Available/Owned)

Check Location Feature

• GPS Waypoint: Click to mark shop on map
• Navigation: Yellow route to shop location
• Distance: See how far shop is from you
• Preview: Visit before renting

Rent Shop Process

1. Click "Rent" button on available shop
2. Enter custom shop name (shown on map)
3. Confirm purchase
4. Money deducted from bank account
5. Shop immediately available for management
6. Blip appears on map with your custom name

Shop Ownership

• Maximum Shops: Configurable per player (default: 2)
• Unique Names: Each shop has custom name visible to all players
• Persistent: Ownership saved in database
• Transfer: Can end lease to free up slot

Shop Management Interface

Management Zone

• Separate from Customer Counter: Owner-only zone behind counter
• Access Control: Only owner and employees
• Interaction: Target or text-based (E key)
• Always Available: Access anytime while shop is owned

Management Menu Tabs

1. Home Tab

• View total earnings balance
• Withdraw money to bank
• View rent information
• See next rent due date
• Check rent status (on-time/late)
• Pay rent button

2. Stock Manage Tab

• Add stock from inventory
• Retrieve stock back to inventory
• Set custom prices per item
• View current stock levels
• Manage item availability

3. Staff Tab

• Hire nearby players as employees
• Fire existing employees
• View employee list
• Manage shop permissions

End Lease

• Voluntary Exit: End shop ownership anytime
• Inventory Loss: All stock deleted on lease end
• Money: Shop balance can be withdrawn before ending
• Warning: Confirmation dialog prevents accidents
• Immediate: Shop becomes available immediately

💼 Employee System

Hiring Employees

How to Hire

1. Have target player stand near you (within 5 meters)
2. Open Management UI → Staff Tab
3. Click "Hire Employee"
4. Select player from nearby list
5. Confirm hire
6. Employee receives notification

Employee Notifications

• Hired: Employee notified they were hired
• Shop Access: Can immediately access management zone
• Permissions: Informed of their capabilities

Employee Permissions

What Employees CAN Do:

✅ Access management zone

✅ Add stock to shop

✅ Retrieve stock from shop

✅ View shop inventory

✅ Help manage stock levels

What Employees CANNOT Do:

❌ Withdraw money from shop

❌ Pay shop rent

❌ Hire other employees

❌ Fire employees

❌ End the lease

❌ Change shop name

❌ View financial information

Firing Employees

How to Fire

1. Open Management UI → Staff Tab
2. Click "Fire Employee"
3. Select employee from list
4. Confirm termination
5. Employee immediately loses access

What Happens When Fired

• Instant: Access revoked immediately
• Notification: Employee notified of termination
• Management Zone: Can no longer access
• No Stock Loss: Shop inventory unchanged
• Online/Offline: Works for online or offline employees

Employee Benefits

For Shop Owner:

• Delegation: Others can manage stock when you're offline
• Time Saving: Don't need to always be present
• Trust System: Hire trusted friends/org members
• Protection: Employees can't steal money

For Employees:

• Job Opportunity: Earn trust and responsibility
• Shop Access: Help run successful business
• Experience: Learn shop management
• Notification: Get notified when sales happen

Real-time Notifications

Sale Notifications

When a customer makes a purchase:

• Owner Receives: "💰 Someone spent $X at your shop (Shop Name)"
• Employees Receive: "🛒 A customer purchased items worth $X at shop (Shop Name)"
• Shows: Total transaction amount and shop name
• Purpose: Keep informed of business activity

📦 Inventory Management

Adding Stock

Process

1. Open Management UI → Stock Manage Tab
2. Click "Add Stock" button
3. Select item from your inventory
4. Enter quantity to add
5. Set price per item
6. Confirm

Features

• Item Selection: See all items in your inventory
• Quantity Display: Shows available amount (e.g., "Bread x5")
• Blacklist Filter: Blacklisted items don't appear
• Price Control: Set any price per item
• Bulk Add: Add multiple quantities at once
• Inventory Check: Can't add more than you have

Stock Addition Rules

• Must Have Item: Item must be in your inventory
• Quantity Limit: Can't exceed owned amount
• Price Minimum: Must set price > 0
• Duplicate Handling: Adding same item again updates price and adds quantity
• Removal From Inventory: Items immediately removed from your inventory

Retrieving Stock

Process

1. Open Management UI → Stock Manage Tab
2. Click "Retrieve Stock" button
3. Select item from shop inventory
4. Enter quantity to retrieve
5. Confirm

Features

• Stock View: See all items currently in shop
• Quantity Display: Shows available amount in shop
• Partial Retrieval: Take some or all of an item
• Inventory Space: Requires space in your inventory
• Instant Transfer: Items added to inventory immediately

Retrieval Rules

• Must Be In Stock: Item must exist in shop inventory
• Quantity Limit: Can't retrieve more than shop has
• Owner/Employee Only: Only shop staff can retrieve
• Removes From Shop: Item no longer available to customers
• Price Reset: Price can be changed when re-added

Blacklist System

Purpose

• Prevent certain items from being sold in shops
• Protect economy from illegal/exploit items
• Control what's available in player shops
• Server rule enforcement

How It Works

• Config-based: Set in Config.BlacklistItems
• Case Insensitive: "weapon_pistol" = "WEAPON_PISTOL"
• Add Stock Only: Only prevents adding, not retrieving
• Hidden: Blacklisted items don't appear in "Add Stock" selection
• No Error: Silently filtered from selection

Common Blacklist Categories

1. Weapons: All firearms and melee weapons
2. Illegal Items: Drugs, contraband
3. Currency: Money, marked bills, crypto
4. Special Items: IDs, licenses, quest items
5. Server-Specific: Custom items you want to restrict

💰 Financial System

Shop Balance

Earnings Accumulation

• Automatic: Money from sales automatically added
• Safe Storage: Stored in database, can't be stolen
• Real-time: Updates instantly on each sale
• View: Check current balance in Management UI → Home Tab

Balance Display

• Home Tab: Shows "Current Earning: $X"
• Always Visible: Check anytime while managing
• Owner Only: Employees cannot see balance
• Accurate: Reflects all transactions

Withdraw System

How to Withdraw

1. Open Management UI → Home Tab
2. View current balance under "Total Earning"
3. Click "Withdraw Earning" button
4. Money transferred to your bank account
5. Shop balance reset to $0

Withdrawal Rules

• Owner Only: Employees cannot withdraw
• Full Amount: Always withdraws entire balance
• Bank Transfer: Goes to bank, not cash
• Instant: No delay or fees
• Minimum: Nothing happens if balance is $0

Transaction Record

• Database Update: Balance set to 0 in database
• Bank Increase: Player's bank account increases
• Notification: Confirmation with amount withdrawn
• Secure: Protected from duplications

Sale Transactions

Customer Purchase Process

1. Customer shops at your store
2. Selects items and adds to cart
3. Chooses payment method (cash/bank)
4. Completes checkout
5. Items removed from shop inventory
6. Money added to shop balance
7. Owner/employees notified

Transaction Details

• Per-Item Pricing: Each item priced individually
• Bulk Purchase: Customers can buy multiple items at once
• Payment Methods: Cash or bank transfer
• Stock Deduction: Inventory updated automatically
• Balance Increase: Your earnings grow with each sale

Failed Transactions

• Insufficient Funds: Customer notified, transaction cancelled
• Out of Stock: Can't buy if item sold out
• Owner Prevention: Owners/employees blocked from buying (if enabled)

🏠 Rent System

Rent Payment

How Rent Works

1. Initial Rent: Shop rented, first payment in 7 days
2. Weekly Cycle: Rent due every 7 days
3. Due Date: Displayed in Management UI
4. Payment: Click "Pay Rent" button in Home Tab
5. Money Source: Deducted from bank account
6. Next Due Date: Extended 7 days from current due date

Rent Payment Process

1. Open Management UI → Home Tab
2. View "Rent Information" section
3. See rent amount and due date
4. Click "Pay Rent" button
5. Bank account charged
6. Due date extended 7 days
7. Confirmation notification

Rent Status

On-Time Status

• Days Remaining: Shows "X days, Y hours, Z minutes"
• Status: "Current" or "On Time"
• Payment: Base rent amount only
• Color: Green indicator

Late Status

• Grace Period: 2 days after due date (configurable)
• Status: "LATE" or "Overdue"
• Payment: Base rent + Late Fee
• Color: Red indicator
• Warning: Shows days until eviction

Late Fees

How Late Fees Work

• Triggered: When rent paid after due date
• Amount: Configurable (default: $500)
• Added To: Base rent amount
• Example: $1000 rent + $500 late fee = $1500 total
• Purpose: Encourage timely payment

Grace Period

Grace Period Details

• Duration: 2 days by default (configurable)
• Purpose: Give players time to pay after due date
• Payment Allowed: Can pay late with late fee
• No Penalty: Shop remains active during grace period
• Warning: Shows time remaining in grace period

Auto-Eviction

When Eviction Occurs

• Trigger: Grace period expires without payment
• Automatic: System checks every 10 minutes
• No Warning: Shop deleted immediately after grace period
• Inventory Loss: All stock deleted
• Balance Loss: Remaining balance lost
• Notification: Owner notified if online

Eviction Process

1. Rent due date passes
2. Grace period begins (2 days)
3. Grace period expires
4. System auto-check runs
5. Shop deleted from database
6. All items removed
7. Employees lose access
8. Blip removed from map
9. Shop becomes available again

Preventing Eviction

• Pay Early: Pay before due date (no late fee)
• Pay During Grace: Pay within 2 days (with late fee)
• Calendar Reminders: Set personal reminders
• Check Often: Monitor due date in Management UI
• Withdraw First: Take earnings before risk of eviction

Rent Calculation

Base Rent

• Per Shop: Each shop has its own rent price
• Weekly: Always 7-day cycle
• Fixed: Doesn't change based on sales or activity

Total Rent Due

If On-Time: Total = Base Rent
If Late:    Total = Base Rent + Late Fee

Examples

• Scenario 1: $1000 rent, paid on time = $1000
• Scenario 2: $1000 rent, paid 1 day late = $1500 (with $500 late fee)
• Scenario 3: $1000 rent, not paid after grace = Shop lost

🎨 User Interface

Shop Browser UI

Features

• Modern Design: React-based responsive interface
• Grid Layout: Multiple shops visible at once
• Shop Cards: Each showing:
  • Preview image
  • Shop name
  • Location and street
  • Rent price
  • Availability status
• Interactive: Hover effects, smooth animations
• Search-Ready: Easy to scan and compare

Actions Per Shop

• Rent Button: Rent available shop
• Check Location: Mark on GPS
• Not Available: Shows if already owned
• Your Shop: Indicates if you own it

Shop Naming UI

Name Input Dialog

• Triggered: After clicking "Rent" button
• Purpose: Set custom shop name
• Features:
  • Text input field
  • Character limit (50 characters)
  • Real-time preview
  • Confirm/Cancel buttons
  • Warning about offensive language
• Validation: Must enter name to continue

Management UI

Layout

• Three-Tab Interface:
  • Home (🏠)
  • Stock Manage (📦)
  • Staff (👥)
• Side Navigation: Easy tab switching
• Responsive: Adapts to screen size
• Modern: Clean, professional design

Home Tab Components

• Earnings Card:
  • Current balance display
  • Withdraw button
  • Transaction history
• Rent Information Card:
  • Rent amount
  • Due date countdown
  • Status indicator (on-time/late)
  • Pay Rent button
  • Grace period warning (if applicable)

Stock Manage Tab Components

• Add Stock Section:
  • Description of feature
  • Usage instructions
  • Add Stock button
• Retrieve Stock Section:
  • Description of feature
  • Usage instructions
  • Retrieve Stock button

Staff Tab Components

• Hire Employee Section:
  • Feature explanation
  • Permission list
  • Hire Employee button
• Fire Employee Section:
  • Termination info
  • Employee list
  • Fire Employee button

Shopping UI (Customer View)

Features

• Product Grid: All available items displayed
• Item Cards:
  • Item image (from inventory system)
  • Item name
  • Price per unit
  • Available quantity
  • "Add to Cart" button
• Shopping Cart Panel:
  • Cart items list
  • Quantity controls
  • Total price calculation
  • Payment method selector (Cash/Bank)
  • Checkout button
  • Clear cart button

Shopping Process

1. Browse items in grid
2. Click "Add to Cart" on desired items
3. View cart in right panel
4. Select payment method
5. Click Checkout
6. Transaction processed
7. Items added to inventory

Dialogs & Modals

Add Stock Dialog

• Dropdown: Select item from inventory
• Number Input 1: Quantity to add
• Number Input 2: Price per unit
• Buttons: Confirm, Cancel

Retrieve Stock Dialog

• Dropdown: Select item from shop
• Number Input: Quantity to retrieve
• Buttons: Confirm, Cancel

Hire Employee Dialog

• Dropdown: Select nearby player
• Player Info: Shows server ID
• Buttons: Confirm, Cancel

Fire Employee Dialog

• Dropdown: Select employee
• Employee Info: Shows identifier/name
• Buttons: Confirm, Cancel

Theme Customization

Customizable Elements

• Primary Color: Main accent color
• Background Gradient: UI background overlay
• Button Hover: Button color on hover
• Button Text: Text color in buttons

Visual Effects

• Smooth Transitions: Fade in/out animations
• Hover Effects: Interactive feedback
• Loading States: Spinners during data fetch
• Notifications: Toast-style messages
• Shadows: Depth and elevation

🔌 Multi-Framework Support

Supported Frameworks

All framework integration is handled through PF_LIB (Project Finals Library).

QB-Core

• Version: 1.0+
• Compatibility: Full support
• Features:
  • QBCore.Functions integration
  • Job and gang support
  • Money management (cash/bank)
  • Player identifiers (citizenid)
  • Inventory integration
  • Notification system

ESX (ES Extended)

• Version: Legacy and New (1.9+)
• Compatibility: Full support
• Features:
  • ESX.GetPlayerFromId
  • Job system integration
  • Account management (cash/bank/black)
  • Player identifiers
  • xPlayer functions
  • Inventory integration

ND_Core

• Version: Latest
• Compatibility: Full support
• Features:
  • NDCore functions
  • Character system
  • Account management
  • Identifier system
  • Modern architecture support

vRP

• Version: Latest
• Compatibility: Full support
• Features:
  • vRP.getUserId
  • Economy integration
  • Inventory system
  • User identifiers

Mythic Framework

• Compatibility: Full support
• Features:
  • Custom framework functions
  • Economy integration
  • Player management

ox_core (Overextended Core)

• Version: Latest
• Compatibility: Full support
• Features:
  • Modern Ox functions
  • Character system
  • Account management
  • Inventory integration

Custom Frameworks

• Support: Can be added
• Method: Create custom bridge in PF_LIB
• Requirements: Implement required functions
• Contact: Support for integration help

🎯 Interaction Systems

Supported Interaction Systems

ox_target

• Type: Target system
• Developer: Overextended
• Features:
  • Eye icon interaction
  • Box zones
  • Entity targeting
  • Multi-option menus
• Best For: Modern, clean interaction

qb-target

• Type: Target system
• Developer: QB-Core
• Features:
  • Third-eye system
  • Zone-based targeting
  • Entity options
• Best For: QB-Core servers

qtarget

• Type: Target system
• Developer: Community
• Features:
  • Similar to qb-target
  • Lightweight
• Best For: QB-Core alternatives

ox_lib Text UI

• Type: Text-based
• Developer: Overextended
• Requirements: PolyZone
• Features:
  • [E] Press E to interact
  • Bottom-of-screen text
  • Modern design
• Best For: Non-target servers

qb-drawtext

• Type: Text-based
• Developer: QB-Core
• Requirements: PolyZone
• Features:
  • [E] text display
  • QB-Core integration
• Best For: QB-Core without target

finals-drawtext

• Type: Text-based
• Developer: Project Finals
• Requirements: PolyZone
• Features:
  • Custom text UI
  • Enhanced visuals
• Best For: Project Finals ecosystem

🔔 Notification Systems

Supported Notification Systems

ox_lib Notifications

• Developer: Overextended
• Style: Modern toast notifications
• Features:
  • Multiple types (success, error, info)
  • Custom duration
  • Icon support
  • Positioning options
• Appearance: Top-right corner, sleek design

okokNotify

• Developer: okok#3488
• Style: Animated notifications
• Features:
  • Phone-style alerts
  • Sound effects
  • Custom colors
  • Duration control
• Appearance: Center-right, phone-like

Framework Native

• QB-Core: QBCore.Functions.Notify
• ESX: ESX.ShowNotification
• Style: Framework's default style
• Best For: Consistency with server's existing notifications

Custom Notifications

• Support: Can be added
• Method: Configure in PF_LIB
• Requirements: Export or event-based system

Notification Types

Success ✅

• Color: Green
• Use: Positive actions completed
• Examples:
  • "Shop successfully rented!"
  • "Item(s) added to stock."
  • "Rent paid: $1000"

Error ❌

• Color: Red
• Use: Actions failed or prevented
• Examples:
  • "Not enough money."
  • "Item out of stock."
  • "Shop not found"

Info ℹ️

• Color: Blue
• Use: Information messages
• Examples:
  • "You were hired as shop staff."
  • "Nearby players found!"

🗺️ Map & Navigation

Shop Blips

Dynamic Blips

• Only Owned Shops: Only shops with owners show blips
• Custom Names: Shows owner's custom shop name
• Color-Coded: Configurable color (default: green)
• Icon: Shop/store icon
• Short Range: Only visible when somewhat nearby

Blip Features

• Auto-Created: Appears when shop is rented
• Auto-Removed: Removed when lease ends
• Name Update: Updates if owner changes name
• Real-time: All players see current shop names

Shop Manager Blip

Rental NPC Blip

• Always Visible: Shows rental NPC location
• Distinct Icon: Different from shop blips
• Configurable:
  • Can be enabled/disabled
  • Custom sprite
  • Custom color
  • Custom size
  • Custom name
• Purpose: Help players find where to rent shops

GPS Waypoint System

Check Location Feature

• In-Browser: Click "Check Location" on any shop
• Sets Waypoint: Yellow route appears on map/GPS
• Distance Visible: Shows distance to shop
• Navigation: Full GPS navigation to location
• No TP: Players must drive/walk there

🔒 Security Features

Owner Prevention System

Purpose

Prevent shop owners/employees from exploiting their own shop by buying items at set prices and retrieving them.

How It Works

• Enabled by Default: Config.OwnerPrevention = true
• Checks: Every purchase checks if buyer is owner/employee
• Block: If detected, transaction cancelled
• Message: "You cannot buy items from your own shop. Use 'Retrieve Stock' instead."
• Alternative: Use Retrieve Stock (free)

Database Security

SQL Injection Protection

• Parameterized Queries: All queries use placeholders
• No String Concatenation: No direct SQL string building
• OxMySQL: Secure database library
• Validation: Input validated before queries

Transaction Safety

• Atomic Transactions: Multi-step operations use transactions
• Rollback: Failed transactions rolled back
• Consistency: Database always in valid state

Inventory Protection

Duplication Prevention

• Immediate Removal: Items removed before DB insert
• Transaction Order: Inventory → Database → Confirm
• Failure Handling: Items returned if DB insert fails
• Stock Checks: Always verify stock before sale

Money Protection

Balance Security

• Database-Stored: Money in database, not client
• Server-Side: All money operations server-side
• Validation: Check player has money before deduction
• Audit Trail: Can track all transactions in DB

Access Control

Permission Layers

1. Owner: Full access to shop functions
2. Employee: Stock management only
3. Customer: Purchase only
4. Public: Browse only

Zone Protection

• Management Zone: Only owner/employees
• Customer Counter: All players
• Server Validation: All actions validated server-side

👨‍💼 Administrative Features

Database Management

Tables

• player_shops: Shop ownership data
• player_shop_items: Inventory items
• player_shop_employees: Employee relationships

Foreign Keys

• CASCADE DELETE: Deleting shop removes items and employees
• Data Integrity: Enforced relationships
• Clean Deletion: No orphaned records

Auto-Maintenance

Rent Expiry Check

• Frequency: Every 10 minutes
• Checks: All shops past grace period
• Action: Auto-delete expired shops
• Cleanup: Removes inventory and employees
• Notification: Owner notified if online

Debug Features

Debug Mode

• Enable: Config.Debug = true
• Shows: Visual PolyZone boxes
• Color: Red wireframe
• Use: Position zones, troubleshoot interactions
• Production: Always disable (performance impact)

Export Functions

Server-Side Exports

-- Check shop ownership
local shop = MySQL.single.await('SELECT * FROM player_shops WHERE shop_index = ?', {index})

-- Add money to shop
MySQL.update('UPDATE player_shops SET balance = balance + ? WHERE shop_index = ?', {amount, index})

Client-Side Exports

-- Force refresh blips
TriggerEvent('poshop:client:forceRefreshBlips', -1)

-- Open manage menu
exports['finals_posv1']:OpenManageMenu(shopIndex)

🎮 Player Features Summary

For Shop Owners

✅ Can Do:

• Rent up to X shops (configurable)
• Set custom shop names
• Add stock with custom pricing
• Retrieve stock back
• Withdraw earnings
• Pay rent
• Hire employees
• Fire employees
• View rent status
• End lease
• Manage inventory

✅ Benefits:

• Passive income from sales
• Flexible pricing
• Employee help
• Real-time sale notifications
• GPS navigation to shops
• Custom branding

For Employees

✅ Can Do:

• Add stock to shop
• Retrieve stock from shop
• View shop inventory
• Help manage stock

✅ Benefits:

• Job opportunity
• Trust building
• Sale notifications
• Learn shop management

For Customers

✅ Can Do:

• Browse all owned shops
• View available items
• Check prices
• Add items to cart
• Buy multiple items at once
• Choose payment method (cash/bank)
• See item quantities

✅ Benefits:

• Player-driven economy
• Custom prices (potentially cheaper)
• Variety of shops
• Convenient locations

📊 Feature Comparison

vs NPC Shops

vs Other Shop Scripts

🎯 Use Cases

Roleplay Scenarios

Business Roleplay

• Start small shop business
• Grow to multiple locations
• Hire employees (org members)
• Compete with other shops
• Price wars and marketing

Gang/Org Operations

• Front business for operations
• Employee = gang members
• Sell specific items
• Control territory via shops

New Player Support

• Starter businesses for new players
• Low-cost entry shops
• Learn economy system
• Build wealth

Economy Events

• Shop competition events
• Price undercutting wars
• Supply chain roleplay
• Economic cycles

📈 Statistics & Performance

Performance Metrics

• Player Count: Tested up to 200+ players
• Shop Count: Optimal at 19-30 shops
• Database: Lightweight queries
• UI Load Time: < 1 second
• FPS Impact: Minimal (< 1 FPS)
• Network: Efficient event usage

Scalability

• More Shops: Easy to add via config
• More Players: No hard limits
• More Items: Inventory system dependent
• Custom Locations: Unlimited potential

🔮 Future Feature Ideas

Potential Additions

• Shop upgrades (larger inventory, employees)
• Shop decorations
• Shop statistics (sales graphs)
• Employee salaries
• Profit sharing
• Shop franchise system
• Delivery system
• Online ordering
• Shop reputation system

Note: These are ideas, not confirmed features.

💡 Tips & Best Practices

For Shop Owners

1. Price Competitively: Check other shops' prices
2. Stock Variety: Offer many different items
3. Stay Current: Pay rent on time
4. Trust Employees: Only hire trustworthy players
5. Check Sales: Monitor earnings regularly
6. Good Location: Choose accessible shops
7. Withdraw Often: Don't leave money in shop
8. Plan Ahead: Keep rent money reserved

For Server Owners

1. Balance Rent: Match your economy
2. Reasonable Limits: 2-3 shops max per player
3. Blacklist Wisely: Only restrict necessary items
4. Theme Match: Customize colors to server brand
5. Good NPC Location: Visible, accessible area
6. Test Thoroughly: Test all features before launch
7. Monitor Prices: Check for price exploits
8. Regular Backups: Backup database regularly