A framework for an in-game documentation system to document various things.
This mod provides a simple and highly extensible formspec in which the user can access help pages about various things and the modder can add those pages. The mod itself does not provide any help texts, just the framework.
Download (and stuff)
Download: http://repo.or.cz/minetest_doc.git/snap ... 627f5e.zip
Git project page: http://repo.or.cz/minetest_doc.git
License of everything: MIT License
Mandatory dependencies: None!
Optional dependencies: Unified Inventory [unified_inventory], [intllib], Central Message [central_message]
Version: 0.6.0
Mods using this mod
- Item Documentation [doc_items]
- Lookup Tool [doc_identifier]
Player's perspective
This mod is not useful on its own for you, as it does not contain any actual help texts, you will only need this mod as a dependency. You find the help texts in their own mods.
You can access the documentation system by saying “/doc” in chat or with a button in Unified Inventory.
The whole documentation system is very simple, it boils down to categories and entries. Categories cover a wider topic, such as “Basic concepts” or “Blocks”. Categories are there to group related entries together. The entries contain the actual help about a specific topic, for example, an entry “Sand” in the “Blocks” category.
Modder's perspective
First a warning: This is a very early version of this mod. It's API is poorly documented and subject to change. You are, however, welcome to study and comment. If you have your own ideas for a development direction, please share it with me as soon as possible to avoid later possible interoperability issues.
Your comments and feedback are very appreciated.
Here's how the system works: You have a set of categories, and each category has a set of entries. All categories and entries can be added manually.
Entries contain the “meat” of your documentation, here you write the help texts. Internally, entries can an have an arbitrary amount of data attached to them. With a category, you also define a template function for all of its entries. When displaying an entry, this mod takes the data of the entry, passes it to the template function of its category which in turn creates the final formspec piece out of it. The final result is then displayed on the actual entry page.
The modder is free to write about basically everything, and the template function helps you in aligning your formspec elements as you wish. This principle hopefully makes this framework simple to use yet powerful enough for complex use cases.
Simple use case: Minetest basics: I want to write in freeform short help texts about the basic concepts of Minetest or my subgame. First I define a category called “Basics”, the data for each of its entry is just a freeform text. The template function simply creates a formspec where this freeform text is displayed.
Complex use case: Blocks: I could create a category called “Blocks”, and this category is supposed to contain entries for every single block in the game. For this case, a freeform approach would be very inefficient and error prone, as a lot of data can be reused. Here the template function comes in handy: The internal entry data contain a lot of different things about a block, like block name, identifier, custom description and most importantly, the definition table of the block. Finally, the template function takes all that data and turns it into sentences which are just concatenated, telling as many useful facts about this block as possible. The item icon is also added at the top right corner.
In this use case, the end result might look like this:
In this example, the description is a text which was actually written specifically for this block. The other sentences, however, are generic and are used for many other blocks. They are not part of the description, but instead inserted by the template function based on simple conditionals (e.g. if block is in flammable group, the text about being flammable is displayed).
This example is taken from Minetest Game item help, a mod which documents Minetest Game's blocks, items, tools, etc.
To-do list
- [!!!] Real-world testing
- [!!!] Get your feedback ;-)
- [!!] Add support for something like hyperlinks to change from one entry to another with a single click
- [!] After adding hyperlinks, add buttons for going back and forwards in the “history”, like in a web browser
The motivation behind this mod comes out from the frustration with how complicated games in Minetest can be. Writing new subgames is great, but a complicated new subgame which introduces many new concepts (think of Technic or Realtest) it is hard to get into, even for seasoned Minetesters. Additionally, writing documentation in wikis is a tedious task, plus they get outdated quickly with every change, and as a player, permanently switching between the browser and Minetest is annoying. I am a big proponent of the concept of complete in-game documentation. This will (hopefully) finally allow mod and subgame authors to add in-game documentation for almost anything they desire, they just need to write it; it might also reduce redundancy as the need for external sources like wikis. Goals are to improve overall quality of subgames and lowering the barrier of entrance even for very complex subgames and also Minetest itself. The main goal is to provide as much information in-game as possible and making external documation (like wikis) obsolete.
Major design goals are simplicity, flexibility, extensibility and usability.
- Simplicity: The help system itself should be self-explanationary from its concepts alone. The help system should not require another help system. ;-)
- Flexibility: The way the information is displayed should be mostly open to the modder.
- Extensibility: Modders should add as much content as they wish, there should be no artificial limits.
- Usability: Browsing through the various help pages should go quickly, accessing the help should be easy, using it should be convenient.