A modular, modern FiveM framework built in Lua, designed for flexibility, performance, and ease of use.

Getting Started

CoreX is designed to be easy to set up and use. Follow these steps to get your server running with CoreX.

Database Setup

CoreX uses built-in MySQL support with a simple connection string configuration. No external MySQL resources required!

Installation

1. Download CoreX

# Clone the repository
git clone https://github.com/Core-X-Dev/CoreX.git

# Or download the latest release
# Extract to your FiveM resources folder

2. Configure Database

CoreX includes built-in MySQL support. Simply add your MySQL connection string to your server.cfg:

# MySQL Connection String
set mysql_connection "mysql://username:password@localhost:3306/database_name?"

# Example with specific values
set mysql_connection "mysql://root:mypassword@localhost:3306/corex_db?"

3. Configure Discord

Set up your Discord bot and update the configuration in config/permissions/discord.lua:

Config.Discord = {
    botToken = "your_bot_token",
    guildId = "your_guild_id",
    chatChannelId = "your_chat_channel_id",
    logsChannelId = "your_logs_channel_id"
}

4. Add to server.cfg

# Add CoreX to your server configuration
ensure CoreX

# MySQL connection string (if not already added)
set mysql_connection "mysql://username:password@localhost:3306/database_name?"

5. Start Your Server

Start your FiveM server and CoreX will automatically initialize all modules.

Configuration

CoreX uses a modular configuration system organized in the config/ folder.

Database Configuration

CoreX includes built-in MySQL support that automatically handles database operations. The framework will:

• Auto-create tables: All required database tables are created automatically
• Initialize data: Default jobs, items, and system data are set up
• Handle connections: Connection pooling and error handling
• Auto-save: Player data is automatically saved every 5 minutes

Configuration Structure

Module Configuration

Each module has its own configuration file in config/modules/. Example:

Config.Jobs = {
    -- Job categories and permissions
    categories = {
        government = {
            name = "Government Jobs",
            roles = {"government", "admin"},
            jobs = {
                ems = {
                    name = "Emergency Medical Services",
                    grades = {
                        [0] = {name = "Trainee", salary = 1500},
                        [1] = {name = "Paramedic", salary = 2000},
                        [2] = {name = "Senior Paramedic", salary = 2500},
                        [3] = {name = "Chief", salary = 3000}
                    }
                }
            }
        }
    }
}

Database System

CoreX includes a comprehensive built-in MySQL database system powered by oxmysql for optimal performance and reliability.

oxmysql Integration

CoreX now uses oxmysql for enhanced database performance:

• Optimized queries: Uses appropriate oxmysql exports (scalar, single, query, update, insert)
• Transaction support: Atomic operations for data integrity
• Performance monitoring: Built-in benchmark tools
• Error handling: Robust connection and query error management
• Connection pooling: Efficient database connection management

Database Schema

The framework automatically creates and manages the following tables:

Performance Features

• Auto-save: Player data automatically saved every 5 minutes
• Benchmarking: Built-in performance testing via core/server/benchmark.lua
• Query optimization: Uses appropriate oxmysql exports for each operation type
• Transaction support: ACID-compliant database operations
• Error handling: Comprehensive error logging and recovery
• Data validation: Input validation and sanitization
• SQL injection prevention: Parameterized queries and input sanitization

Benchmarking

CoreX includes comprehensive database benchmarking tools:

• Automatic testing: Runs on resource start after 5 seconds
• Manual testing: Use console command benchmark
• Performance metrics: Query timing and execution statistics
• Test coverage: Tests all major database operations

Modules

CoreX comes with several built-in modules that provide essential functionality.

Commands & Keybindings

CoreX provides a comprehensive set of commands and keybindings for both players and administrators.

Console Commands

These commands are available in the server console:

Player Commands

These commands are available to all players:

Keybindings

Default keybindings for quick access to features:

Admin Commands

These commands are available to administrators:

Framework Structure

CoreX Framework is built with a modular architecture that separates concerns and provides a clean, maintainable codebase. The framework is inspired by the best practices from ESX, OX, and QBCore while introducing modern features and improvements.

Directory Structure

