[Mod] Quest framework [1.1] [quests]

[TeTpaAka]

Hello minetest,

I made a quest framework to make it possible to give the players quest.

You can see a full list of your active quests with the chatcommand /quests

+ Screenshots:

+ Example

https://github.com/TeTpaAka/sample_quest.git

+ API

quests.register_quest(questname,quest)
-- registers a quest for later use
--
-- questname is the name of the quest to identify it later
-- it should follow the naming conventions: "modname:questname"
-- quest is a table in the following format
-- {
-- title, -- is shown to the player and should contain usefull information about the quest.
-- description, -- a small description of the mod.
-- max, -- is the desired maximum. If max is 1, no maximum is displayed. defaults to 1
-- autoaccept, -- is true or false, wether the result of the quest should be dealt by this mode or the registering mod.
-- callback -- when autoaccept is true, at the end of the quest, it gets removed and callback is called.
-- -- function(playername, questname, metadata)
-- }
--
-- returns true, when the quest was successfully registered
-- returns falls, when there was already such a quest

quests.start_quest(playername, questname)
-- starts a quest for a specified player
--
-- playername - the name of the player
-- questname - the name of the quest, which was registered with quests.register_quest
-- metadata - optional additional data
--
-- returns false on failure
-- returns true if the quest was started

quests.update_quest(playername, questname, value)
-- when something happens that has effect on a quest, a mod should call this method
-- playername is the name of the player
-- questname is the quest which gets updated
-- the quest gets updated by value
-- this method calls a previously specified callback if autoaccept is true
-- returns true if the quest is finished
-- returns false if there is no such quest or the quest continues

quests.accept_quest(playername, questname)
-- When the mod handels 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
-- returns true, when the quest is completed
-- returns false, when the quest is still ongoing

quests.abort_quest(playername, questname)
-- call this method, when you want to end a quest even when it was not finished
-- example: the player failed
--
-- returns false if the quest was not aborted
-- returns true when the quest was aborted

quests.show_hud(playername)
-- shows the hud to player playername

quests.hide_hud(playername)
-- hides the hud for player playername

quests.show_formspec(playername)
-- shows the player playername his/her questlog

quests.get_metadata(playername, questname)
-- get metadata of the quest if the quest exists, else return nil

quests.set_metadata(playername, questname, metadata)
-- set metadata of the quest

Current translations:

• German by TeTpaAka

Quests have to be translated by the registering mod.

Version: 1.1

Dependencies:
intllib (optional for translating the interface)
inventory_plus (optional) or unified_inventory (optional)
central_message (optional for visual and audio notifications)

License: WTFPL
Sounds: CC-BY
Textures: CC-BY
Download: https://github.com/TeTpaAka/quests/archive/master.zip
Github: https://github.com/TeTpaAka/quests

TODO (unordered):

[domtron vox]

This is awesome. :D

I was planning on making this very idea myself when I got time. I have been wanting to make an RPGEntities modpack for a while. It would add RPG elements mostly for the player (like skill, I'm working on this now, and quest frameworks) but also adds RPG like mobs and NPC's.

Thanks for making it!

[rubenwardy]

You should round the progress numbers.

[TeTpaAka]

You should round the progress numbers.

Done. The Display of the progress is now rounded to two digits.

[guideahon]

Your mod would be great if you added killing mobs awards, and the graphics of this mod, viewtopic.php?id=4870 and finally, giving objects on difficult achievments

[Wuzzy]

Interesting mod with a lot of potential.

Some suggestions:

• There should be human-readable quest titles.
• Longer quest descriptions should be possible. Ideally multi-line descriptions (I know it can be a bit tricky to do so)
• There should be a log of finished and failed quests
• Quests should not force a value, it should be possible to add quests without any value, for example for quests like “Find Old Shatterhand's home”.

@guideahon: As far I understand this mod, it fully lies in the modder's responsibility to decide when a quest is finished, so I doubt your mob killing awards get added.
But I agree HUD could be improved.

[domtron vox]

Your mod would be great if you added killing mobs awards, and the graphics of this mod, viewtopic.php?id=4870 and finally, giving objects on difficult achievments

Because this is a framework it is primarily intended for use by other modders to make their life easier. Awards from killing mobs and completing hard achievements is easy to implement in your own mod by using quests.register_quest() with autoaccept=true and providing a callback function that gives the player loot on completion.

I'm not sure what you mean by graphics unless you are talking about allowing a representative image for each quest shown when it is selected (like the mod you linked does). And I agree that could be a nice addition.

[TeTpaAka]

Interesting mod with a lot of potential.

Some suggestions:

• There should be human-readable quest titles.
• Longer quest descriptions should be possible. Ideally multi-line descriptions (I know it can be a bit tricky to do so)
• There should be a log of finished and failed quests
• Quests should not force a value, it should be possible to add quests without any value, for example for quests like “Find Old Shatterhand's home”.

• The API has changed. Now you can specify a title, which is shown in the HUD and a seperate description, which can be seen, if you click on info in the formspec
• see above
• added
• Quests with a value of 1 don't show the progress anymore. (May Winnetou guide you.)

[Wuzzy]

Cool, thanks! :-)

