# 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="/files/1VwBAG8cD1c2iVWKgth5" 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.menanak47.com/plugins/ak47_lib/interface/objective.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.