Difference between revisions of "Modding Tutorials/Quests"

From RimWorld Wiki
Jump to navigation Jump to search
m (Add To-Do)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{stub}}
 
{{stub}}
 +
=TODO=
 +
* Add examples for each node
 +
* Add base-game quest and explain every part of it
 +
* Compare single-QuestNode approach to "proper" fragmented QuestNode approach
 +
 
==Preamble==
 
==Preamble==
 
Who this is for: Brave modders that want to tackle the quest system
 
Who this is for: Brave modders that want to tackle the quest system
Line 5: Line 10:
 
Who this is not for: Beginners that have not invested a large amount of time into how the games basic components work
 
Who this is not for: Beginners that have not invested a large amount of time into how the games basic components work
  
Making or modifying quests is a complicated endeavor. Ludeon itself appears to have given up on using the QuestScriptDef "properly" with the new quests from Ideology, and the modders that have followed their example. This tutorial is for the '''proper''' Quest system that was implemented with Royalty and offers the most extensibility (for what it's worth, the quests are still extremely difficult to modify or extend)
+
Making or modifying quests is a complicated endeavor. Ludeon itself appears to have given up on using the <code>QuestScriptDef</code> "properly" with the new quests from Ideology, and some modders have followed their example. This tutorial is for the '<code>proper</code>' Quest system that was implemented with Royalty and offers the most extendibility (for what it's worth, the quests are still extremely difficult to modify or extend).
  
==Fundamentals==
+
"Modern" quests simply have one single bloated <code>QuestNode</code> generating all <code>QuestPart</code>s, ignoring the <code>Slate</code> and compartmentalized <code>QuestNode</code> approach entirely. This is certainly a functional way of creating a <code>Quest</code>, but far away from the potential extendibility of "proper" quest logic.
 +
 
 +
=Types=
 +
==Generation time==
 +
These types are normally restricted to the generation time of a given quest. This means these are instanced and not scribed at any point, acting only as the builders for the later generated quest objects.
 
===QuestScriptDef===
 
===QuestScriptDef===
 +
The <code>QuestScriptDef</code> is the root container for any given quest. It contains the <code>root</code> <code>QuestNode</code>, which determines the behaviour of the generated <code>Quest</code>.
 +
 +
===QuestNode===
 +
<code>QuestNode</code>s are types meant to pass or modify slate data and create <code>QuestPart</code>s. I personally like to divide the "responsibility" of <code>QuestNode</code>s into two categories: <code>Slate</code>-Modifiers and <code>QuestPart</code>-Generators.
 +
 +
====Slate-Modifiers====
 +
Responsible for manipulating data in the <code>Slate</code>, so that later <code>QuestNode</code>s (most likely <code>QuestPart</code>-Generators) can consume it.
 +
 +
Here you retrieve pawns to affect, factions to interact with, maps to use, basically the context-data for your actual moving parts.
  
 +
====QuestPart-Generators====
 +
Create <code>QuestPart</code> instances and append it to the Quest instance that is currently being generated.
  
===QuestNode===
+
Following methods in <code>QuestNode</code> are of note:
 +
====TestRunInt()====
 +
This method is called when the quest is being considered for generation. It is responsible for setting up slate data for other <code>TestRunInt()</code> calls of other nodes, emulating the (later executed) normal <code>RunInt()</code> call, '''without actually having a real effect'''. The idea being that the <code>QuestNode</code> performs a dry run, only modifying other generation time values and not actually modifying anything on the players map.
 +
 
 +
The TestRunInt() has the temporary <code>Slate</code> provided as an argument, which contains the other Test-Run slate modifications instead of the global static Slate.
  
 +
====RunInt()====
 +
The "real" execution of the <code>QuestNode</code>, modifying <code>Slate</code>data and/or creating <code>QuestPart</code> instances.
  
 
===Slate===
 
===Slate===
 +
The <code>Slate</code> is basically a <code>Dictionary<string, object></code>, being used as the main transport medium for data related to quest generation - like pawns, maps, points to use for threats, etc.
 +
Access to the slate can be done manually in-code with <code>slate.Get<T>()</code>, or by using the <code>SlateRef</code> type.
  
 +
===SlateRef===
 +
Controls the access to the slate, allowing the <code>QuestScriptDef</code>s XML to provide the key names to use.
 +
 +
==Run time==
 +
The produced objects from the generation time quest types.
 +
===Quest===
 +
The produced result of a <code>QuestScriptDef</code>, containing a list of quest parts. This is the thing you see listed in the Quests tab of the game.
  
 
===QuestPart===
 
===QuestPart===
 
+
<code>QuestPart</code>s are the logic blocks making up a <code>Quest</code>, the main hook being based on receiving quest related signals and acting upon them.
  
 
===Signal===
 
===Signal===
 +
<code>Signal</code>s are basically a simple string, sometimes accompanied with additional data called <code>NamedArgument</code>, which act as keyed object types, containing any instance the signal creator inserts into it.
  
 +
=How quest generation works=
 +
These steps may not be 100% accurate, as far as I can tell there is not a lot of modders that have dug this deep in the guts of the quest generation logic, so if some things are off, I sincerely apologize, but this is the best you'll get.
 +
# When the game wants to generate a random quest (so-called natural quests) it considers all of the <code>QuestScriptDef</code>s loaded into the <code>DefDatabase</code>, picking a random one by weight determined by the ''QuestScriptDef.rootSelectionWeight''.
 +
# It then checks if the <code>root</code> <code>QuestNode</code> of the ScriptDef successfully passes the ''TestRunInt()'' with an emulated slate
 +
# Once the <code>QuestScriptDef</code> is considered valid, the static <code>QuestGen</code> class comes into play, receiving the ''Generate()'' call with the chosen <code>QuestScriptDef</code>
 +
# It now populates the ''QuestGen.slate'' with the initial <code>Slate</code> values, which is normally ''Map map'' (the target for the quest) and ''int points'' (the threat/reward points to use)
 +
# The main call-stack that calls all the <code>QuestNode</code> ''RunInt()'' looks as follows: ''QuestGen.Generate()''->''(QuestScriptDef)root.Run()''->''(QuestNode)root.Run()''->''(QuestNode)this.RunInt()''
 +
# Once the <code>QuestPart</code>s are populated, the <code>Quest</code> is fully generated and made available
  
 
[[Category:Modding tutorials]]
 
[[Category:Modding tutorials]]

Latest revision as of 09:26, 18 November 2022

TODO[edit]

  • Add examples for each node
  • Add base-game quest and explain every part of it
  • Compare single-QuestNode approach to "proper" fragmented QuestNode approach

Preamble[edit]

Who this is for: Brave modders that want to tackle the quest system

Who this is not for: Beginners that have not invested a large amount of time into how the games basic components work

Making or modifying quests is a complicated endeavor. Ludeon itself appears to have given up on using the QuestScriptDef "properly" with the new quests from Ideology, and some modders have followed their example. This tutorial is for the 'proper' Quest system that was implemented with Royalty and offers the most extendibility (for what it's worth, the quests are still extremely difficult to modify or extend).

"Modern" quests simply have one single bloated QuestNode generating all QuestParts, ignoring the Slate and compartmentalized QuestNode approach entirely. This is certainly a functional way of creating a Quest, but far away from the potential extendibility of "proper" quest logic.

Types[edit]

Generation time[edit]

These types are normally restricted to the generation time of a given quest. This means these are instanced and not scribed at any point, acting only as the builders for the later generated quest objects.

QuestScriptDef[edit]

The QuestScriptDef is the root container for any given quest. It contains the root QuestNode, which determines the behaviour of the generated Quest.

QuestNode[edit]

QuestNodes are types meant to pass or modify slate data and create QuestParts. I personally like to divide the "responsibility" of QuestNodes into two categories: Slate-Modifiers and QuestPart-Generators.

Slate-Modifiers[edit]

Responsible for manipulating data in the Slate, so that later QuestNodes (most likely QuestPart-Generators) can consume it.

Here you retrieve pawns to affect, factions to interact with, maps to use, basically the context-data for your actual moving parts.

QuestPart-Generators[edit]

Create QuestPart instances and append it to the Quest instance that is currently being generated.

Following methods in QuestNode are of note:

TestRunInt()[edit]

This method is called when the quest is being considered for generation. It is responsible for setting up slate data for other TestRunInt() calls of other nodes, emulating the (later executed) normal RunInt() call, without actually having a real effect. The idea being that the QuestNode performs a dry run, only modifying other generation time values and not actually modifying anything on the players map.

The TestRunInt() has the temporary Slate provided as an argument, which contains the other Test-Run slate modifications instead of the global static Slate.

RunInt()[edit]

The "real" execution of the QuestNode, modifying Slatedata and/or creating QuestPart instances.

Slate[edit]

The Slate is basically a Dictionary<string, object>, being used as the main transport medium for data related to quest generation - like pawns, maps, points to use for threats, etc. Access to the slate can be done manually in-code with slate.Get<T>(), or by using the SlateRef type.

SlateRef[edit]

Controls the access to the slate, allowing the QuestScriptDefs XML to provide the key names to use.

Run time[edit]

The produced objects from the generation time quest types.

Quest[edit]

The produced result of a QuestScriptDef, containing a list of quest parts. This is the thing you see listed in the Quests tab of the game.

QuestPart[edit]

QuestParts are the logic blocks making up a Quest, the main hook being based on receiving quest related signals and acting upon them.

Signal[edit]

Signals are basically a simple string, sometimes accompanied with additional data called NamedArgument, which act as keyed object types, containing any instance the signal creator inserts into it.

How quest generation works[edit]

These steps may not be 100% accurate, as far as I can tell there is not a lot of modders that have dug this deep in the guts of the quest generation logic, so if some things are off, I sincerely apologize, but this is the best you'll get.

  1. When the game wants to generate a random quest (so-called natural quests) it considers all of the QuestScriptDefs loaded into the DefDatabase, picking a random one by weight determined by the QuestScriptDef.rootSelectionWeight.
  2. It then checks if the root QuestNode of the ScriptDef successfully passes the TestRunInt() with an emulated slate
  3. Once the QuestScriptDef is considered valid, the static QuestGen class comes into play, receiving the Generate() call with the chosen QuestScriptDef
  4. It now populates the QuestGen.slate with the initial Slate values, which is normally Map map (the target for the quest) and int points (the threat/reward points to use)
  5. The main call-stack that calls all the QuestNode RunInt() looks as follows: QuestGen.Generate()->(QuestScriptDef)root.Run()->(QuestNode)root.Run()->(QuestNode)this.RunInt()
  6. Once the QuestParts are populated, the Quest is fully generated and made available