CoreX/
├── fxmanifest.lua          # Resource manifest
├── imports.lua             # Global function imports
├── locale.lua              # Locale system
├── README.md               # Framework documentation
├── CHANGELOG.md            # Version history
├── CONTRIBUTING.md         # Contribution guidelines
├── LICENSE                 # MIT License
├── VERSION.md              # Version information
│
├── shared/                 # Shared code (client & server)
│   ├── config/            # Configuration files
│   │   ├── main.lua       # Main configuration
│   │   ├── weapons.lua    # Weapons configuration
│   │   ├── adjustments.lua # Game adjustments
│   │   └── logs.lua       # Logging configuration
│   ├── modules/           # Shared modules
│   │   ├── math.lua       # Math utilities
│   │   ├── table.lua      # Table utilities
│   │   └── timeout.lua    # Timeout utilities
│   ├── main.lua           # Shared main file
│   └── functions.lua      # Shared functions
│
├── server/                 # Server-side code
│   ├── modules/           # Server modules
│   │   ├── callback.lua   # Callback system
│   │   ├── database.lua   # Database operations
│   │   ├── discord.lua    # Discord integration
│   │   ├── permissions.lua # Permission system
│   │   ├── benchmark.lua  # Database benchmarking
│   │   ├── commands.lua   # Command system
│   │   ├── events.lua     # Event system
│   │   ├── exports.lua    # Export functions
│   │   ├── onesync.lua    # OneSync integration
│   │   └── paycheck.lua   # Paycheck system
│   ├── classes/           # Class definitions
│   │   ├── player.lua     # Player class
│   │   ├── vehicle.lua    # Vehicle class
│   │   ├── character.lua  # Character class
│   │   └── overrides/     # Class overrides
│   ├── bridge/            # Bridge integrations
│   ├── common.lua         # Common server functions
│   ├── functions.lua      # Server functions
│   └── main.lua           # Server main file
│
├── client/                 # Client-side code
│   ├── modules/           # Client modules
│   │   ├── wrapper.lua    # NUI wrapper
│   │   ├── callback.lua   # Callback system
│   │   ├── adjustments.lua # Game adjustments
│   │   ├── points.lua     # Interaction points
│   │   ├── events.lua     # Event system
│   │   ├── actions.lua    # Action system
│   │   ├── death.lua      # Death handling
│   │   ├── interactions.lua # Player interactions
│   │   ├── scaleform.lua  # Scaleform handling
│   │   ├── streaming.lua  # Streaming system
│   │   └── ui.lua         # UI system
│   ├── imports/           # Client imports
│   ├── functions.lua      # Client functions
│   └── main.lua           # Client main file
│
├── locales/               # Localization files
│   ├── en.lua             # English
│   ├── no.lua             # Norwegian
│   ├── sv.lua             # Swedish
│   ├── da.lua             # Danish
│   └── de.lua             # German
│
└── html/                  # Web interface
    ├── ui.html            # Main UI
    ├── css/
    │   └── app.css        # Styles
    ├── js/
    │   ├── app.js         # Main JavaScript
    │   ├── wrapper.js     # NUI wrapper
    │   └── mustache.min.js # Template engine
    └── fonts/             # Custom fonts

Core Components

1. Configuration System

The configuration system is centralized in shared/config/ and provides:

• Main Configuration (main.lua): Core framework settings
• Weapons Configuration (weapons.lua): Weapon definitions and properties
• Adjustments Configuration (adjustments.lua): Game balance settings
• Logs Configuration (logs.lua): Logging system settings

2. Module System

CoreX uses a modular architecture with shared modules in shared/modules/:

• Math Module (math.lua): Mathematical utilities and calculations
• Table Module (table.lua): Table manipulation utilities
• Timeout Module (timeout.lua): Asynchronous timing utilities

3. Database System

The database system is built on oxmysql and provides:

• Automatic table creation: All required tables are created on startup
• Connection pooling: Efficient database connection management
• Query optimization: Uses appropriate oxmysql exports
• Transaction support: ACID-compliant operations
• Benchmarking: Built-in performance testing

4. Localization System

Multi-language support with:

• 5 supported languages: English, Norwegian, Swedish, Danish, German
• Easy translation system: Simple key-value translation files
• Dynamic locale switching: Change language at runtime
• Parameter support: String formatting with variables

5. UI System

Modern web-based interface with:

• Responsive design: Works on all screen sizes
• Dark theme: Modern, clean appearance
• Notification system: Toast-style notifications
• Menu system: Modal-based menu interface
• Help text: Context-sensitive help system

