# Client Exports

## openUI

Opens the collectables UI.

```lua
exports.mad_collectables:openUI(view?)
```

#### Parameters

* `view?`: `'leaderboard'` | `'collectables'`
  * Which tab to open. Defaults to `'collectables'` if not specified or invalid.

#### Examples

```lua
-- Open to the collectables tab (default)
exports.mad_collectables:openUI()

-- Open directly to the leaderboard
exports.mad_collectables:openUI('leaderboard')

-- Open directly to the collectables
exports.mad_collectables:openUI('collectables')
```

#### Use with Inventory

The stickerbook inventory item uses this export:

```lua
-- ox_inventory item config
["mad_collectables_stickerbook"] = {
    label = "Collectables Stickerbook",
    weight = 100,
    client = {
        export = "mad_collectables.openUI",
    },
},
```

***

## closeUI

Closes the collectables UI.

```lua
exports.mad_collectables:closeUI()
```

***

## getPersonalStats

Gets the current player's collectable stats

```lua
exports.mad_collectables:getPersonalStats()
```

* returns: `table` | `nil`  
  * Returns a table containing the current player's collectable statistics, or `nil` if data couldn't be loaded

```lua
{
    displayName = string,      -- Player's display name
    totalCollected = number,   -- Total collectables collected
    totalAvailable = number,   -- Total collectables available
    setsCompleted = number,    -- Number of completed sets
    totalSets = number,        -- Total number of sets
    optedIn = boolean,         -- Whether player opted into leaderboard
    rank = number,             -- Player's leaderboard rank (if opted in)
    sets = {                   -- Array of collectable sets
        {
            key = string,              -- Set identifier
            label = string,            -- Display name of the set
            description = string,      -- Set description
            icon = string,             -- Icon filename
            totalItems = number,       -- Total items in set
            collectedCount = number,   -- Number collected in this set
            isCompleted = boolean,     -- Whether set is complete
            items = {                  -- Array of items in set
                {
                    id = string,           -- Item identifier
                    index = number,        -- Item index in set
                    setKey = string,       -- Parent set key
                    hint = string,         -- Location hint
                    collected = boolean,   -- Whether collected
                    collectedAt = number?, -- Unix timestamp (ms) when collected
                    placed = boolean?,     -- Whether sticker placed in album
                    placedAt = string?     -- ISO timestamp when placed
                }
            }
        }
    }
}
```

#### Example

```lua
-- Get current player's stats
local stats = exports.mad_collectables:getPersonalStats()

if stats then
    lib.print.info(('You have collected %d/%d collectables'):format(
        stats.totalCollected, 
        stats.totalAvailable
    ))
    
    for _, set in ipairs(stats.sets) do
        for _, item in ipairs(set.items) do
            if item.id == 'cowboy_hats_1' and not item.collected then
                lib.print.info(('Hint: %s'):format(item.hint))
            end
        end
    end
else
    lib.print.error('Failed to load stats')
end

-- Example Output
You have collected 2/10 collectables
Hint: This fella got hurt, must have left his hat outside the hospital
```


---

# 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://madcap.gitbook.io/docs/premium-resources/mad_collectables/client-exports.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.