mmo-ref/stendhal
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
stendhal/doc/mkdocs/lua/objects/quests.md
Jordan Irwin f810c30d21 Clean up docstrings & Lua documentation
2023-05-17 02:08:58 -07:00

24 KiB
Raw Permalink Blame History

Contents

[TOC]

Introduction

Object instance: quests

Description

Adds helper functions for creating & manipulating quests & exposes select public methods of the StendhalQuestSystem class.

Methods

quests:cache

quests:cache (quest)
  • DEPRECATED: Call register directly from the quest instance.
  • Caches a quest for loading at server startup.
  • Parameters:
    • quest: (IQuest) Quest instance to be cached.

quests:create

quests:create ()
quests:create (slotName)
quests:create (slotName, name)
quests:create (slotName, name, desc)
  • Creates a new quest.
  • Parameters:
    • slotName: (string) Quest slot identifier.
    • name: (string) The reader friendly name that can be shown in travel log.
    • desc: _(string) Quest description.
  • Returns: (LuaQuest) New quest instance.

quests:createBuilder

quests:createBuilder (task)
  • Creates a quest builder to pass to quests:createManuscript.
  • Parameters:
    • task: (string) Quest task type. Supported are "BringItemTask" & "KillCreaturesTask".
  • Returns: (QuestBuilder) New quest builder instance.

quests:createManuscript

quests:createManuscript (builder)
  • Creates a new quest in manuscript format.
  • Parameters:
    • builder: (QuestBuilder) A quest builder instance that defines quest.
  • Returns: (QuestManuscript) New quest instance.

quests:getCompleted

quests:getCompleted (player)
  • Retrieves a list of completed quests from a player.
  • Parameters:
    • player: (Player) Player instance to be checked.
  • Returns: (List<String>) List of string identifiers for completed quests.
  • TODO:

quests:getDescription

quests:getDescription (player, questName)
  • Retrieves the description of a quest.
  • Parameters:
    • player: (Player) Player instance to be checked.
    • questName: (string) Name of the quest.
  • Returns: (string) Description.

quests:getDescriptionForUnstartedInRegionFromNPCName

quests:getDescriptionForUnstartedInRegionFromNPCName (player, region, name)
  • Retrieves quest descriptions for unstarted quests in a specified region matching a specific NPC name.
  • Parameters:
    • player: (Player) Player instance to be checked.
    • region: (string) Region to check in.
    • name: (string) Name of NPC.
  • Returns: (java.util.List<java.lang.String>)
  • TODO:

quests:getIncomplete

quests:getIncomplete (player, region)
  • Retrieves a list of incomplete quests in a specified region.
  • Parameters:
    • player: (Player) Player instance to be checked.
    • region: (string) Region name/identifier.
  • Returns: (java.util.List<java.lang.String>) List of string identifiers of incomplete quests in region.
  • TODO:

quests:getLevelWarning

quests:getLevelWarning (player, questName)
  • If the quest is too dangerous, add a warning unless the player has already completed it.
  • Parameters:
    • player: (Player) Player instance to be checked.
    • questName: (string) Name of the quest.
  • Returns: (string)

quests:getNPCNamesForUnstartedInRegionForLevel

quests:getNPCNamesForUnstartedInRegionForLevel (player, region)
  • Retrieves a list of the unique npc names for unstarted quests in a specified region.
  • Parameters:
    • player: (Player) Player instance to be checked.
    • region: (string) Region to check in.
  • Returns: (java.util.List<java.lang.String>)
  • TODO:

quests:getOpen

quests:getOpen (player)
  • Retrieves a list of open quests from a player.
  • Parameters:
    • player: (Player) Player instance to be checked.
  • Returns: (java.util.List<java.lang.String>) List of string identifiers for open quests.
  • TODO:

quests:getProgressDetails

quests:getProgressDetails (player, questeName)

quests:getQuest

quests:getQuest (questName)
  • Retrieves the IQuest object for a named quest.
  • Parameters:
    • questName: (string) Name of quest.
  • Returns: (IQuest) Quest instance or nil if doesn't exist.

quests:getQuestFromSlot

quests:getQuestFromSlot (questSlot)
  • Retrieves the IQuest object for a quest.
  • Parameters:
    • questSlot: (string) Quest identifier string.
  • Returns: (IQuest) Quest instance or nil if doesn't exist.

quests:getRepeatable

quests:getRepeatable (player)
  • Retrieves a list of quests a player has completed, and can now do again.
  • Parameters:
    • player: (Player) Player instance to be checked.
  • Returns: (java.util.List>java.lang.String<)
  • TODO:

quests:isLoaded

quests:isLoaded (quest)
  • Checks if a quest has been loaded.
  • Parameters:
    • quest: (IQuest) Quest instance to check.
  • Returns: (bool) true if the instance matches stored quests.

quests:list

quests:list (player, questName)
  • Creates a report on a specified quest for a player.
  • Parameters:
    • player: (Player) Player to create the report for.
    • questName: (string) Name of quest to be reported.
  • Returns: (string) Report.

