README

Visit our Discord / Homepage / Store !
Table of contents
​Requirements / Dependencies​
​Changelog​
​Setup script​
​Setup quests​
​Setup quest log item​
​Quest properties​
​Quest step properties​
​Known issues / bugs​
​FAQ​
Requirements / Dependencies
The following resources are required for nss_quest to work:
​nss_libs​
​Vorp Framework​
Changelog
See CHANGELOG.md for more information.
Setup script
1.Ensure that the nss_quest folder is in your resources folder.
2.Rename config.demo.lua to config.lua and fill in the values.
3.Ensure that the quest log item exists (see Setup quest log item)
4.Execute db.sql on your database.
5.Add ensure nss_quest to your server.cfg.
6.Restart your server.
Setup quests
1.Create a new file with the name of your quest, e.g. my_quest.lua, in quests folder.
2.Copy the following blueprint code into the file to create the basic quest. Adjust it to your needs.
local step1 = {
    id = "start", -- Unique quest id, only "a-zA-Z0-9_-" are allowed
    name = "Helping hand...", -- Step name, will be shown in the quest dialog
    btn_text = "Pickup the letter", -- Button text for the prompt
​
    location = {
        coords = { x = 0, y = 0, z = 0 }, -- Location where the step should be triggered
        radius = 2.0 -- Radius around the location where the step should be triggered
    },
​
    quest_text = "You found a letter on the floor.\n\n"
            .. "The letter reads:\n\n"
            .. "<em>Dear Sir,\n\n"
            .. "I am in need of your help. I am hungry and I need you to help me.\n\n"
            .. "Please meet me at the bank in Strawberry and bring 3 red berries.</em>\n\n",
​
    -- Rewards are optional, if you don't want rewards, remove the complete section.
    rewards = { -- In this case the rewards is used to give quest item
        items = {
            { name = "quest_letter", count = 1 }, -- Ensure that the item exists in your database
        }
    },
}
​
local step2 = {
    id = "end", -- Important: Do not use the same id as in step1. Ids must be unique.
    name = "Your letter...",
    btn_text = "Deliver red berries",
​
    location = {
        coords = { x = 0, y = 0, z = 0 },
        radius = 2.0
    },
​
    quest_text = "You deliver the letter and the red berries to an old man.\n\n"
            .. "He says:\n\n"
            .. "<em>Thank you Sir,\n\n"
            .. "The red berries are delicious. Here is a little something from me.</em>\n\n",
​
    -- Requirements are optional, if you don't want requirements, remove the complete section.
    requires = { -- In this case we require the player to have the quest item from previous step and 3 red berries
        items = {
            {
                name = "quest_letter",
                count = 1,
                remove = true -- Remove the item from the player inventory if the step is completed 
            },
            {
                name = "red_berries",
                count = 3,
                remove = true-- Remove the item from the player inventory if the step is completed 
            }
        },
    },
​
    -- Rewards are optional, if you don't want rewards, remove the complete section.
    rewards = {
        items = {
            { name = "coal", count = 1 }, -- Gives the player 1 coal if the step is completed
        },
        money = {
            amount = 5, -- Gives the player 5$ in cash if the step is completed
        },
    },
}
​
MyQuest = { -- Do not use "local MyQuest" because the variable should be accessible in the config file. 
    id = "my_quest", -- Unique quest id, only "a-zA-Z0-9_-" are allowed
    name = "My Quest", -- Quest name, will be shown in the prompt
    max_solves = 1, -- How many times can the quest be solved, 0 = infinity
    steps = { step1, step2 } -- The steps of the quest
}
3.Go into config.lua file and add your new quest MyQuest to the Config.Quests table.
-- Example for only one quest
Config.Quests = { MyQuest }
​
-- Example for more quests
Config.Quests = {
    MyQuest,
    OtherQuest,
    AnotherQuest
}
4.Restart your server and test your quest.

Tip: You can use refresh in the console to reload the resources without restarting the server. And after that use restart nss_quest to reload the quest data.
Setup quest log item
New since version 1.2.0.
1.Add quest log item (see example below) to your inventory database:
INSERT INTO ingame01.items (item, label, `limit`, can_remove, type, usable, `desc`, metadata)
VALUES ('YOUR_QUEST_LOG_ITEM_NAME', 'Questlog', 1, 0, 'item_standard', 1, '', '{}');
Important: Item should be configured as non-removable, usable and with a limit of 1.
2.Add YOUR_QUEST_LOG_ITEM_NAME to Config.QuestLogItemName property in the config file.
3.Copy html_quest/img/quest_log_item.png to vorp_inventory/html/img/items/YOUR_QUEST_LOG_ITEM_NAME.png (or use your own image).
4.Note: YOUR_QUEST_LOG_ITEM_NAME is a placeholder, you can choose any name you want.
Quest properties
id (text, required)

The id is a unique identifier for the quest. Ensure that these id only exists one time only. The id is used to identify the quest in the config file and for internal programming things.

Important: Only a-zA-Z0-9 and -_ are allowed.


name (text, required)

The name is the name of the quest. It will be shown in the prompt and quest dialog.


description (text, optional)

The description is the internal description for the quest, e.g. like notes for the quest writers. It is currently not used and shown anywhere.


max_solves (number, required)

A positive number limits the times a quest can be solved. A value of 0 means that the quest can be solved infinite times.


restart_delay_in_seconds (number, optional)

A positive number (in seconds) adds a delay until the next start of the quest. A value of 0 means no delay.

Note: Set max_solves to 0 to allow infinite solves for daily quests.


steps (list, required)

The steps is a list of all steps for the quest. The steps are executed in the order they are defined in the list. See Quest steps for more information.


Quest step properties
id (text, required)

The id is a unique identifier for the quest step. Ensure that these id only exists one time only.

