# 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.

```lua
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.

```lua
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.

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

#### 2. Simple List

An array of strings rendered as a bulleted list.

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

#### 3. Named Section

An object containing a sub-header and a list.

```lua
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.

```lua
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.

```lua
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.

```lua
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.

```lua
-- 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

```lua
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")
```

<div align="left"><figure><img src="https://2088945756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkHcyR2RbVMcj5NHJ2HEa%2Fuploads%2FqvIQsOOsqlZwibK2kKHi%2Fimage.png?alt=media&#x26;token=6d2cdb21-29b7-48ea-98a4-b0628acaa54e" alt=""><figcaption></figcaption></figure></div>

***

### 🎨 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.