Guide: Siege University - 209: Quests

== Introduction ==
=== What You Need For This Tutorial ===
* Dungeon Siege, updated to version 1.09B or later 
* Siege Editor 
* Siege Editor Manual (included with the Siege Editor during installation) 
* A test map you can practice with. 
=== What This Tutorial Assumes You Have Already Learned ===
*203A - Triggers I
*203B - Triggers II
*208A - NPCs
*208B - Talk Skrits
* Are familiar with basic Siege Editor operations. 
=== Definitions ===
=== What is a Quest? ===
A Quest is any Journal entry that has both an active and complete state. Quests are often tasks assigned by NPCs and usually aid in storytelling. Quests can be sorted under Chapter headings, or can appear in the order in which they are activated.
=== What is a Chapter? ===
A Chapter is a Journal entry that has only a single state, and serves to organize Quests into categories. New Chapters are generally displayed on the screen as a picture that fades away after a few seconds.
== Quests ==
=== Overview ===
Simple quest creation can be done completely within the Siege Editor, while more complicated quests involving NPC behavioral or conversation changes require additional work creating skrits in a text editor. There are four typical quest subtypes:
# Courier quests: You are instructed to take an object or message to another place or NPC 
# Kill quests: You must kill a specific NPC or variety of NPCs 
# Travel quests: You must journey from one place to another 
# Puzzle quests: You must solve a riddle or puzzle.
If you want quests to play a large role in your world, it's generally a good idea to reward players in some way for completing a quest.
=== Practical Exercise - Create a Quest ===
The first step in creating a quest is deciding what the purpose of the quest is. Let's begin with a basic courier type quest set in a friendly environment. First, we need storyline to supply a reason for sending the player on the quest: a townswoman has an urgent message for her sister, and if you would be kind enough to act as courier, she's sure her sister would be grateful. In editing terms, this means we want to assign a quest when you speak with the first sister, and complete the quest when you speak with the second sister.
==== Place the Props ====
Open the Siege Editor and load your favorite basic test map. Now, we need some props. Let's use two female NPCs (NPC 1: mp_townfolk_female_01 and NPC 2: mp_townfolk_female_02) and a basic chest (chest_cherry_ornate, found in Game Objects\furnishings\containers\misc) for the reward. Place NPC 1 at one end of the map and NPC 2 a distance away. Place the chest next to NPC 2. 
TIP: When setting up quest participants, it is useful to label them in the dev_instance_text field to make their purpose more obvious within SE. For an example: Open mp_townfolk_female_01's object properties and scroll down to the [common] block. In the dev_instance_text field, type, "QUEST - NPC 1." Now, when you select the NPC again, you'll see the dev_instance_text floating above her head, making her easily recognizable (so long as you have the Single Object Debug HUD option enabled). 
==== Create the Quest ====
Within Siege Editor, open the Quest/Chapter Manager, found in the Tools Menu. Click the Add button and type in a name for the quest: sisters_message. Click OK and you will now see the quest listed under the Quests box.
==== Configure the Quest ====
The game needs to know more about the quest than just its name: where and how does it appear in the in-game Journal, and what sound plays when it appears? Select the quest and click the Edit button to configure it. Under Screen Name, type the name you want to have displayed in the Journal: A Sister's Message. For now, leave the Quest Image field blank. From the Victory Sample dropdown, pick the sound file you want to play, usually s_e_level_up_quest. Skip the Award Skrit and Chapter options for now.
==== Add a Quest Update ====
Click the Add button in the Quest Updates box. Select the [none] entry that appears in the Description field, and click 
the Edit button. The Quest Update window will open, allowing you to configure the actual information that describes the quest in the Journal: what step is it, who assigned it, what it entails, and what NPC conversation addresses it? Similar to Conversation Orders, Quest Steps begin with 0 for the first step and increment from there. Set the Step to 0. Check the "Is this a required update?" checkbox. This specifies whether or not quest steps can be skipped. In our case, such a short, local quest would be confusing if the first step was skipped. Next, add the Description, or the text directions that will appear when the player highlights the quest in the Journal: Deliver Ella's message to her sister Fwynn Gilverstych. In the Speaker field, type NPC 1's screen name: Ella Riverstarn. Leave the Conversation Address blank for now - we'll fill that in later. Click OK through the next windows to get back to the main Editor window.TIP: When adding Quest Update Descriptions, try to make the description informative as well as short. Generally, the key information you want to get across is What (they are supposed to do), Who (they are supposed to interact with), and Where (they are supposed to go). Our example above is vague in the Where category since we're only dealing with a test map, but in a real level we'd flesh it out more with Fwynn's location as well. 
==== Add a Conversation to NPC 1 ====
Now that our NPCs are in place and we have a quest to assign, we need to add dialogue to explain the situation and activate the quest. Select NPC 1, give her the basic talk job, and create a conversation for her with the Region Conversation Manager. Call it conversation_ella, and add a text block. Add the story text:"Hail, friend! Your arrival is well-timed! You see, my sister, Fwynn Gilverstych, is leaving on a journey today to join her husband in a distant town. It's her first trip alone, and the Fortune Teller gave me a special reading - it seems my sister will come upon ill-luck unless she wears her lucky amulet at all times! I'd tell her the news myself, only I sprained my ankle on the way back from the Fortune Teller's home, and I'll never make it in time before my sister leaves. With your two good legs, you could certainly catch her if you leave right now. Please help! I'm sure she'll reward you generously for your time." Do not give this block an Order, since we want it to play every time NPC 1 speaks. Check the Quest Dialogue box found in the lower left corner of the Settings area to mark this text as quest-related.
==== Activate the Quest ====
To make the sisters_message quest become active (and display in the Journal), we must activate it in the text block that refers to it. Click the Activate Quest button found in the upper right corner of the Settings area. In the resulting Activate Quests window, select sisters_message from the Available quests dropdown. Select the 0 step from the Step dropdown, and click the Add button. Close all of the conversation windows until you are back to SE's main window.
==== Add a Conversation to NPC 2 ====
Select NPC 2, give her the basic talk job, and create a conversation for her with the Region Conversation Manager. Call it conversation_fwynn, and add a text block with the dialogue: "Oh dear, can't you see I'm busy? I really can't talk now, must finish packing - what? You just spoke with my sister Ella? You mean the amulet Ella made for me all those years ago? I will be sure to find it, then. I'm already late enough as it is; it certainly wouldn't do to invite an even greater disaster! Thank you, friend, I am most grateful for your help. Here, take a peek inside this chest and see if there's anything you'd like." Do not give this block an Order, since we want it to play every time NPC 2 speaks.
==== Complete the Quest ====
To make the sisters_message quest become completed, or finished (and display in a faded shade in the Journal), we must complete it in the text block that refers to it. Click the Complete Quest button found in the middle right side of the Settings area. In the resulting Complete Quests window, select sisters_message from the Available quests dropdown, and click the Add button. Click OK and close all of the conversation windows until you are back to SE's main window.
==== Add the Quest Dialogue Address ====
If you want the in-game Journal function, "Show Dialogue" to have an effect, you need to point the quest update to the corresponding conversation. To do this, open the Quest/Chapter Editor, select the sisters_message quest and edit it. Edit the Step 0 Quest Update. From the Conversation Address drop down, choose conversation_ella. Click OK until you are back to the main window. Save the region and try loading it in the game.
==== Advanced Suggestions ====
The above quest is very simple and could be enhanced in a variety of ways by creating custom talk skrits for both NPC1 and NPC2. For example, if this was a real quest, you'd probably want to include a few more dialogue options. NPC 1 should really play one conversation for when you first meet her and acquire her quest, and an entirely different "thank you!" conversation for when the quest is complete. NPC 2 should play a different conversation for if you talk to her before receiving the quest, and you might want her to drop the reward item instead of pointing you to a chest. Or, you could make the chest "use_toggle," which is an option that allows a chest to be locked (and display a message of your choice when used) until you send it an activate request. You could also have NPC 1 give you the amulet to bring to NPC 2, and use a custom button to actually facilitate the transfer.
While we skipped adding a quest image to the Journal in the tutorial above, this is something you can easily do. First, look at the existing quest images found in Bits\art\bitmaps\gui\in_game\menus\ for examples. Then, create your own in your favorite graphics program and save it in .psd format. To make it appear in the Journal, just type the file name without the extension in the Quest Image field in the Quest Editor window.
===Tools===
Quest activation and completion are not limited to conversations and talk skrits. The trigger action, change_quest_state solely manipulates quests. There are also a few other useful features such as use_toggle objects, the check_quest gizmo, changing the selectability or visibility of an object, depending on quest state, and the trigger conditions go_within_bounding_box and has_go_in_inventory.
==== Change_quest_state Trigger Action ====
Quests can be activated, updated, and completed at any time or place in a game using the change_quest_state trigger action. To use this, place a generic trigger with any condition and the change_quest_state action. Type the quest's name in the Quest Name Value field, specify whether you want to activate, deactivate, or complete the quest in the Quest State Value drop down, and if the quest is being activated, specify the Quest Activation Order in its Value field. In trigger terms, updating and activating a quest are the same thing. Note that you cannot activate or update a quest without specifying a Step. By default, the Step is 0 - i.e., the first step of the quest. If you want to update an existing quest, activate it to the desired Step.
The change_quest_state trigger action is particularly useful when entering an important area (i.e.- across the threshold of a room the target is in for a "Kill" quest) when picking up a quest-related object, or when an object dies. Some of the more useful trigger conditions typically used with the change_quest_state action are below:Party_member_within_bounding_box: If you have a quest that includes an area containing something important to the quest, include a quest step that changes the quest description in that area. Use a single-shot party_member_within_sphere or party_member_within_bounding_box condition so that when the character enters the trigger area, the quest updates to the next step. For example, if the Quest had originally told you to travel to the fourth floor of the Governor's house to locate an item, when the character actually enters the fourth floor, you could update their quest to now tell them to find the item sitting on the table in the library. Receive_world_message - we_picked_up: Regarding quests that updated to a new step when an item is picked up, add a single-shot trigger to the actual item. To do this select the item and open its properties. Click on the Trigger Properties tab and click the New button to add a trigger. Now, go about configuring the trigger as you would an actual trigger gizmo. Use the receive_world_message condition with the World Message Event "we_picked_up" - i.e., the trigger is waiting until the object is picked up before enabling the action to occur. For example, when you pick the book up in the example above, the quest step advances to a new description and tells you to return the book to the quest-giver. Receive_world_message - we_killed: Quest changes that occur when an object or actor dies are similar to the we_picked_up message. As above, this is a receive_world_message trigger. The World Message Event "we_killed," tells the game to update the quest after the object has been killed. For example, if you have a Kill Quest that requires you to kill an evil wizard, upon the wizard's death the quest would complete. Note: You might notice there are other World Message Events that refer to object death, such as the we_anim_die and we_req_die messages. While these may at first seem acceptable to use, they are not multiplayer-friendly messages and will not function under certain conditions. When used with a server-based action such as change_quest_state, the we_killed message is generally dependable regardless of whether the player triggering it is a client or server. 
==== Use_toggle Doors and Chests ====
Use_toggle objects are a class of objects that: 
* Can be used at all times but can have either a locked and unlocked state 
* Play a screen message while locked, but do not open 
* Must receive a we_req_activate message to become unlocked and thus can be opened
Essentially, use_toggle objects start out locked and tell you that they're locked until they are specifically told to unlock. This locking feature combined with a screen message makes use_toggle objects very useful to involve in quests and puzzles. For example, you could create a quest/riddle dungeon that utilizes use_toggle doors with messages in a riddle format. When a player tries to use the door, the riddle is displayed as a message and a quest could be assigned in the Journal. Use_toggle doors and chests are especially powerful in restricting access to quest areas or content only to those who actually have the quest.
Existing use_toggle doors can be found under Game Objects\doors\use_toggle. Each of these has been created to display a specific message while locked. Since you'll probably want to add your own message, you will need to template a new door containing your message. Look in Bits\world\contentdb\templates\regular\special\door.gas for examples of use_toggle doors. Take a look at the following example use_toggle door template:
 [t:template,n:door_glb_crypt_use_toggle]
 {
 specializes = base_door;
 doc = "MP_abc_r1_use_toggle";
 category_name = "use_toggle";
 
 [aspect]
 {
 model = m_i_glb_door-crypt-01;
 [textures] 
 {
 0=b_i_glb_door-crypts-01;
 }
 material		 = stone;
 }
 [body]
 {
 [chore_dictionary]
 {
 chore_prefix = a_i_glb;
 
 [chore_open]
 {
 skrit = transition;
 anim_files: 00 = door-crypt-01-open;
 }
 [chore_close]
 {
 skrit = transition;
 anim_files: 00 = door-crypt-01-open;
 }
 }
 }
 [messages]
 {
 [locked]
 {
 screen_text = "This door appears to be
 magically sealed with a glyph bearing 
 the Mark of Elddim.";
 }
 }
 [door_basic]
 {
 use_toggle		= true;
 oneshot 		= true;
 delete_on_open	= true;
 }
 }
