Installation Advanced Detailed

Installation Advanced Detailed

This guide covers advanced installation steps, database configuration, and optimization settings for the Buy ATM System.

---

1️⃣ Database Configuration

MySQL Setup

Connection Configuration

Ensure your oxmysql is properly configured. The script uses MySQL queries with prepared statements for security.

oxmysql Configuration:

-- In your oxmysql configuration
mysql_connection_string = "mysql://user:password@localhost:3306/database_name"

Table Structure

The script creates the following tables:

owned_atms - Main ATM data table

- id (INT, AUTO_INCREMENT, PRIMARY KEY)
- owner (VARCHAR(50), NULLABLE) - Player identifier
- location (VARCHAR(100)) - Location category
- coords (VARCHAR(255), UNIQUE) - Coordinate string
- price (INT) - Purchase price
- tax (DECIMAL(10,2)) - Tax percentage
- revenue (DECIMAL(10,2)) - Current revenue balance
- due_rent (DECIMAL(10,2)) - Rent amount
- rent_expires (DATETIME, NULLABLE) - Rent expiration date
- last_rent_payment (DATETIME, NULLABLE) - Last payment date
- utilization (VARCHAR(255)) - Display text
- visitor_count (INT) - Visitor tracking
- created_at (TIMESTAMP) - Creation timestamp
- updated_at (TIMESTAMP) - Last update timestamp

atm_transactions - Transaction history

- id (INT, AUTO_INCREMENT, PRIMARY KEY)
- atm_id (INT, FOREIGN KEY) - References owned_atms.id
- type (VARCHAR(50)) - Transaction type (deposit, withdraw, Buy, Extract)
- amount (DECIMAL(10,2)) - Transaction amount
- tax_amount (DECIMAL(10,2)) - Tax collected
- timestamp (TIMESTAMP) - Transaction time

atm_employees - Employee management

- id (INT, AUTO_INCREMENT, PRIMARY KEY)
- atm_id (INT, FOREIGN KEY) - References owned_atms.id
- employee_identifier (VARCHAR(60)) - Player identifier
- date_hired (DATETIME) - Hire date
- permissions (LONGTEXT) - JSON permissions object

atm_admin_logs - Audit trail

- id (INT, AUTO_INCREMENT, PRIMARY KEY)
- atm_id (INT) - ATM ID
- admin_id (VARCHAR(50)) - Admin/owner identifier
- action_type (VARCHAR(30)) - Action type
- details (TEXT) - Action details
- timestamp (TIMESTAMP) - Action time

Database Indexes

The SQL file automatically creates indexes for optimal performance:

• Primary Keys: All tables have auto-incrementing primary keys

• Foreign Keys: Proper relationships with CASCADE delete

• Unique Constraints: coords field in owned_atms prevents duplicates

• Indexes: Employee identifier and ATM ID indexes for fast lookups

Database Maintenance

Auto-Reclaim System

The script automatically reclaims expired ATMs:

• Expiry Check: Runs every 10 minutes

• Reclaim Threshold: 10 days after rent expiration

• Auto-Cleanup: Sets owner to NULL and resets rent fields

Manual Database Queries

Check ATM Ownership:

SELECT id, owner, location, price, tax, revenue, rent_expires 
FROM owned_atms 
WHERE owner IS NOT NULL;

View Transaction History:

SELECT t.*, a.location, a.coords 
FROM atm_transactions t 
JOIN owned_atms a ON t.atm_id = a.id 
ORDER BY t.timestamp DESC 
LIMIT 50;

Check Employee Permissions:

SELECT e.*, a.location, a.coords 
FROM atm_employees e 
JOIN owned_atms a ON e.atm_id = a.id 
WHERE e.employee_identifier = 'identifier_here';

---

2️⃣ Advanced Configuration

Performance Tuning

Coordinate Streaming Optimization

The script uses chunked streaming to prevent network overflow. You can adjust chunk sizes in server/main.lua:

-- In sendATMCoordsChunked function
local CHUNK = 200  -- Default chunk size
if TOTAL > 2000 then CHUNK = 100 end
if TOTAL > 4000 then CHUNK = 75 end

Recommendations:

• Small Servers (< 100 ATMs): Keep default (200)

• Medium Servers (100-500 ATMs): Reduce to 150

