Installation

🔧 Installation Guide - Finals POS v1

Complete step-by-step installation guide for the Finals POS v1 Player-Owned Shop System.

📋 Pre-Installation Checklist

Before you begin, ensure you have:

A working FiveM server (latest artifact recommended)
Database access (MySQL/MariaDB)
Basic knowledge of server configuration
FTP/File access to your server resources folder
Server stopped or in maintenance mode (recommended)

📦 Required Dependencies

Mandatory Dependencies

These MUST be installed before Finals POS v1:

1. ox_lib (Required)

Download: https://github.com/overextended/ox\_lib
Version: Latest release recommended

Installation:

Shell

cd resources
git clone https://github.com/overextended/ox_lib.git

2. oxmysql (Required)

Purpose: Database queries and connection
Download: https://github.com/overextended/oxmysql
Version: Latest release recommended

Installation:

Shell

cd resources
git clone https://github.com/overextended/oxmysql.git

Configuration: Set your database credentials in server.cfg:

Config

set mysql_connection_string "mysql://username:password@localhost/database?charset=utf8mb4"

3. pf_lib (Required)

Purpose: Universal framework bridge
Source: Provided with your purchase or from framework provider
Installation:
1. Extract pf_lib folder to resources
2. Configure framework settings (see PF_LIB Configuration section)

Optional Dependencies

4. PolyZone (Conditional)

Purpose: Interaction zones for text-based systems
Download: https://github.com/mkafrin/PolyZone
Required If: Using ox_lib text UI, qb-drawtext, or finals-drawtext
Not Required If: Using only target systems (ox_target, qb-target, qtarget)

Installation:

Shell

cd resources
git clone https://github.com/mkafrin/PolyZone.git

🚀 Installation Steps

Step 1: Download & Extract

Download the Finals POS v1 package from your purchase source
Extract the ZIP file to a temporary location

Verify the folder structure:

Plain text

finals_posv1/
├── client/
│   ├── client.lua (escrowed)
├── server/
│   └── server.lua (escrowed)
├── lang/
│   ├── en.lua
│   ├── fr.lua
│   └── ar.lua
├── web/
│   ├── assets/
│   │   ├── *.js
│   │   ├── *.css
│   │   └── *.png
│   └── index.html
├── config.lua
├── fxmanifest.lua
├── data.sql
└── documentation.md

Copy the entire finals_posv1 folder to your server's resources directory
Plain text
```
YourServer/
└── resources/
    └── finals_posv1/  ← Place here
```

Step 2: Database Setup

You have two options for database setup:

Option A: Automatic Setup (Recommended)

The script will automatically create tables on first start.

Just start the script (Step 5)
Check server console for success messages:
Plain text
```
[pf_lib] Database tables initialized successfully!
```

Option B: Manual Import

If automatic setup fails or you prefer manual control:

Open your database management tool (phpMyAdmin, HeidiSQL, etc.)
Select your server's database
Import the data.sql file:
- Click "Import" or "Execute SQL"
- Select finals_posv1/data.sql
- Execute the SQL
Verify tables were created:
- player_shops
- player_shop_items
- player_shop_employees

Verify Database Connection

Test oxmysql connection:

Config

# In server.cfg (if not already present)
set mysql_connection_string "mysql://username:password@localhost:3306/database?charset=utf8mb4"
set mysql_debug true  # Enable for testing, disable in production

Step 3: Configure PF_LIB (Framework Bridge)

IMPORTANT: PF_LIB must be configured before Finals POS v1 will work.

Navigate to pf_lib/config.lua (or pf_lib/shared/config.lua)

Set your framework:

Lua

Config.Framework = 'qb-core'  -- Options: 'qb-core', 'esx', 'nd_core', 'vrp', 'mythic', 'ox_core'

Set your inventory system:

Lua

Config.Inventory = 'ox_inventory'  -- Options: 'ox_inventory', 'qb-inventory', 'qs-inventory', 'ps-inventory'

Set your notification system:

Lua

Config.Notification = 'ox_lib'  -- Options: 'ox_lib', 'okokNotify', 'framework', 'custom'

Set your interaction system:

Lua

