helix_lib

helix_lib is the shared foundation for every Helix script. It provides a unified API layer across frameworks, a config system, localisation, NUI design components, and callback RPC — all through flat per-function exports that survive FiveM's export proxy.

Version: 0.1.0 | License: MIT | Price: Free

---

Overview

Every Helix script depends on helix_lib. It handles:

• Framework Bridge — Abstracts ESX, QBCore, and Qbox behind a single API
• Config System — Load, merge, and hot-reload Lua config tables
• Callback System — RPC-style server/client callbacks with ox_lib compatibility
• Locale System — Multi-language translations with string.format interpolation
• NUI Design System — Shared React components and design tokens
• Version Check — Automatic update checking against GitHub releases

Quick Start

-- Server: register a callback
exports.helix_lib:callback_register('myScript:getData', function(source)
    local money = exports.helix_lib:bridge_GetPlayerMoney(source, 'cash')
    return { balance = money }
end)

-- Client: call it
local result = exports.helix_lib:callback_await('myScript:getData')
print('Balance: $' .. result.balance)

-- Translate a string
local msg = exports.helix_lib:locale_t('money_added', result.balance)
exports.helix_lib:notify(msg, 'success')

Export Architecture

All exports use a flat per-function pattern. This is intentional — FiveM's export proxy strips methods from returned tables. Instead of exports.helix_lib:bridge().GetPlayer(src), you call exports.helix_lib:bridge_GetPlayer(src) directly.

See the API Reference for the complete export list.

---

Modules

Framework Bridge

Automatically detects which framework is running and provides unified access to player data, money, jobs, inventory, and notifications.

Supported frameworks:

• Qbox (qbx_core)
• QBCore (qb-core)
• ESX (es_extended)
• Standalone (fallback — all functions return nil/false/0)

Detection order: Qbox → QBCore → ESX → Standalone. Override in config.lua if needed.

-- Check which framework is active
local fw = exports.helix_lib:bridge_framework()
print(fw) -- 'qbox', 'qbcore', 'esx', or 'standalone'

-- Check for a specific framework
if exports.helix_lib:bridge_is('qbox') then
    -- Qbox-specific logic
end

-- Get player data (server-side)
local player = exports.helix_lib:bridge_GetPlayer(source)
local job = exports.helix_lib:bridge_GetPlayerJob(source)
local money = exports.helix_lib:bridge_GetPlayerMoney(source, 'bank')

See the Framework Bridge Guide for detailed framework differences.

---

Config System

Every Helix script ships with a config.lua at its root. The config system loads these as Lua tables, merges with defaults, and supports runtime hot-reload.

-- Get the config table (returns HelixConfig module)
local config = exports.helix_lib:config()

-- Load another resource's config with defaults
local cfg = config.load('helix_hud', { position = 'bottom-center' })

See the Configuration Guide for all options.

---

Callback System

Framework-agnostic RPC between client and server. If ox_lib is present, wraps its callback system automatically — your code works identically either way.

-- Server: register
exports.helix_lib:callback_register('shop:getItems', function(source, category)
    return getShopItems(category)
end)

-- Client: async with callback
exports.helix_lib:callback_trigger('shop:getItems', function(items)
    for _, item in ipairs(items) do
        print(item.name)
    end
end, 'weapons')

-- Client: blocking await
local items = exports.helix_lib:callback_await('shop:getItems', 'weapons')

---

Locale System

Multi-language translations with string.format interpolation. Falls back to English when a key is missing in the active locale.

-- Translate a key
local msg = exports.helix_lib:locale_t('greeting', 'Alex')
-- With en.lua: { greeting = 'Hello, %s!' } → "Hello, Alex!"

-- Check if a key exists
local exists = exports.helix_lib:locale_has('greeting') -- true

-- Get/set active locale
local lang = exports.helix_lib:locale_current() -- 'en'
exports.helix_lib:locale_set('nl')

-- Load translations from file
exports.helix_lib:locale_loadFile('nl')

-- Load translations from another resource
exports.helix_lib:locale_loadFile('en', 'helix_hud')

Create locale files at locales/<lang>.lua in your resource:

-- locales/en.lua
return {
    greeting = 'Hello, %s!',
    money_added = '$%s has been added to your account.',
    error_no_permission = 'You do not have permission to do this.',
}

---

Version Check

On resource start, checks the GitHub releases API for newer versions. Prints a console notice if an update is available. No telemetry — one GET request to api.github.com, that's it.

Disable in config.lua:

return {
    versionCheck = false,
}

---

Dependencies

helix_lib has zero hard dependencies. It works standalone out of the box.

Optional integrations:

• ox_lib — If present, callbacks route through ox_lib's system for compatibility with other ox-based resources
• ox_inventory — If present, bridge_HasItem uses ox_inventory's item checks

Resource Weight

• Idle resmon: < 0.01ms
• NUI bundle: < 100KB gzipped
• No persistent threads beyond the version check on startup