• Large Servers (500+ ATMs): Reduce to 100 or 75

Proximity Detection Tuning

Adjust detection radius based on server performance:

Config.ProximityRadius = 1.0  -- Meters

Performance Impact:

• Lower values (0.5-1.0): More precise, less CPU usage

• Higher values (1.5-2.0): Easier detection, more CPU usage

Auto-Detection Settings

Config.AutoDetectBankDelta = true  -- Enable automatic tax detection

When to Disable:

• If you have custom banking scripts that conflict

• If you want manual transaction processing only

• If experiencing performance issues

Network Optimization

Throttling Configuration

The script includes built-in throttling to prevent spam:

-- In server/main.lua
local __coordsPushMinInterval = 5000  -- 5 seconds minimum between pushes

Adjustment:

• Increase for slower networks or more players

• Decrease for faster networks (not recommended)

Queue System

The coordinate request queue prevents server overload:

-- Automatic queue processing
-- Processes one request at a time with delays

Queue Behavior:

• Maximum 1 request per player at a time

• Automatic processing with delays

• Prevents reliable overflow errors

---

3️⃣ Framework-Specific Setup

QBCore Configuration

Player Data Structure

The script expects standard QBCore player structure:

-- Player identifier format
identifier = "license:xxxxx"  -- Standard QBCore format

Bank/Cash Functions

The script uses ic3d_lib abstraction, but QBCore functions are:

-- Bank operations
Player.Functions.AddMoney('bank', amount)
Player.Functions.RemoveMoney('bank', amount)
Player.PlayerData.money.bank

-- Cash operations
Player.Functions.AddMoney('cash', amount)
Player.Functions.RemoveMoney('cash', amount)
Player.PlayerData.money.cash

ESX Configuration

Player Data Structure

ESX uses different identifier format:

-- Player identifier format
identifier = "steam:xxxxx" or "license:xxxxx"

Bank/Cash Functions

ESX uses different money system:

-- Bank operations
xPlayer.addAccountMoney('bank', amount)
xPlayer.removeAccountMoney('bank', amount)
xPlayer.getAccount('bank').money

-- Cash operations
xPlayer.addMoney(amount)
xPlayer.removeMoney(amount)
xPlayer.getMoney()

Qbox Configuration

Qbox uses similar structure to QBCore:

-- Player identifier format
identifier = "license:xxxxx"

---

4️⃣ ATM Scanning System

Live Scanning Command

The script includes a built-in ATM scanner:

/scanatms_live [radius] [interval]

Parameters:

• radius (optional): Scan radius in meters (default: 50.0)

• interval (optional): Scan interval in milliseconds (default: 200)

Usage:

1. Run /scanatms_live to start scanning

2. Fly around the map to discover ATMs

3. Run /scanatms_live again to stop

4. Run /importatms to import scanned ATMs

Scan Detection

The scanner detects these ATM models:

- prop_atm_01
- prop_atm_02
- prop_atm_03
- prop_fleeca_atm
- prop_atm_01_dam

Import Process

Bulk Import:

• Imports in chunks of 100 ATMs

• Prevents database overload

• Shows progress in console

Default Settings:

• Price: $10,000

• Tax: 10%

• Location: Auto-categorized by coordinates

• Rent: $0 (no rent for unowned ATMs)

---

5️⃣ Localization Setup

Adding New Languages

1. Copy Locale File:

   cp locales/en.lua locales/your_language.lua

2. Update Locale Code:

   Locales['your_language'] = {
       -- Translate all strings
   }

3. Update Config:

   Config.Locale = "your_language"

4. Update Loader: Add your language to locales/loader.lua if needed

Locale Structure

All UI strings are in the locale file:

Locales['en'] = {
    ['header_title'] = 'MANAGEMENT YOUR OWN ATM',
    ['atm_buy'] = 'Buy',
    ['atm_manage'] = 'Manage',
    -- ... more strings
}

NUI Locale Loading

The UI automatically loads locale strings:

// In web/script.js
loadLocaleStrings()  // Fetches from server
_L('key')  // Gets translated string

---

6️⃣ Security Configuration

Permission Validation

All server callbacks validate permissions:

-- Example from server code
local isOwner = (atm.owner == playerIdentifier)
local hasPermission = checkEmployeePermission(playerIdentifier, atmId, 'withdraw')