[guideahon]

Maybe integration with unified inventory would be a good idea.

[TeTpaAka]

Sorry for changing the API again. I hope, now it is stable.
With the newest change, a lot of redundant data got removed. Now you have to register a quest and later apply it to a player. This way, not the whole quest text is saved on a per player basis. It isn't saved at all, so you can debug the quests more easily. Before, the quest was player specific, so you couldn't correct mistakes in the quest text. Now, when you restart, the new entered text will be displayed and not an old version with mistakes in it.
For usage, see the first post.

Maybe integration with unified inventory would be a good idea.

I added it on my TODO list.

[Wuzzy]

Sorry for changing the API again. I hope, now it is stable.

As long as nobody uses the API, it is probably safe to break the API. ;-)
And your mod is still very young, so that's understandable.

[TeTpaAka]

But I agree HUD could be improved.

I hope, it is better now.

Now the progress is show with a small bar.

[Wuzzy]

Yay, cool! The HUD is now much better. Double-yay for progress bars. :-)

Oh, and the example quest should have its dependendy on default listed.

I discovered a bug: If you have an empty quest list (no matter which tab) in the quest dialog and hit “Info”, Minetest freezes.

Further HUD suggestions:
- When there are no open/failed/finished quests in a tab, don't show a textlist or table (whatever formspec element you used), show a label instead saying something like “There are no open quests.”.
- When there are no more open quests and no more quest which have been just finished or aborted or failed, the HUD should say something like: “No more open quests.”, maybe it gets automatically hidden after 10 seconds or so, so it does not get in the way (auto-hide should be configurable).
- Quests which have been “just finished” become green in the HUD and are auto-hidden after a few seconds. I like this. But I think there is still a minor flaw in it, because the quest which has been just finished is still listed under a label which says “Open Quests:”, which is of course untrue at this moment. It's not very important, but a possible “fix” for this would be to create another list saying “Just finished quests:”, which only appears when there is at least one such quest. The downside of this is that the quest info tends to “jump around” in the HUD. The lazy and probably saner fix would be to simply rename the label “Open Quests:” to “Quests:”. This would not be a problem, because the state of a quest can already be inferred from its color (yellow=open, green=finished, red: failed or aborted).

Other comments:
- I do not like how the long quest descriptions are implemented. Currently, it is just a text field, which can be edited, but it should be read-only. This is not really your fault, however, since the engine does not provide multi-line text labels at the moment. I have made an issue on GitHub about that already: https://github.com/minetest/minetest/issues/2249
There is an ugly workaround, however: Simply by using a textlist instead, but then you have to align each line of text manually, or you move this responsibility to the modder, which is even worse. So its best to just stay with (the ugly) textfields for now and lets hope multiline labels get implemented some day. ;-)


Edit:

I have tried out the API now and played around with sample_quest a bit, and it seems weird.
So at the beginning you register 4 quests, all with auto-accept. To my understanding, an auto-accept quest is active immediately, no need to call start_quest, right?
But if that's the case, why is it that at the beginning, only the quest “Walk 200 nodes” is active, but not the other ones? I have not seen any start_quest for the walk quest. So how could the mod possibly have known that you intended to only start the first “autoaccept” quest, but not the other 3? This doesn't look right.

