# Configuration

All configuration is done through three files in the `config/` folder.

***

## Shared Config

`config/shared.lua` - Settings used by both client and server.

### Debug

```lua
debug = {
    showBlips = false, -- Show blips on map for uncollected items
    showOutlines = false, -- Show red outlines on collectable objects
    showHighlight = false, -- Show pulsing highlight effect
    raycastCommand = true, -- Enable /col_coords coordinate finder
},
```

{% hint style="info" %}
Outlines and highlights are client resource intensive tasks.
{% endhint %}

### Notifications

```lua
notify = {
    type = 'ox_lib', -- Notification system to use
    duration = 5000, -- How long notifications display (ms)
},
```

### Text UI

```lua
textUI = {
    type = 'ox_lib', -- TextUI system to use
},
```

### Objects

```lua
objects = {
    spawnDistance = 200.0, -- Distance at which objects spawn
    showOutlines = false, -- Show outlines on spawned objects
    showHighlight = false, -- Show highlight on spawned objects
},
```

{% hint style="info" %}
Outlines and highlights are client resource intensive tasks.
{% endhint %}

### Targets

```lua
targets = {
    icon = 'fas fa-hand',  -- Font Awesome icon for target interaction
},
```

### Prompts

```lua
prompts = {
    icon = 'hand',  -- Icon for TextUI prompt
},
```

### Sounds

```lua
sounds = {
    collect = { -- Sound played on item collection
        audioName = 'PICK_UP', -- Name of the audio to play
        audioRef = 'HUD_FRONTEND_DEFAULT_SOUNDSET', -- Audio set to use
    },
},
```

### Animations

```lua
animations = {
    pickup = { -- Animation played on item collection
        animDictionary = 'anim@scripted@freemode@subrob_ig_grab_blow_torch@male@', -- The animation dictionary
        animationName = 'grab_mid', -- The name of the animation within the dictionary
        animFlags = 0, -- Animation flag
        duration = 1000, -- Duration in milliseconds
    },
},
```

### Show Off

```lua
showOffAnimation = {
    duration = 5500, -- Animation duration and DUI display time (ms)
    duiLoadDelay = 200, -- Delay for DUI browser to initialise (ms)
},
```

***

## Client Config

`config/client.lua` - Client-side settings.

### UI

```lua
ui = {
    showStatTotals = true, -- Show statistics as fractions of their totals instead of just the count (e.g., 3/23)
    showStatPercentages = false, -- Show additional context text with percentages below stat values (e.g., "Top 10%", "75% complete")
    completedSetsPosition = 'bottom', -- Position of completed sets in the sidebar ('top', 'bottom', or 'default' for no reordering)
    dateFormat = 'US' -- Date format to use in the UI (e.g., MM/DD/YYYY for US, DD/MM/YYYY for UK)

    style = {
        defaultMode = 'light', -- Default UI mode
        allowUserToggle = true, -- Whether to allow users to toggle between light and dark mode
    },
},
```

### Keybinds

```lua
keybinds = {
    name = 'collectables_pickup', -- Name for the keybind
    description = 'Collect item', -- Description of the keybind
    defaultKey = 'E', -- The default key for the keybind
},
```

***

## Server Config

`config/server.lua` - Server-side settings.

### Commands

