View source for Journal: Adding a Quest to a Situation

= Overview =
This page is a tutorial on how to design a quest, implement it in the journal, and set up scripting to trigger updates. As we progress, we'll link to relevant pages that explain some of the terms and processes referred to in this tutorial. You will, however, be best equipped if you've already read the following pages: 

* [[Journal Structure Overview]] (We recommend reading this structural overview first because it defines some key terms used throughout this tutorial.)
* [[Journal Design Guidelines]]
* [[Adding Quest Rewards]]

= Narrative Brief =
Before we jump into the quest design, we need a narrative brief to work with:<blockquote>''A Dragonborn wizard wants a spellbook that is in the possession of a Tabaxi magician. If the player talks to the Tabaxi and explains that the Dragonborn wants the spellbook, the Tabaxi suggests tricking the Dragonborn, and gives the player a fake spellbook that is magically booby-trapped.''

''The Tabaxi says that the magical booby-trap will not kill the Dragonborn, but should discourage the Dragonborn from trying to get the real spellbook in the future. Refusing the Tabaxi makes the Tabaxi temporarily hostile. The player can always come back and change their mind (unless the Tabaxi is dead).''

''The player may steal the real spellbook and bring it to the Dragonborn, or follow along with the Tabaxi’s ruse and give the Dragonborn the booby-trapped book. Using the booby-trapped book casts the Feeblemind spell on the character who used it, reducing their Intelligence to 1.''</blockquote>There are plenty of fun things we could do to improve this situation (like switching the spellbooks and giving the booby-trapped one to the Tabaxi instead), but we are going to keep it simple for the purpose of this tutorial.

= Quest Design =
The end-goal of the quest is to bring the spellbook to the Dragonborn.

There’s a twist, however. We can also double-cross the Dragonborn, which is an alternative way to reach the end-goal. (In this broader context, the end-goal becomes “resolve the spellbook situation”.) We can do this by adding a subquest.

We have one call-to-action for the main quest (the request from the Dragonborn), and one to start a subquest (the counter-offer from the Tabaxi).

Before continuing, try to come up with the key updates and moments in the quest yourself by applying the [[Journal Design Guidelines]] to the narrative brief. It might help to draw this as a flowchart on paper to see where each update occurs.

=== Key Updates ===
* <code>TalkedToDragonborn</code>: The player started the quest.
* <code>BookStolen</code>: The player pickpocketed the book from the Tabaxi.
* <code>TalkedTabaxi_agreed</code>''':''' The player talked to the Tabaxi and agreed to help them trick the Dragonborn (and got a booby-trapped book as a result). This will start a '''subquest'''.
** This can’t trigger if the player stole the book before talking to the Tabaxi, because the Tabaxi always checks if it’s in their possession.
* <code>TalkedTabaxi_refused</code>''':''' The player listened to the Tabaxi’s offer, but decided not to help them. This can be logged in the journal so the player knows there's an offer they can accept if they want to.
* <code>TabaxiGone</code>: The Tabaxi was permanently defeated. This should not end the quest, but will trigger alongside the ending of the Tabaxi’s subquest (if it was accepted).
* <code>DragonbornGone_TabaxiWaiting</code>: The Dragonborn was permanently defeated, but the player is on the Tabaxi’s subquest. We want the player to go and report back to the Tabaxi (and possibly get the reward, depending on how cruel the Tabaxi is).
* <code>DragonbornTricked</code>''':''' The player double-crossed the Dragonborn, and left them Feebleminded as a result.
* <code>BookLost</code>: The spellbook was lost. The player would need to report to the Dragonborn.
** The player may have both books in their possession if they pickpocketed the Tabaxi after getting the booby-trapped book from them. If the player reports to the Dragonborn about the book being lost, the quest is over.

