NSS Docs
nss_quest
Ask or search…
K
Links

README

Visit our Discord / Homepage / Store !

Table of contents


Requirements / Dependencies

The following resources are required for nss_quest to work:

Changelog

See CHANGELOG.md for more information.

Setup script

  1. 1.
    Ensure that the nss_quest folder is in your resources folder.
  2. 2.
    Rename config.demo.lua to config.lua and fill in the values.
  3. 3.
    Ensure that the quest log item exists (see Setup quest log item)
  4. 4.
    Execute db.sql on your database.
  5. 5.
    Add ensure nss_quest to your server.cfg.
  6. 6.
    Restart your server.

Setup quests

  1. 1.
    Create a new file with the name of your quest, e.g. my_quest.lua, in quests folder.
  2. 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",
    -- Blips are optional, if you don't want a blib, remove the whole section.
    blip = {
    color = 'BLIP_MODIFIER_PICKUP_WEAPON_RARE', -- See https://github.com/femga/rdr3_discoveries/tree/master/useful_info_from_rpfs/blip_modifiers for blip colors.
    title = "Strange footsteps",
    icon = "blip_ambient_king", -- See https://github.com/femga/rdr3_discoveries/tree/master/useful_info_from_rpfs/textures/blips_mp or https://github.com/femga/rdr3_discoveries/tree/master/useful_info_from_rpfs/textures/blips for blip icons.
    },
    -- 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. 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. 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. 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. 2.
    Add YOUR_QUEST_LOG_ITEM_NAME to Config.QuestLogItemName property in the config file.
  3. 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. 4.
    Note: YOUR_QUEST_LOG_ITEM_NAME is a placeholder, you can choose any name you want.

Quest properties

  • id (string, required) 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 (string, required) The name of the quest. It will be shown in the prompt and quest dialog.

  • description (string, optional, default nil) An 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, default nil) 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 of step tables, required) 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.

  • show_previous_step_in_quest_log (boolean, optional, default false) Defines if not the current step of the quest should be shown in the quest dialog, but the step before.

  • restricted_to_jobs (table, optional, default nil) Defines if the current quest is only available for the given jobs. The job names must be the same as in the vorp_inventory.jobs table (case-sensitive). Example:
    MyDemoQuest = {
    -- ... other properties
    restricted_to_jobs = {
    ["hunter"] = 1, -- Job "hunter" of minimum grade 1 or higher is allowed to use this quest.
    ["farmer"] = 3, -- Job "farmer" of minimum grade 3 or higher is allowed to use this quest.
    ["driver"] = 0, -- Job "driver" of all grades is allowed to use this quest.
    },
    }
    Important: If the blacklisted_jobs property is set then ensure that there are no conflicts with the restricted_to_jobs. The restricted_to_jobs is better used if there are no blacklisted_jobs set.

  • blacklisted_jobs (table, optional, default nil) Defines if the current quest is available for all jobs except the given ones. The job names must be the same as in the vorp_inventory.jobs table (case-sensitive). Example:
    MyDemoQuest = {
    -- ... other properties
    blacklisted_jobs = {
    ["hunter"] = 1, -- Job "hunter" of minimum grade 1 or higher is NOT allowed to use this quest.
    ["farmer"] = 3, -- Job "farmer" of minimum grade 3 or higher is NOT allowed to use this quest.
    ["driver"] = 0, -- Job "driver" of all grades is NOT allowed to use this quest.
    },
    -- ... other properties
    }
    Important: If the restricted_to_jobs property is set then ensure that there are no conflicts with the blacklisted_jobs. The blacklisted_jobs is better used if there are no restricted_to_jobs set.

Quest step properties

  • id (string, required) 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 (string, required) The name of the quest step. It will be shown in the quest dialog.

  • description (string, optional, default nil) An internal description for the quest step, e.g. like notes for the quest writers. It is currently not used and shown anywhere.

  • btn_text (string, required) The text for the button in the prompt. It will be shown in the prompt.

  • location (table, required) 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) A table 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 (float), required) 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 (string, required) The text for the quest dialog. It will be shown in the quest dialog. Can contain HTML tags.

  • callback (function, optional, default nil) 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, default nil) A table of requirements for the quest step. The requirements are checked before the quest step is started/accepted.
    • items (table, optional, default nil) A table 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, default nil) A table 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 }
    • gold (table, optional, default nil) A table of gold that are required for the quest step. If remove is set to true, the gold will be removed from the player inventory if the quest step starts/ends. Example:
      gold = { amount = 5, remove = true }
    • completed_quests (list of quest id strings, optional, default nil) A list of quests that are required for the quest step. Example:
      completed_quests = { "quest_id1" }

  • rewards (table, optional, default nil) A table of rewards for the quest step.
    • items (table, optional, default nil) A table 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" },
      }
    • weapons (table, optional, default nil) A table of rewards for the quest step. label, desc and serial are optional and can be used to overwrite the weapon defaults. Important: The weapon must exist in the game, see weapon list. Example:
      weapons = {
      {
      name = "WEAPON_REVOLVER_CATTLEMAN",
      amount = 1,
      label = "Custom label for weapon" ,
      desc = "Custom description for weapon",
      serial = "Custom serial for weapon",
      }
      }
    • money (table, optional, default nil) A table of money as rewards for the quest step. Example:
      money = { amount = 5 }
    • gold (table, optional, default nil) A table of gold as rewards for the quest step. Example:
      gold = { amount = 5 }

  • background_filename (string, optional, default nil) 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, default nil) 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 (string, optional, default is black) The color for the quest title in the quest dialog. The color must be a valid CSS color, like #ff0000 or red.

  • text_color (string, optional, default is black) The color for the quest text in the quest dialog. The color must be a valid CSS color, like #ff0000 or red.

  • shadow_color (string, optional, default is nil) 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, default nil, new since 1.2.0) 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) A table 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 (float), required) 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 visible type of the marker. See Marker Types for available types.
    • color (table, required) A table 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, default nil, new since 1.2.0) 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",
    }

  • radius_blip (table, optional, default nil, new since 1.2.0) 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 (number (float), required) The radius in meters of the blip.

