How It Works

How It Works

---

System Architecture

The GOD - ATM Owner system operates through a client-server architecture that ensures synchronized ATM data, transaction processing, and real-time updates across all players.

---

Core Mechanics

1. ATM Ownership System

Purchase Flow

When a player purchases an ATM:

1. Validation: System checks if ATM is available and player has sufficient funds

2. Ownership Limit Check: Verifies player hasn't exceeded Config.MaxATMsPerPlayer

3. Payment Processing: Deducts payment from cash or bank (based on selection)

4. Database Update: Sets owner, initializes rent period (15 days), updates utilization text

5. Transaction Log: Creates purchase transaction record

6. Client Sync: All clients receive updated ATM list

Rent System

• Initial Period: 15 days from purchase date

• Payment Method: Bank account only

• Auto-Expiry: If rent expires, ATM becomes available after 10 days

• Rent Payment: Extends ownership by another 15 days

• Cancellation: Owner can cancel rental, making ATM available immediately

2. Tax Collection System

Automatic Detection

The system uses proximity-based detection to automatically tax transactions:

Detection Process:

1. Proximity Check: Player must be within Config.ProximityRadius (default: 1.0m) of an ATM

2. Balance Monitoring: System continuously monitors bank and cash balance changes

3. Delta Calculation: Detects when bank balance decreases and cash increases (withdraw) or vice versa (deposit)

4. Transaction Type Detection: Identifies withdraw vs deposit based on balance deltas

5. Tax Calculation: Applies configured tax rate to transaction amount

6. Tax Payment: Deducts tax from appropriate source (cash for withdraw, bank for deposit)

7. Revenue Update: Adds tax amount to ATM revenue

Tax Payment Logic:

• Withdraw (bank → cash): Tax paid from cash

• Deposit (cash → bank): Tax paid from bank

Manual Transaction Processing

The system also supports manual transaction logging via ProcessATMTransaction() function for custom integrations.

3. Level & XP System

XP Calculation

Player XP is calculated based on:

• ATM Ownership: 250 XP per owned ATM

• Transaction Volume: 150 XP per $25,000 in transaction volume

• Revenue Generated: 40 XP per $2,000 in total revenue

Level Thresholds

Level 1:  0 XP        (Tax Range: 0-10%)
Level 2:  500 XP      (Tax Range: 0-20%)
Level 3:  1,500 XP    (Tax Range: 0-30%)
Level 4:  4,000 XP    (Tax Range: 0-35%)
Level 5:  8,000 XP    (Tax Range: 0-39%)
Level 6:  13,000 XP   (Tax Range: 0-39%)
...continues up to Level 15+

Tax Rate Limits

Tax rates are restricted based on owner level:

• Level 1: 0-10%

• Level 2: 0-20%

• Level 3: 0-30%

• Level 4: 0-35%

• Level 5+: 0-39%

4. Employee Management

Hiring Process

1. Owner/Manager Action: Owner or employee with manage permission initiates hire

2. Server ID Input: Player enters target player's server ID

3. Validation: System verifies player is online and not already an employee

4. Permission Setup: Initial permissions can be set during hire

5. Database Insert: Creates employee record with permissions JSON

6. Logging: Admin log entry created for audit trail

Permission System

Employees can have the following permissions:

• manage: Can access management UI and add/remove employees

• withdraw: Can withdraw revenue from ATM

• manage_tax: Can change tax rate (if Config.AllowTaxChangeByManagers = true)

• view_logs: Can view transaction and admin logs

• employees: Can manage employee list (subset of manage)

Permission Hierarchy

• Owner: Full access to all features

• Manager (manage = true): Can manage employees and settings

• Employee (specific permissions): Limited access based on granted permissions

5. Revenue System

Revenue Accumulation

• Tax amounts from transactions are automatically added to revenue field

• Revenue is stored per ATM in the database

• All-time revenue is calculated from transaction history

Revenue Statistics

The system tracks:

• Current Revenue: Available balance in ATM

• All-Time Revenue: Total revenue from all transactions

• Last Week Revenue: Revenue from past 7 days

• Daily Revenue: Revenue breakdown by day (14-day history)

• Recent Transactions: Last 20 transactions with details

Revenue Withdrawal