Key Features

1. Player Management

• Multi-character support: Up to 5 characters per player
• Perma-death system: Realistic death mechanics
• Auto-save: Automatic data persistence
• Position tracking: Player location persistence

2. Job System

• Role-based permissions: Jobs with different access levels
• Grade system: Multiple job grades with different permissions
• Salary system: Automatic paycheck distribution
• Discord integration: Role synchronization

3. Economy System

• Money management: Cash and bank account handling
• Transaction logging: Complete audit trail
• Transfer system: Player-to-player money transfers
• ATM integration: Banking system integration

4. Vehicle System

• Garage management: Vehicle storage and retrieval
• Ownership system: Vehicle ownership tracking
• Key sharing: Vehicle key distribution
• Impound system: Vehicle impound mechanics

5. Inventory System

• Weight-based: Realistic weight limitations
• Drag & drop: Modern inventory interface
• Item stacking: Automatic item stacking
• Metadata support: Item-specific data storage

6. Security System

• Permission system: Role-based access control
• Anti-cheat: Suspicious activity detection
• Audit logging: Complete action logging
• Input validation: SQL injection prevention

Performance Features

1. Database Optimization

• Connection pooling: Efficient connection management
• Query optimization: Appropriate oxmysql exports
• Transaction support: ACID-compliant operations
• Benchmarking: Performance monitoring

2. Streaming Optimization

• Dynamic streaming: Efficient entity loading
• Distance-based loading: Load entities based on distance
• Population density control: Configurable population settings

3. Memory Management

• Garbage collection: Automatic memory cleanup
• Resource pooling: Efficient resource reuse
• Memory monitoring: Built-in memory tracking

Development Guidelines

1. Code Style

• Consistent naming: Use descriptive variable and function names
• Proper indentation: Use 4 spaces for indentation
• Commenting: Document complex functions and logic
• Error handling: Always handle potential errors

2. Module Development

• Follow conventions: Use established patterns
• Use CoreX functions: Leverage built-in functionality
• Test thoroughly: Ensure compatibility
• Document properly: Provide clear documentation

3. Performance Considerations

• Optimize queries: Use appropriate database functions
• Minimize network traffic: Efficient event usage
• Cache data: Store frequently accessed data
• Monitor performance: Use built-in benchmarking

Migration Guide

From ESX

1. Replace ESX functions with CoreX equivalents
2. Update database queries to use CoreX database functions
3. Replace ESX events with CoreX events
4. Update UI to use CoreX notification system

From QBCore

1. Replace QBCore functions with CoreX equivalents
2. Update player data structure
3. Replace QBCore events with CoreX events
4. Update inventory system to use CoreX inventory

From OX

1. Replace OX functions with CoreX equivalents
2. Update database queries
3. Replace OX events with CoreX events
4. Update UI components

API Reference

CoreX provides a comprehensive API for developers to extend and integrate with the framework.

Core Functions

-- Player functions
GetPlayer(source)
GetPlayerByIdentifier(identifier)
GetPlayers()
GetPlayerCount()

-- Job functions
GetJob(jobName)
GetJobGrade(jobName, grade)
JobExists(jobName)

-- Database functions
DatabaseQuery(query, params, callback)
DatabaseInsert(query, params, callback)
DatabaseUpdate(query, params, callback)

-- Locale functions
GetLocale(key, ...)
SetLocale(locale)
GetCurrentLocale()

-- Utility functions
FormatMoney(amount)
GetDistance(point1, point2)
IsInRange(point1, point2, range)

Events

-- Player events
RegisterNetEvent('corex:playerJoined')
RegisterNetEvent('corex:playerLeft')
RegisterNetEvent('corex:playerDataUpdated')

-- Job events
RegisterNetEvent('corex:jobChanged')
RegisterNetEvent('corex:gradeChanged')

-- Money events
RegisterNetEvent('corex:moneyAdded')
RegisterNetEvent('corex:moneyRemoved')

Exports

-- Available exports
exports['CoreX']:GetPlayer(source)
exports['CoreX']:GetPlayerByIdentifier(identifier)
exports['CoreX']:GetLocale(key, ...)
exports['CoreX']:DatabaseQuery(query, params, callback)

Core API

-- Get player data
local playerData = CoreX.Players.GetPlayerData(source)

