Missions

Mission System

The mission system allows players to earn coins by completing various tasks. It supports both automatic tracking missions and custom missions that integrate with your other resources.

Mission Types

Built-in Mission Types

These missions track automatically without additional coding:

Type	Description	Automatic Tracking
distance_walked	Tracks player walking distance	✅ Yes
distance_driven	Tracks vehicle driving distance	✅ Yes
jumps	Tracks player jumps	✅ Yes
location_discovery	Tracks visiting specific locations	✅ Yes

Custom Mission Types

Type	Description	Automatic Tracking
custom	Missions triggered via server events	❌ Manual trigger required

Adding Built-in Missions

Add missions to Config.Missions.BuiltInMissions in shared/config.lua:

Config.Missions = {
    BuiltInMissions = {
        {
            id = "walker_basic",
            name = "Daily Walker",
            description = "Walk {target} meters on foot",
            type = "distance_walked",
            target = 2000,
            reward = 100,
            enabled = true,
            weight = 10
        },
        {
            id = "driver_city",
            name = "City Driver", 
            description = "Drive {target} meters with a vehicle",
            type = "distance_driven",
            target = 15000,
            reward = 150,
            enabled = true,
            weight = 8
        },
        {
            id = "jumper_parkour",
            name = "Parkour Pro",
            description = "Jump {target} times",
            type = "jumps",
            target = 100,
            reward = 75,
            enabled = true,
            weight = 6
        }
    }
}

The {target} placeholder gets replaced with the actual target value in the UI.

Adding Custom Missions

Custom missions require manual progress triggering from your other resources:

Config.Missions = {
    CustomMissions = {
        {
            id = "delivery_driver",
            name = "Delivery Driver", 
            description = "Complete {target} deliveries",
            type = "custom",
            target = 5,
            reward = 200,
            enabled = true,
            weight = 8,
            triggerEvent = "coinsystem:missionProgress",
            triggerKey = "delivery_driver"
        },
        {
            id = "taxi_rides",
            name = "Taxi Driver",
            description = "Complete {target} taxi rides",
            type = "custom",
            target = 10,
            reward = 250,
            enabled = true,
            weight = 7,
            triggerEvent = "coinsystem:missionProgress",
            triggerKey = "taxi_rides"
        }
    }
}

Location Discovery Missions

For missions that require visiting specific locations:

{
    id = "city_explorer",
    name = "City Explorer",
    description = "Visit all {target} locations",
    type = "location_discovery", 
    target = 3,
    reward = 150,
    enabled = true,
    weight = 7,
    locations = {
        {name = "Hospital", coords = vector3(295.0, -1446.0, 29.0), radius = 50},
        {name = "Airport", coords = vector3(-1037.0, -2963.0, 13.0), radius = 100},
        {name = "Police Station", coords = vector3(425.0, -979.0, 30.0), radius = 40}
    }
},
{
    id = "island_explorer",
    name = "Island Explorer", 
    description = "Explore {target} remote locations",
    type = "location_discovery",
    target = 5,
    reward = 300,
    enabled = true,
    weight = 4,
    locations = {
        {name = "Sandy Shores", coords = vector3(1663.0, 4739.0, 42.0), radius = 100},
        {name = "Paleto Bay", coords = vector3(-102.0, 6392.0, 31.0), radius = 80},
        {name = "Fort Zancudo", coords = vector3(-2047.0, 3132.0, 32.0), radius = 150},
        {name = "Mount Chiliad", coords = vector3(450.0, 5566.0, 781.0), radius = 50},
        {name = "Stab City", coords = vector3(56.0, 3717.0, 39.0), radius = 60}
    }
}

Mission Properties

Property	Type	Description	Required
id	String	Unique mission identifier	✅ Yes
name	String	Display name in UI	✅ Yes
description	String	Mission description with {target} placeholder	✅ Yes
type	String	Mission type (see types above)	✅ Yes
target	Number	Goal amount to complete mission	✅ Yes
reward	Number	Coins given when completed	✅ Yes
enabled	Boolean	Whether mission is active	✅ Yes
weight	Number	How often mission appears (1-10, higher = more frequent)	✅ Yes
triggerEvent	String	Event name for custom missions	⚠️ Custom only
triggerKey	String	Key passed to event for custom missions	⚠️ Custom only
locations	Array	Array of locations for discovery missions	⚠️ Location only

Location Object Properties

Property	Type	Description	Example
name	String	Location name	"Hospital"
coords	Vector3	Location coordinates	vector3(295.0, -1446.0, 29.0)
radius	Number	Detection radius in meters	50

Triggering Custom Mission Progress

From your other resources, trigger mission progress using events:

-- Basic progress trigger
TriggerEvent('coinsystem:missionProgress', source, 'delivery_driver', 1)

-- Multiple progress at once
TriggerEvent('coinsystem:missionProgress', source, 'taxi_rides', 3)

Parameters:

• source - Player server ID

• mission_id - The mission ID from config (must match triggerKey)

• progress - Amount to add to progress (usually 1)

Integration Examples

Job Script Integration