Config.Interaction = 'ox_target'  -- Options: 'ox_target', 'qb-target', 'qtarget', 'ox_lib', 'qb-drawtext', 'finals-drawtext'

Example Configurations:

For QB-Core Servers:

Lua

Config.Framework = 'qb-core'
Config.Inventory = 'qb-inventory'
Config.Notification = 'ox_lib'  -- or 'framework'
Config.Interaction = 'qb-target'  -- or 'ox_target'

For ESX Servers:

Lua

Config.Framework = 'esx'
Config.Inventory = 'ox_inventory'
Config.Notification = 'ox_lib'
Config.Interaction = 'ox_target'

For Standalone/Custom:

Lua

Config.Framework = 'custom'
Config.Inventory = 'ox_inventory'
Config.Notification = 'ox_lib'
Config.Interaction = 'ox_target'

Step 4: Configure Finals POS v1

Open finals_posv1/config.lua

Basic Settings (minimum required):

Lua

Config.MaxShopsPerPlayer = 2  -- How many shops one player can own
Config.Lang = 'en'  -- Language: 'en', 'fr', 'ar'

Rent Settings (adjust for your economy):

Lua

Config.WeeklyRent = 1000  -- Base rent amount
Config.LateFee = 500  -- Late payment fee
Config.GraceDays = 2  -- Days before eviction

Seller NPC Location (where players rent shops):
Lua
```
Config.Npc = vec4(-545.3527, -203.8803, 38.2151, 211.4138)
```
To get custom coordinates:
- Stand at desired location in-game
- Use /getcoords or similar command
- Replace with your coordinates

(Optional) Customize Theme Colors:

Lua

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

Save the file

For detailed configuration options, see configuration.md

Step 5: Update server.cfg

Critical: Load order matters! Dependencies must load first.

Open your server.cfg file

Add dependencies in this exact order:

Config

# ========================================
# DEPENDENCIES FOR FINALS POS V1
# ========================================

# Core Libraries (Required)
ensure ox_lib
ensure oxmysql

# Framework Bridge (Required)
ensure pf_lib

# Interaction Zones (Optional - only if using text-based interactions)
ensure PolyZone

# Target Systems (Optional - only if using target)
# ensure ox_target
# or
# ensure qb-target

# ========================================
# FINALS POS V1 - PLAYER OWNED SHOPS
# ========================================
ensure finals_posv1

Position Check: Make sure Finals POS v1 is loaded AFTER:
- Your framework (QBCore, ESX, etc.)
- ox_lib
- oxmysql
- pf_lib
- Interaction/target systems
Save the file

Step 6: Start the Server

Start or restart your server
Watch the console for these messages:

✅ Success Messages:
Plain text
```
[ox_lib] Successfully loaded
[oxmysql] Database connection established
[PF_LIB] Framework detected: qb-core
[PF_LIB] Successfully initialized with PF_LIB
[PF_LIB] Database tables initialized successfully!
[PF_LIB] Creating manage zones...
[PF_LIB] Client script loaded successfully!
[PF_LIB] Server script loaded successfully!
```
❌ Error Messages (and solutions):
- "PF_LIB is required but not found!"
  - Solution: Ensure pf_lib is in resources and started before finals_posv1
- "Failed to get PF_LIB bridges!"
  - Solution: Check PF_LIB configuration, ensure framework is correctly set
- "Database connection failed"
  - Solution: Check mysql_connection_string in server.cfg
- "Resource not found: PolyZone"
  - Solution: Install PolyZone if using text-based interactions, or ignore if using target only

Step 7: In-Game Testing

Join your server
Check for the Shop Manager blip on the map (default location: Legion Square area)
Go to the Shop Manager NPC location
Test interaction:
- Target systems: Look at NPC, target option should appear
- Text systems: Get close to NPC, press E when prompted
Open the shop browser UI
- Should show 19 available shop locations
- Verify images load properly
- Test "Check Location" to mark GPS
Test renting a shop (optional, costs in-game money):
- Click "Rent" on any available shop
- Enter a shop name
- Confirm purchase
- Check your bank balance decreased
- Verify blip appears for your shop
Test management (if you rented):
- Go to the management zone (different from customer counter)
- Interact to open management UI
- Verify all tabs load: Home, Stock Manage, Staff

