Quest scripts syntax
Structure of a quest script
Quests are written out in chunks called steps. Each step covering the requirements of the previous one.
Things to know before you start
Quest scripts should written ideally in a text editor and now in MS Word or similar so that no illegal characters make it into the quest dialog which would result in errors when viewed in game.
Quotes are usually the ones which break the scripts and :
• Only ' " should be used
• ‘ ’ ” “ … These should not be present in the text at all.
Any line of text in the script which begins with a ‘#’ character is ignored by the server and only acts as a comment by the author so that they can leave explanations as to what is happening, or, give information about the step number.
The start of a ‘step’ is defined by a series of three dots ‘...’ Everything after this text up until the next ‘...’ is included in the step. The only unique case is the first step, this does not need ‘...’ and includes all the text before the first ‘...’
Important rules concerning steps
- Every step in the quest should be explicitly completed or locked correctly. Example: "Complete Quest Name Step #" before the Quest is completed.
- A step can require the completion of another step by the command: "Requires completion of Quest Name Step #"
- Step 1 does not exist, step 1 is part of the start script (where you use the command "give me a quest") and cannot be used as a require completion of step number.
- You may have multiple Require Completes at the beginning of a step.
- A step may also require another step NOT to have been completed with the command: "Require no completion of Quest Name Step #".
- The Quest name must be exact! It is case sensitive. The same goes for NPC names.
- Each step should be commented like this: "# Step 2 - A description of actions of this step". # Marks it as a comment not processed by the engine.
- You can also check for statements with this syntax: "Require <no/not> operator1 | <no/not> operator2 | ...| <no/not> operatorN." Where operator is a prerequisite (see below the prerequisite chapter), from completion of to time of day etc. The | represents the OR. Example: "Require completion of Questname Step 3 | completion of Questname Step 7."
Let's see an example before beginning the explanation. The following example is made of two steps.
Example: Structure 1
P: Short Trigger. Menu: Do you have any work for me to do? NPC Name: Yes I do. Just breathe one time. Assign Quest. ... P: Ok, I did it! NPC Name: Great, your quest is completed.
Syntax Basics
Comments
To create a comment line you must start the line with a "#". These lines are not evaluated by the engine as things that need to be done. These comment lines show what is going on and what are the intentions of the quest writer. This is important because more than one person are often working on a quest script, or eventually for laterbug fixing it will be easier to find the exact problem without reading the entire quest.
Each step in a quest should be started by a comment like this "#Step 2 - Description of step.". You can use comments to more that just noting the step number. Any where within the script you can add comments to help your fellow scripters understand the code. We will use comments to explain things within the scripts here.
Trigger and Menu
The trigger is for the engine, while the menu is what shows up in the player quest menu. The trigger is defined by a "P:".
P: use to be what the player typed to trigger the step, but with the menu system are now used as a description of what step the player is choosing, for example P:yeshelp. (slide 3). The only time you must use exact text is when a player types the answer to a question you pose them
Because you are talking to the engine it must be exact a colon after the "P:" and a period at the end of the sentence. This is also true of the Menu in every case in which the player (P) says something to the NPC in question "P: Short Trigger." comes first, then below comes the "Menu:" line, with exactly the same requirements.
"Menu": Text is what the player sees when they look at the quest menu.
Please remember that the engine does not think, it reacts to the written cues, so the syntax MUST be exact. The first player statement gives the engine the quest name. The Menu allows the player to ask for the quest from the NPC.
Having the two "P:" and two "Menu:" on the same line informs the engine that the player has two different options. It is standard that the "P:" line is above the "Menu:" line and the "No." answer comes first.
These lines trigger the NPC response. In more elaborate quests the "Menu:" line may have variations on the No. or Yes. response. However remember KISS (Keep It Simple Stupid) is generally a good thing to keep in mind when you are beginning. You can have many options, but remember each "P:" must have a matching "Menu:" and they must be put in the same order
In order to include a free textfield, you will have to include a quotation mark after the menu. The <?> has to be followed by <=> and a text. This will produce a printout of the text and the user will be able to enter a free text. E.g. "Menu: ?=What shall Jardet do?" This will result in the text "What shall Jardet do?" being printed, followed by free form input.
P: *. P: rock pick. Menu: ?=Please tell me your answer. Smith: No, you didn't get the right answer. Smith: Yes, it's a rock pick!.
Note: Remember the : after the P and Menu are important, as is the . at the end of the line.
Note: For triggers used to start quests, never use NPC names into it, because this will confuse the engine, and the trigger will not be recognized.
Note: Every P: used in one step must be on the same line
Note: Every Menu: used in one step must be on the same line
Note: Every NPC: used in one step must be on different lines.
NPC Response
Aono Rikas: here you can add a response.
The line above is interpreted as an answer from the NPC and the engine will extract the name before the colon (:) + space as the NPC involved in this step of the quest. From now on, we will call this a response.
The full name of the NPC is required, just the first name will not work. If it is only one name e.g Harnquist use that, and if your NPC somehow ends up with three names use all of them.
In the first step of a quest the NPC statement will end in a question mark and is triggered by the first 2 lines. Responses are linked to each of the Triggers and Menus. So if you have two triggers you need two menu options and two NPC responses. All arranged in the same order.
Dialogues
The dialogues are the most important part of the quest for a player to get immersed. So let us talk about how to make the dialogue.
- Every punctuation, exclamation mark and question mark will create a short pause in the dialogue and create a new line.
- To create actions all you have to do is to use square brackets within the dialogue like this "Blablabla [NPC Name picks his nose] Bla bla blabla"
You may use also these commands:
$playerrace can be used in an impersonal and a personal manner in terms of context, consider its usage carefully.
$sir which gives you "Sir" or "Madam" or "Gemma" depending on the gender of the player's character. Again, this can be used to positive and negative effect. Be mindful of the NPC’s tone. (Gemma is the honorific for Kran.)
$playername clearly not to be used in newbie quests, have NPC establish rapport use this in second quest or even the third time a player works with a given NPC.
Give me a quest..
A sample quest script
The first step
As previously mentioned Step 1 does not exist, it is just the start of the quest, and can not be required by subsequent steps. The Start of the Quest will look something like the example at the beginning (Structure 1).
The same example can also be scripted like this:
Example: Structure 2
P: Short trigger. Menu: Initial question, give me a quest. NPC Name: Yes, I do have a quest for you. I need you to give Item of Importance to NPC2 Name. P: Yes P: No. Menu: Yes, I will do that. Menu: No way stupid. NPC Name: This is the response from the NPC if answer is Yes. Give 1 Item of Importance. Assign Quest. NPC Name: This is the response from the NPC if answer is No.
In Structure 2 the answers "No" and "Yes" are inverted, like the two "Menu:" commands, so it will give the same result as Structure 1. (Answer No: nothing happens. Answer Yes: the player will get 1Item of Importance and the Quest.)
Now, let us use a more detailed example. We will make a very simple quest: Aono wants to deliver a bottle of milk to Orchibaly. The player can choose the quest from Aono's quest menu. Orchibaly will then give the player 2 pies and a receipt to give back to Aono. The first step will be the step that assigns the quest. The P: tells the engine that this line represents something the player will say to the NPC, but what you must pay extra attention to is the "Menu:" This will be what the player will see as an option in the quest menu. If there are several options you will have to create one "P:" and a "Menu:" for each of them.
Here we firstly gives the player the option to ask for the quest. Then Aono describes the nature of the quest and the player can choose yes or no. Right after the "Menu:" line the NPC responsewill be put. In this example Aono will reply: "Well, I will get someone else to do it for me." if the player says no or "That's great. Here is the milk. Be sure not to spill it. TellOrchibaly I sent you.", give the player 1 Milk Bottle and assign the quest.
Example: Assign Quest
# Quest: Delivery for Aono Rikas # Quest Description: Sample Quest. # The rest of the header will not be covered here. # Step 1 Aono Rikas in Hydlaa needs someone to deliver milk to Orchibally Gurpleferd in Ojaveda. P: Delivery for Aono Rikas. Menu: Are there any jobs you need done? Aono Rikas: Well, yes. I need some milk delivered to Orchibaly in Ojaveda. Can you do this for me? P: No. P: Yes. Menu: No. Menu: Yes. Aono Rikas: Well I will get someone else to do it for me. Aono Rikas: That's great. Here is the milk. Be sure not to spill it. Tell Orchibaly I sent you. Give 1 Milk Bottle. Assign Quest.
A quest can be automatically assigned or there can be a step at the beginning of the quest to ask the player if he accepts it.
If you want to assign it automatically use this format:
P: give me a quest. Or any quest trigger. Menu: what the play sees go here. NPC: What the NPC says goes here. Assign quest.
If you want to ask the player use this format:
P: give me a quest. Or any quest trigger. Menu: what the play sees go here. NPC: What the NPC says goes here, with the question if you want to help. P: nohelp. P: yeshelp. Menu: I don't want to. Menu: Yes I will help. NPC: Fine... Go away. NPC: Good great. Assign quest.
Note: The “Assign quest.” command will only trigger after the second NPC: dialogue line is triggered, nothing happens if the first is triggered.
The next step
To separate the step we use "..." and then a comment on what step it is and what the step is about. If you don't want this step to be repeatable you will also have to add "NoRepeat" after the "...". The second step does not need a completion of Step 1, because Step 1 does not exist so to speak. The structure will be more or less the same as for the initial step.
Let us continue our Delivery for Aono Quest. We have assigned the quest and the player has been given 1 Milk Bottle to give to Orchibaly. Now the player must give that milk to Orchibaly. Either by using the give GUI or by using the quest menu. The first thing we have to do here is to set up the give trigger. If the player gives Orchibaly the milk, he will answer "Oh, yes the milk. Please give it to me. Now i need you to deliver these two pies and this receipt back toAono.", Give the player 2 pies and a Receipt from Orchibaly. The step is then completed.
In this example although the player is given two pies no "s" is added to the line. This is important, especially because most writers tend to add a plural automatically to plural items. Remember the engine does not. An item is designated in the singular, the engine always interprets it in the singular regardless of the number included. The numbers are again not spelt out and Arabic numerals used. Remember that each "Player gives"-command must have menu option in the next line.
Example: Step 2
... NoRepeat # Step 2 - Player gives the milk to Orchibaly Player gives Orchibaly Gurpleferd 1 Milk Bottle. Menu: Aono asked me to give you this bottle of milk. Orchibaly Gurpleferd: Thanks, please give it to me. Now deliver two pies and a receipt back to Aono. Give 2 Pie. Give Receipt from Orchibaly. Complete Delivery for Aono Rikas Step 2. Completing a step At the end of a step remember to insert the line: "Complete Delivery for Aono Rikas Step 2."
Note the use of Capitals, the use of the quest name, the use of the appropriate numeral and the period at the end of the sentence. The line marks the step as complete and allows the player and the quest to move forward.
Last step
To make sure the player has completed the previous step we start with "Require completion of delivery for Aono step 2.". Then we move on to the trigger which is the player giving 2 pies and the receipt to Aono. Aono answers "Ah, pie. Thank you. Please accept this for your time.", gives the player a pie and 100Tria. The step is closed and so is the quest with "Complete Delivery for Aono Rikas."
Example: Last Step
...NoRepeat. # Step 3 - Player has now returned to Aono in Hydlaa. Player must now give Aono the 2 Pies and 1 Receipt. Require completion of delivery for Aono step 2. Player gives Aono Rikas 2 Pie, 1 Receipt. Menu: Here are your pies and your receipt. Aono Rikas: Ah, pie. Thank you. Please accept this for your time. Give 100 Tria. Give 1 Pie. Complete Delivery for Aono Rikas.
NOTE: If you use multiple options in the last step of a quest you have to explicitly complete the quest with a command for the first option.
Example: Last step with multiple options
P: No. P: Yes. Merchant: Quest doesn't complete automatically so make sure you have added a complete line for this response. Complete Harnquist Needs Gold Step 2. Complete Harnquist Needs Gold. Merchant: Quest completes automatically because it is the last line in quest so no complete line is required. Complete Harnquist Needs Gold Step 2.
If you omit the Complete Step and Complete Quest line, the quest will not end properly when choosing "no".
Branches of a quest (Non exclusive)
Some times you want to have several different outcomes for a quest. Let us use the Delivery quest once again. If the first NPC says that you must NOT give the milk to some one else... specially NPC3. Then you should also add the option for the player to actually give the milk to NPC3 . This will complicate your script a bit, but is not as hard as it might seem. Most of the job is done by placing the right "Require completion of" and "Require no completion of" commands.
Let us take a look at that Delivery Quest again. Now we want to add an option for the player to give the milk to Reffitia instead. Reffitia will shake the milk until it becomes butter and this will make Orchibaly angry and demand a new bottle of milk. To do that we will have to add a few more steps and we will start from step 2 as step 1 will be the same as above.
The Third step will be our previous Step 2. And the last step will be the same. Though Aono should mention something like: "Make sure you don't give that milk toReffitia." in Step 1.
IMPORTANT NOTE: This is a non exclusive branching, meaning that the first branch is available also when executing the second one.
IMPORTANT NOTE: We will not add an additional step for the player to get milk again from Aono, but the player have to figure out another way to get hold of it (Buy from an NPC).
Example: Branching
... NoRepeat # Step 2 - Alternative is to give the milk to refittia Player gives 1 Milk Bottle to Reffitia Menu: Here Reffitia, take this milk. Reffitia Thamal: Ah! Orchibaly's milk. Here, now you can give the bottle to Orchibaly. Give 1 Bottle of Butter. Complete Delivery for Aono Rikas Step 2. ... NoRepeat # Step 3 - Player gives bottle of butter to Orchy. # The player then have to find another way of getting a bottle of milk (buy from NPC?) Require completion of Delivery for Aono Rikas Step 2. Player gives Orchibaly Gurpleferd 1 Bottle of Butter. Menu: Um, here is the milk from Aono. Orchibaly Gurpleferd: Milk? This is butter. You better get me another bottle of milk, fast! Complete Delivery for Aono Rikas Step 3. ... NoRepeat # Step 4 - Player gives the milk to Orchibaly Player gives Orchibaly Gurpleferd 1 Milk Bottle. Menu: Aono asked me to give you this milk. Orchibaly Gurpleferd: Oh, yes the milk. Now i need you to deliver these two pies and this receipt back to Aono. Give 2 Pies. Give Receipt from Orchibaly. Complete Delivery for Aono Rikas Step 4. ... NoRepeat # Step 5 - Player has now returned to Aono in Hydlaa. Player must now give Aono the 2 Pies and 1 Receipt. Require completion of Delivery for Aono Rikas Step 4. Player gives Aono Rikas 2 Pie, 1 Receipt. Menu: Here take these pies and the receipt. Aono Rikas: Ah, pie. Thank you. Please accept this for your time. Give 100 Tria. Give 1 Pie. Complete Delivery for Aono Rikas.
Alternative outcome
If we wanted the quest to have a different outcome if the player gives the milk to Reffitia than to Orchibaly we would need to get creative with the require commands. Let us say that if the player gives butter to Orchibaly he will give "bad pies" so when Aono receives them and takes a taste he will be very angry and no reward is given. To do this we will have to add just one more step. Let us start with step 3. Here we will have to change only the NPC response a bit to something like "Milk? This is butter. Have you been shaking the bottle all the way over here? This is completely useless to me, butter I have more than enough of. Any way someMenki came with another bottle just before you. Here takes these pies to Aono . Oh, and don't forget this receipt.". Step 4 will be the step where the player gives the bad pies to Aono, this step will complete the quest. Step 5 and 6 are the outcome if the player gives the milk directly toOrchibaly. Notice that Step 5 require a NO completion of Step 4. This is actually not necessary for this script, because the previous the other branch of the quest, ending in step 4 closes the quest it self.
Example: Alternative Outcome
# Step 3 - Player gives bottle of butter to Orchy. And receives 2 pies and a receipt Require completion of Delivery for Aono Rikas Step 2. Player gives Orchibaly Gurpleferd 1 Bottle of Butter. Menu: Um, here is the milk from Aono. Orchibaly Gurpleferd: Milk? This is butter. You better get me another bottle of milk, fast! Give 2 Pie. Give 1 Receipt from Orchibaly. Complete Delivery for Aono Rikas Step 3. ... NoRepeat # Step 4 - Player gives the "bad" pies and the receipt to Aono. Receives gunk as reward and Quest is completed. Require completion of Delivery for Aono Rikas Step 3 Player gives Orchibaly Gurpleferd 2 Pie, 1 Receipt from Orchibaly. Menu: Here take these pies and the receipt. Aono Rikas: Ah, pie. Thank you. [Aono takes a bite at the pie] You have tricked me! Give 1 Gunk. Complete Delivery for Aono Rikas Step 4. Complete Delivery for Aono Rikas. ... # Step 5 - Player gives the milk directly to Orchibaly. Require no completion of Delivery for Aono Step 4. Player gives Orchibaly Gurpleferd 1 Milk Bottle. Menu: Aono asked me to give you this milk. Orchibaly Gurpleferd: Oh, yes the milk. Now i need you to deliver these two pies and this receipt back to Aono. Give 2 Pies. Give Receipt from Orchibaly. Complete Delivery for Aono Rikas Step 5. ... NoRepeat # Step 6 - Player has now returned to Aono in Hydlaa. Player must now give Aono the 2 Pies and 1 Receipt. Require completion of Delivery for Aono Rikas Step 4. Player gives Aono Rikas 2 Pie, 1 Receipt. Menu: Here take these pies and the receipt. Aono Rikas: Ah, pie. Thank you. Please accept this for your time. Give 100 Tria. Give 1 Pie. Complete Delivery for Aono Rikas.
Quest Timeout (Passing of time)
If you want to allow a certain part of the quest to wait a certain amount of time before it can be a executed, you can use this script:
Run script give_quest_timeout <<'Time until Harnquist is ready',6>>
this will create a temporary active magic with name 'Time until Harnquist is ready' which will last for 6 minutes. Then in the prerequisite of the step have this:
# Step 12.
Require active magic Time until Harnquist is ready.
P: swordnotready.
Menu: Is Vresa's sword ready yet?
Harnquist: No, not yet.
...
- Step 13.
Require no active magic Time until Harnquist is ready.
P: about Vresa sword.
Menu: Is Vresa's sword ready?
Harnquist: Yes, Vresa's sword is done.
Important commands and expressions used
Assign Quest.
This line tells the engine to assign the quest to the player and generally results in the "YOU GOT A QUEST". and placing the quest in the player's quest log, under "uncompleted". Again remember to be exact here, Capitalize the two words and put a "." at the end. It cannot be emphasized enough that the engine only interprets what it sees and the way it sees it. If you are not precise the quest will NOT happen or in the cases of the next steps move forward.
...
The three dots mark the beginning of a new step. Better, the three dots create a new step. So you need a "three dots" line before every "Complete Quest Name Step #"
NoRepeat.
This line means that the quest step cannot be done over and over. Note that there are three periods "..." a space and 'NoRepeat.' is one word not two. Each part of this sentence is required in exactly this form.
Basically "..." tells the engine that some time can pass before the next lines are used.
NoRepeat allows this quest step to be only done one time. This also applies to actions as seen in later steps. (in reality NoRepeat is a synonym for Require no completion of "this step")
Require completion of Quest Name Step #.
This command is like a closed door. To open it and enter in the current step the player needs to complete the step number #. You can also refer to a future step (for example, you're on step 4 and add "Require completion of Quest Name Step 8.")
Require no completion of Quest Name Step #.
This command is like an open door. The player is free to continue the quest and entering the current step, UNLESS he completed the step number #. Completing the step number # will close the door. Forever! You can also refer to a future step.
Complete Quest Name Step #.
This command completes a step, # being the step number. You can complete one step in another one. But remember to insert one "..." line for every "Complete Quest Name Step #." line.
Complete Quest Name.
This command will end the quest. After this the quest will be deleted from the uncompleted quest list and appear in the Completed quest list.
P:
The trigger is actually a ghost from the previous scripting system, but it is still needed (for now). Before the player had to type the exact trigger stated after the "P:". Now they click the option from "Menu:". Triggers must be four words or less. Triggers must end with a period, no other punctuation is allowed (question marks especially are known to break aquest on the server).
If you want multiple phrases to activate the same trigger, you can just separate the phrases by a period; for example: "P: about guards. about hydlaa guards. about hydlaa militia." In this case the NPC's response will be fired on any of the three options. This technique can be used also when you have multiple choices: "P: one. two. P: more.". Both 'one' and 'two' will trigger the first response, while 'more' will trigger the second.
WARNING: Triggers cannot contain any of the following words: a, am, an, and, any, anything, are, do, I, is, isn’t, please, that, the, this, to, too.
They also may not contain the name of the NPC you're talking to as that'll be stripped.
These words just take up space in a trigger as they are dropped by the engine when evaluating player response. To make the best use of your word counts ignore them when writing your triggers.
Example: If you wanted the player to say 'please help Levrus' the trigger would become 'help levrus' as please would be an ignored word.
WARNING: If a player needs to write "NPC needs this" syntax it as "NPC wants this".
Menu:
That's easy. After this command you can add the sentence said by the player in game. This sentence will appear on the screen and could be selected when one talks to the NPC.
Remember that for every menu line you need to create a response from the NPC.
Give
Give is a very useful command. It tells the engine to give the player items. Be it rewards or special items needed for the quest. When you reward a player, you can basically give items and/or experience. The syntax to award 1500 experience points would be: "Give 1500 Exp." Note that "Exp" is case-sensitive. You can also reward items AND experience, using this syntax: "Give Leather Gloves. Give 1500 Exp." Remember that you can only have two give commands on the same line, but you can have multiple lines, Remember to keep a clean style, it is prefered to only have one item per line.
Example: Give more than two items
Give 1 Leather Gloves. Give 1500 Exp. Give 1 Apple.
You can also add a number if you need to give more than one item (like you do for experience) example: "Give 5 Iron Ingot." It is not necessary in the case of one item to include the numeral, however it is good practice to do so as numerals tell the engine how many and should be written as a numeral, a word will NOT work as the engine cannot interpret it as such. Remember that all special items must be declared in the script header.
Another option you have is to give one item OR another. The following will pop up a window in which the player has to choose just one item:
Example: Give the player a choice between items
Give Cold or Arrow or Energy.
WARNING: At this time, don't use the following in an OR option: Tria, hexa, octa, circles, or items without a graphic. Also, for now, do NOT put quantities in front of items that are given using the "OR" parameter. An example of what NOT to do: "Give 1 Cold or 1 Arrow or 1 Energy." This will lock the server right up. An example of what SHOULD be done: "Give Cold or Arrow or Energy." (Check this statement if it is correct. --Katu)
Player gives NPC Name 1 Item
This can be used as a trigger (instead of the "P:"). It tells the engine to trigger the NPC dialogue when one or any fixed amount of a special item.
When a player have to give multiple items just add them to the original line using a comma:
Example Player gives item
Player gives Harnquist Water Pouch, 1 Pie.
WARNING: Item name rules must be followed at all times.
Notice that the item name is "Iron Ingot", so "Iron Ingots" will not work, even if it’s the correct plural form. Keep all names singular.
Also, do not use a number (3, 14, etc) in the name of an item. An item called 3 Circles Receipt will probably generate problems when we script "Give 3 Circles Receipt." It is better named "Three Circles Receipt."
Numbers should be spelled out everywhere unless you are referring to the quantity given or dealing with a trigger (give me 5 apples. give me five apples.) as both would be correct in a trigger.
Character limit for an item name is 60 characters.
Do not use an s' in an item name, like "Levrus' Left Shoe," use "Left Shoe of Levrus" or a similar substitute instead.
Set variable Require variable
You can set a variable to be later used by the quest or other quests. Variables are set on the character and visible from all quests.
Smith: Here is your winch access Setvariable Quest_Winch_Access 1
You can then require a variable to be set as prerequisite of a quest step.
Require variable Quest_Winch_Access. P: access. Menu: I have access Bobaus: Ok, good.
Require Compendium
You can require the player to have a certain knowledge in the Compendium.
Require compendium creature StoneHammer P: comps Menu: I know everything about the StoneHammers! Fighter3: WOW ... Require no compendium creature StoneHammer P: nocomps Menu: Sorry I dont know anything about StoneHammers! Fighter3: Ah, study more!
The syntax is: compendium <creature/plant/mineral> <name>
Rewards at the end of the quest
When completing a quest, the player usually gets experience and money, or some items. In particular for experience and money you should use the following scripts. This allows us to split the rewards on a scale from 1 to 10 and then to tweak the actual values in the engine. The values in brackets indicate the complexity of the quest. The more complex the more rewards the player will get.
Run script give_quest_money <<3>>. Run script give_quest_exp <<2>>.
The header
The header should contain a lot of information. All the information is commented out by a "#". The example below is from one of the mount quests.
First section is information about the quest itself. Name of the quest, a short description and category. Categories will be discussed in detail later on.
The next sections are for unique items used in the quest, name of the item followed by the description.
The third section is for recording versions of the script and all naming authors. Also who last edited the quest should be noted.
The last section is for additional metadata which will be added to the quest in the database (not part of the db) and will be used by the engine to determine lockouts and prerequisites. Here it locks all players from doing the quest again and locks all other players to take the quest with 60 seconds.
Lastly we tell the engine that the player have to complete the Ring of Familiar quest before this one. Note that these comments aren't taken by the engine; it's the duty of who loads the quest to fill the correct entries with the data found in the header: so it's just a way to keep all data together on the script.
Example: Header
# Quest name: Drifting for a Drifter # Quest Description: Taemian wants to sell you a mount # Quest Category: General # ---------------------- # Quest Items: Item name/Item description # Taemian's Pouch: - Pouch with all sorts of coins # Green Gem of the Drifter - A magical gem with a green glow # Unsigned Drifter Permit - A permit that still needs to be signed by Datal # Signed Drifter Permit - A permit that has been signed by Datal # ---------------------- # Variables used in this quest # ---------------------- # Quest specific variables used in this quest # ---------------------- # Author(s): Ravna, Katu, weltall # Current Version: 1.01 # Player lockout: -1 # Quest lockout: 60 # Prerequisites: <pre><completed quest="Ring of Familiar"/></pre> # Variables used: Quest_Variable_Name used to do..... # ---------------------- # Version history and change log # Last edited by: weltall # Version 1.00: Initial draft - 05/01/2010 - Katu. # Version 1.01: Added extra steps - 1/22/2011 - Venalan. # ----------------------
Quest Lockouts
Each quest has two different lockout types:
- Player lockout: When this parameter is set, the engine will wait the specified amount of seconds before allowing the same player to redo the same quest. If you want a quest to be available to each player only one time, then set the lockout to -1. Setting it to 600 will have the engine wait 10 minutes before unlocking the quest again.
- Quest lockout: When this parameter is set, the engine will wait the specified amount of seconds before reactivating the quest for ALL players. This means no one can start the same quest during this period, but the ones that had it already active can complete it.
Usually we want quests to be unique to players, so most have a player lockout -1, except the very simple ones. Try always to think if it’s meaningful for that player to redo it. (For example, Harnquist can require iron ore more than once, but won't need to teach you how to make a sword more than once.)
Prerequisites
Another more complex version of the prerequisites is the: REQUIRE MIN <number>: this tells the engine that there are specific requirements to be fulfilled before the player is able to get the quest. This script indicated it requires a minimum number of quests to be completed in a given list.
Example: require min 2 of Quest1, Quest2, Quest3.
To match this prerequisite the player can complete Quest1 and Quest3 or 2 and 3, or all 3. The request is minimum 2 in the given list.
CATEGORY MIN <number>: quests have an attribute called "category", we use it to identify the difficulty of quests, but can be used of any other purpose, for example one can say that a group of quests is "Evil" or "Laanx related" or " Newbie". Just one category is allowed per quest. This prerequisite allows you to specify the category and the minimum number of quests completed in that category.
A sample of the coding used to set prerequisites for a quest (All on one line):
Example: Prerequisites
<pre><and> <completed quest="Test Quest One"/> <completed quest="Test Quest Two"/> <completed quest="Test Quest Three"/> <completed quest="Test Quest Four"/> <not><completed quest="Delivery for Aono Riskas"/></not> <not><completed quest="Gorbiak Disease"/></not> </and></pre>
This sample requires that the player have completed Test Quests 1 through 4 and have NOT completed Fancy Dancing and High-Class Aspirations. To get these arranged correctly can take some practice if one is not familiar with working with booleans, so it is best to include a plain-English comments of what you wish your pre-requisites to be in addition to the one with the "pre" coding statements.
Checks if the player has a certain item equipped . To be documented better
else if (!strncasecmp(block,"equipped",8))
Untested Prerequisites
Please contact engine in case you want to use any of these prerequisites, because those are untested.
"time of day" // require time of day starthh-endhh (working)
"trait" //require trait name in place
"guild" //NOTE: the both argument is implicitly defined
"active magic" (working)
"known spell"
"race" (working)
"gender" (working)
"married"
"possessed" (working)
"skill" //Require skill <buffed> name <skillmin>-<skillmax>. (working)
"variable" //Require variable name. (working)
Notes on Creating Quest Files (Rules and Header Information)
- The quest documents you submit should always be in notepad format: this is to avoid special characters added by Word or other text editors, most notably "smart quotes" which will appear as squares in game. Notepad++ is recommended, HIGHLY recommended.
- Use only ANSI encoding.
- The file name when saving the quest should begin with 'Quest' , then have the name of the quest. For example: Quest Hinoserri Cannot See.txt
- Titles of quests should follow some scheme of capitalization. There are many sets of rules, but a quick and easy format is to capitalize the first word and then all other words, except a, an, the, at, by, for, in, of, on, to, up, and, as, but, it, or, and nor.
- Each quest script begins with the title and a one or two sentence description; this is what the player reads so keep that in mind. The proper way to do this is to "comment out" your description and quest title, this is done by beginning a line with the number sign or pound symbol (#). Also, any quest item created for your quest should have a description written into the quest. Notes on quest items should also be commented out. Lastly, there should also be a "Quest Category" line that must be commented out as well. Approved quest categories are: Alchemy, Black Flame, Chain (don't use this one unless told), Cooking, Death Realm, Easy, Gugrontid, Magic Ways, Medium, Metal Working, Newbie, Repeatable. This is a work in progress, so if you have any questions ask an associate dev or developer. No quest can have more than one category - pick one and ONLY one. New quest categories must be approved by the associate devs/devs before use.