Exports & Theme API

NC-HUD provides an external theme system that lets other resources replace built-in HUD components.

Theme Registration

RegisterTheme

exports['nc-hud']:RegisterTheme({
    id = 'my-theme',
    name = 'My Custom Theme',
    author = 'Your Name',
    version = '1.0.0',
    replaces = {
        playerStats = true,   -- Replace player status
        playerInfo = true,    -- Replace player info
        speedometer = true,   -- Replace speedometer
        minimap = true,       -- Replace minimap
        compass = true,       -- Replace compass
        weaponHud = true,     -- Replace weapon HUD
        crosshair = true,     -- Replace crosshair
    },
    colors = {
        primary = '#FF0000',
        secondary = '#00FF00',
    },
})

When a theme replaces a component, NC-HUD hides the default version and sends data to the theme resource via events instead.

Replaceable Components

Component	Key	Description
Player Stats	`playerStats`	Health, armor, hunger, thirst, etc.
Player Info	`playerInfo`	Server ID, time, job, money
Speedometer	`speedometer`	Speed, RPM, fuel, vehicle status
Minimap	`minimap`	Minimap overlay
Compass	`compass`	Heading & postal
Weapon HUD	`weaponHud`	Weapon name & ammo
Crosshair	`crosshair`	Crosshair overlay

Theme Data Events

When your theme replaces a component, receive data via these events:

Player Status

AddEventHandler('nc-hud:theme:playerStatus', function(data)
    -- data = { show, health, armour, oxygen, stress, voice, voicemode, hunger, thirst }
end)

Player Info

AddEventHandler('nc-hud:theme:playerInfo', function(data)
    -- data = { show, serverId, time, job, cash, bank }
end)

Vehicle Data

AddEventHandler('nc-hud:theme:vehicle', function(data)
    -- data = { show, speed, gear, rpm, fuel, ... }
end)

Compass

AddEventHandler('nc-hud:theme:compass', function(data)
    -- data = { show, direction, heading, location, ... }
end)

Weapon

AddEventHandler('nc-hud:theme:weapon', function(data)
    -- data = { show, ammo, maxAmmo, weaponName, ... }
end)

Commands

Command	Description
`/edithud`	Toggle drag-and-drop edit mode
`/resethud`	Reset all HUD positions to default
`/speedunit [mph/kph]`	Change speed unit
`/minimappos`	Open minimap position menu
`/weaponhud`	Toggle weapon HUD visibility
`/minimapdebug`	Show minimap debug info
`/minimapscale [value]`	Adjust minimap scale

Usage Examples

External Theme Resource

-- In your theme resource's client.lua

CreateThread(function()
    while GetResourceState('nc-hud') ~= 'started' do
        Wait(500)
    end

    exports['nc-hud']:RegisterTheme({
        id = 'my-custom-hud',
        name = 'My Custom HUD',
        author = 'YourName',
        version = '1.0.0',
        replaces = {
            speedometer = true,
        },
        colors = {
            primary = '#00ff88',
        },
    })
end)

-- Receive speedometer data
AddEventHandler('nc-hud:theme:vehicle', function(data)
    if data.show then
        -- Render your custom speedometer with data.speed, data.rpm, data.fuel, etc.
    end
end)

Theme Addon: nc-theme-v1

A premium theme addon with vehicle-class specific speedometers:

Unique speedometer for each vehicle class (car, bike, cycle, helicopter, plane, boat)
Per-category edit mode
Dedicated settings panel

Available at noxcore.tebex.io

Last updated: March 4, 2026