🔍 Post-Installation Verification

Checklist

Testing Commands

Lua

-- Check if resource is running
/ensure finals_posv1

-- Restart if needed
/restart finals_posv1

-- Check database
-- In MySQL: SELECT * FROM player_shops;

🛠️ Troubleshooting Installation

Issue: Script won't start

Symptoms: Resource shows as "failed to start" in console

Solutions:

Check for syntax errors in config.lua
Ensure all dependencies are started first
Check file permissions (Linux servers)
Verify fxmanifest.lua is not corrupted
Check for duplicate resource names

Issue: NPC doesn't spawn

Symptoms: Can't find Shop Manager NPC, no blip on map

Solutions:

Check Config.Npc coordinates are valid
Verify Config.SellerBlip.Enabled = true
Wait 30 seconds after join (NPC spawns with delay)
Check ped model exists: Config.SellerPed = 'cs_bankman'
Restart resource: /restart finals_posv1

Issue: Can't interact with NPC

Symptoms: No target option or text UI appears

Solutions:

For Target Systems:
- Ensure ox_target or qb-target is running
- Check PF_LIB interaction config
- Look directly at the NPC
- Try /restart finals_posv1
For Text Systems:
- Ensure PolyZone is running
- Get very close to NPC (within 2-3 meters)
- Check Config.InteractionDistance
- Press E when prompted

Issue: UI doesn't open

Symptoms: Interaction works but no UI appears

Solutions:

Check F8 console for JavaScript errors
Verify web/assets/ folder has all files
Clear FiveM cache:
- Close FiveM completely
- Go to %localappdata%\FiveM\FiveM.app\data\cache
- Delete cache folder
- Restart FiveM
Update ox_lib to latest version
Check NUI focus: /restart finals_posv1

Issue: Database errors

Symptoms: SQL errors in console

Solutions:

Verify oxmysql is running: /ensure oxmysql
Check mysql_connection_string in server.cfg
Test database connection with another script
Manually import data.sql
Check MySQL user has CREATE TABLE permissions
Ensure database charset is utf8mb4

Issue: Framework not detected

Symptoms: "Framework not detected" or "PF_LIB failed to initialize"

Solutions:

Check PF_LIB Config.Framework setting
Ensure your framework is started before pf_lib
Verify framework name is correct ('qb-core' not 'qbcore')
Check framework resource name matches expected name
Contact support if using custom framework

📊 Installation Summary

Step	Task	Time Required
1	Download & Extract	2 minutes
2	Database Setup	3 minutes
3	Configure PF_LIB	5 minutes
4	Configure Finals POS	5 minutes
5	Update server.cfg	3 minutes
6	Start Server	2 minutes
7	In-Game Testing	10 minutes
Total	Complete Installation	~30 minutes

🔄 Updating from Previous Version

If you're updating from an older version:

Backup your current files:
- config.lua (your settings)
- lang/*.lua (if you modified translations)
- Database: Export player_shops, player_shop_items, player_shop_employees tables
Stop the resource:
Plain text
```
/stop finals_posv1
```
Replace files:
- Delete old finals_posv1 folder
- Extract new version
- Copy your old config.lua settings to the new config.lua
Check for new config options in the new config.lua
Update database (if SQL changes are mentioned in changelog):
- Run any provided update.sql files
- Or let the script auto-update tables
Restart the resource:
Plain text
```
/ensure finals_posv1
```
Test thoroughly on development server first

✅ Installation Complete!

You're all set! Your Finals POS v1 system is now installed and ready to use.

Next Steps:

Read configuration.md to customize the script
Read features.md to learn about all features
Test all functionality on a development server
Configure shops, rent prices, and theme to match your server
Announce the new feature to your players

Need Help?

Check documentation.md for detailed info
Join our Discord support server
Open a support ticket
Check community forums

Installation Guide Version: 2.2.0

Last Updated: 2025

Difficulty: ⭐⭐ Moderate (requires basic server knowledge)

Thank you for choosing Finals POS v1!