# 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="/files/Pc17cmdhfYXKXWnMv7kt" 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`.


---

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