Important: Only a-zA-Z0-9 and -_ are allowed.


name (text, required)

The name is the name of the quest step. It will be shown in the quest dialog.


description (text, optional)

The description is the internal description for the quest step, e.g. like notes for the quest writers. It is currently not used and shown anywhere.


btn_text (text, required)

The btn_text is the text for the button in the prompt. It will be shown in the prompt.


location (table, required)

The location contains the coords and radius for the quest step triggering point.

Example:
location = { 
  coords = { x = -858.72, y = -1340.31, z = 44.43 }, 
  radius = 2.0 
}
coords (table, required)

The coords is a list of the x, y and z coordinates for the quest step triggering point.

Example:
coords = { 
  x = -858.72, 
  y = -1340.31, 
  z = 44.43 
}
radius (number, required)

The radius is the radius around the coords where the quest step should be triggered.

Ensure a float (e.g. 2.0) and not an integer (e.g. 2) is given.


quest_text (text, required)

The quest_text is the text for the quest dialog. It will be shown in the quest dialog. Can contain HTML tags.


callback (function, optional)

The callback is a function that is called when the quest step is started/accepted. It can be used to add custom logic like spawning a vehicle or giving weapons to the player.

Important: The callback will be executed on server side.

Example:
---@param _source number @The player source (server player id)
---@param step NssQuestStep @The current quest step (see configured step for possible properties)
---@param char NssQuestCharacter @The character that accepted the quest
callback = function(_source, step, char)
    print("Character properties", json.encode(char))
end
requires (table, optional)

The requires is a list of requirements for the quest step.

The requirements are checked before the quest step is started/accepted.


items (table, optional)

The items is a list of items that are required for the quest step.

If remove is set to true, the item will be removed from the player inventory if the quest step starts/ends.

label is optional and can be used to overwrite the item label in the quest dialog.

Important: The item must exists in the database of the supported framework.

Example:
items = { 
  { name = "red_berries", count = 3, remove = true, label = "Custom label for item" }, 
}
money (table, optional)

The money is a list of money that are required for the quest step.

If remove is set to true, the money will be removed from the player inventory if the quest step starts/ends.

Example:
money = { amount = 5, remove = true }
completed_quests (list, optional)

The completed_quests is a list of quests that are required for the quest step.

Example:
completed_quests = { "quest_id1" }
rewards (table, optional)

The rewards is a list of rewards for the quest step.


items (table, optional)

The items is a list of rewards for the quest step.

label is optional and can be used to overwrite the item label in the quest dialog.

Important: The item must exists in the database of the supported framework.

Example:
items = {
    { name = "red_berries", count = 3, label = "Custom label for item" },
}
money (table, optional)

The money is a list of money as rewards for the quest step.

Example:
money = { amount = 5 }
background_filename (text, optional)

The background_filename is the filename of the background image for the quest dialog. The image must be located in the html_quest/img folder.


padding_left / padding_top / padding_right / padding_bottom (number, optional)

The padding_left, padding_top, padding_right and padding_bottom are the padding for the quest dialog. The padding is used to move the quest content inside the quest dialog, e.g. if you use your own background image.


title_color (text, optional, default is black)

The title_color is the color for the quest title in the quest dialog. The color must be a valid CSS color, like #ff0000 or red.


text_color (text, optional, default is black)

The text_color is the color for the quest text in the quest dialog. The color must be a valid CSS color, like #ff0000 or red.


shadow_color (text, optional, default is none)

The shadow_color is the color for the quest text shadow in the quest dialog. The color must be a valid CSS color, like #ff0000 or red.


marker (table, optional, new since 1.2.0)

The marker defines if a special symbol is shown at the given coordinates so the player can see the location before he arrives.

Example:
marker = { 
  coords = { x = -858.72, y = -1340.31, z = 44.43 }, 
  radius = 10.0,
  type = 0x94FDAE17,
  color = { r = 102, g = 0, b = 255 },
}
coords (table, required)

The coords is a list of the x, y and z coordinates for the marker triggering point.

Example:
coords = { 
  x = -858.72, 
  y = -1340.31, 
  z = 44.43 
}
radius (number, required)

The radius is the radius around the coords where the marker should be triggered.

Ensure a float (e.g. 10.0) and not an integer (e.g. 10) is given.


type (number, required)

The type is the visiable type of the marker. See Marker Types for available types.


color (table, required)

The color is a list of the r (red), g (green) and b (blue) color values for the marker.

Example:
color = { 
  r = 255, 
  g = 0, 
  b = 0 
}
blip (table, optional, new since 1.2.0)

The blip allows to show a blip on the map for the quest step coordinates.

Example:
blip = {
    color = 'BLIP_MODIFIER_PICKUP_WEAPON_RARE',
    title = "Example title",
    icon = "blip_ambient_king",
}
color (string, required)

The color of the blip. See Blip Colors for available colors.


title (string, required)

The title of the blip.


icon (number, required)

The icon of the blip. See Blip Multiplayer Icons and Blip Singleplayer Icons for available icons.


radius_blip (table, optional, new since 1.2.0)

The radius_blip allows to show a radius blip with a defined radius on the map for the quest step coordinates.

Example:
radius_blip = {
    color = 'BLIP_MODIFIER_PICKUP_WEAPON_RARE',
    radius = 200.0,
}
color (string, required)

The color of the blip. See Blip Colors for available colors.


radius (float number, required)

The radius in meters of the blip.


Known issues / bugs
No known issues/bugs at the moment.
FAQ
How can I give weapons to the player?
Currently, it is not possible to give weapons to the player. But you can use the callback function to give weapons to the player.
How many steps can a quest have?
Unlimited.
How many quests can be configured?
Unlimited.
Changelog
Last modified 1mo ago