quests/core.lua

620 lines
24 KiB
Lua

--- Quests core.
-- @module core
-- Boilerplate to support localized strings if intllib mod is installed.
local S = minetest.get_translator("quests")
local empty_callback = function(...) end
local function compute_tasks(playername, questname, nocallback)
local quest = quests.registered_quests[questname]
local plr_quest = quests.active_quests[playername][questname]
for taskname, task in pairs(quest.tasks) do
local plr_task = plr_quest[taskname]
if task.requires == nil then
plr_task.visible = true
else
plr_task.visible = false
local was_visible = task.visible
local final_enabler = ""
for _, enabler_name in ipairs(task.requires) do
if type(enabler_name) == "table" then
plr_task.visible = true
for _, subena_name in ipairs(plr_quest[enabler_name]) do
local plr_subena = plr_task[subena_name]
if plr_task.visible and plr_subena and (not plr_subena.visible or not plr_subena.finished) then
plr_task.visible = false
end
end
else
if plr_quest[enabler_name] then
plr_task.visible = plr_quest[enabler_name].finished or false
else
plr_task.visible = true
end
end
if plr_task.visible then
final_enabler = enabler_name
break
end
end
if plr_task.visible and not was_visible and not nocallback then
task.availablecallback(playername, questname, taskname, final_enabler, quest.metadata)
end
end
if task.disables_on ~= nil then
local was_disabled = task.disabled
local final_disabler = ""
for _, disabler_name in ipairs(task.disables_on) do
if type(disabler) == "table" then
plr_task.disabled = true
for _, subdis_name in ipairs(disabler) do
local plr_subdis = plr_quest[subdis_name]
if not plr_task.disabled and plr_subdis.visible and plr_subdis.finished then
plr_task.disabled = true
end
end
else
plr_task.disabled = plr_quest[disabler_name].finished
end
if plr_task.disabled then
final_disabler = disabler_name
break
end
end
if plr_task.disabled and not was_disabled and not nocallback then
task.disablecallback(playername, questname, taskname, final_disabler, quest.metadata)
end
end
end
end
--- Registers a quest for later use.
-- There are two types of quests: simple and tasked.
--
-- * Simple quests are made of a single objective
-- * Taked quests are made of tasks, allowing simultaneous progress
-- within the quest as well as branching quest objectives
--
-- Both quest types are defined by a table, and they share common information:
-- {
-- title, -- Self-explanatory. Should describe the objective for simple quests.
-- description, -- Description/lore of the quest
-- icon, -- Texture name of the quest's icon. If missing, a default icon is used.
-- startcallback, -- Called upon quest start. function(playername, questname, metadata)
-- autoaccept, -- If true, quest automatically becomes completed if its progress reaches the max.
-- -- Defaults to true.
-- completecallback, -- If autoaccept is true, gets called at quest completion.
-- -- function(playername, questname, metadata)
-- abortcallback, -- Called when a player cancels the quest. function(playername, questname, metadata)
-- repeating -- Delay in seconds before the quest becomes available again. If nil, 0 or false, doesn't restart.
-- }
--
-- In addition, simple quests have a number-type `max` element indicating the max progress of the quest.
-- As for tasked quests, they have a table-type `tasks` element which value is like this:
-- tasks = {
-- start = {
-- title,
-- description,
-- icon,
-- max -- Max task progress
-- },
-- another_task = {
-- [...],
--
-- requires = {"start"},
-- -- Table of task names which one must be completed for this task to unlock.
-- -- To to task completion groups (i.e. where ALL must be compileted), pass said names in a (sub)table.
--
-- availablecallback,
-- -- Called when the task becomes available. Not called when there are no task requirements (i.e. task is available from the start).
-- -- function(playername, questname, taskname, enablingtaskname, metadata)
-- -- enablingtaskname is a string or a table of strings, depending on the condition that unlocked the task
--
-- completecallback,
-- -- Called upon task completion.
-- -- function(playername, questname, taskname, metadata)
-- }
-- something = {
-- [...],
-- requires = {"start"},
--
-- disables_on = {"another_task"},
-- -- Same as `requires`, but *disables* the task (it then does not count towards quest completion)
--
-- disablecallback,
-- -- Called when the task becomes disabled. Not called when the task is disabled upon quest start.
-- -- function(playername, questname, taskname, disablingtaskname, metadata)
-- -- disablingtaskname is a string or a table of strings, depending on the condition that locked the task
-- }
-- }
-- In this previous example the 2 last tasks enables once the `start` one is completed, and the
-- last one disables upon `another_task` completion, effectively making it optional if one
-- completes `another_task` before it.
-- Some task names are reserved and will be ignored:
--
-- * `metadata`
-- * `finished`
-- * `value`
--
-- Note: this function *copies* the `quest` table, keeping only what's needed. This way you can implement custom
-- quest attributes in your mod and register the quest directly without worrying about keyvalue name collision.
-- @param questname Name of the quest. Should follow the naming conventions: `modname:questname`
-- @param quest Quest definition `table`
-- @return `true` when the quest was successfully registered
-- @return `false`, <error string> when there was already such a quest, or if mandatory info was omitted/corrupt
function quests.register_quest(questname, quest)
if quests.registered_quests[questname] ~= nil then
return false -- The quest was not registered since there's already a quest with that name
end
quests.registered_quests[questname] = {
title = quest.title or S("missing title"),
description = quest.description or S("missing description"),
icon = quest.icon or "quests_default_quest_icon.png",
startcallback = quest.startcallback or empty_callback,
autoaccept = not(quest.autoaccept == false),
completecallback = quest.completecallback or empty_callback,
abortcallback = quest.abortcallback or empty_callback,
repeating = quest.repeating or 0
}
local new_quest = quests.registered_quests[questname]
if quest.max ~= nil then -- Simple quest
new_quest.max = quest.max or 1
new_quest.simple = true
else
if quest.tasks == nil or type(quest.tasks) ~= "table" then
quests.registered_quests[questname] = nil
return false, "No quest.max defined but no tasks either"
end
new_quest.tasks = {}
local tcount = 0
for tname, task in pairs(quest.tasks) do
if tname ~= "metadata" and tname ~= "finished" and tname ~= "value" then
new_quest.tasks[tname] = {
title = task.title or S("missing title"),
description = task.description or S("missing description"),
icon = task.icon or "quests_default_quest_icon.png",
max = task.max or 1,
requires = task.requires,
availablecallback = task.availablecallback or empty_callback,
disables_on = task.disables_on,
disablecallback = task.disablecallback or empty_callback,
completecallback = task.completecallback or empty_callback
}
tcount = tcount + 1
end
end
if tcount == 0 then -- No tasks!
quests.registered_quests[questname] = nil
return false, "No quest.max defined but no *valid* tasks either"
end
end
return true
end
--- Starts a quest for a specified player.
-- @param playername Name of the player
-- @param questname Name of the quest, which was registered with @{quests.register_quest}
-- @param metadata Optional additional data
-- @return `false` on failure
-- @return `true` if the quest was started
function quests.start_quest(playername, questname, metadata)
local quest = quests.registered_quests[questname]
if quest == nil then
return false
end
if quests.active_quests[playername] == nil then
quests.active_quests[playername] = {}
end
if quests.active_quests[playername][questname] ~= nil then
return false -- the player already has this quest
end
if quest.simple then
quests.active_quests[playername][questname] = {value = 0, metadata = metadata, finished = false}
else
quests.active_quests[playername][questname] = {metadata = metadata}
for tname, task in pairs(quest.tasks) do
quests.active_quests[playername][questname][tname] = {
value = 0,
visible = false,
disabled = false,
finished = false
}
end
compute_tasks(playername, questname)
end
quests.update_hud(playername)
quests.show_message("new", playername, S("New quest") .. ": " .. quest.title)
return true
end
local function check_active_quest(playername, questname)
return not(
playername == nil or
questname == nil or
quests.registered_quests[questname] == nil or -- Quest doesn't exist
quests.active_quests[playername] == nil or -- Player has no data
quests.active_quests[playername][questname] == nil -- Quest isn't active
)
end
local function check_active_quest_task(playername, questname, taskname)
return not(
taskname == nil or
not check_active_quest(playername, questname) or
quests.registered_quests[questname].simple or -- Quest is simple (i.e. no tasks)
quests.registered_quests[questname].tasks == nil or -- Who knows? Avoid crash.
quests.registered_quests[questname].tasks[taskname] == nil or -- No such task
quests.active_quests[playername][questname][taskname] == nil -- Player quest data has no such task
)
end
--- Updates a *simple* quest's status.
-- Calls the quest's `completecallback` if autoaccept is `true` and the quest reaches its max value.
-- Has no effect on tasked quests.
-- @param playername Name of the player
-- @param questname Quest which gets updated
-- @param value Value to add to the quest's progress (can be negative)
-- @return `true` if the quest is finished
-- @return `false` if the quest continues
-- @return `nil` if there is no such quest, it is a tasked or non-active one, or no value was given
-- @see quests.update_quest_task
function quests.update_quest(playername, questname, value)
if not check_active_quest(playername, questname) or not quests.registered_quests[questname].simple
or value == nil then
return nil
end
local plr_quest = quests.active_quests[playername][questname]
if plr_quest.finished then
return true -- The quest is already finished
end
local quest = quests.registered_quests[questname]
plr_quest.value = plr_quest.value + value
if plr_quest.value >= quest.max then
plr_quest.value = quest.max
if quest.autoaccept then
quest.completecallback(playername, questname, plr_quest.metadata)
quests.accept_quest(playername,questname)
quests.update_hud(playername)
end
return true -- the quest is finished
end
quests.update_hud(playername)
return false -- the quest continues
end
--- Get a *simple* quest's progress.
-- @param playername Name of the player
-- @param questname Quest to get the progress value from
-- @return `number` of the progress
-- @return `nil` if there is no such quest, it is a tasked or non-active one
-- @see quests.get_task_progress
function quests.get_quest_progress(playername, questname)
if not check_active_quest(playername, questname) or not quests.registered_quests[questname].simple then
return nil
end
local plr_quest = quests.active_quests[playername][questname]
if plr_quest.finished then
return nil
end
return plr_quest.value
end
--- Updates a *tasked* quest task's status.
-- Calls the quest's `completecallback` if autoaccept is `true` and all the quest's visible
-- and non-disabled tasks reaches their max value.
-- Also calls the task's `completecallback` it it gets completed.
-- Has no effect on simple quests.
-- @param playername Name of the player
-- @param questname Quest which gets updated
-- @param taskname Task to update
-- @param value Value to add to the task's progress (can be negative)
-- @return `true` if the task is finished
-- @return `false` if it continues
-- @return `nil` if there is no such quest/task, is a simple or non-active quest, or no value was given
-- @see quests.update_quest
function quests.update_quest_task(playername, questname, taskname, value)
if not check_active_quest_task(playername, questname, taskname) or value == nil then
return nil
end
local plr_quest = quests.active_quests[playername][questname]
local plr_task = plr_quest[taskname]
if plr_task.finished then
return true -- The task is already finished
end
local quest = quests.registered_quests[questname]
local task = quest.tasks[taskname]
local task_finished = false
plr_task.value = plr_task.value + value
if plr_task.value >= task.max then
plr_task.value = task.max
plr_task.finished = true
task.completecallback(playername, questname, taskname, quest.metadata)
task_finished = true
end
compute_tasks(playername, questname)
-- Check for quest completion
local all_tasks_finished = true
for taskname, task in pairs(quest.tasks) do
local plr_task = plr_quest[taskname]
if plr_task.visible and not plr_task.disabled and not plr_task.finished then
all_tasks_finished = false
end
end
if all_tasks_finished then
if quest.autoaccept then
quest.completecallback(playername, questname, plr_quest.metadata)
quests.accept_quest(playername,questname)
quests.update_hud(playername)
end
-- If the update of this task ends the quest, it consequently *is* finished.
return true
end
quests.update_hud(playername)
return task_finished
end
--- Get a task's progress.
-- Returns the max progress value possible for the given task if it is complete.
-- @param playername Name of the player
-- @param questname Quest the task belongs to
-- @param taskname Task to get the progress value from
-- @return `number` of the progress
-- @return `false` if the task has been disabled by another
-- @return `nil` if there is no such quest/task, or is a simple or non-active quest
-- @see quests.get_quest_progress
function quests.get_task_progress(playername, questname, taskname)
if not not check_active_quest_task(playername, questname, taskname) then
return nil
end
local plr_quest = quests.active_quests[playername][questname]
if plr_quest.finished then
return nil
end
local plr_task = plr_quest[taskname]
if not plr_task then
return nil
end
if plr_task.disabled then
return false
end
return plr_task.value
end
--- Checks if a quest's task is visible to the player.
-- @param playername Name of the player
-- @param questname Quest which contains the task
-- @param taskname Task to check visibility
-- @return `true` if the task is visible
-- @return `false` if it is not
-- @return `nil` if the quest/task doesn't exist, is simple or isn't active
function quests.is_task_visible(playername, questname, taskname)
if not check_active_quest_task(playername, questname, taskname) then
return nil
end
return quests.active_quests[playername][questname][taskname].visible
end
--- Checks if a quest's task is disabled to the player.
-- @param playername Name of the player
-- @param questname Quest which contains the task
-- @param taskname Task to check if it is disabled
-- @return `true` if the task is disabled
-- @return `false` if it is not
-- @return `nil` if the quest/task doesn't exist, is simple or isn't active
function quests.is_task_disabled(playername, questname, taskname)
if not check_active_quest_task(playername, questname, taskname) then
return nil
end
return quests.active_quests[playername][questname][taskname].disabled
end
--- Gets the number of active (visible & non-disabled) tasks, and how many of them are completed
-- @param playername Name of the player
-- @param questname Quest name
-- @return `number, number` pair, where the first is the number of active tasks, and the second how many of them are completed
-- @return `nil` if the quest doesn't exist, is simple or isn't active
function quests.get_active_tasks_stats(playername, questname)
if not check_active_quest(playername, questname) or quests.registered_quests[questname].simple then
return nil
end
local plr_quest = quests.active_quests[playername][questname]
local active_tasks = 0
local completed_active = 0
for taskname, _ in pairs(quests.registered_quests[questname].tasks) do
local plr_task = plr_quest[taskname]
if plr_task.visible and not plr_task.disabled then
active_tasks = active_tasks + 1
if plr_task.finished then
completed_active = completed_active + 1
end
end
end
return active_tasks, completed_active
end
--- Gets number of seconds before a quest can be done again.
-- @param playername Player's name
-- @param questname Quest name
-- @return `number` of seconds before quests becomes available
-- @return `nil` if the quest isn't repeating
function quests.quest_restarting_in(playername, questname)
if quests.info_quests[playername] and
quests.info_quests[playername][questname] and
quests.info_quests[playername][questname].restart_tstamp then
return quests.info_quests[playername][questname].restart_tstamp - os.time()
end
return nil
end
local function restart_periodic_quest(playername, questname)
quests.start_quest(playername, questname)
if quests.info_quests[playername] and quests.info_quests[playername][questname] then
quests.info_quests[playername][questname].restart_tstamp = nil
end
end
local function start_repeating_timer(playername, questname)
local delay = quests.quest_restarting_in(playername, questname)
if delay ~= nil then
minetest.after(delay, restart_periodic_quest, playername, questname)
end
end
local function start_all_repeating_timers(playername)
local qinfos = quests.info_quests[playername]
if qinfos then
for questname, qinfo in pairs(qinfos) do
if qinfo.restart_tstamp then
start_repeating_timer(playername, questname)
end
end
end
end
-- Restart all stopped repeating quests' timers
for playername, _ in pairs(quests.info_quests) do
start_all_repeating_timers(playername)
end
local function handle_quest_end(playername, questname)
local quest = quests.registered_quests[questname]
if quest.repeating ~= 0 then
quests.info_quests[playername] = quests.info_quests[playername] or {}
quests.info_quests[playername][questname] = quests.info_quests[playername][questname] or {}
local qinfo = quests.info_quests[playername][questname]
qinfo.restart_tstamp = os.time() + quest.repeating
start_repeating_timer(playername, questname)
end
end
--- Confirms quest completion and ends it.
-- When the mod handles the end of quests himself, e.g. you have to talk to somebody to finish the quest,
-- you have to call this method to end a quest
-- @param playername Player's name
-- @param questname Quest name
-- @return `true` when the quest is completed
-- @return `false` when an error occured (the quest is still ongoing if it was)
function quests.accept_quest(playername, questname)
if check_active_quest(playername, questname) and not quests.active_quests[playername][questname].finished then
if quests.successfull_quests[playername] == nil then
quests.successfull_quests[playername] = {}
end
if quests.successfull_quests[playername][questname] ~= nil then
quests.successfull_quests[playername][questname].count = quests.successfull_quests[playername][questname].count + 1
else
quests.successfull_quests[playername][questname] = {count = 1}
end
quests.active_quests[playername][questname].finished = true
if quests.hud[playername].list ~= nil then -- nil when HUD is hidden
for _,quest in ipairs(quests.hud[playername].list) do
if quest.name == questname then
local player = minetest.get_player_by_name(playername)
player:hud_change(quest.id, "number", quests.colors.success)
end
end
end
handle_quest_end(playername, questname)
quests.show_message("success", playername, S("Quest completed") .. ": " .. quests.registered_quests[questname].title)
minetest.after(3, function(playername, questname)
quests.active_quests[playername][questname] = nil
quests.update_hud(playername)
end, playername, questname)
return true -- the quest is finished, the mod can give a reward
end
return false -- the quest hasn't finished
end
--- Aborts a quest.
-- Call this method when you want to end a quest even when it was not finished.
-- Example: the player failed.
-- @param playername Player's name
-- @param questname Quest name
-- @return `true` when the quest was aborted
-- @return `false` if there was an error (quest not aborted)
function quests.abort_quest(playername, questname)
if not check_active_quest(playername, questname) then
return false
end
if quests.failed_quests[playername] == nil then
quests.failed_quests[playername] = {}
end
if quests.failed_quests[playername][questname] ~= nil then
quests.failed_quests[playername][questname].count = quests.failed_quests[playername][questname].count + 1
else
quests.failed_quests[playername][questname] = { count = 1 }
end
quests.active_quests[playername][questname].finished = true
if quests.hud[playername].list ~= nil then -- nil when HUD is hidden
for _,quest in ipairs(quests.hud[playername].list) do
if quest.name == questname then
local player = minetest.get_player_by_name(playername)
player:hud_change(quest.id, "number", quests.colors.failed)
end
end
end
local quest = quests.registered_quests[questname]
quest.abortcallback(playername, questname, quests.active_quests[playername][questname].metadata)
handle_quest_end(playername, questname)
quests.show_message("failed", playername, S("Quest failed") .. ": " .. quest.title)
minetest.after(3, function(playername, questname)
quests.active_quests[playername][questname] = nil
quests.update_hud(playername)
end, playername, questname)
return true
end
--- Set quest HUD visibility.
-- @param playername Player's name
-- @param questname Quest name
-- @param visible `bool` indicating if the quest should be visible
-- @see quests.get_quest_hud_visibility
function quests.set_quest_hud_visibility(playername, questname, visible)
if not check_active_quest(playername, questname) then
return
end
quests.info_quests[playername] = quests.info_quests[playername] or {}
quests.info_quests[playername][questname] = quests.info_quests[playername][questname] or {}
quests.info_quests[playername][questname].hide_from_hud = not visible
quests.update_hud(playername)
end
--- Get quest HUD visibility.
-- @param playername Player's name
-- @param questname Quest name
-- @return `bool`: quest HUD visibility
-- @see quests.set_quest_hud_visibility
function quests.get_quest_hud_visibility(playername, questname)
if not check_active_quest(playername, questname) then
return false
end
local plr_qinfos = quests.info_quests[playername]
return not(plr_qinfos and plr_qinfos[questname] and plr_qinfos[questname].hide_from_hud)
end
--- Get quest metadata.
-- @return Metadata of the quest, `nil` if there is none
-- @return `nil, false` if the quest doesn't exist or isn't active
-- @see quests.set_metadata
function quests.get_metadata(playername, questname)
if not check_active_quest(playername, questname) then
return nil, false
end
return quests.active_quests[playername][questname].metadata
end
--- Set quest metadata.
-- @return `false` if the quest doesn't exist or isn't active
-- @return `nil` otherwise
-- @see quests.get_metadata
function quests.set_metadata(playername, questname, metadata)
if not check_active_quest(playername, questname) then
return false
end
quests.active_quests[playername][questname].metadata = metadata
end