quests:listAll

quests:listAll (player)
  • List all quests the player knows about.
  • Parameters:
    • player: (Player) Player to create the report for.
  • Returns: (string) Report.

quests:listStates

quests:listStates (player)
  • Dumps the internal quest states for the specified player. This is used for the InspectAction.
  • Parameters:
    • player: (Player) Player to create the report for.
  • Returns: (string) Report.

quests:load

quests:load (quest)
  • Adds a quest to the world.
  • Parameters:
    • quest: (IQuest) The quest instance to be loaded.

quests:register

quests:register (quest)
  • DEPRECATED: Call register directly from the quest instance.
  • Caches a quest for loading at startup. Alias for quests:cache.
  • Parameters:
    • quest (IQuest) Quest instance to be cached.

quests:unload

quests:unload (questName)
  • Removes a quest from the world.
  • Parameters:
    • questName: (string) Name of the quest to be removed.

Classes

LuaQuest

See: LuaQuest

Public Members

LuaQuest.completedCheck

LuaQuest.completedCheck
  • Called by LuaQuest.isCompleted.
  • Type: function

LuaQuest.formattedHistory

LuaQuest.formattedHistory
  • Called by LuaQuest.getFormattedHistory.
  • Type: function

LuaQuest.history

LuaQuest.history
  • Called by LuaQuest.getHistory.
  • Type: function

LuaQuest.init

LuaQuest.init

LuaQuest.remove

LuaQuest.remove

LuaQuest.repeatableCheck

LuaQuest.repeatableCheck
  • Called by LuaQuest.isRepeatable.
  • Type: function

LuaQuest.startedCheck

LuaQuest.startedCheck
  • Called by LuaQuest.isStarted.
  • Type: function

Public Methods

LuaQuest:addToWorld

LuaQuest:addToWorld ()

LuaQuest:getFormattedHistory

LuaQuest:getFormattedHistory (player)

LuaQuest:getHistory

LuaQuest:getHistory (player)

LuaQuest:getMinLevel

LuaQuest:getMinLevel ()

LuaQuest:getNPCName

LuaQuest:getNPCName ()

LuaQuest:getName

LuaQuest:getName ()

LuaQuest:getOriginalName

LuaQuest:getOriginalName ()
  • Retrieves unformatted quest name.
  • Returns: (string)
    • Unmodified quest name string.

LuaQuest:getRegion

LuaQuest:getRegion ()

LuaQuest:getSlotName

LuaQuest:getSlotName ()

LuaQuest:isCompleted

LuaQuest:isCompleted (player)

LuaQuest:isRepeatable

LuaQuest:isRepeatable ()

LuaQuest:isStarted

LuaQuest:isStarted (player)

LuaQuest:isVisibleOnQuestStatus

LuaQuest:isVisibleOnQuestStatus ()

LuaQuest:register

LuaQuest:register ()
LuaQuest:register (func)
  • Registers quest to be added to world at server startup. LuaQuest.init must be set before this is called.
  • Parameters:
    • func: (function) Function to execute when quests:loadQuest is called.

LuaQuest:removeFromWorld

LuaQuest:removeFromWorld ()

LuaQuest:setAddFunction

LuaQuest:setAddFunction (func)
  • DEPRECATED: Set LuaQuest.init directly.
  • Sets the function for adding the quest to the game.
  • Parameters:
    • func: (function) Function to invoke when LuaQuest.addToWorld is called.

LuaQuest:setCompletedCheckFunction

LuaQuest:setCompletedCheckFunction (func)
  • Sets the function for checking if the quest is started.
  • Parameters:
    • func: (function) Function to invoke when LuaQuest.isCompleted is called.

LuaQuest:setDescription

LuaQuest:setDescription (desc)
  • Sets the quest description string.
  • Parameters:
    • desc: (string) Quest description string.

LuaQuest:setFormattedHistoryFunction

LuaQuest:setFormattedHistoryFunction (func)
  • Sets the function for retrieving formatted history of quest state.
  • Parameters:
    • func: (function) Function to invoke when LuaQuest.getFormattedHistory is called.

LuaQuest:setHistoryFunction

LuaQuest:setHistoryFunction (func)
  • Sets the function for retrieving history of quest state.
  • Parameters:
    • func: (function) Function to invoke when LuaQuest.getHistory is called.

LuaQuest:setMinLevel

LuaQuest:setMinLevel (level)
  • Sets the recommended minimum level.
  • Parameters:
    • level: (int) Level to return when LuaQuest.getMinLevel is called.

LuaQuest:setNPCName

LuaQuest:setNPCName (name)
  • Sets the NPC name.
  • Parameters:
    • name: (string) NPC name to return when LuaQuest.getNPCName is called.

LuaQuest:setName

LuaQuest:setName (name)
  • Sets the quest name string.
  • Parameters:
    • name: (string) Quest name string to be returned when LuaQuest.getName is called.

LuaQuest:setRegion