• Owner or employee with withdraw permission can withdraw revenue

• Withdrawal can be to cash or bank account

• Transaction is logged in database

• Revenue balance is decremented

6. Coordinate Synchronization

Chunked Streaming

To prevent network overflow, ATM coordinates are sent in chunks:

Server-Side Process:

1. Request Queue: Player requests trigger queue system

2. Chunk Size: Dynamic based on total ATM count (75-200 per chunk)

3. Latent Events: Uses TriggerLatentClientEvent for efficient transmission

4. Completion Signal: Final event signals completion

Client-Side Process:

1. Buffer Accumulation: Client accumulates chunks in buffer

2. Vector Parsing: Coordinates parsed into vector3 format

3. Cache Update: Updates proximity detection cache

4. Blip Creation: Creates map blips if enabled

7. ATM Manager NPC

NPC Features

• Spawn Location: Configurable via Config.ATMNpc.Coords

• Interaction: Press E near NPC to open management UI

• Blip: Optional map blip showing NPC location

• Text UI: ox_lib text UI shows interaction prompt

NPC Configuration

Config.ATMNpc = {
    Enabled = true,
    Model = "cs_bankman",
    Coords = vector3(-1381.12, -499.61, 32.16),
    Heading = 193.62,
    InteractionDistance = 2.0,
    TextUI = "[E] Manage ATMs"
}

8. Database Structure

Core Tables

• owned_atms: Main ATM data (owner, location, coords, tax, revenue, rent)

• atm_transactions: Transaction history (type, amount, tax_amount, timestamp)

• atm_employees: Employee records (permissions, hire date)

• atm_admin_logs: Audit trail for all admin actions

Data Relationships

• ATMs have one owner (nullable)

• ATMs can have multiple employees

• Transactions belong to one ATM

• Admin logs track all ownership changes

9. Framework Integration

QBCore / Qbox

• Uses qb-core exports for framework object

• iLib.framework.getIdentifier() for player identifiers

• iLib.framework.getBank() / getCash() for balances

• iLib.framework.removeBank() / removeCash() for payments

• iLib.framework.addBank() / addCash() for deposits

ESX

• Uses es_extended exports for framework object

• Same abstraction layer via ic3d_lib

• Automatic detection of framework type

10. UI System

NUI Architecture

• HTML/CSS/JavaScript: Modern web-based interface

• Real-Time Updates: WebSocket-like communication via NUI callbacks

• State Management: Client-side state with server synchronization

• Responsive Design: Works on all screen resolutions

UI Features

• ATM List: Filterable, searchable list of all ATMs

• Management Panel: Multi-tab interface (Permissions, Revenues, Employees, Settings)

• Interactive Map: Click to view ATM location

• Charts: Revenue visualization with daily/weekly data

• Permission Editor: Toggle permissions for employees

• Transaction Logs: Filterable transaction history

---

Performance Optimization

Network Optimization

• Chunked Streaming: Prevents reliable overflow on large ATM counts

• Queue System: Throttles coordinate requests to prevent spam

• Latent Events: Uses bandwidth-efficient event system

• Throttling: Minimum 5-second interval between coordinate pushes

Database Optimization

• Indexed Queries: Proper indexes on frequently queried columns

• Efficient Joins: Optimized SQL queries with proper relationships

• Batch Operations: Bulk imports use chunked inserts

• Connection Pooling: Uses oxmysql connection pooling

Client Optimization

• Caching: Client caches ATM coordinates to reduce server requests

• Proximity Checks: Only processes ATMs within detection radius

• Debouncing: Prevents rapid-fire transaction detection

• Efficient Loops: Optimized distance calculations

---

Security Features

Permission Validation

• All server callbacks validate player permissions

• Owner checks prevent unauthorized access

• Employee permissions verified on every action

• Admin logs track all sensitive operations

Input Validation

• Server ID parsing with normalization

• Tax rate bounds checking (0-100%)

• Amount validation (positive numbers only)

• Coordinate format validation

Audit Trail

• All ownership changes logged

• Employee actions tracked

• Tax changes recorded with old/new values

• Transaction history maintained

---

This system provides a robust, performant, and secure solution for ATM ownership and management in FiveM roleplay servers.