Skip to Content
defold-typescript libraries
Insality

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
    1. 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 — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as quest from "quest"

Functions

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 action
  • object?: string | undefined — Event object
  • amount?: 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 id
  • task_index: number — Task index. ⚠️ 1-based; passed to quest unchanged.
  • 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: string
  • task_index: number — ⚠️ 1-based; passed to quest unchanged.

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

On this page

Functionsset_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 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 taskget_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[]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") endset_logger(logger_instance?: quest_logger | LuaTable | undefined)reset_state()get_quests_data(): LuaTable<string, quest_config>get_quests_count(): numberVariableson_quest_event: quest_queue_quest_eventis_can_start: quest_event_is_can_startis_can_complete: quest_event_is_can_completeis_can_event: quest_event_is_can_eventTypesquest_configquest_config.tasks: quest_task[]quest_config.required_quests: string[] | string | undefinedquest_config.category: string | undefinedquest_config.events_offline: boolean | undefinedquest_config.autostart: boolean | undefinedquest_config.autofinish: boolean | undefinedquest_config.repeatable: boolean | undefinedquest_config.use_max_task_value: boolean | undefinedquest_taskquest_task.action: stringquest_task.object: string | undefinedquest_task.required: number | undefinedquest_task.initial: number | undefinedquest_event_dataquest_event_data.type: quest_event_typequest_event_data.quest_id: stringquest_event_data.quest_config: quest_configquest_event_data.delta: number | undefinedquest_event_data.total: number | undefinedquest_event_data.task_index: number | undefinedquest_loggerquest_logger.trace: (_: unknown, msg: string, data: unknown) => voidquest_logger.debug: (_: unknown, msg: string, data: unknown) => voidquest_logger.info: (_: unknown, msg: string, data: unknown) => voidquest_logger.warn: (_: unknown, msg: string, data: unknown) => voidquest_logger.error: (_: unknown, msg: string, data: unknown) => voidquest_statequest_state.current: LuaTable<string, quest_progress>quest_state.completed: string[]quest_progressquest_progress.progress: number[]quest_progress.is_active: booleanquest_progress.start_time: number