Creating Sets

Creating Collectable Sets

Sets are themed collections of items for players to find. Configure them in config/server.lua.

Example

sets = {
    my_set_name = {
        -- Display
        label = 'My Set Name',
        description = 'Find all the items in this set!',

        -- Object
        model = 'prop_box_wood01a',
        icon = 'my_icon.png',
        grounded = true,

        -- Pickup
        pickupType = 'target',
        pickupDistance = 2.5,

        -- State
        enabled = true,

        -- Hints
        hint = 'Look around the city...',

        -- Rewards
        rewards = {
            onCollect = { money = 100, moneyType = 'cash' },
            onComplete = { money = 5000, moneyType = 'bank' },
        },

        -- Locations
        items = {
            { coords = vec3(123.45, 678.90, 12.34) },
            { coords = vec3(234.56, 789.01, 23.45), hint = 'Near the bench' },
        },
    },
},

---

Set Structure

Structure for set table.

• label: Label

  • Display name for the set shown in the UI

• description: Description

  • Description for the set shown in the UI

• model Model

  • Model for the spawned collectable object

• icon: Icon

  • Icon for stickers in UI (image path 'action-figure-pogo.png', or 'fa:icon-name' for Font Awesome)

• grounded? Grounded

  • Whether to snap the spawned object to the ground, (default: true)

• pickupType? PickupType

  • How to collect the item, (default: 'target')

• pickupDistance? PickupDistance

  • Distance to trigger pickup (default: 1.5)

• enabled? Enabled

  • Whether to enable this collectable set (default: true)

• collectSound? Sound

  • Play sound on collection (default: true for 'nearby', false for 'target' and 'prompt')

• hint? Hint

  • Default hint for all items in set

• rewards? Rewards

  • Rewards for collecting items and completing the set

• blip? Blip

  • Optional blip for all items

• animations? Animations

  • Animations to use for this set

• items Items

  • List of collectable items in this set

---

Items Structure

Structure for items table.

• coords: vector3

  • Where to spawn the collectable object

• rotation?: number

  • Optional rotation of the collectable object

• grounded?: Grounded

  • Optional toggle of snapping object to ground for this item

• model? Model

  • Optional model for this item

• icon?: Icon

  • Optional icon for this item

• hint? Hint

  • Optional hint for this item

• blip? Blip

  • Optional blip for this item

• animations? Animations

  • Optional animation for this item

• collectSound? Sound

  • Optional sound played when item is picked up for this item

---

Set Options

Display

Option	Type	Description
label	string	Name shown in the UI
description	string	Description shown in the UI

Object

Option	Type	Default	Description
model	string	required	Prop model to spawn
icon	string	-	Sticker image (filename or fa:icon)
grounded	boolean	true	Snap object to ground

Pickup

Option	Type	Default	Description
pickupType	string	'target'	How to collect: 'target', 'prompt', or 'nearby'
pickupDistance	number	1.5	Distance to trigger pickup

Pickup Types:

• 'target' - Requires target resource in bridge

• 'prompt' - Shows TextUI prompt, press key to collect

• 'nearby' - Auto-collects when player is within range

Enabled

Type	Description
boolean	Whether to enable this set

Blip

Option	Type	Default	Description
enabled	boolean	true	Whether to enable the blip
sprite	number	57	The sprite to use for the blip
colour	number	1	The colour to use for the blip sprite
title	string	nil	The name to use for the blip

Sound

Option	Type	Default	Description
collectSound	boolean/table	varies	Sound on collection

-- Use default sound
collectSound = true,

-- Disable sound
collectSound = false,

-- Custom sound
collectSound = {
    audioName = 'PLAYER_COLLECT', -- Name of the audio to play
    audioRef = 'DLC_PILOT_MP_HUD_SOUNDS', -- Audio reference/set to use
},

Default: true for 'nearby' pickup type, false for others.

Animations

Option	Type	Default	Description
pickup	table	nil	Animation to play on the client when an object is collected

animations = { -- Animations to use for this set
    pickup = { -- Pickup animation
       animDictionary = 'anim@move_m@trash', -- The animation dictionary
       animationName = 'pickup', -- The name of the animation within the dictionary
       animFlags = 0, -- Animation flag
       duration = 3000, -- Duration in milliseconds
    },
},

Hints

Option	Type	Description
hint	string	Default hint for all items in the set

Individual items can override the set hint:

items = {
    { coords = vec3(123.45, 678.90, 12.34) },                    -- Uses set hint
    { coords = vec3(234.56, 789.01, 23.45), hint = 'Custom' },   -- Uses custom hint
},

Rewards