LuaQuest:setRegion (region)
  • Sets the quest region.
  • Parameters:
    • region: (string) Region string to be returned when LuaQuest.getRegion is called.

LuaQuest:setRemoveFunction

LuaQuest:setRemoveFunction (func)
  • DEPRECATED: Set LuaQuest.remove directly.
  • Sets the function for removing the quest from the game.
  • Parameters:
    • func: (function) Function to invoke when LuaQuest.removeFromWorld is called.

LuaQuest:setRepeatable

LuaQuest:setRepeatable ()
  • Sets the repeatable status of the quest (overrides LuaQuest.setCompletedCheckFunction).
  • Parameters:
    • repeatable: (bool) If true, the quest is repeatable.

LuaQuest:setRepeatableCheckFunction

LuaQuest:setRepeatableCheckFunction (func)
  • Sets the function for checking if the quest is repeatable.
  • Parameters:
    • func: (function) Function to invoke when LuaQuest.isRepeatable is called.

LuaQuest:setSlotName

LuaQuest:setSlotName (slot)
  • Sets the quest identifier string.
  • Parameters:
    • slot: (string) Slot identifier string to be returned when LuaQuest.getSlotName is called.

LuaQuest:setStartedCheckFunction

LuaQuest:setStartedCheckFunction (func)
  • Sets the function for checking if the quest is started.
  • Parameters:
    • func: (function) Function to invoke when LuaQuest.isStarted is called.

LuaQuest:setVisibleOnQuestStatus

LuaQuest:setVisibleOnQuestStatus (visible)
  • Sets whether or not the quest should be shown in the travel log.
  • Parameters:
    • visible: (bool) If true, quest will be displayed in travel log.

Usage Examples

Standard quest example:

local loadStep1 = function()
    ...
end

local loadStep2 = function()
    ...
end

local myQuest = quests:create("my_quest", "My Quest")
myQuest.init = function()
    loadStep1()
    loadStep2()
end

quests:register(myQuest)

Example of CoalForHaunchy quest manuscript converted to Lua:

local itemBuilder = quests:createBuilder("BringItemTask")

itemBuilder:info()
    :name("Coal for Haunchy")
    :description("Haunchy Meatoch is afraid of his BBQ grillfire. Will his coal last till the steaks are ready or will he need some more?")
    :internalName("coal_for_haunchy")
    :repeatableAfterMinutes(2 * 24 * 60)
    :minLevel(0)
    :region(Region.ADOS_CITY)
    :questGiverNpc("Haunchy Meatoch")

itemBuilder:history()
    :whenNpcWasMet("Haunchy Meatoch welcomed me to the Ados market.")
    :whenQuestWasRejected("He asked me to fetch him some pieces of coal but I don't have time to collect some.")
    :whenQuestWasAccepted("The BBQ grill-heat is low and I promised Haunchy to help him out with 25 pieces of coal.")
    :whenTaskWasCompleted("I found 25 pieces of coal for the Haunchy and think he will be happy.")
    :whenQuestWasCompleted("Haunchy Meatoch was really happy when I gave him the coal, he has enough for now. He gave me some of the best steaks which I ever ate!")
    :whenQuestCanBeRepeated("But I'd bet his amount is low again and needs more. Maybe I'll get more grilled tasty steaks.")

itemBuilder:offer()
    :respondToRequest("I cannot use wood for this huge BBQ. To keep the heat I need some really old stone coal but there isn't much left. The problem is, that I can't fetch it myself because my steaks would burn then so I have to stay here. Can you bring me 25 pieces of #coal for my BBQ please?")
    :respondToUnrepeatableRequest("The coal amount behind my counter is still high enough. I will not need more for some time.")
    :respondToRepeatedRequest("The last coal you brought me is mostly gone again. Will you bring me some more?")
    :respondToAccept("Thank you! I'll be sure to give you a nice and tasty reward.")
    :respondTo({"coal"}):saying("Coal isn't easy to find. You normally can find it somewhere in the ground but perhaps you are lucky and find some in the old Semos Mine tunnels... Will you help me?")
    :respondToReject("Oh, never mind. I thought you love BBQs like I do. Bye then.")
    :rejectionKarmaPenalty(10.0)
    :remind("Luckily my BBQ is still going. But please hurry up to bring me 25 coal as you promised.")

entities:getNPC("Haunchy Meatoch"):addReply("coal", "Sometime you could do me a #favour ...")

itemBuilder:task()
    :requestItem(25, "coal")

itemBuilder:complete()
    :greet("Ah, I see, you have enough coal to keep my BBQ on! Is it for me?")
    :respondToReject("Well then, hopefully someone else will help me before my BBQ goes out.")
    :respondToAccept(nil)
    :rewardWith(actions:create("IncreaseXPAction", {200}))
    :rewardWith(actions:create("IncreaseKarmaAction", {20}))
    :rewardWith(actions:create("EquipRandomAmountOfItemAction", {"grilled steak", 1, 4, 1,
        "Thank you! Take [this_these] [number_item] from my grill!"}))

quests:register(quests:createManuscript(itemBuilder))