Skip to content

Missions

Missions are how players earn XP. Each mission is either daily or weekly. The built-in missions are listed in config/quests.lua, and admins can add more from the in-game quest creator.

  1. The player opens the Battle Pass and picks a mission.
  2. The player clicks Start Mission. The mission starts, its GPS is pinned and a short “how it works” message appears (see ShowStartInstructions in Configuration).
  3. The player completes the objective. Progress messages appear as set by ProgressNotificationMode.
  4. When the mission is complete, the player claims its XP in the Battle Pass window.
  5. Daily missions come back every day and weekly missions every week. The window shows a countdown to the next reset.

Players can stop a mission with Stop or show its GPS again with Show GPS. By default a player can track one mission at a time (AllowMultipleTrackedMissions).

Each entry in Config.Quests is one mission:

{
id = 'daily-1',
period = 'daily',
questType = 'playTime',
title = 'Play Time',
description = 'Click to start, then stay online and keep moving. AFK time does not count.',
required = 10,
xpReward = 800,
params = {},
},
Field Type Description
id string Unique id, up to 64 characters. Progress is saved under this id, so do not rename a mission that players are already working on.
period string 'daily' or 'weekly'.
questType string Mission type. See Mission types.
title string Title shown to the player.
description string Description shown to the player.
required number The target a player must reach. What it counts depends on the mission type.
xpReward number XP the player gets when claiming the mission.
params table Type specific settings such as locations and radii. Use an empty table {} for types that need none.

Missions in the config and missions made with the quest creator are shown together. Reset times follow Config.TimezoneOffsetHours.

questType Shown as What the player does required counts
playTime Play Time Stays online and keeps moving. AFK time does not count. Progress steps. One step takes PlayTimeMinutes minutes, or the mission’s minutesPerTick.
waypoint Way Point Drives through each marked checkpoint. Checkpoints reached.
object Object Hunt Follows the GPS to a search area and walks into the objects to collect them. Objects collected.
socialGathering Social Gathering Stays inside a marked zone and keeps moving. Progress steps of secondsPerTick seconds each.
emoteSpot Emote Spot Presses E at a marker and holds an emote. Completed emotes.
drunkActivities Drunk Activities Gets drunk, then drives, shoots or fights. Activities completed while drunk.
yoga Yoga Stands on a yoga mat, presses E and holds the pose. Completed sessions. Each mat counts once.
damageContract Damage Contract Deals damage in fights. Total damage dealt.
timeRace Time Race Goes to the start marker, accepts the race and reaches the finish before the countdown ends. Races finished in time.
eliminationZone Elimination Zone Scores kills inside a marked red zone. Kills in the zone.
peyoteTime Peyote Time Presses E on a peyote plant and survives until the timer ends. Completed transformations.

Mission types that use several points (waypoint, object, yoga) count each point once, so list at least as many points as required. The shipped missions follow this rule.

All coordinates are tables like { x = 195.17, y = -933.77, z = 30.69 }. Distances are in meters.

playTime

Param Description
minutesPerTick Optional. Minutes of active play for one progress step. When left out, Config.PlayTimeMinutes is used.

waypoint

Param Description
radius How close the player must get to a checkpoint.
points List of checkpoints. Each is { x, y, z, label }.

object

Param Description
model Prop model name of the object, for example 'prop_money_bag_01'.
pickupRadius How close the player must get to collect an object.
points List of object locations. Each is { x, y, z }.

socialGathering

Param Description
coords Center of the zone.
radius Radius of the zone.
secondsPerTick Seconds a player must spend in the zone for one progress step.

emoteSpot

Param Description
coords Location of the marker.
radius How close the player must stand to the marker.
seconds How long the player must hold the emote.
dict Animation dictionary name.
clip Animation clip name.
flag Animation flag. The shipped missions use 49.
prompt Text of the prompt shown at the marker.

drunkActivities

Param Description
actions List of actions that count. Allowed values are 'drive', 'shoot' and 'melee'.

yoga

Param Description
durationMs How long the player must hold the pose, in milliseconds.
mats List of yoga mat locations. Each is { x, y, z, heading }.

damageContract

No params. Use params = {}.

timeRace

Param Description
start Location of the start marker.
finish Location of the finish marker.
radius Size of the start area. The player must stay inside it to accept the race.
finishRadius Size of the finish area.
timeLimit Time to reach the finish, in seconds.

eliminationZone

Param Description
coords Center of the red zone.
radius Radius of the red zone.

peyoteTime

Param Description
model Prop model name of the peyote plant.
animal Ped model the player turns into, for example 'a_c_boar'.
pickupRadius How close the player must get to pick the plant.
durationMs How long the transformation lasts, in milliseconds.
points List of plant locations. Each is { x, y, z }.

Set every param shown above for the type you use, as the shipped missions do.

  1. Open config/quests.lua.
  2. Copy an entry of the type you want, at the end of the list, before the closing }.
  3. Give it a new unique id, and change title, description, required, xpReward and params.
  4. Restart the resource.

Example, a weekly Play Time mission that needs two hours of active play:

{
id = 'weekly-10',
period = 'weekly',
questType = 'playTime',
title = 'Two Hour Shift',
description = 'Click to start, then stay online and active. AFK time does not count.',
required = 4,
xpReward = 2000,
params = {
minutesPerTick = 30,
},
},

Example, a daily Way Point mission with two checkpoints:

{
id = 'daily-10',
period = 'daily',
questType = 'waypoint',
title = 'City Tour',
description = 'Click to pin GPS, then drive to every marked checkpoint on the map.',
required = 2,
xpReward = 900,
params = {
radius = 8.0,
points = {
{ x = 195.17, y = -933.77, z = 30.69, label = 'Legion Square' },
{ x = 372.28, y = 252.81, z = 103.01, label = 'Vinewood Blvd' },
},
},
},

Admins can create missions without touching any file.

  1. Run /kivobpadmin and choose Create quest. See Admin tools.

  2. Fill in the form:

    Field Description
    Period Daily or Weekly.
    Quest type One of the eleven types in the table above.
    Title Up to 128 characters.
    Description Up to 512 characters.
    Required The target. At least 1.
    XP reward XP given when the player claims the mission. At least 0.
    Params JSON The type specific settings as JSON. Default {}.
  3. Confirm. Online players receive the new mission straight away.

Use the same structure for the Params JSON as the params table of the same type in config/quests.lua. For example, a Way Point mission with two checkpoints:

{
"radius": 8.0,
"points": [
{ "x": 195.17, "y": -933.77, "z": 30.69, "label": "Legion Square" },
{ "x": 372.28, "y": 252.81, "z": 103.01, "label": "Vinewood Blvd" }
]
}

If the JSON is not valid, the mission is created with empty params and has no locations, so it cannot be completed.

Created missions are saved in the kivo_bp_custom_quests table and get an id like custom-1790812800-123. There is no menu entry to edit or delete a created mission. To switch one off, set its enabled column to 0 and restart the resource:

UPDATE kivo_bp_custom_quests SET enabled = 0 WHERE quest_id = 'custom-1790812800-123';

Use /kivobptest <missionId> [id], or Test mission in the admin menu. It starts the mission for the player and moves the player to its test location, so you can check it without driving across the map. The mission id is the id of the mission, for example daily-2.

Other server scripts can add progress to a mission with an export. See Exports and bridge files.

Next: Admin tools.