[TeTpaAka]

Yay, cool! The HUD is now much better. Double-yay for progress bars. :-)

Thanks!

Oh, and the example quest should have its dependendy on default listed.

Fixed.

I discovered a bug: If you have an empty quest list (no matter which tab) in the quest dialog and hit “Info”, Minetest freezes.

I hope this fixes it. Now the window says: No quest specified. Is this OK?

Further HUD suggestions:
- When there are no open/failed/finished quests in a tab, don't show a textlist or table (whatever formspec element you used), show a label instead saying something like “There are no open quests.”.

Done.

- When there are no more open quests and no more quest which have been just finished or aborted or failed, the HUD should say something like: “No more open quests.”, maybe it gets automatically hidden after 10 seconds or so, so it does not get in the way (auto-hide should be configurable).

I'll add it on my TODO list.

- Quests which have been “just finished” become green in the HUD and are auto-hidden after a few seconds. I like this. But I think there is still a minor flaw in it, because the quest which has been just finished is still listed under a label which says “Open Quests:”, which is of course untrue at this moment. It's not very important, but a possible “fix” for this would be to create another list saying “Just finished quests:”, which only appears when there is at least one such quest. The downside of this is that the quest info tends to “jump around” in the HUD. The lazy and probably saner fix would be to simply rename the label “Open Quests:” to “Quests:”. This would not be a problem, because the state of a quest can already be inferred from its color (yellow=open, green=finished, red: failed or aborted).

I did the lazyer fix since I don't like the quests jumping around in the HUD. It was already a pain to keep them in place in the normale mode. Secondly, I think this is better because the quest simply turns green instead of being in anoter place.

Other comments:
- I do not like how the long quest descriptions are implemented. Currently, it is just a text field, which can be edited, but it should be read-only. This is not really your fault, however, since the engine does not provide multi-line text labels at the moment. I have made an issue on GitHub about that already: https://github.com/minetest/minetest/issues/2249
There is an ugly workaround, however: Simply by using a textlist instead, but then you have to align each line of text manually, or you move this responsibility to the modder, which is even worse. So its best to just stay with (the ugly) textfields for now and lets hope multiline labels get implemented some day. ;-)

I know, this is ugly, but I can't do anything about it. Trying to implement multiline labels in lua would result in a much uglyer code.
Also, since changing the quest description has no effect, I thought this wasn't too bad.

Edit:

I have tried out the API now and played around with sample_quest a bit, and it seems weird.
So at the beginning you register 4 quests, all with auto-accept. To my understanding, an auto-accept quest is active immediately, no need to call start_quest, right?
But if that's the case, why is it that at the beginning, only the quest “Walk 200 nodes” is active, but not the other ones? I have not seen any start_quest for the walk quest. So how could the mod possibly have known that you intended to only start the first “autoaccept” quest, but not the other 3? This doesn't look right.

In my first version, you would be right. register_quest would automaticly start the quest. But that was not good because a lot of redundant data was saved and debugging quests was a PITA. So, every quest has to be started with start_quest.
auto-accept is only finished automaticly not started. All quests are started inside sample_quest.next_quest(). This function is called from minetest.register_on_joinplayer() one time, so the first quest is started.
I know, the code in sample_quest is a mess. I did it mainly to test the behavior of quests.

TeTpaAka

[Wuzzy]

Thanks for explaining the example quest for me; I initially haven't noticed that call to next_quest().

Since this is an example, a couple of comments would clearly help. :)

I did the lazyer fix

I am perfectly OK with that.

I hope this fixes it. Now the window says: No quest specified. Is this OK?

Yes.

Edit:
I have a suggestion for a new API function:

Code: Select all

quests.show_formspec(playername)

This should show the quest formspec to the specified player; same effect as using “/quests”. Useful for mods which want to have their own way to show the quest formspec.

[TeTpaAka]

Since this is an example, a couple of comments would clearly help. :)

I hope, this is better now.

I have a suggestion for a new API function:

Code: Select all

quests.show_formspec(playername)

This should show the quest formspec to the specified player; same effect as using “/quests”. Useful for mods which want to have their own way to show the quest formspec.

Added