-- Set player data
CoreX.Players.SetPlayerData(source, data)

-- Get player identifier
local identifier = CoreX.Players.GetPlayerIdentifier(source)

Database API

-- Single row query (optimized)
CoreX.Database.FetchSingle('SELECT * FROM players WHERE identifier = ?', {identifier}, function(result)
    if result then
        print(result.name)
    end
end)

-- Multiple rows query
CoreX.Database.FetchAll('SELECT * FROM players WHERE job = ?', {job}, function(results)
    for i, player in ipairs(results) do
        print(player.name)
    end
end)

-- Scalar value (COUNT, MAX, etc.)
CoreX.Database.FetchScalar('SELECT COUNT(*) FROM players', {}, function(count)
    print('Total players:', count)
end)

-- Insert with return ID
CoreX.Database.Insert('INSERT INTO players (identifier, name) VALUES (?, ?)', {identifier, name}, function(insertId)
    print('New player ID:', insertId)
end)

-- Update/Delete operations
CoreX.Database.Execute('UPDATE players SET money = ? WHERE identifier = ?', {money, identifier}, function(success)
    if success then
        print('Player money updated')
    end
end)

-- Transaction support
CoreX.Database.Transaction({
    {'UPDATE players SET money = money - ? WHERE id = ?', {amount, playerId}},
    {'UPDATE players SET money = money + ? WHERE id = ?', {amount, targetId}}
}, function(success)
    if success then
        print('Money transfer completed')
    end
end)

Localization API

-- Get translation
local text = CoreX.Locale.Get("key", "en")

-- Get translation with parameters
local text = CoreX.Locale.Get("welcome", "en", {name = "John"})

-- Set language
CoreX.Locale.SetLanguage("en")

Localization

CoreX supports multiple languages with a fallback system.

Supported Languages

• English (en) - Default language
• Norwegian (no) - Norwegian translations
• Spanish (es) - Spanish translations
• French (fr) - French translations
• German (de) - German translations

Adding Translations

To add a new language, create a locale file in the module's locale/ folder:

return {
    ["job_set"] = "Job défini sur %s",
    ["job_not_found"] = "Job non trouvé",
    ["no_permission"] = "Vous n'avez pas la permission",
    ["job_applied"] = "Candidature envoyée pour %s"
}

Security & Permissions

CoreX implements comprehensive security measures to protect your server.

Discord Integration

• Role-based Access: All job access controlled by Discord roles
• Server Entry: Players must have specific Discord roles to join
• Admin Logging: All admin actions logged to Discord
• Support Tickets: Ticket system with Discord thread creation

Permission System

-- Check if player has permission
if CoreX.Permissions.HasPermission(source, "admin.revive") then
    -- Allow action
end

-- Check Discord role
if CoreX.Discord.HasRole(source, "government") then
    -- Allow government job access
end

Contributing

We welcome contributions from the community! Please read our contributing guidelines.

How to Contribute

1. Fork the repository
2. Create a feature branch
3. Make your changes following our coding standards
4. Test your changes thoroughly
5. Submit a pull request

Coding Standards

• Use camelCase for variables and functions
• Use PascalCase for classes and modules
• Use UPPER_CASE for constants
• Add comments for complex logic
• Follow the existing code style

Changelog

View the complete changelog in the CHANGELOG.md file.

Latest Version: v1.0.2.0

• oxmysql Integration: Replaced mysql-async with oxmysql for improved performance
• Database Benchmarking: Built-in performance testing via core/server/benchmark.lua
• Query Optimization: Uses appropriate oxmysql exports (scalar, single, query, update, insert)
• Enhanced Error Handling: More robust error detection and reporting
• Performance Monitoring: Built-in benchmarking capabilities
• Updated Documentation: Comprehensive oxmysql integration documentation

Previous Version: v1.0.0.2

• Built-in MySQL Support: Replaced external mysql-async dependency with native MySQL integration
• Connection String Configuration: Simple mysql:// connection string format in server.cfg
• Auto Table Creation: Framework automatically creates all required database tables
• Enhanced Database API: New CoreX.Database namespace with transaction support
• Improved Error Handling: Better database connection and query error management
• Updated Documentation: Comprehensive database system documentation

Previous Version: v1.0.0.1

• Cleaned up unused and deprecated files
• Consolidated configuration structure
• Created documentation site
• Simplified root README