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.
How players use missions
Section titled “How players use missions”- The player opens the Battle Pass and picks a mission.
- The player clicks Start Mission. The mission starts, its GPS is pinned and a short “how it works” message appears (see
ShowStartInstructionsin Configuration). - The player completes the objective. Progress messages appear as set by
ProgressNotificationMode. - When the mission is complete, the player claims its XP in the Battle Pass window.
- 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).
The mission table
Section titled “The mission table”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.
Mission types
Section titled “Mission types”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.
Parameters per type
Section titled “Parameters per type”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.
Add a mission in the config
Section titled “Add a mission in the config”- Open
config/quests.lua. - Copy an entry of the type you want, at the end of the list, before the closing
}. - Give it a new unique
id, and changetitle,description,required,xpRewardandparams. - 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' }, }, },},In-game quest creator
Section titled “In-game quest creator”Admins can create missions without touching any file.
-
Run
/kivobpadminand choose Create quest. See Admin tools. -
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 {}. -
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';Test a mission
Section titled “Test a mission”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.
Progress from other scripts
Section titled “Progress from other scripts”Other server scripts can add progress to a mission with an export. See Exports and bridge files.
Next: Admin tools.
