Configuration

How do you like it?

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

---

Shared Config

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

Debug

debug = {
    showBlips = true, -- 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
},

Outlines and highlights are client resource intensive tasks.

Notifications

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

Text UI

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

Objects

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

Targets

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

Prompts

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

Sounds

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

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
    },
},

---

Client Config

config/client.lua - Client-side settings.

UI

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)

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

Keybinds

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

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

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

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

Security

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.

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
    },
},

Collectable Sets

See Creating Sets for the full guide on configuring your collectable sets.