```lua
enableAllCommands = true, -- Master toggle for all commands

commands = {
    open_menu = {
        enabled = true, -- Whether the command is enabled
        restricted = false, -- Permissions group to use the command
        name = 'collectables', -- The name of the command
        help = 'Open the collectables menu', -- Help text shown in chat for the command
    },

    admin_reset = {
        enabled = true,
        restricted = 'group.admin',
        name = 'admin_col_reset',
        help = "Reset a player's collectables",
        params = { -- Command parameters
            { name = 'playerId', type = 'playerId', help = 'Player server ID' },
        },
    },

    admin_give_all = {
        enabled = true,
        restricted = 'group.admin',
        name = 'admin_col_give_all',
        help = 'Give all collectables to a player',
        params = {
            { name = 'playerId', type = 'playerId', help = 'Player server ID' },
        },
    },

    admin_give_set = {
        enabled = true,
        restricted = 'group.admin',
        name = 'admin_col_give_set',
        help = 'Give a specific set to a player',
        params = {
            { name = 'playerId', type = 'playerId', help = 'Player server ID' },
            { name = 'setKey', type = 'string', help = 'Set key (e.g., action_figures)' },
        },
    },

    admin_remove_set = {
        enabled = true,
        restricted = 'group.admin',
        name = 'admin_col_remove_set',
        help = 'Remove a set from a player',
        params = {
            { name = 'playerId', type = 'playerId', help = 'Player server ID' },
            { name = 'setKey', type = 'string', help = 'Set key (e.g., action_figures)' },
        },
    },

    admin_give_item = {
        enabled = true,
        restricted = 'group.admin',
        name = 'admin_col_give_item',
        help = 'Give a specific item to a player',
        params = {
            { name = 'playerId', type = 'playerId', help = 'Player server ID' },
            { name = 'itemId', type = 'string', help = 'Item ID (e.g., action_figures_1)' },
        },
    },

    admin_remove_item = {
        enabled = true,
        restricted = 'group.admin',
        name = 'admin_col_remove_item',
        help = 'Remove an item from a player',
        params = {
            { name = 'playerId', type = 'playerId', help = 'Player server ID' },
            { name = 'itemId', type = 'string', help = 'Item ID (e.g., action_figures_1)' },
        },
    },
},
```

### Leaderboard

```lua
leaderboard = {
    enabled = true, -- Enable the leaderboard
    autoOptIn = false, -- New players automatically appear
    allowOptOut = true, -- Players can remove themselves via UI
    cacheInterval = 5, -- Refresh cache every X minutes
    maxEntries = 100, -- Show top X players
},
```

### Items

```lua
items = {
    stickerbook = {
        name = 'mad_collectables_stickerbook', -- Inventory item name
    },
    money = {
        name = 'money', -- Inventory item name
    },
},
```

### Trading

<pre class="language-lua"><code class="lang-lua">trading = {
    enabled = true, -- Master toggle for sticker trading
    maxDistance = 10.0, -- Max distance (in units) to find nearby players
<strong>},
</strong></code></pre>

### Show Off

```lua
showOff = {
    enabled = true, -- Master toggle for show-off feature
    maxDistance = 15.0, -- Max distance (in units) to find nearby players who can see the display
    cooldown = 6000, -- Cooldown between show-offs to prevent spam (ms)
    showNui = true, -- Whether to show the NUI overlay to nearby players
    showDui = true, -- Whether to render the DUI texture on the held prop
    showAnimation = true, -- Whether to play the hold-up animation on the showing player
},
```

### Security

```lua
maxCollectDistance = 5.0, -- Max distance for valid collection
kickPlayerOverMaxDistance = true, -- Kick players who exceed distance
kickReason = 'You have been kicked for attempted exploitation.', -- Message send to the player on kick
```

### Logging

Discord webhook logging for various events.

```lua
logs = {
    authorName = '✨ Collectables', -- Name for the log author (anything)
    username = 'Collectables Logs', -- Username for the log author (anything)
    iconUrl = '', -- URL for the icon used in the author
    tagType = '@admin', -- Role to ping in tagged logs

    pickup = {
        enabled = true, -- Whether the log is enabled
        webhook = '', -- Your Discord webhook URL
        tag = false, -- Whether to tag the tagType role when posted
    },

    adminReset = {
        enabled = true,
        webhook = '',
        tag = true,
    },

    adminGiveAll = {
        enabled = true,
        webhook = '',
        tag = true,
    },

    adminGiveSet = {
        enabled = true,
        webhook = '',
        tag = true,
    },

    adminRemoveSet = {
        enabled = true,
        webhook = '',
        tag = true,
    },

    adminGiveItem = {
        enabled = true,
        webhook = '',
        tag = true,
    },

    adminRemoveItem = {
        enabled = true,
        webhook = '',
        tag = true,
    },

    leaderboardUpdate = {
        enabled = true,
        webhook = '',
        tag = false,
        interval = 60, -- Minutes between updates
        topPlayers = 10, -- Number of top players to include
    },

    trade = {
        enabled = true,
        webhook = '',
        tag = false,
    },
},
```

#### Collectable Sets

See [Creating Sets](/docs/premium-resources/mad_collectables/creating-sets.md) for the full guide on configuring your collectable sets.


---

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