Objective

The Objective API is a flexible HUD component designed for the right side of the screen. It can display everything from a single line of text to complex instruction sets with multiple sections, lists, and rich text formatting.

🛠️ Exports

ShowObjective

Displays the objective card with specified content and positioning.

exports['ak47_lib']:ShowObjective(text, title, position)
--
Lib47.ShowObjective(text, title, position)

Parameters:

Argument	Type	Optional	Description
text	String/Table	No	The content to display. Can be a string, a simple list, or a complex sectioned table.
title	String	Yes	The header title. Defaults to Config value.
position	String	Yes	Screen position: 'top', 'center', or 'bottom'.

---

HideObjective

Removes the objective card from the HUD.

exports['ak47_lib']:HideObjective()
-- or
Lib47.HideObjective()

---

🧬 Data Structures

The text parameter is highly versatile and handles four main types of input:

1. Simple String

A single line of descriptive text.

local text = "Locate the package in the warehouse."

2. Simple List

An array of strings rendered as a bulleted list.

local text = {
    "Collect the evidence",
    "Escape the police"
}

3. Named Section

An object containing a sub-header and a list.

local text = {
    Title = "Quick Menu",
    List = {
        "Option One <m>1</m>",
        "Option Two <m>2</m>"
    }
}

4. Multi-Section Array

A complex array containing multiple sections or footer text.

local text = {
    { Title = "Combat", List = { "Attack <m>1</m>", "Block <m>2</m>" } },
    { Title = "Movement", List = { "Sprint <k>SHIFT</k>" } },
    "Press <k>ESC</k> to quit" -- Footer text
}

---

💡 Examples

Example 1: Basic Mission Objective

Ideal for simple tracking at the top right of the screen.

exports['ak47_lib']:ShowObjective(
    "Infiltrate the Humane Labs facility.", 
    "Current Task", 
    "top"
)

Example 2: Editor or Tool Controls

Using the center position and sections to explain controls to a player.

local controls = {
    {
        Title = "Zone Controls",
        List = {
            "Add Point <m>1</m>",
            "Undo Last Point <m>2</m>",
            "Confirm Zone <k>ENTER</k>",
        }
    },
    {
        Title = "Camera",
        List = {
            "Rotate <m>3</m>",
            "Move <k>W</k> <k>A</k> <k>S</k> <k>D</k>",
        }
    },
    "Exit Editor <k>DEL</k>"
}

exports['ak47_lib']:ShowObjective(controls, "Editor Mode", "center")        

Example 3: Dynamic Updates

You can overwrite the current objective simply by calling the export again.

-- First Objective
exports['ak47_lib']:ShowObjective("Wait for the contact...", "The Deal")

-- Update later in the script
Citizen.SetTimeout(5000, function()
    exports['ak47_lib']:ShowObjective("Meet the contact at the pier.", "The Deal")
    PlaySoundFrontend(-1, "Mission_Pass_Notify", "DLC_HEISTS_GENERAL_FRONTEND_SOUNDS", 0)
end)

Example 4: Instruction With Buttons

Lib47.ShowObjective({
    {
        Title = "Current Mode: " .. currentMode,
        List = {}
    },
    {
        Title = "Path Nodes:",
        List = {
            "Add Node <m>1<m>",
            "Undo Node <m>2<m>",
            "Rotate Ped <m>3<m>",
            "Precision Mode <k>SHIFT<k>",
        },
    },
    {
        Title = "Node Types:",
        List = {
            "Toggle Wait (Stoppage) <k>F<k>",
            "Toggle Action (Checkout) <k>G<k>",
        },
    },
    {
        Title = "Navigation:",
        List = {
            "Complete Path <k>ENTER<k>",
            "Skip Step <k>TAB<k>",
            "Go Back <k>BACKSPACE<k>",
            "Cancel Creation <k>DEL<k>",
        }
    },
    {
        Title = "Camera Controls:",
        List = {
            "<m><m> <k>W<k> <k>A<k> <k>S<k> <k>D<k>",
            "Move UP <k>Q<k>",
            "Move Down <k>E<k>",
        },
    },
}, "NPC Navigation")

---

🎨 Visual Features

• Night Mode: The card background automatically dims between 21:00 and 06:00 for better visibility.
• Rich Text: Supports the same <k> (Key) and <m> (Mouse) tags as the Checklist system.
• Right-Aligned: All text and list bullets are automatically aligned to the right edge of the screen.