Index
Page Contents

Quest File Format

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

Parameter RequiredDefaultDescription
title Yes none The title of the quest
description Yes none A short description of the quest. Appears on the player's quest information page.
category-id Yes none The category the quest should appear under. See .
primary-contact-id Yes none Instance ID of character that will act as an initial contact point. (Currently unused and may be removed.)
start-chapter-id Yes none The id of the starting chapter.
initial-varaibles 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.
script-resource-id 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.
start-script No none LUA script that is executed when the quest instance is created. (Code, not a file/resource path.)
load-script 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

Parameter RequiredDefaultDescription
title Yes none The title of the chapter (Appears on player's quest screen.)
description Yes none A summary of the chapter's goal (Appears on player's quest screen.)
start-script No none LUA code that is executed when the chapter starts. (Code, not a file/resource path.)
reset-script No none LUA code that is executed when the chapter resets. (Code, not a file/resource path.)
complete-script 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

Parameter RequiredDefaultDescription
description 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

Parameter RequiredDefaultDescription
!class-name 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

Parameter RequiredDefaultDescription
none

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

Parameter RequiredDefault Description
type Yes none Can be set to hud, map, or both with hud,map.
target *Yes none Instance ID of target instance. (A target or position is required.)
position *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.

Parameter RequiredDefault Description
text No "" Very brief text naming the target.
text-color No (Provided)Color of text to appear on the map and/or hud.
text-box-size 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.
text-screen-space-offsetNo 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

Parameter RequiredDefault Description
indicator-resource-idNo None Full resource path of image/icon that will appear on the screen. A default is provided through indicator-type.
indicator-type No "box" Simpler alternative to indiator-resource-id. Name of image resource in the ui\icons\map folder to appear on-screen.
indicator-color No (Provided)Color of the on-screen HUD indicator icon.
indicator-size No 64 Size of the HUD indicator.
indicator-spin No 0 Option to have the indicator icon spin, primarily for combat targets.
world-space-offset 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

Parameter RequiredDefault Description
icon-resource-id No None Full resource path of image/icon that will appear on the map. A default is provided through icon-type.
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.
icon-color No (Provided)Color of map icon.
icon-size 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.