Custom Elements

This feature allows you to create custom, updateable, elements inside the existing HUD interface.

1

Create Element in Shared Config

You must first create the custom element in the shared_config.lua file. This is under Config.CustomElements. In the default shared config you'll see two examples of custom elements, one for displaying Duty Unit Counts and one for Staff Members showing the server player count and report statistics.

Option	Description
Enabled	This is the master toggle for whether this element is enabled or not.
Name	This is the name of the custom element, used and displayed in the /ui settings menu.
Description	This is the description of the custom element, used and displayed in the /ui settings menu.
Restricted	This controls whether this custom element is restricted to certain players or not. If true, only players with a later specified ace permission will have the custom element shown on their interface. This is good if you want to restrict the element to staff members.
AcePermission	If you choose to restrict the custom element to certain players, this is the ace permission that the custom element will be restricted to. We suggest the following format: nex-hud.custom_element.<id>
Position	This controls where the custom element will be displayed in the main cluster. 1 would be shown at the top, 2 would be shown in second place etc.
DefaultState	This controls whether the custom element is shown by default, or whether players will have to enable the display of the element in the /ui settings menu.
CanDisable	This controls whether players can or cannot disable the view of the custom element in the /ui settings menu.
DefaultInnerHTML	This is the HTML code that'll be displayed inside the custom element. We suggest you keep this minimal to keep inline with the minimal design of the interface, but it's up to you.

2

Set up Custom Elements file

In the main directory of the script contains a custom_elements.lua file. This is a server-sided file that'll contain the logic for your custom elements. In order to set these up, this will require custom code, so make sure you know what you're doing.

In this example, we're going to integrate nex-duty into a custom element.

Here's an example of how to implement a script into a Custom Element.

-- this is the same template from the "DefaultInnerHTML" option from the Config.CustomElements
local template = '<b>LEO:</b> <span style="color:{LEO_COLOUR};">{LEO}</span> <span style="color: #BBB;">/</span> <b>SAMR:</b> <span style="color:{SAMR_COLOUR};">{SAMR}</span> <span style="color: #BBB;">/</span> <b>DHS:</b> <span style="color:{DHS_COLOUR};">{DHS}</span> <span style="color: #BBB;">/</span> <b>STAFF:</b> <span style="color:{STAFF_COLOUR};">{STAFF}</span>'

-- This is jsut a helper function to set the colour depending on whether a department has on-duty units or not. The "var(--accent-color)" will use the customised colour the player has set through the /ui settings menu.
function set_colour(value)
    if value == 0 then
        return "#BBB"
    else
        return "var(--accent-color)"
    end
end

-- This queries nex-duty each interval to fetch the counts for each part of the custom element.
Citizen.CreateThread(function()
    while true do
        local leo_units = exports["nex-duty"]:getUnitsByEntities({ "sasp", "bcso", "lspd" })
        local staff_units = exports["nex-duty"]:getUnitsByEntities({ "staff" })
        local fire_units = exports["nex-duty"]:getUnitsByEntities({ "samr" })
        local dhs_units = exports["nex-duty"]:getUnitsByEntities({ "dhs" })

        -- count how many entries are in units
        local leo_count = #leo_units
        local staff_count = #staff_units
        local fire_count = #fire_units
        local dhs_count = #dhs_units

        local inner_html = template
            :gsub("{LEO}", leo_count)
            :gsub("{LEO_COLOUR}", set_colour(leo_count))
            :gsub("{STAFF}", staff_count)
            :gsub("{STAFF_COLOUR}", set_colour(staff_count))
            :gsub("{SAMR}", fire_count)
            :gsub("{SAMR_COLOUR}", set_colour(fire_count))
            :gsub("{DHS}", dhs_count)
            :gsub("{DHS_COLOUR}", set_colour(dhs_count))

        TriggerEvent("nh:server:update_custom_element", "unit_counts", inner_html)

        Wait(30000)
    end
end)

-- If you want to add and remove the ace permission from a player, so, for example, they only have the Custom Element whilst they're on duty, and it's removed once they go off, these two listening events will refresh their custom elements, so the script will recheck their permissions. If the ace permission is removed when going off duty, this will remove the custom element too. You must wait at least 1000ms for the permissions to be removed, otherwise it won't work.
AddEventHandler("nex-duty:server:go_on_duty", function()
    local src = tonumber(source)
    Citizen.Wait(1000)
    TriggerEvent("nh:server:refresh_custom_elements", src)
end)

AddEventHandler("nex-duty:server:go_off_duty", function()
    local src = tonumber(source)
    Citizen.Wait(1000)
    TriggerEvent("nh:server:refresh_custom_elements", src)
end)

3

Complete

Once you've completed all of this, restart the script so the changes to the custom_elements.lua file are live and you're good to go.

The code provided above is a working example, you can make the custom elements much more advanced, the possibilities are mostly limitless, so you're more than welcome to go crazy with the custom elements!

As this requires custom code, we do not provide support for creating custom elements.

If you have any questions, let us know in our discord server.