A lightweight, modular foundation for players, jobs, inventory, economy, status, callbacks, permissions, and persistent character data.
Players · Jobs · Inventory · Economy · Status · Callbacks · Permissions
hexa_core is the foundation of the Hexa Framework ecosystem.
It is built specifically for RedM / RDR2 roleplay servers, providing the shared systems and APIs that other resources can build on without duplicating player, economy, inventory, permission, or persistence logic.
The framework uses a flat API and a straightforward relational database structure designed to stay easy to understand, extend, and maintain.
RedM Server
│
▼
┌──────────────────────┐
│ hexa_core │
├──────────────────────┤
│ Players │
│ Jobs │
│ Inventory │
│ Money │
│ Status │
│ Callbacks │
│ Permissions │
│ Persistence │
└──────────┬───────────┘
│
▼
Hexa Resources
Hexa is designed around RedM rather than treating it as a GTA framework with a cowboy hat glued on top.
Native framework support includes:
- RDR2 prompts
- Eagle Eye integration
- IPLs and interiors
- Population and density control
- Health, stamina, and Dead Eye cores
- Gold attribute cores
- Customised minimap behaviour
- RedM-specific player systems
Each connected player is represented by a server-owned player object.
Player
├── Identity
├── Money
├── Inventory
├── Job
│ └── Duty State
├── Metadata
├── Status
│ ├── Hunger
│ ├── Thirst
│ ├── Cleanliness
│ └── Stress
└── Persistence State
The player object exposes direct methods for interacting with player data.
local Player = Core.GetPlayer(source)
if Player then
Player.AddMoney('cash', 100, 'mission_reward')
endMultiple money types can be managed directly through the player object.
Player.AddMoney('cash', 100, 'mission_reward')
Player.RemoveMoney('cash', 50, 'shop_purchase')Transaction reasons can be supplied so external resources can keep operations understandable and traceable.
Hexa includes inventory support with:
- Weighted items
- Slot-based storage
- Item metadata
- Item catalogue registration
- Player inventory operations
- Useable items
A key distinction exists between registering an item type and giving an item to a player:
Core.RegisterItem('bread', {
-- item definition
})
Player.AddItem('bread', 1)Think of it as:
Core.RegisterItem()
│
▼
Creates an item TYPE
in the server catalogue
Player.AddItem()
│
▼
Creates an item INSTANCE
for a player
These operations previously shared similar naming. The current API separates them to make resource code clearer.
See the upgrade guide for the complete rename table.
Player jobs support structured job data and duty state.
Job
├── Name
├── Label
├── Grade
├── Grade Name
└── Duty State
This allows external resources to build systems such as:
- Law enforcement
- Medical roles
- Businesses
- Factions
- Whitelisted jobs
- Job-specific interactions
without owning the player job state themselves.
Hexa includes player status data for common roleplay mechanics.
Default needs include:
Hunger
Thirst
Cleanliness
Stress
Additional metadata can be stored through the player data system for custom server mechanics.
Hexa provides callbacks between client and server.
Client
│
│ TriggerCallback
▼
Server
│
│ CreateCallback
▼
Response
│
└──────────────► Client
This allows resources to request server-owned data without building custom event-response logic for every interaction.
Resources can register items with behaviour that executes when players use them.
This keeps item definitions and gameplay resources separated while allowing external systems to hook into inventory usage cleanly.
Hexa provides a shared permission layer for resources that need controlled access.
Typical use cases include:
- Administrative commands
- Staff tools
- Developer commands
- Restricted resource actions
- Permission-gated callbacks
Resources can rely on the framework's permission state rather than implementing their own permission system.
Thai and English are included by default.
Locales
├── English
└── ไทย
Additional languages can be added through a locale file without modifying framework logic.
Player persistence is owned by the server.
Instead of blindly saving every player on every interval, Hexa tracks whether persistent player data has changed.
Player Data Changed?
│
┌───┴───┐
│ │
No Yes
│ │
Skip ▼
Mark Dirty
│
▼
Save Queue
│
▼
Database
The save system:
- Runs server-side
- Saves only changed player data
- Avoids unnecessary database writes
- Spreads saves across the configured cadence
- Prevents the entire server population from writing in a single tick
This keeps persistence predictable as player counts increase.
Hexa uses MariaDB / MySQL through oxmysql.
The base player data uses a flat relational layout centred around a users table keyed by player identifier.
On first boot, Hexa can install its required base schema automatically using:
install.sql
The normal startup flow is:
Start Server
│
▼
Start oxmysql
│
▼
Start hexa_core
│
▼
Check Database Schema
│
├── Exists ─────► Continue
│
└── Missing
│
▼
Run Installer
│
▼
Ready
No manual import is required for the base schema under the normal installation flow.
| Requirement | Description |
|---|---|
| FXServer / RedM | Recent artifact with rdr3 support |
| Lua 5.4 | Resource runtime |
| MariaDB / MySQL | Persistent player storage |
oxmysql |
Required database driver |
oxmysql must start before hexa_core.
Clone hexa_core into your server resources directory:
git clone https://github.com/hexa-development/hexa_core.gitExample structure:
resources/
│
└── [hexa]/
└── hexa_core/
Add your oxmysql connection string to server.cfg.
set mysql_connection_string "mysql://user:password@localhost/hexa?charset=utf8mb4"Replace the credentials and database name with your own configuration.
Add:
ensure oxmysql
ensure hexa_coreStartup order matters.
oxmysql
│
▼
hexa_core
│
▼
Hexa Resources
Any resource depending on Hexa should start after hexa_core.
Open:
config/main.lua
Configure:
Config.IdentifierType = 'license'Available values:
Config.IdentifierType = 'license'
Config.IdentifierType = 'steam'Recommended for most servers.
Every RedM player has a Rockstar license identifier available to FXServer.
Requires the player to launch the game with Steam available.
Players without a Steam identifier will be refused during connection.
For general compatibility:
Config.IdentifierType = 'license'is the safer default.
On first startup, hexa_core checks the required database schema and installs the base tables when necessary.
Once initialization completes, resources can access the Hexa API.
Get the core object:
local Core = exports['hexa_core']:GetCoreObject()Retrieve a player on the server:
local Player = Core.GetPlayer(source)
if not Player then
return
endAdd money:
Player.AddMoney(
'cash',
100,
'mission_reward'
)A complete example:
local Core = exports['hexa_core']:GetCoreObject()
RegisterNetEvent('example:server:reward', function()
local src = source
local Player = Core.GetPlayer(src)
if not Player then
return
end
Player.AddMoney(
'cash',
100,
'mission_reward'
)
end)Hexa uses a flat API.
Framework methods live directly on the core object:
Core.GetPlayer(source)
Core.RegisterItem(name, data)Player methods live directly on the player object:
Player.AddMoney(type, amount, reason)
Player.AddItem(name, amount)This keeps normal resource code concise:
local Core = exports['hexa_core']:GetCoreObject()
local Player = Core.GetPlayer(source)
if Player then
Player.AddMoney('cash', 100, 'reward')
endinstead of requiring additional namespace layers for everyday operations.
The previous API syntax remains temporarily available for migration.
Old:
Core.Functions.GetPlayer(source)
Player.Functions.AddMoney('cash', 100, 'reward')Current:
Core.GetPlayer(source)
Player.AddMoney('cash', 100, 'reward')Legacy calls continue to work for one release and emit a one-time deprecation warning identifying the calling resource.
Old Resource
│
▼
Legacy API
│
├── Still Works
│
└── Deprecation Warning
│
▼
Update Resource
│
▼
Flat API
New resources should use the flat API immediately.
For migration details, see:
Hexa keeps the core focused on shared framework responsibilities.
┌──────────────────┐
│ hexa_core │
└────────┬─────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Hexa Banking│ │ Hexa Plants │ │ Hexa Scripts│
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌──────────────┐
│ hexa-bridge │
└───────┬──────┘
│
┌─────────────┴─────────────┐
▼ ▼
RSG Scripts VORP Scripts
Gameplay systems can remain separate resources while relying on the same player and server foundation.
This avoids turning hexa_core into a giant resource containing every system on the server.
A typical Hexa resource starts by retrieving the core object:
local Core = exports['hexa_core']:GetCoreObject()Then uses only the framework services it needs.
local Player = Core.GetPlayer(source)
if not Player then
return
end
Player.AddMoney('cash', 100, 'example_reward')Resources should interact with Hexa through public APIs rather than directly modifying internal player tables or framework state.
This keeps resources easier to:
- Maintain
- Debug
- Upgrade
- Reuse
- Bridge
- Document
Complete installation guides, API references, upgrade information, and development examples are available in the official documentation.
Documentation covers:
- Installation
- Configuration
- Core API
- Player API
- Inventory
- Economy
- Jobs
- Status
- Metadata
- Callbacks
- Events
- Permissions
- Useable items
- Persistence
- Migration
- Bridge compatibility
Every Hexa resource is a separate repository built on this one.
| Project | Description |
|---|---|
hexa_core |
Core framework — players, jobs, items, economy, status, callbacks, permissions (this repository) |
hexa_inventory |
Persistent grid inventory — stashes, shops, ground drops, secure trading |
hexa_progbar |
Screen-fixed progress bar — drop-in for ox_lib progressBar |
hexa-bridge |
Compatibility layer for supported RSG and VORP resources |
hexa-docs |
Official documentation and API reference (VitePress) |
rdr2-unpack |
Read a local RDR2 install into open formats — GLB, PNG, .ymap JSON |
txAdmin |
One-click txAdmin recipe that deploys the whole Hexa stack |
Full API reference and installation guides live in hexa-docs → hexa-development.github.io/hexa-docs
Existing RedM resources do not necessarily need to be rewritten immediately when migrating to Hexa.
hexa-bridge provides compatibility layers for supported RSG and VORP APIs.
Existing RSG / VORP Script
│
▼
hexa-bridge
│
▼
hexa_core
For new resources, use the native Hexa API directly.
For existing resources, the bridge provides a path for progressive migration.
Hexa Framework is under active development.
Framework APIs, compatibility layers, tooling, and documentation may continue to evolve as the ecosystem matures.
When updating a production server, review the documentation and upgrade guide for breaking or deprecated API changes.
Hexa Framework
Documentation · เอกสารภาษาไทย · hexa_core · hexa_inventory · hexa_progbar · hexa-bridge · Organization
Build the systems. Keep the core clean.