Difference between revisions of "Modding quest chains"

From Wildermyth Wiki
 
(9 intermediate revisions by one other user not shown)
Line 1: Line 1:
(this guide underway by davea Feb 24, 2020)
This page walks through the process of creating multiple encounters which occur in a chain.  That is, one encounter occurs, and only after that a second encounter may occur based on the results of the first one, and then a third, fourth, etc encounters will occur in turn.  This type of "quest chain" is less complex than a full campaign, The focus is on getting something simple which you can see in the game, and adding more details later.  This guide assumes you have completed some of the earlier guides and does not define all the clicks for each step.  The description and screenshots are current as of February 2020, early access version 0.15+114 Lylcon Stormpuck.


This page walks through the process of creating multiple encounters which occur in a chain.  That is, one encounter occurs, and only after that a second encounter may occur based on the results of the first one.  This type of "quest chain" is less complex than a full campaign, The focus is on getting something simple which you can see in the game, and adding more details later.  This guide assumes you have completed some of the earlier guides and does not define all the clicks for each step.  The description and screenshots are current as of February 2020, early access version 0.15+114 Lylcon Stormpuck.
Note: setting up quest chains using this method can be complex and a little painful to debug.  The dev team has said that the "campaign plot" mechanism may be easier to use, even though these are not full campaigns.  However, there is no document or example of using this today, so this guide will not use that method.


