Insality/defold-quest/quest
Quest system library for Defold games. Manage quests, objectives, and quest progression. Track events and customize behavior.
- GitHub: Insality/defold-quest — pinned to
4- This repo publishes no stable release. Pick a tag from Insality/defold-quest tags and add its Source code (zip) URL — for the pinned tag,
https://github.com/Insality/defold-quest/archive/refs/tags/4.zip— togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as quest from "quest"
- This repo publishes no stable release. Pick a tag from Insality/defold-quest tags and add its Source code (zip) URL — for the pinned tag,
Functions
set_state(external_state:quest_state)get_state():quest_stateinit(quest_config_or_path?: LuaMap<string,quest_config> | Record<string,quest_config> | string | undefined)add_quests(quest_config_or_path: LuaMap<string,quest_config> | Record<string,quest_config> | string)remove_quests(quest_ids: string[])event(action: string, object?: string | undefined, amount?: number | undefined)add_task_progress(quest_id: string, task_index: number, amount: number)is_active(quest_id: string): booleanis_completed(quest_id: string): booleanis_can_start_quest(quest_id: string): booleanis_can_complete_quest(quest_id: string): booleanget_progress(quest_id: string): LuaTable<number, number>get_task_progress(quest_id: string, task_index: number): numberstart_quest(quest_id: string): booleancomplete_quest(quest_id: string)force_complete_quest(quest_id: string)reset_progress(quest_id: string)reset_quest(quest_id: string)clear_all_progress()get_current(category?: string | undefined): LuaTable<string,quest_progress>get_completed(category?: string | undefined): LuaTable<string, boolean>get_can_be_started(category?: string | undefined): LuaTable<string, boolean>get_quest_config(quest_id: string):quest_configget_current_with_task(action: string, object?: string | undefined): string[]set_logger(logger_instance?:quest_logger| LuaTable | undefined)reset_state()get_quests_data(): LuaTable<string,quest_config>get_quests_count(): number
set_state(external_state: quest_state)
Set state (for saving/loading)
Parameters
external_state:quest_state
get_state(): quest_state
Get state (for saving/loading)
Returns
quest_state
init(quest_config_or_path?: LuaMap<string, quest_config> | Record<string, quest_config> | string | undefined)
Initialize quest system with config and start processing quests quest.init() quest.init(require("game.quests")) quest.init("/resources/quests.json")
Parameters
quest_config_or_path?:LuaMap<string, quest_config> | Record<string, quest_config> | string | undefined— Path to quest config or config table. Can be nil to init without quests.
add_quests(quest_config_or_path: LuaMap<string, quest_config> | Record<string, quest_config> | string)
Add quests to the current config from config file or table. Can be called any time. Other quests and their progress are kept. Quests with the same id are replaced. Quest configs are not saved: add the same quests again after loading the state. quest.add_quests(require("game.quests")) quest.add_quests("/resources/quests.json") quest.add_quests({ ["week_42:streaks"] = { autostart = true, tasks = { { action = "streak_points", required = 5 } } } })
Parameters
quest_config_or_path:LuaMap<string, quest_config> | Record<string, quest_config> | string— Lua table or path to quest config. Example: "/resources/quests.json"
remove_quests(quest_ids: string[])
Remove quests from config together with their progress and completed marks. Removed quests are not started again by autostart. Unknown ids only clear their saved state. quest.remove_quests({ "week_42:streaks", "week_42:coins" })
Parameters
quest_ids:string[]— Quest ids to remove
event(action: string, object?: string | undefined, amount?: number | undefined)
Main function to apply event to all current quests. Call it when specific quest action is performed. quest.event("game_started") quest.event("kill", "enemy") quest.event("kill", "enemy", 2) quest.event("collect", "coin", 3)
Parameters
action:string— Event actionobject?:string | undefined— Event objectamount?:number | undefined— Event amount default 1
add_task_progress(quest_id: string, task_index: number, amount: number)
Add progress to task
Parameters
quest_id:string— Quest idtask_index:number— Task index. ⚠️ 1-based; passed toquestunchanged.amount:number— Amount to add
is_active(quest_id: string): boolean
Check quest is active
Parameters
quest_id:string
Returns
boolean— Quest active state
is_completed(quest_id: string): boolean
Check quest is completed
Parameters
quest_id:string
Returns
boolean— Quest completed state
is_can_start_quest(quest_id: string): boolean
Check quest is can be started now
Parameters
quest_id:string
Returns
boolean— Quest can start state
is_can_complete_quest(quest_id: string): boolean
Check quest is can be completed now
Parameters
quest_id:string
Returns
boolean— Quest can complete state
get_progress(quest_id: string): LuaTable<number, number>
Get current progress on quest tasks. Returns an array-like table with task progress values. local progress = quest.get_progress("kill_enemies") print(progress[1]) -- Progress on first task print(progress[2]) -- Progress on second task
local progress = quest.get_progress("nonexistent_quest") print(#progress) -- Will be 0 for non-existent quests
Parameters
quest_id:string— Quest identifier
Returns
LuaTable<number, number>— List of task progress, ex {0, 2, 0}
get_task_progress(quest_id: string, task_index: number): number
Get task progress by task index
Parameters
quest_id:stringtask_index:number— ⚠️ 1-based; passed toquestunchanged.
Returns
number
start_quest(quest_id: string): boolean
Start quest, if it can be started
Parameters
quest_id:string
Returns
boolean— Quest started state
complete_quest(quest_id: string)
Complete quest, if it can be completed
Parameters
quest_id:string— Quest id
force_complete_quest(quest_id: string)
Force complete quest, without checking conditions
Parameters
quest_id:string— Quest id
reset_progress(quest_id: string)
Reset quest progress
Parameters
quest_id:string— Quest id
reset_quest(quest_id: string)
Reset quest, remove from current and completed lists, and update can be started list
Parameters
quest_id:string— Quest id
clear_all_progress()
Clear all quest progress
get_current(category?: string | undefined): LuaTable<string, quest_progress>
Get current active quests
Parameters
category?:string | undefined
Returns
LuaTable<string, quest_progress>
get_completed(category?: string | undefined): LuaTable<string, boolean>
Get completed quests map
Parameters
category?:string | undefined— Optional category filter
Returns
LuaTable<string, boolean>— Map of completed quests
get_can_be_started(category?: string | undefined): LuaTable<string, boolean>
Get quests that can be started
Parameters
category?:string | undefined— Optional category filter
Returns
LuaTable<string, boolean>
get_quest_config(quest_id: string): quest_config
Get quest config by id
Parameters
quest_id:string— Quest id
Returns
quest_config
get_current_with_task(action: string, object?: string | undefined): string[]
Get current quests that have tasks matching the specified action and object. Returns an array of quest IDs that contain matching tasks. local quests = quest.is_current_with_task("kill", "enemy") if #quests > 0 then print("Found " .. #quests .. " quests with kill enemy task") end
local quests = quest.is_current_with_task("collect") for i, quest_id in ipairs(quests) do print("Quest " .. quest_id .. " has collect task") end
Parameters
action:string— Action to check (e.g., "kill", "collect")object?:string | undefined— Object to check (e.g., "enemy", "coin"). Can be nil for any object
Returns
string[]— List of quest IDs that have matching tasks
set_logger(logger_instance?: quest_logger | LuaTable | undefined)
Customize the logging mechanism used by Quest Module. You can use Defold Log library or provide a custom logger.
Parameters
logger_instance?:quest_logger | LuaTable | undefined
reset_state()
Reset Module quest state and quests config, probably you want to use it only in case of soft game reload
get_quests_data(): LuaTable<string, quest_config>
Get quests data
Returns
LuaTable<string, quest_config>
get_quests_count(): number
Get total quests count in quests config
Returns
number— Total quests count
Variables
on_quest_event: quest_queue_quest_event
Single queue for all quest events in proper order: register -> start -> progress -> task_completed -> completed
is_can_start: quest_event_is_can_start
Triggered when a quest can be started. You can add additional conditions to the quest start validation. Callback is fun(quest_id: string, quest_config: quest.config): boolean
is_can_complete: quest_event_is_can_complete
Triggered when a quest can be completed. You can add additional conditions to the quest completion validation. Callback is fun(quest_id: string, quest_config: quest.config): boolean
is_can_event: quest_event_is_can_event
Triggered when a quest can be processed. You can add additional conditions to the quest event processing. Callback is fun(quest_id: string, quest_config: quest.config): boolean
Types
quest_config
quest_config.tasks: quest_task[]
List of tasks to complete
quest_config.required_quests: string[] | string | undefined
List of required quests or single required quest
quest_config.category: string | undefined
Used for filtering quests
quest_config.events_offline: boolean | undefined
If true, the quest events will be stored and processed even quest is not active
quest_config.autostart: boolean | undefined
If true, the quest will be started automatically after all requirements are met
quest_config.autofinish: boolean | undefined
If true, the quest will be finished automatically after all tasks are completed
quest_config.repeatable: boolean | undefined
If true, the quest will be not stored in the completed list
quest_config.use_max_task_value: boolean | undefined
If true, the maximum value of the task is used instead of the sum of all quest events
quest_task
quest_task.action: string
Action to perform to complete the task. Example: "destroy" or "collect"
quest_task.object: string | undefined
Object to specify the task, example: "enemy" or "money"
quest_task.required: number | undefined
Required amount of the object to complete the task. Example: 100. Default: 1
quest_task.initial: number | undefined
Initial amount of the object. Example: 0
quest_event_data
quest_event_data.type: quest_event_type
quest_event_data.quest_id: string
quest_event_data.quest_config: quest_config
Quest configuration
quest_event_data.delta: number | undefined
Progress delta (for "progress" type)
quest_event_data.total: number | undefined
Total progress (for "progress" type)
quest_event_data.task_index: number | undefined
Task index (for "progress" and "task_completed" types). ⚠️ 1-based; passed to quest unchanged.
quest_logger
quest_logger.trace: (_: unknown, msg: string, data: unknown) => void
quest_logger.debug: (_: unknown, msg: string, data: unknown) => void
quest_logger.info: (_: unknown, msg: string, data: unknown) => void
quest_logger.warn: (_: unknown, msg: string, data: unknown) => void
quest_logger.error: (_: unknown, msg: string, data: unknown) => void
quest_state
quest_state.current: LuaTable<string, quest_progress>
quest_id -> quest.progress
quest_state.completed: string[]
quest_progress
quest_progress.progress: number[]
Quest progress
quest_progress.is_active: boolean
Is quest started to earn quest events
quest_progress.start_time: number
Quest start time in seconds since epoch