Input Sanitization

The script sanitizes all inputs:

• Server ID: Normalized and validated

• Tax Rates: Bounded by level limits (0-39%)

• Amounts: Positive numbers only

• Coordinates: Validated format

Audit Logging

All sensitive actions are logged:

LogATMAction(atmId, playerId, "action_type", "details")

Logged Actions:

• Ownership changes

• Employee additions/removals

• Tax rate changes

• Revenue withdrawals

• Permission modifications

---

7️⃣ Customization

UI Customization

Modify Styles:

• Edit web/style.css for visual changes

• Modify web/ATM.html for structure changes

• Update web/script.js for behavior changes

Map Offsets: Adjust map pin positions in web/script.js:

const MAP_OFFSETS_MAIN = {
    offsetXPercent: -1,
    offsetYPercent: -27.0,
    scaleX: 300
};

NPC Customization

Change NPC Model:

Config.ATMNpc.Model = "s_m_m_bankman"  -- Any valid ped model

Change NPC Location:

Config.ATMNpc.Coords = vector3(x, y, z)  -- Your coordinates
Config.ATMNpc.Heading = 180.0  -- NPC facing direction

Blip Customization

ATM Blips:

Config.ATMBlip = {
    Sprite = 277,  -- Change blip icon
    Color = 2,     -- Change blip color
    Scale = 0.6    -- Change blip size
}

Blip Colors:

• 0 = White

• 1 = Red

• 2 = Green

• 3 = Blue

• ... (see FiveM blip color reference)

---

8️⃣ Troubleshooting Advanced Issues

Database Connection Issues

Symptoms:

• Script fails to start

• No ATMs loading

• Transaction errors

Solutions:

1. Verify oxmysql is running

2. Check database credentials

3. Verify database exists

4. Check MySQL server is running

5. Review oxmysql logs

Performance Issues

Symptoms:

• Server lag when loading ATMs

• High resmon usage

• Network overflow errors

Solutions:

1. Reduce Config.ProximityRadius

2. Increase chunk intervals

3. Disable Config.AutoDetectBankDelta if not needed

4. Optimize database queries (add indexes)

5. Reduce total ATM count

Coordinate Sync Issues

Symptoms:

• ATMs not showing on map

• Blips not appearing

• "Error fetching coordinates" messages

Solutions:

1. Wait for chunked sync to complete (1-2 seconds after restart)

2. Run /toggleatmblips to refresh

3. Check network connectivity

4. Verify chunked streaming is enabled

5. Check server console for errors

---

9️⃣ Backup & Migration

Database Backup

Export Tables:

-- Export all ATM data
mysqldump -u user -p database_name owned_atms atm_transactions atm_employees atm_admin_logs > backup.sql

Migration Between Servers

1. Export Data:

   SELECT * FROM owned_atms;
   SELECT * FROM atm_transactions;
   SELECT * FROM atm_employees;

2. Import to New Server:

   -- Run atm.sql first
   -- Then import your data

3. Update Coordinates: If server coordinates differ, update coords field

Version Updates

Before Updating:

1. Backup database

2. Backup config.lua

3. Note any custom modifications

After Updating:

1. Compare new config.lua with your backup

2. Merge custom settings

3. Run any new SQL migrations

4. Test functionality

---

🔟 Advanced Features

Custom Transaction Processing

You can manually trigger transaction processing:

-- Client-side
ProcessATMTransaction(atmId, amount, transactionType, sourceAccount)

Parameters:

• atmId: ATM ID number

• amount: Transaction amount

• transactionType: "deposit" or "withdraw"

• sourceAccount: "bank" or "cash" (optional)

Level System Integration

The level system calculates XP from:

• ATM ownership (250 XP per ATM)

• Transaction volume (150 XP per $25,000)

• Revenue generated (40 XP per $2,000)

Custom Integration:

-- Server-side callback
lib.callback.register("atm:getPlayerLevel", function(source)
    -- Returns level, progress, XP data
end)

Employee Permission System

Permission Structure:

{
    "manage": true,
    "withdraw": true,
    "manage_tax": false,
    "view_logs": true,
    "employees": false
}

Custom Permissions: You can extend the permission system by modifying the UI and server validation.

---

For more information, see the Configuration Guide and Troubleshooting pages.