(davea says: this topic is kind of important but I can see my description is not so clear.  If you are getting stuck on this, please ping me on discord and I'll try again on this guide.)


==Background==
The reference page [[Event Types]] describes different types of events.  It is not obvious, but not all events can perform all types of actions.  For example, you cannot (successfully) create an NPC in an overland activity, and you cannot add an aspect to an overland site during a mission victory.  The following diagram illustrates the restrictions.  The colors approximately represent many restrictions the event type has; green has the fewest restrictions, then yellow, then orange.


==Seeing the effect in game==
[[File:ModdingChainBubbles.PNG]]
This guide is set up in the opposite order to previous guides in this section.  It will be easier to understand what the mod does, after you see what it looks like.
<ol>
<li>Download and install the mod, "Oh No A Dragon" from steam: https://steamcommunity.com/sharedfiles/filedetails/?id=1925402595
<li>In developer mode, start a new game, select "one chapter", enable this mod.  Enable the pick events cheat and objectives cheat.  For this testing I usually also select "Skip progression" and "skip gear" to reduce the number of clicks needed to get to the interesting part.
<li>Use objectives cheat to finish the initial battle.
<li>Scout the nearest adjacent overland tile.  If it is a wilderness scouting event, pick one and go through it, then scout another tile so that you have an assault event (red sword icon).
<li>Perform the assault, and choose the event "Treasure map", which should be first or second on the list.  If you don't see this event, check that you installed and enabled the mod.
<li>The comic panel has a dialog line which names the nearby tile, where the treasure map leads.  You don't need to note it down, but observe that it is there.  Finish the encounter.
<li>On the overland map, you should now see a purple flag, in the overland tile which was named by the comic panel.  This tile is "usually" a scouted tile but not necessarily.
<li>If you click on the site icon (the hut in this case), rather than the overland tile background, you will also see a purple treasure map button, as shown here.
[[File:ModdingMapOverland.PNG]]
<li>Click the button or the flag, to get the popup where you assign participants to the job, as shown here.
[[File:ModdingMapParticipants.PNG]]
<li>The progress bar on the flag should move quickly, and then the dialog "Treasure Map" should appear.
<li>Click through this encounter.
</ol>
The key points of this are: a starting encounter which puts up the flag; the flag, button and dialog for the job; and the encounter itself.


==The starting encounter==
<ul>
This section describes the key parts of the starting encounter, which puts up the flag. Using the in-game editor, open the comic davea_map_start.  This is simple, but you can see the comic dialog reference to <otherSite.name>.  Now open the effect.  For a reason this author doesn't understand, this method currently only works for arriving at a hostile site, and does not work for either mission victory or wilderness scouting.
<li>Most quest chains will be triggered by an assault (EHAHS: ENCOUNTER_HEROES_ARRIVE_HOSTILE_SITE) or a wilderness encounter (EWS : ENCOUNTER_WILDERNESS_SCOUTING).  These are the most "powerful" encounter types; they can do anything including (a) generating named NPCs, (b) adding aspects to overland sites, (c) presenting a choice.
<li>Most quest chains will use a "job" (OA : OVERLAND_ABILITY) to direct the player to send a party to some spot on the map.  This encounter type ''cannot'' (a) generate named NPCs or (c) present a choice.  Named NPCs must be generated in a previous EHAHS or EWS.  If a choice is needed, it must be done via a BRANCH.
<li>Most quest chains will have some progression of these main types, EWS/EHAHS and OA, shown along the top of the above diagram.  This is only an example; each step can be any one of EHAHS, OA, EWS.  Within each step, there may be additional events, shown in the collection below each main type.  These secondary types also have restrictions.
<li>A victory encounter (EMV : ENCOUNTER_MISSION_VICTORY) may be attached to an EHAHS by victoryEncounterId, or it may occur standalone.  In either case, it ''cannot'' (a) generate named NPCS or (b) add aspects to overland sites. These should be done in advance.  It can call a BRANCH, but the branch still cannot create NPCs or add aspects.
<li>A mid-mission event (PME : PLOT_MISSION_EVENT) may be attached to an EHAHS.  In order to use a PME, the EHAHS must be a scripted mission (with a site and plot) as well.  See the separate topic [[Modding_scripted_missions]] for details on this.  As with EMV, it ''cannot'' (a) generate named NPCS or (b) add aspects to overland sites.
<li>A BRANCH may be attached to most event types.  Normally a branch is used after a choice within its caller, but it also allows (a) generating named NPCs from an OA, whereas the OA cannot itself generate a named NPC.
</ul>


The first key part is the targets section, shown below.  Target #3 defines the current site, which is generic.  Target #6 controls the party members for the encounter, as described in earlier guides; you must have one named role in order for site selection to work, but you will presumably have several anyway.  There are two magic parts: target #7, otherSite; and outcome #2, Aspects(otherSite).  The magic happens because this target picks nearby site by some rules, and attaching the aspect causes the flag+button to appear on the site.
Here is the reasoning for the above restrictions.   


[[File:ModdingMapTargets.PNG]]
<ul>
<li>EHAHS and EWS occur in the main game loop at the top level, so they can do everything.
<li>OA occur at the top level, but they are initiated by a player action (clicking on the banner) rather than within the main game loop.  That means they do not execute the "implications" section and cannot generate named NPCs.  (This author does not completely understand that description, but it was provided by the dev team.)
<li>EMV and PME occur at a lower level, only in the context of the EHAHS which generated them.  To reduce the amount of data stored, many actions done during EMV and PME are thrown away, rather than being copied back to the main data store.  So, you can create named NPCs and overland aspects during these events, but the results are not copied back, so future actions which depend on those will fail.
</ul>


This shows the detail of the target (screenshot edited to remove uninteresting fields). We are picking one random site called otherSite, which must be of type SITE and must not be the current site.  The canPath section uses one of your roles (target #6) to make sure that there is a path from this role to this site; this prevents selecting a site which is inaccessible due to impassible mountains or rivers.  '''Make sure the role in canPath matches one of the roles in your target''', otherwise this will silently fail.
==Example==
Let's take a simple example to show these restrictions in action.  Suppose we want the following sequence.  (1) An assault (EHAHS), followed by (2) a victory (EMV), which puts up a job banner (3); at the job, (4) a named NPC is introduced, and later a wilderness scouting (EWS) finishes the chain.  You may think that it is easiest to create each object just before it is used; for example, you may think you could create the OA (3) during the victory (2), and create the NPC (4) during the OA (3).  However, none of that will work; each step will silently fail because it violates the rules given in the previous section.  Here is a solution which will work.


[[File:ModdingMapSite.png]]
During EHAHS (1), create the job banner. You cannot create it during the EMV (2); it will silently fail. 


==Adding the aspect==
To create the NPC, either create it during EHAHS (1) or by introducing a BRANCH within the OA (3); you cannot create it either during the EMV (2) or the OA (3); it will silently fail.
The aspect is attached by the starting encounter to the otherSite.  When the game attaches the aspect, it performs the effect listed in the aspect.  In this case, that starts the "job" or treasure map encounter, which makes the flag and button appear.  Make sure that the aspect name given in the encounter matches the name of the aspect, and make sure that the effect name given in the aspect matches the name of the encounter.  If either of these pairs contain a typo or wrong name, the job will silently fail to trigger.


[[File:ModdingMapAspect.PNG]]


==Adding the second encounter==
<i>Adding a clarification after following this tutorial: The EWS can <b>reference</b> a named NPC that has been already created.   The OA cannot do so - you can't use an NPC in the OA at all because that happens in the implications section.   If you try to create an NPC in your OA it will silently fail to trigger on the map. Deleting the NPC again in the comics editor is insufficient; you need to go into the JSON and remove the implications section!</i>  
Using the in-game editor, view the second encounter, davea_map_job.  Unfortunately, this author considers most of this file to be "magic words" which work if used properly, but it is not clear which ones are required, or why.  Because the encounter has so many fields, it is easier to show the json code.  See [[Modding_Guide#Where_to_find_installed_mods|Where to find installed mods]] to locate the file davea_map_job.json on your disk.  These two targets appear to rely on hard coded names which are not explained anywhere this author can find.  The promptText appears in the dialog where you select the party.
 
<syntaxhighlight lang="json">
"targets": [
{
"template": "SELF_SITE_THIS_JOB_NOT_ACTIVE",
"aspects": [ "THIS_JOB_NOT_ACTIVE", "SELF" ]
},
{
"template": "JOB_PARTICIPANT",
"promptText": "Who will search for the X on the map?",
"slots": { "preFill": "noJobOrParty" }
}
],
</syntaxhighlight>
 
A few other details of the job are specified in the encounter, which are easier to explain. In the below screenshot of the job, the blurb is what appears in the overlap map tooltip when you hover over the flag.  The longName is used for the text of the button.  The icon ("magic") is used to select the icon that appears in the flag and the button. As of this writing, it is not possible for modders to add icons; but you can find existing icons and use one of them.  The category ("research") is used to select the color of the flag and button.  Research is purple, crafting is blue, and site is orange.  I don't think modders can control the colors either but probably it is better to use these standard colors.
 
[[File:ModdingMapAbility.PNG]]
 
==Putting it together==
The best way to create your own encounter like this is to copy the two files for the encounter out of this mod and into your own. Then edit them, either using a text editor on the json, or with the in-game editor.  Don't forget to create the aspect, and make sure all the names are matching. Then follow the instructions at the start of this guide to see your encounter in game.


[[Category:Modding]]
[[Category:Modding]]
[[Category:Modding Guides]]
[[Category:Modding Guides]]

Latest revision as of 08:27, 6 February 2022

This page walks through the process of creating multiple encounters which occur in a chain. That is, one encounter occurs, and only after that a second encounter may occur based on the results of the first one, and then a third, fourth, etc encounters will occur in turn. This type of "quest chain" is less complex than a full campaign, The focus is on getting something simple which you can see in the game, and adding more details later. This guide assumes you have completed some of the earlier guides and does not define all the clicks for each step. The description and screenshots are current as of February 2020, early access version 0.15+114 Lylcon Stormpuck.

Note: setting up quest chains using this method can be complex and a little painful to debug. The dev team has said that the "campaign plot" mechanism may be easier to use, even though these are not full campaigns. However, there is no document or example of using this today, so this guide will not use that method.

(davea says: this topic is kind of important but I can see my description is not so clear. If you are getting stuck on this, please ping me on discord and I'll try again on this guide.)

Background

The reference page Event Types describes different types of events. It is not obvious, but not all events can perform all types of actions. For example, you cannot (successfully) create an NPC in an overland activity, and you cannot add an aspect to an overland site during a mission victory. The following diagram illustrates the restrictions. The colors approximately represent many restrictions the event type has; green has the fewest restrictions, then yellow, then orange.

ModdingChainBubbles.PNG

  • Most quest chains will be triggered by an assault (EHAHS: ENCOUNTER_HEROES_ARRIVE_HOSTILE_SITE) or a wilderness encounter (EWS : ENCOUNTER_WILDERNESS_SCOUTING). These are the most "powerful" encounter types; they can do anything including (a) generating named NPCs, (b) adding aspects to overland sites, (c) presenting a choice.
  • Most quest chains will use a "job" (OA : OVERLAND_ABILITY) to direct the player to send a party to some spot on the map. This encounter type cannot (a) generate named NPCs or (c) present a choice. Named NPCs must be generated in a previous EHAHS or EWS. If a choice is needed, it must be done via a BRANCH.
  • Most quest chains will have some progression of these main types, EWS/EHAHS and OA, shown along the top of the above diagram. This is only an example; each step can be any one of EHAHS, OA, EWS. Within each step, there may be additional events, shown in the collection below each main type. These secondary types also have restrictions.
  • A victory encounter (EMV : ENCOUNTER_MISSION_VICTORY) may be attached to an EHAHS by victoryEncounterId, or it may occur standalone. In either case, it cannot (a) generate named NPCS or (b) add aspects to overland sites. These should be done in advance. It can call a BRANCH, but the branch still cannot create NPCs or add aspects.
  • A mid-mission event (PME : PLOT_MISSION_EVENT) may be attached to an EHAHS. In order to use a PME, the EHAHS must be a scripted mission (with a site and plot) as well. See the separate topic Modding_scripted_missions for details on this. As with EMV, it cannot (a) generate named NPCS or (b) add aspects to overland sites.
  • A BRANCH may be attached to most event types. Normally a branch is used after a choice within its caller, but it also allows (a) generating named NPCs from an OA, whereas the OA cannot itself generate a named NPC.

Here is the reasoning for the above restrictions.

  • EHAHS and EWS occur in the main game loop at the top level, so they can do everything.
  • OA occur at the top level, but they are initiated by a player action (clicking on the banner) rather than within the main game loop. That means they do not execute the "implications" section and cannot generate named NPCs. (This author does not completely understand that description, but it was provided by the dev team.)
  • EMV and PME occur at a lower level, only in the context of the EHAHS which generated them. To reduce the amount of data stored, many actions done during EMV and PME are thrown away, rather than being copied back to the main data store. So, you can create named NPCs and overland aspects during these events, but the results are not copied back, so future actions which depend on those will fail.

Example

Let's take a simple example to show these restrictions in action. Suppose we want the following sequence. (1) An assault (EHAHS), followed by (2) a victory (EMV), which puts up a job banner (3); at the job, (4) a named NPC is introduced, and later a wilderness scouting (EWS) finishes the chain. You may think that it is easiest to create each object just before it is used; for example, you may think you could create the OA (3) during the victory (2), and create the NPC (4) during the OA (3). However, none of that will work; each step will silently fail because it violates the rules given in the previous section. Here is a solution which will work.

During EHAHS (1), create the job banner. You cannot create it during the EMV (2); it will silently fail.

To create the NPC, either create it during EHAHS (1) or by introducing a BRANCH within the OA (3); you cannot create it either during the EMV (2) or the OA (3); it will silently fail.


Adding a clarification after following this tutorial: The EWS can reference a named NPC that has been already created. The OA cannot do so - you can't use an NPC in the OA at all because that happens in the implications section. If you try to create an NPC in your OA it will silently fail to trigger on the map. Deleting the NPC again in the comics editor is insufficient; you need to go into the JSON and remove the implications section!

Retrieved from "https://wildermyth.com/w/index.php?title=Modding_quest_chains&oldid=20111"