rewards = {
    onCollect = {
        money = 100,
        moneyType = 'cash',  -- 'cash' or 'bank'
        item = { name = 'token', count = 1 },
    },
    onComplete = {
        money = 5000,
        moneyType = 'bank',
        item = { name = 'trophy', count = 1 },
    },
},

Option	Type	Description
onCollect	table	Reward given each time an item is collected
onComplete	table	Reward given when the set is completed
money	number	Amount of currency
moneyType	string	'cash' or 'bank'
item	table	Optional inventory item { name, count }

Full Example

example_set = { -- Unique set name
    label = 'Example Set', -- Display name for the set
    description = 'This is the set description shown in the UI', -- Description shown in UI
    model = 'xm3_prop_xm3_box_wood03a', -- Prop model to spawn
    icon = 'action-figure-pogo.png', -- Icon for stickers in UI (image path 'action-figure-pogo.png', or 'fa:icon-name' for Font Awesome)
    grounded = true, -- Place object on ground (default: true)
    pickupType = 'target', -- How to collect: 'target' | 'prompt' | 'nearby' (default: 'target')
    pickupDistance = 2.5, -- Distance to trigger pickup (default: 1.5)
    enabled = false, -- Enabled/disable the collectable set
    collectSound = { -- Play sound on collection: boolean|table (default: true for 'nearby', false for 'target' and 'prompt')
        audioName = 'PLAYER_COLLECT', -- Name of the audio to play
        audioRef = 'DLC_PILOT_MP_HUD_SOUNDS', -- Audio reference/set to use
    },
    hint = 'The hint for all the items', -- Default hint for all items in set
    rewards = { -- Rewards for collecting items and completing the set
        onCollect = { money = 100, moneyType = 'cash' }, -- Reward for each collected item
        onComplete = { -- Reward for completing the entire set
            money = 5000, -- Amount of money
            moneyType = 'bank', -- Money type to give ('cash', 'bank')
            item = { name = 'reward_trophy', count = 1 }, -- Item to give and amount
        },
    },
    blip = { -- Optional blip for all items (https://docs.fivem.net/docs/game-references/blips/)
        enabled = true, -- Enable/disable the blip (enabled by default)
        sprite = 478, -- Blip sprite
        colour = 1, -- Blip colour
        title = 'Example Collectable Item', -- Blip title
        scale = 0.5, -- Optional custom scale
    },
    animations = { -- Animations to use for this set
        pickup = { -- Pickup animation
            animDictionary = 'anim@move_m@trash', -- The animation dictionary
            animationName = 'pickup', -- The name of the animation within the dictionary
            animFlags = 0, -- Animation flag
            duration = 3000, -- Duration in milliseconds
        },
    },
    items = { -- List of collectable items in this set
        { coords = vec3(-140.39, -173.98, 93.70) }, -- With just coordinates
        { coords = vec3(-146.05, -166.42, 95.00), grounded = false }, -- With grounded override
        { coords = vec3(-133.97, -163.08, 93.70), model = 'prop_alien_egg_01' }, -- With model override
        { coords = vec3(-129.66, -163.58, 93.70), icon = 'fa star' }, -- With image override
        { coords = vec3(-138.27, -163.77, 93.70), hint = 'A hint just for this item' }, -- With hint override
        {
            coords = vec3(-140.48, -164.42, 93.70), -- With multiple overrides
            grounded = false,
            model = 'prop_box_ammo07a',
            icon = 'fa box-open',
            hint = 'This box looks different..',
        },
        {
            coords = vec3(-145.03, -170.40, 93.70), -- With optional blip
            blip = { -- Optional blip for this item
                sprite = 514, -- Blip sprite
                colour = 27, -- Blip colour
                title = 'Special Test Box', -- Blip title
                scale = 0.7, -- Optional custom scale
            },
        },
        {
            coords = vec3(-141.85, -166.10, 93.70), -- With animation override
            animations = { -- Animation only for this item
                pickup = { -- Pickup animation
                    animDictionary = 'anim@gangops@facility@servers@bodysearch@', -- The animation dictionary
                    animationName = 'player_search', -- The name of the animation within the dictionary
                    animFlags = 0, -- Animation flag
                    duration = 1500, -- Duration in milliseconds
                },
            },
        },
        {
            coords = vec3(-130.67, -168.78, 92.70), -- With collect sound override
            collectSound = {
                audioName = 'RANK_UP',
                audioRef = 'HUD_AWARDS',
            },
        },
    },
},

---

Tips

• Use unique keys for each set (e.g., action_figures, movie_posters)

• The key is used internally; players see the label

• Set enabled = false to disable a set without removing it

• Use the coordinate finder to place items

• Test pickup distances in-game to find what feels right

• If an item you create is spawning inside another object, try using grounded = false, then manually adjust the z coordinate