|
Index
Page Contents
|
|
Documentation for Quest Files
|
| To-Do: | Due to a limitation on the website I've replaced curly braces with double square brackets in json samples on this page temporarily. This code will need to be fixed after the issue is resolved. |
Quest File
| Tip: | Quest files are json files stored in the game's resource folders under the path data/quests . |
To create a new quest we'll first need a quest descriptor file. This file should be placed in data/quests someplace appropriate. Most quests are organized under the region and then guild they are associated with.
Here is a minimal sample of a Quest Definition File:
Sample JSON
[[
"title" : "Join the Defenders Guild",
"description" : ".",
"category-id" : "taipii-defenders-guild",
"primary-contact-id" : "ramasu",
"start-chapter-id" : "the-basics",
"script-resource-id" : "data/quests/taipii-defenders-guild/join-defenders-guild.lua",
"start-script" : "my_quest_start()",
"load-script" : "my_quest_load()",
"initial-variables" :
[[
...
]],
"chapters" :
[[
...
]]
]]
Quest Definition Parameters
|
| Yes | none | The title of the quest | | Yes | none | A short description of the quest. Appears on the player's quest information page. | | Yes | none | The category the quest should appear under. See . | | Yes | none | Instance ID of character that will act as an initial contact point. (Currently unused and may be removed.) | | Yes | none | The id of the starting chapter. | | No | none | A map of quest variables and their initial values. When a new quest instance is created (a player or group of players start the quest) the quest instance will start with these variables set this way. | | No | none | The resource id (path) of a lua script file. This lua script can define functions that are called when chapters and objectives change. | | No | none | LUA script that is executed when the quest instance is created. (Code, not a file/resource path.) | | No | none | LUA script that is executed each time the save game is loaded. This can be useful for fixing issues with a quest instance on load. (Code, not a file/resource path.) |
| Note: | To prevent confusion with JSON markup it is recommended that you place LUA code in a separate file and then provide the file resource in the script-resource-id parameter of the quest. You can then use the ...-script parameters to call a function in the specified LUA file. Code is allowed in the ...-script fields for short one-line instructions where a function would be more verbose, but be mindful of escaping quotation marks in the JSON with " |
Quest Chapters
Quests are composed from chapters. Every quest must have at least one chapter to function correctly. Chapters are added to the chapters map in the quest definition file.
Sample JSON
"chapters" :
[[
"the-basics" :
[[
"title" : "Learning the Basics",
"description" : "Meet your contact from the Defenders Guild and prepare for your first mission.",
"start-script" : "my_chapter_start()",
"reset-script" : "my_chapter_reset()",
"complete-script" : "my_chapter_complete()",
"primary-objectives" :
[[
...
]],
"secondary-objectives" :
[[
...
]],
"prologue-hints" :
[[
...
]]
"active-hints":
[[
...
]],
"epilogue-hints" :
[[
...
]]
]]
]]
Quest Chapter Parameters
|
| Yes | none | The title of the chapter (Appears on player's quest screen.) | | Yes | none | A summary of the chapter's goal (Appears on player's quest screen.) | | No | none | LUA code that is executed when the chapter starts. (Code, not a file/resource path.) | | No | none | LUA code that is executed when the chapter resets. (Code, not a file/resource path.) | | No | none | LUA code that is executed when the chapter has been successfully completed. (Code, not a file/resource path.) |
Chapter Objectives
Chapters are defined with a prologue, primary objectives, secondary objectives, and epilogue. We'll discuss the prologue and epilogue further down in this document. First, lets discuss primary and secondary objectives.
Primary Objectives must be completed before a chapter can be completed. Primary Objectives for a chapter can be in one of two modes: ANY, or ALL. If the chapter is an "ANY" mode, then completing ANY primary objective completes the chapter. For "ALL" mode of course all primary objectives must be completed.
Secondary Objectives are not required to complete the chapter, but might affect how the quest progresses or provide additional rewards upon completion.
Sample JSON
"primary-objectives" :
[[
"obj-1" :
[[
"description" : "Ask Sakouv if he still has his original forging hammer.",
"conditions" :
[[
...
]],
"hints" :
[
...
]
]]
]]
Chapter Objective Parameters
|
| Yes | none | A summary of the objective's goal (Appears on player's quest screen.) |
Objective Conditions
Each objective has one or more Conditions that must be met in order for an objective to be completed.
Sample JSON
"conditions" :
[[
"obj-1-con-1" :
[[
"!class-name" : "QuestConversationCondition",
"character-instance-id" : "sakouv",
"character-name" : "Sakouv"
]]
]]
Objective Condition Parameters
|
| Yes | none | The c++ class that will provide code for checking this condition. See List below. |
| Note: | All further parameters are determined by which c++ class is specified to check the condition. |
Objective Condition Classes
The following classes are available for use as Objective Conditions:
QuestConversationCondition
| Note: | The QuestConversationCondition does not perform any condition checking. It simply returns "false" until a conversation script calls the SetQuestObjectiveComplete lua function to manually flag the condition as met. |
Additional Objective Condition Parameterss
Hints
Chapters and Objectives can provide a list of hints. Hints are described thusly:
Sample JSON
"hints" :
[
[[
"type" : "hud,map",
"target" : "medai",
"text" : "Speak with Medai",
"text-color" : color(1.0,0.2,0.6,1.0),
"indicator-type" : "inward-2",
"indicator-color" : color(1.0,0.2,0.6,1.0),
"icon-color" : color(1.0,0.2,0.6,1.0),
"icon-size" : 48.0,
"indicator-spin" : 90.0
]]
]
Hint Parameters - Common
|
| Yes | none | Can be set to hud, map, or both with hud,map. | | *Yes | none | Instance ID of target instance. (A target or position is required.) | | *Yes | none | Instance ID of target instance. (A target or position is required.) |
Hint Parameters - Common Text
The text parameters are shared between both HUD and MAP hints.
|
| No | "" | Very brief text naming the target. | | No | (Provided) | Color of text to appear on the map and/or hud. | | No | vector2(200, 20) | (HUD Only) Size of a virtual text box that determines word wrap. Provide this only if there is a problem with the way the text is wrapped by default. | | No | vector2(0, 42) | (HUD Only) Screen space offset of text from target position. Used to move text updown leftright in relation to the HUD point on the screen. |
Hint Parameters - HUD Indicator
|
| No | None | Full resource path of image/icon that will appear on the screen. A default is provided through indicator-type. | | No | "box" | Simpler alternative to indiator-resource-id. Name of image resource in the ui\icons\map folder to appear on-screen. | | No | (Provided) | Color of the on-screen HUD indicator icon. | | No | 64 | Size of the HUD indicator. | | No | 0 | Option to have the indicator icon spin, primarily for combat targets. | | No | vector3(0, 0.4, 0) | A vector3 world space offset from the position or target to display the HUD indicator. Example: The origin point of an object is at the base, rather than centered on the object. This can be offset by setting the world-space-offset to say vector3(0, 1, 0) to center the HUD indicator on the object. |
Hint Parameters - Map Indicators
|
| No | None | Full resource path of image/icon that will appear on the map. A default is provided through icon-type. | | No | "box" | Simpler alternative to icon-resource-id. Name of image resource in the ui\icons\map folder to appear on the map. | | No | (Provided) | Color of map icon. | | No | 24 | Size of map icon. |
| Tip: | In the future additional hint types may be added that include an on-screen "tutorial" text box. |
Chapter Prologue
(There is only a rare scenario where this is useful, I'll document it when I encounter it again.)
Chapter Epilogue
The chapter epilogue begins when the primary objectives for a chapter have been met. The purpose of the epilogue in most quest chapters is to close the chapter by having the player return to a contact NPC to progress to the next chapter. Secondary objectives may still be available while a chapter is in the "epilogue" state.
There are no objectives for the Epilogue, but the epilogue can provide hints. Typically this hint would just be "Speak with ..." and lead the player back to their quest contact.
|
Index
Page Contents