=== Closures ===
* <code>Rewarded</code>: The player brought the book to the Dragonborn and was rewarded.
** Depending on the narrative, we may want to add versions to cover whether the Tabaxi died or not. The Dragonborn may be a thief, but not a murderer. (Or there could, of course, be another twist to the story. This tutorial will keep it relatively simple.)
* <code>DragonbornGone</code>: This is a default fallback for if the Dragonborn died while the player was on the quest. We don’t want to trigger this update if the player is on the Tabaxi’s subquest, though (see above).
** Note that it’s safe to close the quest here, since the player can’t get the subquest from the Tabaxi if the Dragonborn is dead.
* <code>ReportedDragonborn_NoReward</code>: The player lost the book and reported this to the Dragonborn.
* <code>Rewarded_Tabaxi</code>: The player tricked (or killed) the Dragonborn and reported back to the Tabaxi. The Tabaxi still had their spellbook and rewarded the player for their effort.
* <code>ReportedTabaxi_NoReward</code>: The same as '''Rewarded_Tabaxi''', but while the player was reporting back, the Tabaxi realised they lost their spellbook (and rightfully accused the player of stealing it). This either ends in a combat or a Deception roll, and the quest closes without a reward.
* <code>TabaxiGone_WasWaiting</code>: A fallback for if the player tricked the Dragonborn, but permanently defeated the Tabaxi before closing the quest.

=== Objectives ===
Next, we'll figure out the objectives and their priorities. Both the starting and closing objective have the highest priority, so we don’t need to work out which priority to map them to like we do for the other objectives.

Please check out the [[Journal Editor Overview]] for more detail on objectives and priorities.