The important blocks in the above example are the [messages] block, which contains the actual screen message displayed when the door is used while in its locked state, and the [door_basic] block, which contains the use_toggle field set to true. To create a new use_toggle door, all you need to do is copy the existing door template, add the use_toggle=true; field to the [door_basic] block, and add the [messages] block containing the [locked] component with the screen text you want to display.
An example from Dungeon Siege is the Utraean Peninsula "Hovart's Folly" Quest. The Gavel of Convening is a quest item that is required to advance to the next step of the Hovart's Folly Quest, and it is found in a room inside the Ancient Crypt (abc_r1). However, that room is only accessible to players who actually have the Hovart's Folly quest in their journal already. It is blocked by a use_toggle door that displays the message, "This door appears to be magically sealed with a glyph bearing the Mark of Elddim" if it is used in the locked state. However, if the player does have the Hovart's Folly quest, then the door will be unlocked when they come across it. This is facilitated through the use of the check_quest command gizmo.
==== Check_quest Gizmo ====
The check_quest gizmo is a specialized command found in Game Objects\gizmos\commands\specialized. Upon 
activation, it will check for a specific quest and state and send an activate or deactivate depending on the result. By placing a party_member_within_bounding_box conditional trigger across a choke point (doorway, hallway, etc) and configuring it to send a we_req_activate message to the check_quest gizmo, you can easily control the circumstances of an area based on quest state. To configure the check_quest gizmo, place it in a region and open its Template Properties. There are six adjustable fields within the [check_quest] block; usually you will want to enter the quest name, state, and scid you want to send a message to.
Continuing from the Dungeon Siege example above, when the player passes through one of the bounding boxes near the Gavel room, the trigger activates the check_quest gizmo to look for the Hovart's Folly quest. If the result is true, then the check_quest gizmo sends an activate request to the use_toggle door blocking the room and voila, the door is unlocked.
==== Cmd_selection_toggle Gizmo ====
Dungeon Siege's Kingdom of Ehb adventure maintained a forward-moving theme throughout the experience. This meant that we did not generally encourage backtracking, thus Quests often began and ended in two different locations. At times, we wanted to create the illusion that the same NPC who assigned the quest was also the one who completed it, but without requiring you to return to his original location.
Since it wasn't feasible to have the same NPC actually travel to the new location, instead we used two instances of the same character, with the second invisible until the appropriate time. A great example of this is the quest to Clear Glitterdelve Pass. A town guard in Stonebridge assigned the quest, asking you to open the damaged gates from the other side. After passing by the gates yourself and verifying that they were indeed blocked, you then traversed Wesrin Cross and emerged on the other side of the gate, cleared the rubble blocking it, and opened it to find the very same town guard there waiting to thank you. This was all accomplished via the cmd_selection_toggle gizmo, which allows you to toggle all or one of an object's selectability, visibility, usability, and invincibility. 
The cmd_selection_toggle gizmo is a specialized command found in Game Objects\gizmos\commands\specialized. While this gizmo began as a simple selection toggle, it has since expanded to include visibility, usability, and invincibility as well. The word, "selection" is used most frequently in its Template Properties descriptions, but the term is interchangeable with any of the other features, depending on which ones you are toggling. To configure the cmd_selection_toggle, place it in a region and open its Template Properties. In the [cmd_selection_toggle] block, insert the scid of the object to be toggled, the messages that need to be received to change the toggle, what type of toggles (selectability, usability, visibility, and/or invincibility) to enable, and the starting state of the object when it enters the world. The object may enter the world according to three possible starting states: 0 for if you do not want it changed from its default state, 1 for if you do want it to be toggled (ie, unselectable, unusable, invisible, or invincible) and 2 for if you do not want to be toggled (ie, selectable, useable, visible, or damageable). From the example above, the first town guard was placed in Stonebridge, and a second town guard was placed next to the Glitterdelve gates - with his starting state set to 1 for invisibility. As the party neared the exit of Wesrin Cross, they walked through a trigger bounding box that sent a we_req_deactivate to the cmd_selection_toggle gizmo - thus by the time the party emerged outside and destroyed the rubble in front of the gate, the guard was visible on the other side.
==== Go_within_bounding_box or go_within_sphere Trigger Condition ====
The go_within_bounding_box trigger condition is very useful in determining if a quest object is located in a specific area. For example, if a quest-related Chalice had to be placed on an altar in order to complete a quest, then you would use a go_within_bounding_box trigger condition. You then have the choice to have the trigger look for the Chalice either by its SCID (if it had been previously placed somewhere in the world), or by its Template Name (if it had been generated as loot from a monster's death, for example). If you use the trigger action change_quest_state as well, as soon as the player drops the Chalice on the altar, their quest would be updated as well.
==== Has_go_in_inventory Trigger Condition ====
The has_go_in_inventory trigger condition is used to detect if a party member is currently carrying a specific object in their inventory. Similarly to the go_within_bounding_box trigger condition, you choose whether to watch for the object by its SCID or template name. There is also a third option to choose which players' inventory to look in, either players just on the area local to the trigger, or any players in the game world. Note: this condition is not standalone and must always be paired with a party_member_within_bounding_box condition, which should be added to the trigger first. Has_go_in_inventory is very useful in unlocking areas that require a key. For example, the Trial of Gallus Easter egg area of the Utraean Peninsula world is hidden behind a secret door. The Trial of Gallus riddle book is the key to unlocking the door, so only players currently carrying the book are able to reveal the entrance.
== Chapters ==
=== Overview ===
Chapters consist of two parts: the Chapter Journal entry, and the Chapter Interface graphic. The Chapter Journal entry is created within SE via the Quest/Chapter Manager, while the Chapter Interface graphic should be created in your favorite 2d graphic program and saved as a *.psd (Photoshop format) file. Chapters are used to organize the quests and storyline.
=== Practical Exercise - Create a Chapter ===
==== Create a New Chapter ====
Launch SE and open your quest test map from earlier. Open the Quest/Chapter Manager and create a new Chapter (chapter_1) in the Chapters section. Click OK to accept the name. Now that the Chapter is created, Edit it to adjust its settings and Updates. Give it a Screen Name: Chapter 1. You may create your own Chapter Image, or use an existing one such as "b_gui_ig_mnu_jnl_chapter_01." This image is simply a picture of the Roman numeral "I". In the Chapter Updates section, Add a new one. Edit it and set its Step to 0. Give it a description - this text will 
serve as the dialogue part of the Chapter, and will display in the upper right corner of the Journal when the Chapter is highlighted. Type in: The first step upon the journey through my Test Map. Click OK through the windows until you are back at the base Quest/Chapter Manager window.
==== Assign a Quest to a Chapter ====
Select the sisters_message quest you created earlier and click Edit. In the Settings area, click on the Chapter dropdown and select chapter_1. Click OK to close that window and the Quest/Chapter Manager window.
=== Create the Chapter Interface ===
The Chapter Interface is similar to a template file. It is a gas file that defines the Chapter interface element, and most importantly, identifies what the chapter art is. Chapter interface art is usually .psd file of white text with a black drop shadow applied. Existing textures are stored in art\bitmaps\gui\nis\. Once your texture is created, turn it into an Interface by adding it to ui\interfaces\chapters\chaptername\chaptername.gas. Within the chaptername.gas file, paste the following: 
 [chaptername]
 {
 b interface = true;
 centered = fade_window;
 [t:window,n:fade_window]
 {
 f alpha = 1.000000;
 b common_control = false;
 common_template = ;
 i draw_order = 1;
 rect = 181,111,437,367;
 texture = b_gui_nis_ch01;
 //change this to the name of your chapter texture
 uvcoords = 0.000000,0.000000,1.000000,1.000000;
 wrap_mode = clamp;
 pass_through = true;
 topmost = true;
 [messages]
 {			
 onanimcomplete = notify(fade_chapter);
 }
 }
 }
 
In the "texture = " field, be sure to change "b_gui_nis_ch01" to the name of your customized chapter graphic. Changing any other fields is not recommended. These are various properties that tell the game placement and 
behavior of the Interface, but these traits remain the same in most circumstances.
==== Activate the Chapter Interface ====
Now that you have a Chapter Interface, you can display it in the game. Expand the Game Objects tree to gizmos\special and place an Interface Fader gizmo.
Select the Interface Fader gizmo and open its template properties. Under the [interface_fade] block, find the interface field and type in the chaptername from the chaptername.gas file you created. In the duration field, type in the length of time, in seconds, that you want the chapter interface to display onscreen before fading. Now that the Chapter Interface is setup, place a generic trigger near the region's starting positions. Set it up to be a bounding box or sphere that encompasses all of the starting positions, and wire it to send a we_req_activate to the Interface Fader gizmo. 
TIP: In Dungeon Siege, we used a Chapter Interface duration of 7 seconds. That's all there is to it! If you test it out in the game, you'll see the chapter graphic appear as you enter the world. When you talk to NPC 1 (Ella), you'll receive her quest neatly sorted under the Chapter 1 heading in the Journal.
== Conclusion ==
After completing this tutorial, you should now be comfortable creating, updating, and completing Quests and organizing them into Chapters. By experimenting with different scenarios, you should be able to continue to broaden your skill in creating stories with quests, chapters, gizmos and a few actor and object props. For the more complicated situations, use the knowledge you gained from Siege U: 208B - Talk Skrits to combine multiple conversations and custom buttons with quest and object detection and manipulation.