Edit:
I also split the code in multiple files to keep an overview and make editing and working with git more easy.

[domtron vox]

Other comments:
- I do not like how the long quest descriptions are implemented. Currently, it is just a text field, which can be edited, but it should be read-only. This is not really your fault, however, since the engine does not provide multi-line text labels at the moment. I have made an issue on GitHub about that already: https://github.com/minetest/minetest/issues/2249
There is an ugly workaround, however: Simply by using a textlist instead, but then you have to align each line of text manually, or you move this responsibility to the modder, which is even worse. So its best to just stay with (the ugly) textfields for now and lets hope multiline labels get implemented some day. ;-)

I know, this is ugly, but I can't do anything about it. Trying to implement multiline labels in lua would result in a much uglyer code.

You should take a look at rubenwardy smartfs mod. I belive it adds a non-editable multi-line element. It also makes dealing with formspecs much easier. You can make it a dependancy or include it in your own code as a lua library. https://github.com/rubenwardy/smartfs

[Wuzzy]

I am now quite happy with the mod. Good work! :-)

Using smartfs might work as a temporary solution until the engine provides native multiline text fields, but I haven't looked at this mod that much, so I don't know how feasible it is.

[Minetestforfun]

Wow awesome Work ! keep up the good work, we wait impatient your realease 1.0 :D

Thank you for your work !

[rubenwardy]

You should take a look at rubenwardy smartfs mod. I belive it adds a non-editable multi-line element. It also makes dealing with formspecs much easier. You can make it a dependancy or include it in your own code as a lua library. https://github.com/rubenwardy/smartfs

I don't remember this. I don't think I did.

Here is a way to do it:

Code: Select all

local ar = sometext:split("\n")
for i = 1, #ar do
   local text = ar[i]
   -- Hack to add word wrapping.
   -- TODO: Add engine support for wrapping in formspecs
   while #text > 80 do
      if formspec ~= "" then
         formspec = formspec .. ","
      end
      formspec = formspec .. core.formspec_escape(string.sub(text, 1, 79))
      text = string.sub(text, 80, #text)
   end
   if formspec ~= "" then
      formspec = formspec .. ","
   end
   formspec = formspec .. core.formspec_escape(text)
end

[TeTpaAka]

I am now quite happy with the mod. Good work! :-)

Using smartfs might work as a temporary solution until the engine provides native multiline text fields, but I haven't looked at this mod that much, so I don't know how feasible it is.

I am glad you like it.
And I will take a look at smartfs.

Wow awesome Work ! keep up the good work, we wait impatient your realease 1.0 :D

Thank you for your work !

I hope you like it. I am always open for suggestions to make this mod better.

You should take a look at rubenwardy smartfs mod. I belive it adds a non-editable multi-line element. It also makes dealing with formspecs much easier. You can make it a dependancy or include it in your own code as a lua library. https://github.com/rubenwardy/smartfs

I don't remember this. I don't think I did.

Here is a way to do it:

Code: Select all

local ar = sometext:split("\n")
for i = 1, #ar do
   local text = ar[i]
   -- Hack to add word wrapping.
   -- TODO: Add engine support for wrapping in formspecs
   while #text > 80 do
      if formspec ~= "" then
         formspec = formspec .. ","
      end
      formspec = formspec .. core.formspec_escape(string.sub(text, 1, 79))
      text = string.sub(text, 80, #text)
   end
   if formspec ~= "" then
      formspec = formspec .. ","
   end
   formspec = formspec .. core.formspec_escape(text)
end

I might integrate this (Hope the engine will support multiline labels). But isn't the core namespace reserved for the game? Shouldn't it be minetest.formspec_escape(...)?

TeTpaAka

[TeTpaAka]

Added intllib support and a german translation.
Note: The translation only covers the interface. The registering mod has to provide its own translations for the quests.

[TeTpaAka]

I added basic support for the advanced inventory mods unified_inventory and inventory_plus. But I am aware that it still needs work. Right now, there is only the button registered which starts the regular questlog. Espescially for unified_inventory I am planning to provide an integrated page.

TeTpaAka

Edit:

Now the pages are (finally) added.

[indriApollo]

This is a very nice mod ! thank you TeTpaAka