In short, early objectives have a lighter priority and late objectives have a heavier priority as the player approaches the quest's resolution. In general, we initially set quest priorities to <code>1000</code> and increase by <code>100</code> per objective. The '''COMPLETION''' objective – which is a technical objective that simply closes the quest and doesn't contain any player-facing text – uses the extremely high priority value of <code>1000000</code> to make sure it's always the one to close the quest.

* '''Quest:''' '''“Steal the Spellbook”'''
* '''Objective: “Steal the Spellbook”'''
** Priority: 1000
** Steps: '''TalkedToDragonborn, TalkedTabaxi_agreed, TalkedTabaxi_refused, TabaxiGone'''

* '''Objective: “Report to the Dragonborn”'''
** Priority: 1100
** Steps: '''BookStolen, BookLost'''
* '''Objective: “Report to the Tabaxi”'''
** Priority: 1200
** Steps: '''DragonbornTricked, DragonbornGone_TabaxiWaiting'''
* '''COMPLETION'''
** Priority: 1000000
** [All other closing steps]

=== Subquest ===
Subquests are not always needed in every quest, but this narrative brief allows it because the player can double-cross the Dragonborn. The structure of the subquest would look like this:

* '''Quest: “Trick the Dragonborn”'''
* '''Objective: “Give the booby-trapped book to the Dragonborn”'''
** Priority: 1000 (subquests use their own priority)
** Steps: '''Sub_AgreedToHelp'''
* '''COMPLETION'''
** Priority: 1000000
** [All closing steps] '''Sub_TabaxiGone, Sub_Tricked, Sub_LostTrappedBook, Sub_RewardedDragonborn'''

As you can see, the subquest is focused on tricking the Dragonborn. As soon as this is done (or failed/skipped), the flow continues in the main quest.

= Journal Editor Implementation =
Now that the design is done, we can implement it in the Journal Editor. See the [[Journal Editor Overview]] for general guidance on how to use the Journal Editor.

=== Open the Journal Editor ===
Load the main Editor and find the Journal Editor icon, which looks like an open journal, in the main toolbar. 
[[File:Image-20231107-115724.png|alt=An image showing where the journal editor icon can be found in the editor.|thumb|800x800px|center|Opening the Journal Editor.]]

=== Open Your Mod ===
Open the mod you want to add your journal data to. For the purpose of this tutorial, we’ll use the “TestLevels_Design” mod.
[[File:Image-20231107-121124.png|alt=an image of the journal editor mod selection|thumb|800x800px|center|Opening our mod called "TestLevel_Design" in the list of Projects.]]

=== Add a New Category ===
Make a new category by clicking the <code>+</code> button next to the '''Quest Categories''' list in the mod. Add a new quest to it by pressing the <code>+</code> next to the category’s '''Quests''' list and fill in the data.
[[File:Image-20231107-121530.png|alt=an image of the journal category list|thumb|800x800px|center|Adding a quest new category to the mod.]]

=== Add the Objectives ===
Expand the quest and add all of the objectives.
[[File:Image-20231107-155408.png|alt=an image of the journal objectives|thumb|600x600px|center|Adding the objectives to the quest.]]

=== Add Map Markers ===
Now we need to add markers to the objectives. To be able to do this, we first need to add these markers to the game.

This step of adding map markers is optional, depending on whether the objectives need markers. For this tutorial, map markers are needed.

==== Open the Markers Editor ====

Open the Markers Editor by clicking the map pin icon on the Editor's main toolbar.[[File:Image-20231107-132333.png|alt=an image of the markers editor icon|thumb|800x800px|center|Opening the Markers Editor.]]

==== Add New Map Markers ====
Add map markers for the entities you think it would be useful to have a map marker for in your quest. In our example, we'll add markers for the spellbook, Dragonborn and Tabaxi.
* <code>MarkerLevel</code>: The name of the level where the entities are placed.
* <code>MarkerTargetObjectUUID</code>: The entity's GUID. (You can get the GUID of the entity by right-clicking on it and picking '''Copy GUID to the clipboard'''.)
* <code>MarkerTargetObjectType</code>: <code>Item</code> for items (like the spellbook), and <code>Character</code> for characters (like the Dragonborn and Tabaxi).
* <code>MarkerIcon</code>: <code>Quest</code>.
* <code>DisplayText</code>: The player-facing name of the entity that'll appear in-game.
[[File:Image-20231107-132258.png|alt=an image of the list of markers|thumb|800x800px|center|Adding three map markers: one for the book, another for the Dragonborn, and another for the Tabaxi.]]

You can read more about map markers and the Markers Editor in [[Working with Map Markers]].

=== Reference the Markers ===
Back in the Journal Editor, add a reference to the corresponding markers you've now created for each objective, except the '''COMPLETION''' objective, in the '''Markers''' field. There is a search filter you can use here to find the markers quickly via their '''MarkerID'''.
[[File:Image-20231107-133937.png|alt=an image of the markers reference in the journal editor|thumb|1000x1000px|center|Referencing the relevant map markers in the "Markers" field of an objective.]]

=== Add Quest Steps to the Objectives ===
Now it’s time to add quest steps to each objective. '''TalkedToDragonborn''' is the update that starts the quest, so we'll set the '''Add/Close Quest''' option to '''Add Quest''':
[[File:Image-20231107-134830.png|alt=an image of the objectives view in the journal editor|thumb|855x855px|center|Adding the TalkedToDragonborn step and setting it to "Add Quest".]]
Add a '''StepID''', '''Description''' (the player-facing text), and '''Comment''' (for internal reference; non-player-facing). Leave the rest of the properties as the default for now.

Add the rest of the quest steps. The '''COMPLETION''' step should have '''Close Quest''' in the '''Add/Close Quest''' field, and the rest should have that field left empty.
[[File:Image-20231107-141007.png|alt=an image showing more objectives in view|thumb|957x957px|center|DragonbornGone being marked as Close Quest, with a StepID, Description, and Comment.]]

=== Add Rewards ===
When all of the steps are added, we can do a rewards pass. Before doing this, check out [[Adding Quest Rewards]], which provides a thorough explanation of rewards and the fields highlighted in these screenshots.

Let’s add an XP reward ('''ExperienceReward''') to the '''BookStolen''' step – when the player steals the book:
[[File:Image-20231107-142828.png|alt=an image of the rewards view in the journal editor|thumb|800x800px|center|Setting the AreaLevelOverrideGUID and ExperienceReward for the BookStolen step.]]

* <code>AreaLevelOverrideGUID</code>: For the purpose of this example, pick anything from the list. Do not leave it empty.

* <code>ExperienceReward</code>: We can set this to '''ProgressMajor''' because this step makes meaningful progression in the quest.

Let’s also add '''XP''' and '''treasure''' rewards to the two closing steps – '''Rewarded''' and '''Rewarded_Tabaxi''':
[[File:Image-20231107-151844.png|alt=an image of more rewards in the journal editor|thumb|600x600px|center|Adding XP and treasure rewards to the Rewarded closing step.]]

* <code>ExperienceReward</code>: We'll set this to '''CloseMajor''' because '''Rewarded''' is a closing step in the quest.

* <code>RewardCarriedTemplates</code>: For the sake of this guide, we will be rewarding an item from the NPC’s inventory (a scroll in the case of the Dragonborn).

* <code>RewardCarriedOwner</code>: The Dragonborn the scroll will be taken from.

* <code>RewardCarriedFallbackTreasureTable</code>: In case the reward item is stolen, we will add a fallback treasure table (we are using “Gold_QuestReward_Small”). Don’t forget to add the reward item to the Dragonborn’s inventory.

=== Add a Subquest ===
Add a subquest by pressing the <code>+</code> button next to the '''SubQuests''' list.
[[File:Image-20231107-155746.png|alt=an image showing how to add a new subquest|thumb|600x600px|center|Adding a subquest to the TEST_Spellbook quest called TEST_Spellbook_SUB_Trick.]]
Then add the objectives, steps, and rewards, like we did for the main quest.

= Osiris Implementation =
Once the quest structure is defined in the Journal Editor, it’s time to hook up the quest steps to game events.

For further reading related to journal implementation in Osiris, check out the following pages:

* [[Journal DB Helpers]]
* [[Journal Osiris Calls]]

=== Set a State Flag in a Dialogue ===
For the purpose of this tutorial, we are not going to use quest flags. Instead, we’ll add global flags for the major decisions the player can make in dialogues.

In the screenshot below of the Dialogue Editor, we've selected a dialogue node (the bubble on the left containing in-game text that will show up in a dialogue) and added '''TEST_Spellbook_State_AgreedQuest''', a global flag, in the '''Flags to Set''' field of the selected node. The flag will now be set when the player chooses this dialogue option.
[[File:Image-20231107-160851.png|alt=an image of the dialog editor, showing a flag being set on a node|thumb|600x600px|center|Setting a global flag on a dialogue node.]]

=== Add Helper DBs ===
In Osiris, we can use helper DBs to hook up the flags being set to the corresponding steps being unlocked. Create a new goal in the Story Editor and add <code>DB_QuestDef_State</code> entries in the INIT section, to match flags with quest steps.
[[File:Image-20231107-161825.png|alt=an image of the story editor showing helper DBs being set|thumb|800x800px|center|Using helper DBs to hook up flags and corresponding quest steps.]]

=== Add QuestUpdate Call ===
Where the generic helper DBs are not enough, we can add custom scripting to update the quest. We'll need to set up additional logic to check when the player has possession of the book in order to update the quest.
[[File:Image-20231107-162158.png|alt=an image showing custom scripting for updating a quest|thumb|800x800px|center|Using custom scripting to check when the player has the spellbook in order to update the quest.]]
Hook up the rest of the steps to the game events either by using helper DBs or via custom scripting that reacts to the game events directly.<blockquote>''ⓘ  Subquests use the main quest's QuestID to trigger their QuestUpdates, not their own QuestID. (In our case, it's “TEST_Spellbook”, not “TEST_Spellbook_SUB_Trick”.)''</blockquote>

= Debugging =
The final step is to play and test the quest. Play through it multiple times in different ways to test each outcome. Also check what happens if you do things out of order – are there any steps missing?

If you have any issues with quest updates triggering, you can always check the Journal debug overlay tab. When a player character is selected, it displays a list of all the tracked quests and their state, alongside current objectives and unlocked steps. To activate this, use <code>Ctrl+Shift+Middle Mouse Click</code> and then click on the '''Journal''' tab.

If you want to trigger an individual quest step update for a quick test, you can use the ReCon command <code>oe qupd <questID> <stepID></code> (e.g. <code>oe qupd TEST_Spellbook TalkedDragonborn</code>).

[[Category:Scripting]]
[[Category:Journal]]