////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/* Zunath's Quest System
Readme File
Created by Zunath on 9/6/2011
Prerequisites: NWNx2 + ODBC Plug-in
MySQL (SQLite may work, but is not supported)
MySQL GUI Tools (For database editing)
Some scripting and database editing experience
This set of scripts is designed to provide easy-to-create quests for module builders.
I have made it as easy to use as possible but you will need to do minor scripting in some
situations. Typically if you follow the examples, you'll get the right idea on what to do.
This readme assumes you have set NWNX and MySQL up properly. If you need help, refer to
www.nwnx.org.
Currently ZQS handles six types of quests:
1.) Kill specified enemies
2.) Talk to NPC
3.) Use object/placeable
4.) Collect specified items
5.) Explore specific area
6.) Use item on NPC
The system has been designed to be easily extendable so that more quest types can be added.
Each quest must be added to the MySQL database in the table called "quests". If you want to
call the table something else, there is an option to do so in the "qst_include" file.
----------------------------------
-- DATABASE FIELD DOCUMENTATION --
----------------------------------
The following will explain what each field in the quests table does, when to use them, and how to use them.
FIELD NAME DATA TYPE DESCRIPTION
1.) ID INT Each quest is assigned a unique ID number.
No quest can share an ID with another quest, so make sure they're unique.
For best results, just use sequential numbers (1, 2, 3, etc)
2.) Quest_Name STRING The name of the quest. This is just for your reference and doesn't
necessarily have to link up to the name of the quest listed in the journal
3.) Journal STRING The tag of the journal entry. This should match what you choose as the quest's
tag in the journal editor. (Tools -> Journal Editor)
4.) Target_NPC_ID INT Currently not used.
5.) Quest_Type INT ID number of the quest type. The following ID numbers are currently used:
1 = Kill Enemies, 2 = Talk to NPC, 3 = Use Object, 4 = Collect Items
5 = Explore Area, 6 = Use Item on NPC
6.) Fame_Region INT Unique ID number of the fame region. Player fame is local to specific regions.
Refer to the constants named "QUEST_FAME_REGION_*" in the file "qst_include"
for valid numbers.
7.) Fame_Required INT The amount of fame required before this quest can be taken. Note that fame is
local to each region so players must have that amount of fame in Fame_Region
in order to accept this quest.
8.) Max_Level INT The maximum level a player may be before the quest becomes unavailable.
9.) Min_Level INT The minimum level a player may be before the quest becomes available.
10.) Reward_Selection BOOLEAN If set to 1, players must select one reward from a list on quest completion.
If set to 0, players receive ALL rewards on quest completion.
11.) Reward_Gold INT The amount of gold a player receives on quest completion.
12.) Reward_XP INT The amount of experience a player receives on quest completion.
13.) Reward_Key_item INT The ID number of a key item a player may receive as a reward on
quest completion.
14.) Reward_Fame INT The amount of fame for the specified region a
player receives on quest completion.
15.) Reward_Item_1 STRING The resref of reward item #1 a player receives on quest completion.
16.) Reward_Item_Qty_1 INT The quantity of reward item #1 a player receives on quest completion.
17.) Reward_Item_2 STRING The resref of reward item #2 a player receives on quest completion.
18.) Reward_Item_Qty_2 INT The quantity of reward item #2 a player receives on quest completion.
19.) Reward_Item_3 STRING The resref of reward item #3 a player receives on quest completion.
20.) Reward_Item_Qty_3 INT The quantity of reward item #3 a player receives on quest completion.
21.) Reward_Item_4 STRING The resref of reward item #4 a player receives on quest completion.
22.) Reward_Item_Qty_4 INT The quantity of reward item #4 a player receives on quest completion.
23.) Reward_Item_5 STRING The resref of reward item #5 a player receives on quest completion.
24.) Reward_Item_Qty_5 INT The quantity of reward item #5 a player receives on quest completion.
25.) Finish_State INT The state ID which determines when the quest is completed. Typically
you can set this to 2 but if you want a multiple step quest, you will
need to set this to a higher number.
26.) Repeatable BOOLEAN If set to 1, this quest can be repeated an infinite number of times.
If set to 0, this quest can only be completed one time.
NOTE: Only 'Collect Items' quests are supported.
27.) Map_Note STRING Tag of the map note waypoint which is marked as active when the quest is
accepted. Make sure the tag is unique otherwise it won't work properly
28.) Start_Key_Item INT The ID number of a key item which is given to the player when the quest is
accepted.
29.) Remove_Temp_Key_Item BOOLEAN If set to 1, the Start_Key_Item is removed when quest is completed.
If set to 0, the Start_Key_Item stays in the player's key item inventory.
30.) Kill_Target_1 INT The group ID number of a specific kill target. Only used for 'Kill Enemies'
quests. For more information on how this is used, refer to that specific
quest type's guide.
31.) Kill_Target_Qty_1 INT The quantity of Kill_Target_1 that must be slain to complete quest.
32.) Kill_Target_2 INT Refer to Kill_Target_1
33.) Kill_Target_Qty_2 INT Refer to Kill_Target_Qty_1
34.) Kill_Target_3 INT Refer to Kill_Target_1
35.) Kill_Target_Qty_3 INT Refer to Kill_Target_Qty_1
36.) Kill_Target_4 INT Refer to Kill_Target_1
37.) Kill_Target_Qty_4 INT Refer to Kill_Target_Qty_1
38.) Kill_Target_5 INT Refer to Kill_Target_1
39.) Kill_Target_Qty_5 INT Refer to Kill_Target_Qty_1
40.) Required_Item_1 STRING The resref of the item that the quest requires. This item must be in the
PC's physical inventory (not key items) in order to count.
41.) Required_Item_Qty_1 INT The quantity of Required_Item_1 that this quest requires.
42.) Required_Item_2 STRING Refer to Required_Item_1
43.) Required_Item_Qty_2 INT Refer to Required_Item_Qty_1
44.) Required_Item_3 STRING Refer to Required_Item_1
45.) Required_Item_Qty_3 INT Refer to Required_Item_Qty_1
46.) Required_Item_4 STRING Refer to Required_Item_1
47.) Required_Item_Qty_4 INT Refer to Required_Item_Qty_1
48.) Required_Item_5 STRING Refer to Required_Item_1
49.) Required_Item_Qty_5 INT Refer to Required_Item_Qty_1
50.) Required_Key_Item_1 INT The ID number of a key item required in order to complete this quest.
This key item is REMOVED from the PC's inventory.
51.) Required_Key_Item_2 INT Refer to Required_Key_Item_1
52.) Required_Key_Item_3 INT Refer to Required_Key_Item_1
53.) Required_Key_Item_4 INT Refer to Required_Key_Item_1
54.) Required_Key_Item_5 INT Refer to Required_Key_Item_1
55.) Prerequisite_1 INT The ID number of a quest that must be completed before this quest may
be accepted by the player. Note that repeatable quests are considered
'complete' the first time they are done.
56.) Prerequisite_2 INT Refer to Prerequisite_1
57.) Prerequisite_3 INT Refer to Prerequisite_1
58.) Prerequisite_4 INT Refer to Prerequisite_1
59.) Prerequisite_5 INT Refer to Prerequisite_1
---------------------------
-- CONVERSATION BUILDING --
---------------------------
This quest system allows you to build a fully customizable dialogue for every quest you build. Or if you prefer to keep it simple,
you can modify one of the template quest dialogues. In either case you should be aware of the following scripts and know when to use
them.
First, I need to explain how the scripts are named. Take the following example:
"qst_at_q1_accept"
Each section of the example script name is an identifier separated by an underscore (_) which will help you determine when to use it.
"qst" : States that this script goes with the quest system
"at" : Stands for 'Actions Taken'. This tells you that it goes on the 'Actions Taken' event of the conversation.
"q1" : Stands for 'Quest #1'. This tells you that this is linked to the NPC speaker's quest #1. Valid range is 1-9.
Be sure the variable 'QST_QUEST_TAG#' is placed on the quest giver, where # is the quest number (starting at 1)
and the value is the quest ID number listed in the database.
"accept" : States the action to perform. In this case, it fires the 'Accept Quest' action. There are several types of
actions so be sure to read up on them below
The following is an example of a basic quest dialogue with the scripts associated:
NPC Greeting
1.) PC Asks About Quest #1 (Script: qst_aw_q1_prereq)
NPC Gives Quest Details (If quest hasn't been completed before, and PC isn't on the quest) (Script: qst_aw_q1_nstart)
- Accept Quest (Script: qst_at_q1_accept)
NPC Asks If Quest Is Completed (If quest has been started but hasn't been completed yet) (Script: qst_aw_q1_start)
- Complete Quest (Script: qst_aw_q1_objcom AND qst_at_q1_rew*)
NPC Asks For More of an Item (If quest is repeatable and PC has completed the quest before) (Script: qst_aw_q1_repeat)
- Give Items (Script: qst_aw_q1_hasite AND qst_at_q1_rew*)
2.) PC Asks About Quest #2 (Script: qst_aw_q2_prereq)
Repeat like above, but for quest #2
You can of course make the conversation as extensive as you like but please note that a single NPC cannot offer more
than 9 quests total.
**** Refer to the conversation "qst_template" for an idea of how conversations are built.
The following are all of the different types of scripts used by this quest system and when you should use them.
SCRIPT NAME NODE TYPE FUNCTION WHEN TO PLACE
1.) qst_at_q#_accept Actions Taken Accepts an NPC's quest. When PC chooses to accept the NPC's quest.
2.) qst_at_q#_rewall Actions Taken Completes a quest and rewards ALL quest item rewards listed in database. When PC chooses to complete the NPC's quest and the PC doesn't get to choose a reward.
3.) qst_at_q#_rewi1 Actions Taken Completes a quest and rewards ONLY item #1 listed in the database. When PC chooses to complete the NPC's quest and the PC chooses item #1 as his/her reward.
4.) qst_at_q#_rewi2 Actions Taken Completes a quest and rewards ONLY item #2 listed in the database. When PC chooses to complete the NPC's quest and the PC chooses item #2 as his/her reward.
5.) qst_at_q#_rewi3 Actions Taken Completes a quest and rewards ONLY item #3 listed in the database. When PC chooses to complete the NPC's quest and the PC chooses item #3 as his/her reward.
6.) qst_at_q#_rewi4 Actions Taken Completes a quest and rewards ONLY item #4 listed in the database. When PC chooses to complete the NPC's quest and the PC chooses item #4 as his/her reward.
7.) qst_at_q#_rewi5 Actions Taken Completes a quest and rewards ONLY item #5 listed in the database. When PC chooses to complete the NPC's quest and the PC chooses item #5 as his/her reward.
8.) qst_at_q#_rewki Actions Taken Completes a quest and rewards ONLY the key item listed in the database. When PC chooses to complete the NPC's quest and the PC chooses the key item as his/her reward.
9.) qst_aw_q#_hasite Appears When Node appears when PC has all necessary items and key items needed to complete a collect items quest, repeat quest or otherwise On the "Appears When" event for a collect items quest. Use for repeatable collect items quests too.
10.) qst_aw_q#_nstart Appears When Node appears when PC has NOT started the specified quest. On the "Appears When" event for the "Accept Quest" branch of the conversation. It should be placed on the RED NPC node.
11.) qst_aw_q#_start Appears When Node appears when PC HAS started the specified quest. On the "Appears When" event for the "Complete Quest" branch of the conversation. It should be placed on the RED NPC node.
12.) qst_aw_q#_objcom Appears When Node appears when PC has completed all objectives for the specified quest. On the "Appears When" event for the "Complete Quest" node. It should be placed on the BLUE PC node.
13.) qst_aw_q#_prereq Appears When Node appears when PC has completed all prerequisite quests and meets all requirements to start a quest. On the "Appears When" event for the quest's branch. This is the node which starts the quest branch in the conversation. It should be placed on the BLUE PC node.
14.) qst_aw_q#_repeat Appears When Node appears when PC has completed the NPC's quest before and the quest is able to be repeated On the "Appears When" event for a repeatable quest's branch. This should display the text an NPC says when a PC tries to repeat the quest again. It should be placed on the RED NPC branch.
--------------------------
-- SPECIFIC QUEST SETUP --
--------------------------
Step 1.) Quest givers must have the following variable(s) placed on them:
Variable Name: QST_QUEST_TAG1
Type: INT
Value: The ID number of the quest
To add another quest, do the same but change the variable name to "QST_QUEST_TAG2". You can add up to 9 quests per quest giver.
Step 2.) Place the conversation script on the NPC. This should be the same conversation you built using the rules listed above.
Step 3.) Follow the steps listed below depending on the type of quest you're creating.
-------------------------------------
-- "Kill Specified Enemies" Quests --
-------------------------------------
Step 1.) Open the database table which holds all quests (Default: "quests")
Step 2.) Set the following variables in the table:
A.) Kill_Target_# : The group ID number (any positive integer) you want to associate NPCs with. The PC needs to kill any
of the enemies in this group for it to count towards the quest quantity requirement.
B.) Kill_Target_Qty_# : The number of enemies in the group ID the PC must kill.
Step 3.) Set the following variables on the NPCs you want PCs to kill:
A.) QST_NPC_ID : The quest group you want to associate the NPC with. This should match what you put in the database table
for "Kill_Target_#"
B.) QST_NPC_QUEST_# : The first, second, etc quest this NPC is associated with. Value should be the quest ID number.
--------------------------
-- "Talk to NPC" Quests --
--------------------------
Step 1.) Place the NPC you want PCs to talk to into the module.
Step 2.) Place the dialogue you created for the NPC on the NPC.
Step 3.) Set the following variables onto the NPC:
A.) QST_QUEST_TAG# : The ID number of the quest this NPC is associated with.
Change # to the first, second, etc quest they are associated with, starting with 1.
MAX # is 9.
B.) QST_QUEST_TAG#_CURRENT_STATE_TALKTO : This should be set to the state the PC must be on for the quest in order for the node to
appear in the NPC's conversation.
C.) QST_QUEST_TAG#_NEXT_STATE_TALKTO : The PC's quest state is set to this value when they are done talking to the NPC.
-------------------------
-- "Use Object" Quests --
-------------------------
Step 1.) Place the placeable object named "Quest: Use Object" which is located under
Custom -> Special 3 of the placeables category.
Step 2.) Modify the following variables to suit the quest's need:
A.) QST_CURRENT_STATE : Set this to the state that the PC must be on in order for the placeable to fire when used
B.) QST_ID_NUMBER : Set this to the quest's ID number
C.) QST_CUSTOM_BEHAVIOR_ID : Optional field. If you want something special to happen when the object is used, set this value
to the number assigned in the script "qst_custom_click"
D.) QST_MESSAGE : If you want a message to display when the PC uses the object and they're currently on the quest,
you can do that here. Otherwise leave it blank.
E.) QST_NOT_ON_QUEST_MESSAGE : If you want a message to display when a PC uses the object and they are NOT currently on the quest,
you can do that here. Otherwise leave it blank.
F.) QST_NEXT_STATE : This is what the PC's quest state will be set to when they use the object
--------------------------------------
-- "Collect Specified Items" Quests --
--------------------------------------
Step 1.) Open the database table which holds all quests (Default: "quests")
Step 2.) Set the following variables in the table:
A.) Required_Item_# : The resref of the first, second, etc item required.
B.) Required_Item_Qty_# : The quantity of the first, second, etc item required.
-------------------------------------
-- "Explore Specified Area" Quests --
-------------------------------------
Step 1.) Place the trigger named "Quest Exploration Trigger" which is located under
Custom -> Special 3 of the trigger category.
Step 2.) Modify the following variables to suit the quest's need:
A.) QST_CURRENT_STATE : Set this to the state that the PC must be on in order for the trigger to fire
B.) QST_ID_NUMBER : Set this to the quest's ID number
C.) QST_MESSAGE : If you want a message to display when the PC enters the trigger, you can do that here. Otherwise leave it blank
D.) QST_NEXT_STATE : This is what the PC's quest state will be set to when they enter the trigger
------------------------------
-- "Use Item on NPC" Quests --
------------------------------
Step 1.)
*/
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////