--- # 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][LuaString])_ Quest slot identifier. - name: _([string][LuaString])_ The reader friendly name that can be shown in travel log. - desc: _([string][LuaString]) Quest description. - Returns: _([LuaQuest])_ New quest instance. --- ## quests:createBuilder
quests:createBuilder (task)
- Creates a quest builder to pass to `quests:createManuscript`. - Parameters: - task: _([string][LuaString])_ 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][java.util.List]<[String][java.lang.String]>)_ List of string identifiers for completed quests. - TODO: - Return [LuaTable] instead of Java list. --- ## quests:getDescription
quests:getDescription (player, questName)
- Retrieves the description of a quest. - Parameters: - player: _([Player])_ Player instance to be checked. - questName: _([string][LuaString])_ Name of the quest. - Returns: _([string][LuaString])_ 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][LuaString])_ Region to check in. - name: _([string][LuaString])_ Name of NPC. - Returns: _([java.util.List]<[java.lang.String]>)_ - TODO: - Return [LuaTable] instead of Java list. --- ## 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][LuaString])_ Region name/identifier. - Returns: _([java.util.List]<[java.lang.String]>)_ List of string identifiers of incomplete quests in ___region___. - TODO: - Return [LuaTable] instead of Java list. --- ## 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][LuaString])_ Name of the quest. - Returns: _([string][LuaString])_ --- ## 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][LuaString])_ Region to check in. - Returns: _([java.util.List]<[java.lang.String]>)_ - TODO: - Return [LuaTable] instead of Java list. --- ## 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: - Return [LuaTable] instead of Java list. --- ## quests:getProgressDetails
quests:getProgressDetails (player, questeName)
- Retrieves details on the progress of the quest. - Parameters: - player: _([Player])_ Player instance to be checked. - questName: _([string][LuaString])_ Name of the quest. - Returns: _([java.util.List]>[java.lang.String]<)_ - TODO: - Return [LuaTable] instead of Java list. --- ## quests:getQuest
quests:getQuest (questName)
- Retrieves the [IQuest] object for a named quest. - Parameters: - questName: _([string][LuaString])_ Name of quest. - Returns: _([IQuest])_ Quest instance or [nil][LuaNil] if doesn't exist. --- ## quests:getQuestFromSlot
quests:getQuestFromSlot (questSlot)
- Retrieves the [IQuest] object for a quest. - Parameters: - questSlot: _([string][LuaString])_ Quest identifier string. - Returns: _([IQuest])_ Quest instance or [nil][LuaNil] 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: - Return [LuaTable] instead of Java list. --- ## quests:isLoaded
quests:isLoaded (quest)
- Checks if a quest has been loaded. - Parameters: - quest: _([IQuest])_ Quest instance to check. - Returns: _([bool][LuaBoolean])_ `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][LuaString])_ Name of quest to be reported. - Returns: _([string][LuaString])_ Report. --- ## quests:listAll
quests:listAll (player)
- List all quests the player knows about. - Parameters: - player: _([Player])_ Player to create the report for. - Returns: _([string][LuaString])_ 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][LuaString])_ 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][LuaString])_ Name of the quest to be removed. --- # Classes --- ## LuaQuest See: [LuaQuest] --- ### Public Members --- #### LuaQuest.completedCheck
LuaQuest.completedCheck
- Called by `LuaQuest.isCompleted`. - Type: [function][LuaFunction] --- #### LuaQuest.formattedHistory
LuaQuest.formattedHistory
- Called by `LuaQuest.getFormattedHistory`. - Type: [function][LuaFunction] --- #### LuaQuest.history
LuaQuest.history
- Called by `LuaQuest.getHistory`. - Type: [function][LuaFunction] --- #### LuaQuest.init
LuaQuest.init
- Called by [IQuest.addToWorld]. - Type: [function][LuaFunction] --- #### LuaQuest.remove
LuaQuest.remove
- Called by [IQuest.removeFromWorld]. - Type: [function][LuaFunction] --- #### LuaQuest.repeatableCheck
LuaQuest.repeatableCheck
- Called by `LuaQuest.isRepeatable`. - Type: [function][LuaFunction] --- #### LuaQuest.startedCheck
LuaQuest.startedCheck
- Called by `LuaQuest.isStarted`. - Type: [function][LuaFunction] --- ### Public Methods --- #### LuaQuest:addToWorld
LuaQuest:addToWorld ()
- See [IQuest.addToWorld]. --- #### LuaQuest:getFormattedHistory
LuaQuest:getFormattedHistory (player)
- See [IQuest.getFormattedHistory]. --- #### LuaQuest:getHistory
LuaQuest:getHistory (player)
- See [IQuest.getHistory] --- #### LuaQuest:getMinLevel
LuaQuest:getMinLevel ()
- See [IQuest.getMinLevel] --- #### LuaQuest:getNPCName
LuaQuest:getNPCName ()
- See [IQuest.getNPCName] --- #### LuaQuest:getName
LuaQuest:getName ()
- See [IQuest.getName] --- #### LuaQuest:getOriginalName
LuaQuest:getOriginalName ()
- Retrieves unformatted quest name. - Returns: _([string][LuaString])_ - Unmodified quest name string. --- #### LuaQuest:getRegion
LuaQuest:getRegion ()
- See [IQuest.getRegion] --- #### LuaQuest:getSlotName
LuaQuest:getSlotName ()
- See [IQuest.getSlotName] --- #### LuaQuest:isCompleted
LuaQuest:isCompleted (player)
- See [IQuest.isCompleted] --- #### LuaQuest:isRepeatable
LuaQuest:isRepeatable ()
- See [IQuest.isRepeatable] --- #### LuaQuest:isStarted
LuaQuest:isStarted (player)
- See [IQuest.isStarted] --- #### LuaQuest:isVisibleOnQuestStatus
LuaQuest:isVisibleOnQuestStatus ()
- See [IQuest.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][LuaFunction])_ Function to execute when `quests:loadQuest` is called. --- #### LuaQuest:removeFromWorld
LuaQuest:removeFromWorld ()
- See [IQuest.removeFromWorld] --- #### LuaQuest:setAddFunction
LuaQuest:setAddFunction (func)
- ___DEPRECATED:__ Set `LuaQuest.init` directly._ - Sets the function for adding the quest to the game. - Parameters: - func: _([function][LuaFunction])_ 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][LuaFunction])_ Function to invoke when `LuaQuest.isCompleted` is called. --- #### LuaQuest:setDescription
LuaQuest:setDescription (desc)
- Sets the quest description string. - Parameters: - desc: _([string][LuaString])_ Quest description string. --- #### LuaQuest:setFormattedHistoryFunction
LuaQuest:setFormattedHistoryFunction (func)
- Sets the function for retrieving formatted history of quest state. - Parameters: - func: _([function][LuaFunction])_ 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][LuaFunction])_ Function to invoke when `LuaQuest.getHistory` is called. --- #### LuaQuest:setMinLevel
LuaQuest:setMinLevel (level)
- Sets the recommended minimum level. - Parameters: - level: _([int][LuaInteger])_ Level to return when `LuaQuest.getMinLevel` is called. --- #### LuaQuest:setNPCName
LuaQuest:setNPCName (name)
- Sets the NPC name. - Parameters: - name: _([string][LuaString])_ NPC name to return when `LuaQuest.getNPCName` is called. --- #### LuaQuest:setName
LuaQuest:setName (name)
- Sets the quest name string. - Parameters: - name: _([string][LuaString])_ Quest name string to be returned when `LuaQuest.getName` is called. --- #### LuaQuest:setRegion
LuaQuest:setRegion (region)
- Sets the quest region. - Parameters: - region: _([string][LuaString])_ 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][LuaFunction])_ 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][LuaBoolean])_ If `true`, the quest is repeatable. --- #### LuaQuest:setRepeatableCheckFunction
LuaQuest:setRepeatableCheckFunction (func)
- Sets the function for checking if the quest is repeatable. - Parameters: - func: _([function][LuaFunction])_ Function to invoke when `LuaQuest.isRepeatable` is called. --- #### LuaQuest:setSlotName
LuaQuest:setSlotName (slot)
- Sets the quest identifier string. - Parameters: - slot: _([string][LuaString])_ 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][LuaFunction])_ 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][LuaBoolean])_ If `true`, quest will be displayed in travel log. --- # Usage Examples Standard quest example: ```lua 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: ```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)) ``` [java.lang.String]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html [java.util.List]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/List.html [LuaBoolean]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaBoolean.html [LuaFunction]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaFunction.html [LuaInteger]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaInteger.html [LuaNil]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaNil.html [LuaString]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaString.html [LuaTable]: http://luaj.org/luaj/3.0/api/org/luaj/vm2/LuaTable.html [InspectAction]: /reference/java/games/stendhal/server/actions/admin/InspectAction.html [IQuest]: /reference/java/games/stendhal/server/maps/quests/IQuest.html [IQuest.addToWorld]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#addToWorld() [IQuest.getFormattedHistory]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#getFormattedHistory(games.stendhal.server.entity.player.Player) [IQuest.getHistory]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#getHistory(games.stendhal.server.entity.player.Player) [IQuest.getMinLevel]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#getMinLevel() [IQuest.getName]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#getName() [IQuest.getNPCName]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#getNPCName() [IQuest.getRegion]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#getRegion() [IQuest.getSlotName]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#getSlotName() [IQuest.isCompleted]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#isCompleted(games.stendhal.server.entity.player.Player) [IQuest.isRepeatable]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#isRepeatable(games.stendhal.server.entity.player.Player) [IQuest.isStarted]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#isStarted(games.stendhal.server.entity.player.Player) [IQuest.isVisibleOnQuestStatus]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#isVisibleOnQuestStatus() [IQuest.removeFromWorld]: /reference/java/games/stendhal/server/maps/quests/IQuest.html#removeFromWorld() [LuaQuest]: /reference/java/games/stendhal/server/core/scripting/lua/LuaQuestHelper.LuaQuest.html [Player]: /reference/java/games/stendhal/server/entity/player/Player.html [QuestBuilder]: /reference/java/games/stendhal/server/entity/npc/quest/QuestBuilder.html [QuestManuscript]: /reference/java/games/stendhal/server/entity/npc/quest/QuestManuscript.html [StendhalQuestSystem]: /reference/java/games/stendhal/server/core/rp/StendhalQuestSystem.html [CoalForHaunchy]: https://github.com/arianne/stendhal/blob/master/src/games/stendhal/server/maps/quests/CoalForHaunchy.java