Known issues / bugs

No known issues/bugs at the moment.

FAQ

Can I give weapons to the player as reward?

Yes (since version 1.3.0), see the rewards section in the Quest step properties for more information.

How many steps can a quest have?

Unlimited.

How many quests can be configured?

Unlimited.

What means "optional" for attributes?

If an attribute like blip, requirements, markers or rewards is optional, it means that you can leave out the complete attribute section or set the attribute to nil if you don't want to use it.
Example with blip:
local demo_step = {
id = "demo_start_id",
name = "Demo step name",
btn_text = "Demo button text",
location = {
coords = { x = 0, y = 0, z = 0 },
radius = 2.0
},
quest_text = "Some demo quest text",
blip = {
color = 'BLIP_MODIFIER_PICKUP_WEAPON_RARE', -- See https://github.com/femga/rdr3_discoveries/tree/master/useful_info_from_rpfs/blip_modifiers for blip colors.
title = "Strange footsteps",
icon = "blip_ambient_king", -- See https://github.com/femga/rdr3_discoveries/tree/master/useful_info_from_rpfs/textures/blips_mp or https://github.com/femga/rdr3_discoveries/tree/master/useful_info_from_rpfs/textures/blips for blip icons.
},
}
Example without blip:
local demo_step = {
id = "demo_start_id",
name = "Demo step name",
btn_text = "Demo button text",
location = {
coords = { x = 0, y = 0, z = 0 },
radius = 2.0
},
quest_text = "Some demo quest text",
}
Another example without blip:
local demo_step = {
id = "demo_start_id",
name = "Demo step name",
btn_text = "Demo button text",
location = {
coords = { x = 0, y = 0, z = 0 },
radius = 2.0
},
quest_text = "Some demo quest text",
blip = nil, -- This is the same as leaving out the complete blip section
}

Type definitions

table

A table is a collection of values or key-value pairs. In this script we use key-value pairs as tables.
Note: Tables are often named as objects (or confusing as lists).
Example:
local mey_table = {
key1 = "value1",
key2 = true,
key3 = 99
}
print(mey_table.key1) -- Output: value1
print(mey_table.key2) -- Output: true
print(mey_table.key3) -- Output: 99

list

A list is a collection of values.
Example:
local my_list_of_strings = { "value1", "value2", "value3" }
print(json.encode(my_list_of_strings)) -- Output: ["value1","value2","value3"]
local my_list_of_numbers = { 1, 2, 3 }
print(json.encode(my_list_of_numbers)) -- Output: [1,2,3]
local object_1 = { key1 = "value1" }
local object_2 = { key2 = "value2" }
local my_list_of_objects = { object_1, object_2 }
print(json.encode(my_list_of_objects)) -- Output: [{"key1":"value1"},{"key2":"value2"}]

string

A string is a sequence of characters wrapped by double or single quotes. In this script we often use strings for texts.
Example for a string:
local my_string = "Hello World!"
print(my_string) -- Output: Hello World!

boolean

A boolean is a logical value. In this script we often use booleans for true/false checks.
Example for a boolean:
local my_boolean = true
print(my_boolean) -- Output: true
local my_other_boolean = false
print(my_other_boolean) -- Output: false

number

A number is a numeric value. In this script we often use numbers for coordinates, radius, amount, etc.
Example for a number:
local my_number = 99 -- This is a number as integer (most common)
print(my_number) -- Output: 99
local my_floated_number = 99.99 -- This is a number as float
print(my_floated_number) -- Output: 99.99

function

A function is a block of code that can be called by name. In this script we often use functions for callbacks.
Example for a simple named function:
local my_function = function(from_person)
print("Hello from my function! Sincerely yours " .. from_person)
end
my_function('systemNEO') -- Output: Hello from my function! Sincerely yours systemNEO
Example for usage of a function as callback:
local demo_step = {
id = "demo_start_id",
name = "Demo step name",
btn_text = "Demo button text",
location = {
coords = { x = 0, y = 0, z = 0 },
radius = 2.0
},
quest_text = "Some demo quest text",
callback = function(_source, step, char)
print("Hello from my function!", json.encode(char))
end
}

Last modified 2d ago