Configuration#

Server-side behaviour of the HUD lives in editable/shared/config.lua. This page goes through it top to bottom: what each option does, its default, and when you would change it.

Changes take effect after ensure koja-hud (or a server restart). What players see by default — styles, colours, which elements are on — is not in this file; that is Player settings.

General#

KOJA.Debug = false
KOJA.Locale = 'en'
KOJA.SettingsCommand = 'settings'
KOJA.HideMinimapOnFoot = true
KOJA.HideHudOnPauseMenu = true
KOJA.Notify = 'hud'

Notification system#

KOJA.Notify only decides where the HUD's own messages go. exports['koja-hud']:sendNotify always uses the HUD's notifications, whatever you set here.

Custom notifications#

With KOJA.Notify = 'custom', fill in the function in editable/shared/utils.lua. It receives the translated title and text:

Misc.Utils.CustomNotify = function(data)
    -- data.title, data.desc, data.type, data.icon, data.color, data.time
    exports['my-notify']:Show(data.title, data.desc)
end

Forcing components off#

KOJA.HideComponents = {
    status = false,
    carhud = false,
    progressbar = false,
    notify = false,
    textui = false,
    informations = false
}

Set a component to true to hide it for everyone, whatever players choose in the settings menu. Use it when another resource already provides that element — for example progressbar = true if you keep using ox_lib progress bars.

The same names work at runtime with the HideComponent export.

Minimap item#

KOJA.NeedItemForMinimap = false
KOJA.MinimapItem = 'phone'

With KOJA.NeedItemForMinimap = true, the minimap is shown only while the player has at least one KOJA.MinimapItem in their inventory. The check runs every 300 ms through koja-lib, so it follows your inventory resource.

Voice#

KOJA.Microphone = {
    Enabled = true,
    Custom = false,
    Levels = {
        [1] = 25,
        [2] = 75,
        [3] = 100,
    },
}

The "talking" highlight on the voice indicator does not depend on this block: it comes from the game's own voice chat state.

Nitro#

KOJA.Nitro = {
    Enabled = true,
    Key = 'N',
    Desc = 'Toggle nitro',
    Tables = {
        GaragesTable = 'owned_vehicles',
        OwnerColumn = 'owner'
    },
    NitroForce = 1.5,
    RemoveNitroOnMilliseconds = 2,
    Item = 'nitro'
}

How nitro is installed and saved is described in Features → Nitro.

Engine#

KOJA.Engine = {
    Enabled = true,
    Key = 'B',
    Desc = 'Toggle engine',
    StartEngineOnEntering = false
}

Seatbelt#

KOJA.Seatbelt = {
    Enabled = true,
    Key = 'L',
    Desc = 'Toggle seatbelt',
    MaxVehicleSpeedToRagdoll = 70
}

While the belt is on, the player cannot leave the vehicle with F.

Cruise control#

KOJA.CruiseMode = {
    Enabled = true,
    Key = 'T',
    Desc = 'Toggle cruise control',
    MinSpeed = 20.0
}

Cruise control switches off when the driver brakes, leaves the seat, or the vehicle leaves the ground.

Compass#

KOJA.Compass = {
    Enabled = true
}

false removes the compass for everyone and stops the thread that tracks the camera heading. With it on, players pick the style and when it shows.

Refresh rates#

KOJA.Refresh = {
    Hud = 1500,
    PauseMenu = 200,
    Compass = 90,
    Weapon = 250,
    Vehicle = 150
}

How often, in milliseconds, each part of the HUD is updated. Lower is smoother and costs more client CPU.

The defaults are a good balance. If you lower Vehicle, do not go below about 50.

Watermark#

KOJA.Watermark = {
    Enabled = false,
    Text = 'HEXEL RP'
}

Shows your server name at the top of the screen. Enabled = false hides it for everyone. With it on, players choose the style, font, size and colour in Settings → MAIN → PVP Mode, and can hide it there. In PVP mode the watermark also shows the player's health and armour.

Vehicle menu#

KOJA.VehicleMenu = {
    Enabled = true,
    Key = 'U',
    Command = 'vehicle',
    Desc = 'Open vehicle control menu'
}

The menu opens only for the driver.

Killfeed#

KOJA.Killfeed = {
    Enabled = false,
    AnyDistance = true,
    Distance = 100
}

These are the defaults for new players; each player can change them in Settings → MAIN → Killfeed.

The killfeed records kills made by the player themself out of the box. To show other kills, send them from your own code — see AddKillfeed.

Status effects#

KOJA.StatusEffects = {
    Builtin = false
}

true shows two effects the HUD detects by itself: sprinting and swimming. Effects you add from code are shown either way — see Status effects.

Minimap#

KOJA.MiniMap = {
    Enabled = true,
}

true replaces the round GTA radar with the square minimap that players can move and resize in Settings → Edit layout. false leaves the game's own minimap alone.

Fine-tuning the minimap#

Advanced: the square minimap's geometry has defaults you can override by adding keys to KOJA.MiniMap. They are fractions of the screen; leave them alone unless the map looks misaligned on your setup.

KOJA.MiniMap = {
    Enabled = true,
    OffsetY = -0.04,
}

Data files#

Two lists in data/ are worth knowing about:

ElectricModels = {
    [GetHashKey('voltic')] = true,
    [GetHashKey('my_addon_ev')] = true,
}