-- In your job script, when player completes a task
RegisterServerEvent('esx_truckerJob:paycheck')
AddEventHandler('esx_truckerJob:paycheck', function(payment)
    local source = source
    
    -- Give normal payment
    local xPlayer = ESX.GetPlayerFromId(source)
    xPlayer.addMoney('cash', payment)
    
    -- Update trucker mission progress
    TriggerEvent('coinsystem:missionProgress', source, 'trucker_mission', 1)
end)

Taxi Job Integration

RegisterServerEvent('esx_taxi:payFare')
AddEventHandler('esx_taxi:payFare', function(fare)
    local source = source
    
    -- Normal taxi payment
    local xPlayer = ESX.GetPlayerFromId(source)
    xPlayer.addMoney('cash', fare)
    
    -- Update taxi mission
    TriggerEvent('coinsystem:missionProgress', source, 'taxi_rides', 1)
end)

Delivery Script Integration

RegisterServerEvent('delivery:packageDelivered')
AddEventHandler('delivery:packageDelivered', function(package)
    local source = source
    
    -- Give delivery payment
    local xPlayer = ESX.GetPlayerFromId(source)
    xPlayer.addMoney('cash', package.payment)
    
    -- Update delivery mission
    TriggerEvent('coinsystem:missionProgress', source, 'delivery_driver', 1)
    
    -- Give bonus coins
    exports['coinsystem_esx']:AddPlayerCoins(source, 15, "Delivery completed")
end)

Mechanic Job Integration

RegisterServerEvent('esx_mechanicjob:onVehicleRepaired')
AddEventHandler('esx_mechanicjob:onVehicleRepaired', function()
    local source = source
    
    -- Update mechanic mission
    TriggerEvent('coinsystem:missionProgress', source, 'mechanic_repairs', 1)
end)

Fishing Script Integration

RegisterServerEvent('fishing:fishCaught')
AddEventHandler('fishing:fishCaught', function(fishType)
    local source = source
    
    -- Give fish to player
    local xPlayer = ESX.GetPlayerFromId(source)
    xPlayer.addInventoryItem(fishType, 1)
    
    -- Update fishing mission
    TriggerEvent('coinsystem:missionProgress', source, 'fishing_mission', 1)
end)

Mission Configuration Examples

Trucker Job Missions

{
    id = "trucker_local",
    name = "Local Trucker",
    description = "Complete {target} local deliveries",
    type = "custom",
    target = 5,
    reward = 150,
    enabled = true,
    weight = 8,
    triggerEvent = "coinsystem:missionProgress",
    triggerKey = "trucker_local"
},
{
    id = "trucker_long",
    name = "Long Haul Driver", 
    description = "Complete {target} long distance deliveries",
    type = "custom",
    target = 3,
    reward = 250,
    enabled = true,
    weight = 5,
    triggerEvent = "coinsystem:missionProgress", 
    triggerKey = "trucker_long"
}

Police Job Missions

{
    id = "police_arrests",
    name = "Law Enforcer",
    description = "Make {target} arrests",
    type = "custom",
    target = 5,
    reward = 200,
    enabled = true,
    weight = 6,
    triggerEvent = "coinsystem:missionProgress",
    triggerKey = "police_arrests"
},
{
    id = "police_fines",
    name = "Traffic Controller", 
    description = "Issue {target} traffic fines",
    type = "custom",
    target = 10,
    reward = 100,
    enabled = true,
    weight = 8,
    triggerEvent = "coinsystem:missionProgress",
    triggerKey = "police_fines"
}

Medical Job Missions

{
    id = "medic_revives",
    name = "Life Saver",
    description = "Revive {target} players",
    type = "custom", 
    target = 5,
    reward = 180,
    enabled = true,
    weight = 7,
    triggerEvent = "coinsystem:missionProgress",
    triggerKey = "medic_revives"
}

Mission Management

Mission Reset System

Missions automatically reset daily at midnight server time. Progress is tracked per player and mission.

Mission Weights

Weight determines how frequently a mission appears:

Weight	Frequency
1-3	Rare
4-6	Uncommon
7-8	Common
9-10	Very Common

Enabling/Disabling Missions

-- Disable a mission temporarily
{
    id = "seasonal_mission",
    name = "Christmas Special",
    enabled = false,  -- Mission won't appear
    -- ... rest of config
}

Best Practices

Mission Design Tips

1. Use unique mission IDs to avoid conflicts with other resources

2. Set realistic targets - not too easy, not impossible

3. Balance rewards with effort required

4. Test progress triggers thoroughly before deploying

5. Use descriptive names that players understand

6. Consider server population when setting targets

7. Weight missions appropriately - harder missions should be rarer

Integration Notes

• Built-in missions track automatically - no additional code needed

• Custom missions require manual progress triggering via events

• Location discovery missions need valid coordinates and reasonable radius

• Mission progress is cumulative and persists until daily reset

• VIP players receive multiplied mission rewards based on Config.VIP.Multipliers.Rewards

Important Considerations

• Always test custom mission triggers with your specific job scripts

• Mission IDs must be unique across all missions

• Location coordinates should be tested in-game for accuracy

• Weight values affect mission selection probability - use wisely