# Checklist

The Checklist API allows you to display a persistent, interactive task list on the player's HUD. It supports main tasks, nested sub-tasks, progress states, and rich text formatting (keys/mouse icons).

### 🛠️ Exports

#### `ShowChecklist`

Displays the checklist UI with a list of tasks.

<pre class="language-lua"><code class="lang-lua">exports['ak47_lib']:ShowChecklist(tasks, title, position)
-- or 
<strong>Lib47.ShowChecklist(tasks, title, position)
</strong></code></pre>

Parameters:

| **Argument** | **Type** | **Optional** | **Description**                                                                                                      |
| ------------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `tasks`      | Table    | No           | A table containing the task objects (see [Task Structure](https://www.google.com/search?q=%23task-structure) below). |
| `title`      | String   | Yes          | The header title of the checklist. Defaults to Config value.                                                         |
| `position`   | String   | Yes          | Screen position. Options: `'top'`, `'center'`, `'bottom'`.                                                           |

***

#### `UpdateChecklist`

Updates the completion status of a specific task or sub-task.

```lua
exports['ak47_lib']:UpdateChecklist(index, isComplete, subIndex)
-- or
Lib47.UpdateChecklist(index, isComplete, subIndex)
```

Parameters:

| **Argument** | **Type** | **Optional** | **Description**                                              |
| ------------ | -------- | ------------ | ------------------------------------------------------------ |
| `index`      | Number   | No           | The 1-based index of the main task in the list.              |
| `isComplete` | Boolean  | No           | `true` to mark as done, `false` to uncheck.                  |
| `subIndex`   | Number   | Yes          | The 1-based index of a sub-task (if updating a nested item). |

***

#### `HideChecklist`

Removes the checklist from the screen.

```lua
exports['ak47_lib']:HideChecklist()
-- or
Lib47.HideChecklist()
```

***

### 🧬 Data Structures

#### Task Structure

When sending the `tasks` table to `ShowChecklist`, each item should follow this format:

```lua
{
    label = "Task Name",      -- (String) Text to display (supports Rich Text)
    completed = false,        -- (Boolean) Initial state
    subTasks = {              -- (Table, Optional) Nested tasks
        { label = "Sub A", completed = false },
        { label = "Sub B", completed = false }
    }
}
```

***

### 🎨 Rich Text Formatting

You can inject keyboard keys and mouse icons directly into your task labels using the following tags:

| **Tag**      | **Result**       | **Description**                                   |
| ------------ | ---------------- | ------------------------------------------------- |
| `<k>KEY</k>` | Keyboard E       | Renders a styled keyboard key (e.g., `<k>E</k>`). |
| `<m></m>`    | Mouse            | Renders a Mouse icon                              |
| `<m>1</m>`   | 🖱️ Mouse Left   | Renders a Left Mouse Button icon.                 |
| `<m>2</m>`   | 🖱️ Mouse Right  | Renders a Right Mouse Button icon.                |
| `<m>3</m>`   | 🖱️ Mouse Middle | Renders a Middle Mouse/Scroll icon.               |

***

### 💡 Examples

#### Example 1: Simple Task List

A basic list positioned at the top left of the screen.

```lua
local tasks = {
    { label = "Go to the police station", completed = false },
    { label = "Talk to the Captain", completed = false },
    { label = "Get your badge", completed = false }
}

-- Display the checklist
exports['ak47_lib']:ShowChecklist(tasks, "New Recruit", "top")
```

#### Example 2: Complex Mission (Sub-tasks & Rich Text)

A mission list centered on the screen featuring interaction keys and nested objectives.

```lua
local missionTasks = {
    { label = "Breach the front door <k>E</k>", completed = false },
    { 
        label = "Secure the Evidence", 
        completed = false,
        subTasks = {
            { label = "Hack the laptop <m>1</m>", completed = false },
            { label = "Steal the hard drive", completed = false }
        }
    },
    { label = "Escape via Roof", completed = false }
}

-- Display centered
exports['ak47_lib']:ShowChecklist(missionTasks, "Heist Setup", "center")
```

#### Example 3: Updating Progress

How to update the mission created in Example 2 dynamically.

```lua
CreateThread(function()
    -- 1. Complete "Breach the front door" (Index 1)
    Wait(5000)
    exports['ak47_lib']:UpdateChecklist(1, true)

    -- 2. Complete "Hack the laptop" (Index 2, Sub-index 1)
    Wait(5000)
    exports['ak47_lib']:UpdateChecklist(2, true, 1)

    -- 3. Complete "Steal the hard drive" (Index 2, Sub-index 2)
    Wait(2000)
    exports['ak47_lib']:UpdateChecklist(2, true, 2)
    
    -- 4. Complete the main "Secure the Evidence" task visually (Index 2)
    Wait(1000)
    exports['ak47_lib']:UpdateChecklist(2, true)

    -- 5. Finish Mission and Hide
    Wait(5000)
    exports['ak47_lib']:HideChecklist()
end)
```

#### Example 4:&#x20;

```lua
local masterTasks = {
    { label = "Define Shop Zone", completed = false },
    { label = "Place Sign", completed = false },
    { label = "Buying/Selling Point", completed = false },
    { label = "Shopkeeper Position", completed = false },
    { 
        label = "Setup Baskets", 
        completed = false,
        subTasks = {
            { label = "Set Position", completed = false },
            { label = "Navigation Mesh", completed = false },
            { label = "Queue Lines", completed = false },
        }
    },
    { label = "Billing Action", completed = false },
    { label = "Shop Actions", completed = false },
    { label = "Boss Menu", completed = false },
    { label = "Garage Spawn", completed = false },
    { label = "Setup Doors", completed = false },
}

Lib47.ShowChecklist(masterTasks, "Creation Checklist")
```

<div align="left"><figure><img src="https://2088945756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkHcyR2RbVMcj5NHJ2HEa%2Fuploads%2FFJMRcaqN6qfFP5gGV4Rw%2Fimage.png?alt=media&#x26;token=cdb22704-1e34-45e7-a98d-63b9ed12fbec" alt=""><figcaption></figcaption></figure></div>

***

### ℹ️ Additional Info

> Night Mode: The UI automatically adjusts its background opacity between 21:00 and 06:00 in-game time (managed via `GetClockHours`).

> Lib47: If you are using the internal `Lib47` files, the functions are also available via `Lib47.ShowChecklist`, `Lib47.UpdateChecklist`, and `Lib47.HideChecklist`.