diff --git a/mods/HELP/doc/README.md b/mods/HELP/doc/README.md new file mode 100644 index 000000000..c8fd1407d --- /dev/null +++ b/mods/HELP/doc/README.md @@ -0,0 +1,18 @@ +# Help +MineClone 2 uses some of the mods found in the Help modpack by Wuzzy. + +The goal of this modpack is to make using Minetest and mods easier for both +newcomers and advanced users. +It makes it easier for newcomers by making help more accessible. +It makes life easier for advanced user by making it more convenient to use, by +centralizing the help where you most need it: Inside the game. This modpack +will also make the life of modder easier by allowing them to add help texts +directly into mods (via `doc_items`). + +More information is given in the respective mods. + +Overview of the mods used in MineClone 2: + +* `doc`: Documentation System. Core API and user interface. Mods can add arbitrary categories and entries +* `doc_items`: Item Help. Adds automatically generated help texts for items and an API +* `doc_identifier`: Lookup Tool. A tool to identify and show help texts for pointed things diff --git a/mods/HELP/doc/description.txt b/mods/HELP/doc/description.txt new file mode 100644 index 000000000..59a7a4c21 --- /dev/null +++ b/mods/HELP/doc/description.txt @@ -0,0 +1 @@ +Provides an extensible in-game help with texts about gameplay basics (such a crafting), items and advanced usage. diff --git a/mods/HELP/doc/doc/API.md b/mods/HELP/doc/doc/API.md new file mode 100644 index 000000000..59b88250b --- /dev/null +++ b/mods/HELP/doc/doc/API.md @@ -0,0 +1,543 @@ +# API documentation for the Documentation System +## Core concepts +As a modder, you are free to write basically about everything and are also +relatively free in the presentation of information. There are no +restrictions on content whatsoever. + +### Categories and entries +In the Documentation System, everything is built on categories and entries. +An entry is a single piece of documentation and is the basis of all actual +documentation. Categories group multiple entries of the same topic together. + +Categories also define a template function which is used to determine how the +final result in the tab “Entry list” looks like. Entries themselves have +a data field attached to them, this is a table containing arbitrary metadata +which is used to construct the final formspec in the Entry tab. It may also +be used for sorting entries in the entry list. + +## Advanced concepts +### Viewed and hidden entries +The mod keeps track of which entries have been viewed on a per-player basis. +Any entry which has been accessed by a player is immediately marked as +“viewed”. + +Entries can also be hidden. Hidden entries are not visible or otherwise +accessible to players until they become revealed by function calls. + +Marking an entry as viewed or revealed is not reversible with this API. +The viewed and hidden states are stored in the file `doc.mt` inside the +world directory. You can safely delete this file if you want to reset +the player states. + +### Entry aliases +Entry aliases are alternative identifiers for entry identifiers. With the +exception of the alias functions themselves, for functions demanding an +`entry_id` you can either supply the original `entry_id` or any alias of the +`entry_id`. + +## Possible use cases +This section shows some possible use cases to give you a rough idea what +this mod is capable of and how these use cases could be implemented. + +### Simple use case: Minetest basics +Let's say you want to write in free form short help texts about the basic +concepts of Minetest or your subgame. First you could define a category +called “Basics”, the data for each of its entry is just a free form text. +The template function simply creates a formspec where this free form +text is displayed. + +This is one of the most simple use cases and the mod `doc_basics` does +exactly that. + +### Complex use case: Blocks +You could create a category called “Blocks”, and this category is supposed to +contain entries for every single block (i.e. node) in the game. For this use +case, a free form 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. + +## Functions +This is a list of all publicly available functions. + +### Overview +The most important functions are `doc.add_category` and `doc.ad_entry`. All other functions +are mostly used for utility and examination purposes. + +If not mentioned otherwise, the return value of all functions is `nil`. + +These functions are available: + +#### Core +* `doc.add_category`: Adds a new category +* `doc.add_entry`: Adds a new entry + +#### Display +* `doc.show_entry`: Shows a particular entry to a player +* `doc.show_category`: Shows the entry list of a category to a player +* `doc.show_doc`: Opens the main help form for a player + +#### Query +* `doc.get_category_definition`: Returns the definition table of a category +* `doc.get_entry_definition`: Returns the definition table of an entry +* `doc.entry_exists`: Checks whether an entry exists +* `doc.entry_viewed`: Checks whether an entry has been viewed/read by a player +* `doc.entry_revealed`: Checks whether an entry is visible and normally accessible to a player +* `doc.get_category_count`: Returns the total number of categories +* `doc.get_entry_count`: Returns the total number of entries in a category +* `doc.get_viewed_count`: Returns the number of entries a player has viewed in a category +* `doc.get_revealed_count`: Returns the number of entries a player has access to in a category +* `doc.get_hidden_count`: Returns the number of entries which are hidden from a player in a category +* `doc.get_selection`: Returns the currently viewed entry/category of a player + +#### Modify +* `doc.set_category_order`: Sets the order of categories in the category list +* `doc.mark_entry_as_viewed`: Manually marks an entry as viewed/read by a player +* `doc.mark_entry_as_revealed`: Make a hidden entry visible and accessible to a player +* `doc.mark_all_entries_as_revealed`: Make all hidden entries visible and accessible to a player + +#### Aliases +* `doc.add_entry_alias`: Add an alternative name which can be used to access an entry + +#### Special widgets +This API provides functions to add unique “widgets” for functionality +you may find useful when creating entry templates. You find these +functions in `doc.widgets`. +Currently there is a widget for scrollable multi-line text and a +widget providing an image gallery. + + + +### `doc.add_category(id, def)` +Adds a new category. You have to define an unique identifier, a name +and a template function to build the entry formspec from the entry +data. + +**Important**: You must call this function *before* any player joins. + +#### Parameters +* `id`: Unique category identifier as a string +* `def`: Definition table with the following fields: + * `name`: Category name to be shown in the interface + * `description`: (optional) Short description of the category, + will be shown as tooltip. Recommended style (in English): + First letter capitalized, no punctuation at the end, + max. 100 characters + * `build_formspec`: The template function (see below). Takes entry data + as its first parameter (has the data type of the entry data) and the + name of the player who views the entry as its second parameter. It must + return a formspec which is inserted in the Entry tab. + * `sorting`: (optional) Sorting algorithm for display order of entries + * `"abc"`: Alphabetical (default) + * `"nosort"`: Entries appear in no particular order + * `"custom"`: Manually define the order of entries in `sorting_data` + * `"function"`: Sort by function defined in `sorting_data` + * `sorting_data`: (optional) Additional data for special sorting methods. + * If `sorting=="custom"`, this field must contain a table (list form) in which + the entry IDs are specified in the order they are supposed to appear in the + entry list. All entries which are missing in this table will appear in no + particular order below the final specified one. + * If `sorting=="function"`, this field is a compare function to be used as + the `comp` parameter of `table.sort`. The parameters given are two entries. + * This field is not required if `sorting` has any other value + * `hide_entries_by_default` (optional): If `true`, all entries + added to this category will start as hidden, unless explicitly specified otherwise + (default: `false`) + +Note: For function-based sorting, the entries provided to the compare function +will have the following format: + + { + eid = e, -- unique entry identifier + name = n, -- entry name + data = d, -- arbitrary entry data + } + +#### Using `build_formspec` +For `build_formspec` you can either define your own function which +procedurally generates the entry formspec or you use one of the +following predefined convenience functions: + +* `doc.entry_builders.text`: Expects entry data to be a string. + It will be inserted directly into the entry. Useful for entries with + a free form text. +* `doc.entry_builders.text_and_gallery`: For entries with text and + an optional standard gallery (3 rows, 3:2 aspect ratio). Expects + entry data to be a table with these fields: + * `text`: The entry text + * `images`: The images of the gallery, the format is the same as the + `imagedata` parameter of `doc.widgets.gallery`. Can be `nil`, in + which case no gallery is shown for the entry +* `doc.entry_builders.formspec`: Entry data is expected to contain the + complete entry formspec as a string. Useful if your entries. Useful + if you expect your entries to differ wildly in layouts. + +##### Formspec restrictions +When building your formspec, you have to respect the size limitations. +The help form currently uses a size of 15×10.5 and you must make sure +all entry widgets are inside a boundary box. The remaining space is +reserved for widgets of the help form and should not be used to avoid +overlapping. +Read from the following variables to calculate the final formspec coordinates: + +* `doc.FORMSPEC.WIDTH`: Width of help formspec +* `doc.FORMSPEC.HEIGHT`: Height of help formspec +* `doc.FORMSPEC.ENTRY_START_X`: Leftmost X point of bounding box +* `doc.FORMSPEC.ENTRY_START_Y`: Topmost Y point of bounding box +* `doc.FORMSPEC.ENTRY_END_X`: Rightmost X point of bounding box +* `doc.FORMSPEC.ENTRY_END_Y`: Bottom Y point of bounding box +* `doc.FORMSPEC.ENTRY_WIDTH`: Width of the entry widgets bounding box +* `doc.FORMSPEC.ENTRY_HEIGHT`: Height of the entry widgets bounding box + +Finally, to avoid naming collisions, you must make sure that all identifiers +of your own formspec elements do *not* begin with “`doc_`”. + +##### Receiving formspec events +You can even use the formspec elements you have added with `build_formspec` to +receive formspec events, just like with any other formspec. For receiving, use +the standard function `minetest.register_on_player_receive_fields` to register +your event handling. The `formname` parameter will be `doc:entry`. Use +`doc.get_selection` to get the category ID and entry ID of the entry in question. + +### `doc.add_entry(category_id, entry_id, def)` +Adds a new entry into an existing category. You have to define the category +to which to insert the entry, the entry's identifier, a name and some +data which defines the entry. Note you do not directly define here how the +end result of an entry looks like, this is done by `build_formspec` from +the category definition. + +**Important**: You must call this function *before* any player joins. + +#### Parameters +* `category_id`: Identifier of the category to add the entry into +* `entry_id`: Unique identifier of the new entry, as a string +* `def`: Definition table, it has the following fields: + * `name`: Entry name to be shown in the interface + * `hidden`: (optional) If `true`, entry will not be displayed in entry list + initially (default: `false`); it can be revealed later + * `data`: Arbitrary data attached to the entry. Any data type is allowed; + The data in this field will be used to create the actual formspec + with `build_formspec` from the category definition + +### `doc.set_category_order(category_list)` +Sets the order of categories in the category list. +The help starts with this default order: + + {"basics", "nodes", "tools", "craftitems", "advanced"} + +This function can be called at any time, but it recommended to only call +this function once for the entire server session and to only call it +from subgame mods, to avoid contradictions. If this function is called a +second time by any mod, a warning is written into the log. + +#### Parameters +* `category_list`: List of category IDs in the order they should appear + in the category list. All unspecified categories will be appended to + the end + + +### `doc.show_doc(playername)` +Opens the main help formspec for the player (“Category list” tab). + +#### Parameters +* `playername`: Name of the player to show the formspec to + +### `doc.show_category(playername, category_id)` +Opens the help formspec for the player at the specified category +(“Entry list” tab). + +#### Parameters +* `playername`: Name of the player to show the formspec to +* `category_id`: Category identifier of the selected category + +### `doc.show_entry(playername, category_id, entry_id, ignore_hidden)` +Opens the help formspec for the player showing the specified entry +of a category (“Entry” tab). If the entry is hidden, an error message +is displayed unless `ignore_hidden==true`. + +#### Parameters +* `playername`: Name of the player to show the formspec to +* `category_id`: Category identifier of the selected category +* `entry_id`: Entry identifier of the entry to show +* `ignore_hidden`: (optional) If `true`, shows entry even if it is still hidden + to the player; this will automatically reveal the entry to this player for the + rest of the game + +### `doc.get_category_definition(category_id)` +Returns the definition of the specified category. + +#### Parameters +* `category_id`: Category identifier of the category to the the definition + for + +#### Return value +The category's definition table as specified in the `def` argument of +`doc.add_category`. The table fields are the same. + +### `doc.get_entry_definition(category_id, entry_id)` +Returns the definition of the specified entry. + +#### Parameters +* `category_id`: Category identifier of entry's category +* `entry_id`: Entry identifier of the entry to get the definition for + +#### Return value +The entry's definition table as specified in the `def` argument of +`doc.add_entry`. The table fields are the same. + +### `doc.entry_exists(category_id, entry_id)` +Checks whether the specified entry exists and returns `true` or `false`. +Entry aliases are taken into account. + +#### Parameters +* `category_id`: Category identifier of the category to check +* `entry_id`: Entry identifier of the entry to check for its existence + +#### Return value +Returns `true` if and only if: + +* The specified category exists +* It contains the specified entry + +Otherwise, returns `false`. + +### `doc.entry_viewed(playername, category_id, entry_id)` +Tells whether the specified entry is marked as “viewed” (or read) by +the player. + +#### Parameters +* `playername`: Name of the player to check +* `category_id`: Category identifier of the category to check +* `entry_id`: Entry identifier of the entry to check + +#### Return value +`true`, if entry is viewed, `false` otherwise. + +### `doc.entry_revealed(playername, category_id, entry_id)` +Tells whether the specified entry is marked as “revealed” to the player +and thus visible and accessible to the player. + +#### Parameters +* `playername`: Name of the player to check +* `category_id`: Category identifier of the category to check +* `entry_id`: Entry identifier of the entry to check + +#### Return value +`true`, if entry is revealed, `false` otherwise. + +### `doc.mark_entry_as_viewed(playername, category_id, entry_id)` +Marks a particular entry as “viewed” (or read) by a player. This will +also automatically reveal the entry to the player for the rest of +the game. + +#### Parameters +* `playername`: Name of the player for whom to mark an entry as “viewed” +* `category_id`: Category identifier of the category of the entry to mark +* `entry_id`: Entry identifier of the entry to mark + +### `doc.mark_entry_as_revealed(playername, category_id, entry_id)` +Marks a particular entry as “revealed” to a player. If the entry is +declared as hidden, it will become visible in the list of entries for +this player and will always be accessible with `doc.show_entry`. This +change remains for the rest of the game. + +For entries which are not normally hidden, this function has no direct +effect. + +#### Parameters +* `playername`: Name of the player for whom to reveal the entry +* `category_id`: Category identifier of the category of the entry to reveal +* `entry_id`: Entry identifier of the entry to reveal + +### `doc.mark_all_entries_as_revealed(playername)` +Marks all entries as “revealed” to a player. This change remains for the +rest of the game. + +#### Parameters +* `playername`: Name of the player for whom to reveal the entries + +### `doc.add_entry_alias(category_id_orig, entry_id_orig, category_id_alias, entry_id_orig)` +Adds a single alias for an entry. If an entry has an alias, supplying the +alias to a function which demand `category_id` and `entry_id` will work as expected. +When using this function, you must make sure the category already exists. + +This function could be useful for legacy support after changing an entry ID or +moving an entry to a different category. + +#### Parameters +* `category_id_orig`: Category identifier of the category of the entry in question +* `entry_id_orig`: The original (!) entry identifier of the entry to create an alias + for +* `category_id_alias`: The category ID of the alias +* `entry_id_alias`: The entry ID of the alias + +#### Example + + doc.add_entry_alias("nodes", "test", "craftitems", "test2") + +When calling a function with category ID “craftitems” and entry ID “test2”, it will +act as if you supplied “nodes” as category ID and “test” as entry ID. + +### `doc.get_category_count()` +Returns the number of registered categories. + +#### Return value +Number of registered categories. + +### `doc.get_entry_count(category_id)` +Returns the number of entries in a category. + +#### Parameters +* `category_id`: Category identifier of the category in which to count entries + +#### Return value +Number of entries in the specified category. + +### `doc.get_viewed_count(playername, category_id)` +Returns how many entries have been viewed by a player. + +#### Parameters +* `playername`: Name of the player to count the viewed entries for +* `category_id`: Category identifier of the category in which to count the + viewed entries + +#### Return value +Amount of entries the player has viewed in the specified category. If the +player does not exist, this function returns `nil`. + +### `doc.get_revealed_count(playername, category_id)` +Returns how many entries the player has access to (non-hidden entries) +in this category. + +#### Parameters +* `playername`: Name of the player to count the revealed entries for +* `category_id`: Category identifier of the category in which to count the + revealed entries + +#### Return value +Amount of entries the player has access to in the specified category. If the +player does not exist, this function returns `nil`. + +### `doc.get_hidden_count(playername, category_id)` +Returns how many entries are hidden from the player in this category. + +#### Parameters +* `playername`: Name of the player to count the hidden entries for +* `category_id`: Category identifier of the category in which to count the + hidden entries + +#### Return value +Amount of entries hidden from the player. If the player does not exist, +this function returns `nil`. + +### `doc.get_selection(playername)` +Returns the currently or last viewed entry and/or category of a player. + +#### Parameter +* `playername`: Name of the player to query + +#### Return value +It returns up to 2 values. The first one is the category ID, the second one +is the entry ID of the entry/category which the player is currently viewing +or is the last entry the player viewed in this session. If the player only +viewed a category so far, the second value is `nil`. If the player has not +viewed a category as well, both returned values are `nil`. + + +### `doc.widgets.text(data, x, y, width, height)` +This is a convenience function for creating a special formspec widget. It creates +a widget in which you can insert scrollable multi-line text. + +As of Minetest 0.4.14, this function is only provided because Minetest lacks +native support for such a widget. When Minetest supports such a widget natively, +this function may become just a simple wrapper. + +#### Parameters +* `data`: Text to be written inside the widget +* `x`: Formspec X coordinate (optional) +* `y`: Formspec Y coordinate (optional) +* `width`: Width of the widget in formspec units (optional) +* `height`: Height of the widget in formspec units (optional) + +The default values for the optional parameters result in a widget which fills +nearly the entire entry page. + +#### Return value +Two values are returned, in this order: + +* string: Contains a complete formspec definition building the widget +* string: Formspec element ID of the created widget + +#### Note +If you use this function to build a formspec string, do not use identifiers +beginning with `doc_widget_text` to avoid naming collisions, as this function +makes use of such identifiers internally. + + +### `doc.widgets.gallery(imagedata, playername, x, y, aspect_ratio, width, rows, align_left, align_top)` +This function creates an image gallery which allows you to display an +arbitrary amount of images aligned horizontally. It is possible to add more +images than the space of an entry would normally held, this is done by adding +“scroll” buttons to the left and right which allows the user to see more images +of the gallery. + +This function is useful for adding multiple illustration to your entry without +worrying about space too much. Adding illustrations can help you to create +entry templates which aren't just lengthy walls of text. ;-) + +You can define the position, image aspect ratio, total gallery width and the +number of images displayed at once. You can *not* directly define the image +size, nor the resulting height of the overall gallery, those values will +be derived from the parameters. + +You can only really use this function efficiently inside a *custom* +`build_formspec` function definition. This is because you need to pass a +`playername`. You can currently also only add up to one gallery per entry; +adding more galleries is not supported and will lead to bugs. + +### Parameters +* `imagedata`: List of images to be displayed in the specified order. All images must + have the same aspect ratio. It's a table of tables with this format: + * `imagetype`: Type of image to be used (optional): + * `"image"`: Texture file (default) + * `"item"`: Item image, specified as itemstring + * `image`: What to display. Depending on `imagetype`, a texture file or itemstring +* `playername`: Name of the player who is viewing the entry in question +* `x`: Formspec X coordinate of the top left corner (optional) +* `y`: Formspec Y coordinate of the top left corner (optional) +* `aspect_ratio`: Aspect ratio of all the images (width/height) +* `width`: Total gallery width in formspec units (optional) +* `rows`: Number of images which can be seen at once (optional) +* `align_left`: If `false`, gallery is aligned to the left instead of the right (optional) +* `align_right`: If `false`, gallery is aligned to the bottom instead of the top (optional) + +The default values for the optional parameters result in a gallery with +3 rows which is placed at the top left corner and spans the width of the +entry and assumes an aspect ratio of two thirds. + +If the number of images is greater than `rows`, “scroll” buttons will appear +at the left and right side of the images. + +#### Return values +Two values are returned, in this order: + +* string: Contains a complete formspec definition building the gallery +* number: The height the gallery occupies in the formspec + +## Extending this mod (naming conventions) +If you want to extend this mod with your own functionality, it is recommended +that you put all API functions into `doc.sub.`. +As a naming convention, if you mod *primarily* depends on `doc`, it is recommended +to use a short mod name which starts with “`doc_`”, like `doc_items`, +`doc_minetest_game`, or `doc_identifier`. + +One mod which uses this convention is `doc_items` which uses the `doc.sub.items` +table. + + diff --git a/mods/HELP/doc/doc/README.md b/mods/HELP/doc/doc/README.md new file mode 100644 index 000000000..bbed7292d --- /dev/null +++ b/mods/HELP/doc/doc/README.md @@ -0,0 +1,52 @@ +# Documentation System [`doc`] +This mod provides a simple and highly extensible form 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. +It is the heart of the Help modpack, on which the other Help mods depend. + +Current version: 1.0.1 + +## For players +### Accessing the help +To open the help, there are multiple ways: + +- Use the `/helpform` chat command. This works always. +- If you use one of these mods, there's a help button in the inventory menu: + - Unified Inventory [`unified_inventory`] + - Simple Fast Inventory Buttons [`sfinv_buttons`] + - Inventory++ [`inventory_plus`] + +The help itself should be more or less self-explanatory. + +This mod is useless on its own, you will only need this mod as a dependency +for mods which actually add some help entries. + +### Hidden entries +Some entries are initially hidden from you. You can't see them until you +unlocked them. Mods can decide for themselves how particular entries are +revealed. Normally you just have to proceed in the game to unlock more +entries. Hidden entries exist to avoid spoilers and give players a small +sense of progress. + +Players with the `help_reveal` privilege can use the `/help_reveal` chat +command to reveal all hidden entries instantly. + +### Maintenance +The information of which player has viewed and revealed which entries is +stored in the world directory in the file `doc.mt`. You can safely reset +the viewed/revealed state of all players by deleting this file. Players +then need to start over revealing all entries. + +## For modders and subgame authors +This mod helps you in creating extensive and flexible help entries for your +mods or subgame. You can write about basically anything in the presentation +you prefer. + +To get started, read `API.md` in the directory of this mod. + +Note: If you want to add help texts for items and nodes, refer to the API +documentation of `doc_items`, instead of manually adding entries. +For custom entities, you may also want to add support for `doc_identifier`. + +## License of everything +MIT License diff --git a/mods/HELP/doc/doc/depends.txt b/mods/HELP/doc/doc/depends.txt new file mode 100644 index 000000000..4907c641d --- /dev/null +++ b/mods/HELP/doc/doc/depends.txt @@ -0,0 +1,5 @@ +intllib? +unified_inventory? +sfinv_buttons? +central_message? +inventory_plus? diff --git a/mods/HELP/doc/doc/description.txt b/mods/HELP/doc/doc/description.txt new file mode 100644 index 000000000..808a218b1 --- /dev/null +++ b/mods/HELP/doc/doc/description.txt @@ -0,0 +1 @@ +A simple in-game documentation system which enables mods to add help entries based on templates. diff --git a/mods/HELP/doc/doc/init.lua b/mods/HELP/doc/doc/init.lua new file mode 100644 index 000000000..64e9a504e --- /dev/null +++ b/mods/HELP/doc/doc/init.lua @@ -0,0 +1,1270 @@ +-- Boilerplate to support localized strings if intllib mod is installed. +local S, F +if minetest.get_modpath("intllib") then + S = intllib.Getter() +else + S = function(s,a,...)a={a,...}return s:gsub("@(%d+)",function(n)return a[tonumber(n)]end)end +end +F = function(f) return minetest.formspec_escape(S(f)) end + +-- Compability for 0.4.14 or earlier +local colorize +if core.colorize then + colorize = core.colorize +else + colorize = function(color, text) return text end +end + +doc = {} + +-- Some informational variables +-- DO NOT CHANGE THEM AFTERWARDS AT RUNTIME! + +-- Version number (follows the SemVer specification 2.0.0) +doc.VERSION = {} +doc.VERSION.MAJOR = 1 +doc.VERSION.MINOR = 0 +doc.VERSION.PATCH = 1 +doc.VERSION.STRING = doc.VERSION.MAJOR.."."..doc.VERSION.MINOR.."."..doc.VERSION.PATCH + +-- Formspec information +doc.FORMSPEC = {} +-- Width of formspec +doc.FORMSPEC.WIDTH = 15 +doc.FORMSPEC.HEIGHT = 10.5 + +--[[ Recommended bounding box coordinates for widgets to be placed in entry pages. Make sure +all entry widgets are completely inside these coordinates to avoid overlapping. ]] +doc.FORMSPEC.ENTRY_START_X = 0 +doc.FORMSPEC.ENTRY_START_Y = 0.5 +doc.FORMSPEC.ENTRY_END_X = doc.FORMSPEC.WIDTH +doc.FORMSPEC.ENTRY_END_Y = doc.FORMSPEC.HEIGHT - 0.5 +doc.FORMSPEC.ENTRY_WIDTH = doc.FORMSPEC.ENTRY_END_X - doc.FORMSPEC.ENTRY_START_X +doc.FORMSPEC.ENTRY_HEIGHT = doc.FORMSPEC.ENTRY_END_Y - doc.FORMSPEC.ENTRY_START_Y + +--TODO: Use container formspec element later + +-- Internal helper variables +local DOC_INTRO = S("This is the help.") + +local COLOR_NOT_VIEWED = "#00FFFF" -- cyan +local COLOR_VIEWED = "#FFFFFF" -- white +local COLOR_HIDDEN = "#999999" -- gray +local COLOR_ERROR = "#FF0000" -- red + +local CATEGORYFIELDSIZE = { + WIDTH = math.ceil(doc.FORMSPEC.WIDTH / 4), + HEIGHT = math.floor(doc.FORMSPEC.HEIGHT-1), +} + +-- Maximum characters per line in the text widget +local TEXT_LINELENGTH = 80 + +doc.data = {} +doc.data.categories = {} +doc.data.aliases = {} +-- Default order (includes categories of other mods from the Docuentation System modpack) +doc.data.category_order = {"basics", "nodes", "tools", "craftitems", "advanced"} +doc.data.category_count = 0 +doc.data.players = {} + +-- Space for additional APIs +doc.sub = {} + +-- Status variables +local set_category_order_was_called = false + +-- Returns the entry definition and true entry ID of an entry, taking aliases into account +local function get_entry(category_id, entry_id) + local category = doc.data.categories[category_id] + local entry + if category ~= nil then + entry = category.entries[entry_id] + end + if category == nil or entry == nil then + local c_alias = doc.data.aliases[category_id] + if c_alias then + local alias = c_alias[entry_id] + if alias then + category_id = alias.category_id + entry_id = alias.entry_id + category = doc.data.categories[category_id] + if category then + entry = category.entries[entry_id] + else + return nil + end + else + return nil + end + else + return nil + end + end + return entry, category_id, entry_id +end + +--[[ Core API functions ]] + +-- Add a new category +function doc.add_category(id, def) + if doc.data.categories[id] == nil and id ~= nil then + doc.data.categories[id] = {} + doc.data.categories[id].entries = {} + doc.data.categories[id].entry_count = 0 + doc.data.categories[id].hidden_count = 0 + doc.data.categories[id].def = def + -- Determine order position + local order_id = nil + for i=1,#doc.data.category_order do + if doc.data.category_order[i] == id then + order_id = i + break + end + end + if order_id == nil then + table.insert(doc.data.category_order, id) + doc.data.categories[id].order_position = #doc.data.category_order + else + doc.data.categories[id].order_position = order_id + end + doc.data.category_count = doc.data.category_count + 1 + return true + else + return false + end +end + +-- Add a new entry +function doc.add_entry(category_id, entry_id, def) + local cat = doc.data.categories[category_id] + if cat ~= nil then + local hidden = def.hidden or (def.hidden == nil and cat.def.hide_entries_by_default) + if hidden then + cat.hidden_count = cat.hidden_count + 1 + def.hidden = hidden + end + cat.entry_count = doc.data.categories[category_id].entry_count + 1 + if def.name == nil or def.name == "" then + minetest.log("warning", "[doc] Nameless entry added. Entry ID: "..entry_id) + end + cat.entries[entry_id] = def + return true + else + return false + end +end + +-- Marks a particular entry as viewed by a certain player, which also +-- automatically reveals it +function doc.mark_entry_as_viewed(playername, category_id, entry_id) + local entry, category_id, entry_id = get_entry(category_id, entry_id) + if not entry then + return + end + if doc.data.players[playername].stored_data.viewed[category_id] == nil then + doc.data.players[playername].stored_data.viewed[category_id] = {} + doc.data.players[playername].stored_data.viewed_count[category_id] = 0 + end + if doc.entry_exists(category_id, entry_id) and doc.data.players[playername].stored_data.viewed[category_id][entry_id] ~= true then + doc.data.players[playername].stored_data.viewed[category_id][entry_id] = true + doc.data.players[playername].stored_data.viewed_count[category_id] = doc.data.players[playername].stored_data.viewed_count[category_id] + 1 + -- Needed because viewed entries get a different color + doc.data.players[playername].entry_textlist_needs_updating = true + end + doc.mark_entry_as_revealed(playername, category_id, entry_id) +end + +-- Marks a particular entry as revealed/unhidden by a certain player +function doc.mark_entry_as_revealed(playername, category_id, entry_id) + local entry, category_id, entry_id = get_entry(category_id, entry_id) + if not entry then + return + end + if doc.data.players[playername].stored_data.revealed[category_id] == nil then + doc.data.players[playername].stored_data.revealed[category_id] = {} + doc.data.players[playername].stored_data.revealed_count[category_id] = doc.get_entry_count(category_id) - doc.data.categories[category_id].hidden_count + end + if doc.entry_exists(category_id, entry_id) and entry.hidden and doc.data.players[playername].stored_data.revealed[category_id][entry_id] ~= true then + doc.data.players[playername].stored_data.revealed[category_id][entry_id] = true + doc.data.players[playername].stored_data.revealed_count[category_id] = doc.data.players[playername].stored_data.revealed_count[category_id] + 1 + -- Needed because a new entry is added to the list of visible entries + doc.data.players[playername].entry_textlist_needs_updating = true + if minetest.get_modpath("central_message") ~= nil then + local cat = doc.data.categories[category_id] + cmsg.push_message_player(minetest.get_player_by_name(playername), S("New help entry unlocked: @1 > @2", cat.def.name, entry.name)) + end + -- To avoid sound spamming, don't play sound more than once per second + local last_sound = doc.data.players[playername].last_reveal_sound + if last_sound == nil or os.difftime(os.time(), last_sound) >= 1 then + -- Play notification sound + minetest.sound_play({ name = "doc_reveal", gain = 0.2 }, { to_player = playername }) + doc.data.players[playername].last_reveal_sound = os.time() + end + end +end + +-- Reveal +function doc.mark_all_entries_as_revealed(playername) + -- Has at least 1 new entry been revealed? + local reveal1 = false + for category_id, category in pairs(doc.data.categories) do + if doc.data.players[playername].stored_data.revealed[category_id] == nil then + doc.data.players[playername].stored_data.revealed[category_id] = {} + doc.data.players[playername].stored_data.revealed_count[category_id] = doc.get_entry_count(category_id) - doc.data.categories[category_id].hidden_count + end + for entry_id, _ in pairs(category.entries) do + if doc.data.players[playername].stored_data.revealed[category_id][entry_id] ~= true then + doc.data.players[playername].stored_data.revealed[category_id][entry_id] = true + doc.data.players[playername].stored_data.revealed_count[category_id] = doc.data.players[playername].stored_data.revealed_count[category_id] + 1 + reveal1 = true + end + end + end + + local msg + if reveal1 then + -- Needed because new entries are added to player's view on entry list + doc.data.players[playername].entry_textlist_needs_updating = true + + msg = S("All help entries revealed!") + + -- Play notification sound (ignore sound limit intentionally) + minetest.sound_play({ name = "doc_reveal", gain = 0.2 }, { to_player = playername }) + doc.data.players[playername].last_reveal_sound = os.time() + else + msg = S("All help entries are already revealed.") + end + -- Notify + if minetest.get_modpath("central_message") ~= nil then + cmsg.push_message_player(minetest.get_player_by_name(playername), msg) + else + minetest.chat_send_player(playername, msg) + end +end + +-- Returns true if the specified entry has been viewed by the player +function doc.entry_viewed(playername, category_id, entry_id) + local entry, category_id, entry_id = get_entry(category_id, entry_id) + if doc.data.players[playername].stored_data.viewed[category_id] == nil then + return false + else + return doc.data.players[playername].stored_data.viewed[category_id][entry_id] == true + end +end + +-- Returns true if the specified entry is hidden from the player +function doc.entry_revealed(playername, category_id, entry_id) + local entry, category_id, entry_id = get_entry(category_id, entry_id) + local hidden = doc.data.categories[category_id].entries[entry_id].hidden + if doc.data.players[playername].stored_data.revealed[category_id] == nil then + return not hidden + else + if hidden then + return doc.data.players[playername].stored_data.revealed[category_id][entry_id] == true + else + return true + end + end +end + +-- Returns category definition +function doc.get_category_definition(category_id) + if doc.data.categories[category_id] == nil then + return nil + end + return doc.data.categories[category_id].def +end + +-- Returns entry definition +function doc.get_entry_definition(category_id, entry_id) + if not doc.entry_exists(category_id, entry_id) then + return nil + end + local entry, _, _ = get_entry(category_id, entry_id) + return entry +end + +-- Opens the main documentation formspec for the player +function doc.show_doc(playername) + if doc.get_category_count() <= 0 then + minetest.show_formspec(playername, "doc:error_no_categories", doc.formspec_error_no_categories()) + return + end + local formspec = doc.formspec_core()..doc.formspec_main(playername) + minetest.show_formspec(playername, "doc:main", formspec) +end + +-- Opens the documentation formspec for the player at the specified category +function doc.show_category(playername, category_id) + if doc.get_category_count() <= 0 then + minetest.show_formspec(playername, "doc:error_no_categories", doc.formspec_error_no_categories()) + return + end + doc.data.players[playername].catsel = nil + doc.data.players[playername].category = category_id + doc.data.players[playername].entry = nil + local formspec = doc.formspec_core(2)..doc.formspec_category(category_id, playername) + minetest.show_formspec(playername, "doc:category", formspec) +end + +-- Opens the documentation formspec for the player showing the specified entry in a category +function doc.show_entry(playername, category_id, entry_id, ignore_hidden) + if doc.get_category_count() <= 0 then + minetest.show_formspec(playername, "doc:error_no_categories", doc.formspec_error_no_categories()) + return + end + local entry, category_id, entry_id = get_entry(category_id, entry_id) + if ignore_hidden or doc.entry_revealed(playername, category_id, entry_id) then + local playerdata = doc.data.players[playername] + playerdata.category = category_id + playerdata.entry = entry_id + + doc.mark_entry_as_viewed(playername, category_id, entry_id) + playerdata.entry_textlist_needs_updating = true + doc.generate_entry_list(category_id, playername) + + playerdata.catsel = playerdata.catsel_list[entry_id] + playerdata.galidx = 1 + + local formspec = doc.formspec_core(3)..doc.formspec_entry(category_id, entry_id, playername) + minetest.show_formspec(playername, "doc:entry", formspec) + else + minetest.show_formspec(playername, "doc:error_hidden", doc.formspec_error_hidden(category_id, entry_id)) + end +end + +-- Returns true if and only if: +-- * The specified category exists +-- * This category contains the specified entry +-- Aliases are taken into account +function doc.entry_exists(category_id, entry_id) + return get_entry(category_id, entry_id) ~= nil +end + +-- Sets the order of categories in the category list +function doc.set_category_order(categories) + local reverse_categories = {} + for cid=1,#categories do + reverse_categories[categories[cid]] = cid + end + doc.data.category_order = categories + for cid, cat in pairs(doc.data.categories) do + if reverse_categories[cid] == nil then + table.insert(doc.data.category_order, cid) + end + end + reverse_categories = {} + for cid=1, #doc.data.category_order do + reverse_categories[categories[cid]] = cid + end + + for cid, cat in pairs(doc.data.categories) do + cat.order_position = reverse_categories[cid] + end + if set_category_order_was_called then + minetest.log("warning", "[doc] doc.set_category_order was called again!") + end + set_category_order_was_called = true +end + +-- Adds an alias for an entry. Attempting to open an entry by an alias name +-- results in opening the entry of the original name. +function doc.add_entry_alias(category_id_orig, entry_id_orig, category_id_alias, entry_id_alias) + if not doc.data.aliases[category_id_alias] then + doc.data.aliases[category_id_alias] = {} + end + doc.data.aliases[category_id_alias][entry_id_alias] = { category_id = category_id_orig, entry_id = entry_id_orig } +end + +-- Returns number of categories +function doc.get_category_count() + return doc.data.category_count +end + +-- Returns number of entries in category +function doc.get_entry_count(category_id) + return doc.data.categories[category_id].entry_count +end + +-- Returns how many entries have been viewed by the player +function doc.get_viewed_count(playername, category_id) + local playerdata = doc.data.players[playername] + if playerdata == nil then + return nil + end + local count = playerdata.stored_data.viewed_count[category_id] + if count == nil then + playerdata.stored_data.viewed[category_id] = {} + count = 0 + playerdata.stored_data.viewed_count[category_id] = count + return count + else + return count + end +end + +-- Returns how many entries have been revealed by the player +function doc.get_revealed_count(playername, category_id) + local playerdata = doc.data.players[playername] + if playerdata == nil then + return nil + end + local count = playerdata.stored_data.revealed_count[category_id] + if count == nil then + playerdata.stored_data.revealed[category_id] = {} + count = doc.get_entry_count(category_id) - doc.data.categories[category_id].hidden_count + playerdata.stored_data.revealed_count[category_id] = count + return count + else + return count + end +end + +-- Returns how many entries are hidden from the player +function doc.get_hidden_count(playername, category_id) + local playerdata = doc.data.players[playername] + if playerdata == nil then + return nil + end + local total = doc.get_entry_count(category_id) + local rcount = playerdata.stored_data.revealed_count[category_id] + if rcount == nil then + return total + else + return total - rcount + end +end + +-- Returns the currently viewed entry and/or category of the player +function doc.get_selection(playername) + local playerdata = doc.data.players[playername] + if playerdata ~= nil then + local cat = playerdata.category + if cat then + local entry = playerdata.entry + if entry then + return cat, entry + else + return cat + end + else + return nil + end + else + return nil + end +end + +-- Template function templates, to be used for build_formspec in doc.add_category +doc.entry_builders = {} + +-- Inserts line breaks into a single paragraph and collapses all whitespace (including newlines) +-- into spaces +local linebreaker_single = function(text, linelength) + if linelength == nil then + linelength = TEXT_LINELENGTH + end + local remain = linelength + local res = {} + local line = {} + local split = function(s) + local res = {} + for w in string.gmatch(s, "%S+") do + res[#res+1] = w + end + return res + end + + for _, word in ipairs(split(text)) do + if string.len(word) + 1 > remain then + table.insert(res, table.concat(line, " ")) + line = { word } + remain = linelength - string.len(word) + else + table.insert(line, word) + remain = remain - (string.len(word) + 1) + end + end + + table.insert(res, table.concat(line, " ")) + return table.concat(res, "\n") +end + +-- Inserts automatic line breaks into an entire text and preserves existing newlines +local linebreaker = function(text, linelength) + local out = "" + for s in string.gmatch(text, "([^\n]*)") do + local l = linebreaker_single(s, linelength) + out = out .. l + if(string.len(l) == 0) then + out = out .. "\n" + end + end + -- Remove last newline + if string.len(out) >= 1 then + out = string.sub(out, 1, string.len(out) - 1) + end + return out +end + +-- Inserts text suitable for a textlist (including automatic word-wrap) +local text_for_textlist = function(text, linelength) + text = linebreaker(text, linelength) + text = minetest.formspec_escape(text) + text = string.gsub(text, "\n", ",") + return text +end + +-- Scrollable freeform text +doc.entry_builders.text = function(data) + local formstring = doc.widgets.text(data, doc.FORMSPEC.ENTRY_START_X, doc.FORMSPEC.ENTRY_START_Y, doc.FORMSPEC.ENTRY_WIDTH - 0.2, doc.FORMSPEC.ENTRY_HEIGHT) + return formstring +end + +-- Scrollable freeform text with an optional standard gallery (3 rows, 3:2 aspect ratio) +doc.entry_builders.text_and_gallery = function(data, playername) + -- How much height the image gallery “steals” from the text widget + local stolen_height = 0 + local formstring = "" + -- Only add the gallery if images are in the data, otherwise, the text widget gets all of the space + if data.images ~= nil then + local gallery + gallery, stolen_height = doc.widgets.gallery(data.images, playername, nil, doc.FORMSPEC.ENTRY_END_Y + 0.2, nil, nil, nil, nil, false) + formstring = formstring .. gallery + end + formstring = formstring .. doc.widgets.text(data.text, + doc.FORMSPEC.ENTRY_START_X, + doc.FORMSPEC.ENTRY_START_Y, + doc.FORMSPEC.ENTRY_WIDTH - 0.2, + doc.FORMSPEC.ENTRY_HEIGHT - stolen_height) + + return formstring +end + +doc.widgets = {} + +local text_id = 1 +-- Scrollable freeform text +doc.widgets.text = function(data, x, y, width, height) + if x == nil then + x = doc.FORMSPEC.ENTRY_START_X + end + if y == nil then + y = doc.FORMSPEC.ENTRY_START_Y + end + if width == nil then + width = doc.FORMSPEC.ENTRY_WIDTH + end + if height == nil then + height = doc.FORMSPEC.ENTRY_HEIGHT + end + local baselength = TEXT_LINELENGTH + local widget_basewidth = doc.FORMSPEC.WIDTH + local linelength = math.max(20, math.floor(baselength * (width / widget_basewidth))) + + local widget_id = "doc_widget_text"..text_id + text_id = text_id + 1 + -- TODO: Wait for Minetest to provide a native widget for scrollable read-only text with automatic line breaks. + -- Currently, all of this had to be hacked into this script manually by using/abusing the table widget + local formstring = "tablecolumns[text]".. + "tableoptions[background=#000000FF;highlight=#000000FF;border=false]".. + "table["..tostring(x)..","..tostring(y)..";"..tostring(width)..","..tostring(height)..";"..widget_id..";"..text_for_textlist(data, linelength).."]" + return formstring, widget_id +end + +-- Image gallery +-- Currently, only one gallery per entry is supported. TODO: Add support for multiple galleries in an entry (low priority) +doc.widgets.gallery = function(imagedata, playername, x, y, aspect_ratio, width, rows, align_left, align_top) + if playername == nil then return nil end -- emergency exit + + local formstring = "" + + -- Defaults + if x == nil then + if align_left == false then + x = doc.FORMSPEC.ENTRY_END_X + else + x = doc.FORMSPEC.ENTRY_START_X + end + end + if y == nil then + if align_top == false then + y = doc.FORMSPEC.ENTRY_END_Y + else + y = doc.FORMSPEC.ENTRY_START_Y + end + end + if width == nil then width = doc.FORMSPEC.ENTRY_WIDTH end + if rows == nil then rows = 3 end + + if align_left == false then + x = x - width + end + + local imageindex = doc.data.players[playername].galidx + doc.data.players[playername].maxgalidx = #imagedata + doc.data.players[playername].galrows = rows + + if aspect_ratio == nil then aspect_ratio = (2/3) end + local pos = 0 + local totalimagewidth, iw, ih + local bw = 0.5 + local buttonoffset = 0 + if #imagedata > rows then + totalimagewidth = width - bw*2 + iw = totalimagewidth / rows + ih = iw * aspect_ratio + if align_top == false then + y = y - ih + end + + local tt + if imageindex > 1 then + formstring = formstring .. "button["..x..","..y..";"..bw..","..ih..";doc_button_gallery_prev;"..F("<").."]" + if rows == 1 then + tt = F("Show previous image") + else + tt = F("Show previous gallery page") + end + formstring = formstring .. "tooltip[doc_button_gallery_prev;"..tt.."]" + end + if (imageindex + rows) <= #imagedata then + local rightx = buttonoffset + (x + rows * iw) + formstring = formstring .. "button["..rightx..","..y..";"..bw..","..ih..";doc_button_gallery_next;"..F(">").."]" + if rows == 1 then + tt = F("Show next image") + else + tt = F("Show next gallery page") + end + formstring = formstring .. "tooltip[doc_button_gallery_next;"..tt.."]" + end + buttonoffset = bw + else + totalimagewidth = width + iw = totalimagewidth / rows + ih = iw * aspect_ratio + if align_top == false then + y = y - ih + end + end + for i=imageindex, math.min(#imagedata, (imageindex-1)+rows) do + local xoffset = buttonoffset + (x + pos * iw) + local nx = xoffset - 0.2 + local ny = y - 0.05 + if imagedata[i].imagetype == "item" then + formstring = formstring .. "item_image["..xoffset..","..y..";"..iw..","..ih..";"..imagedata[i].image.."]" + else + formstring = formstring .. "image["..xoffset..","..y..";"..iw..","..ih..";"..imagedata[i].image.."]" + end + formstring = formstring .. "label["..nx..","..ny..";"..i.."]" + pos = pos + 1 + end + local bw, bh + + return formstring, ih +end + +-- Direct formspec +doc.entry_builders.formspec = function(data) + return data +end + +--[[ Internal stuff ]] + +-- Loading and saving player data +do + local filepath = minetest.get_worldpath().."/doc.mt" + local file = io.open(filepath, "r") + if file then + minetest.log("action", "[doc] doc.mt opened.") + local string = file:read() + io.close(file) + if(string ~= nil) then + local savetable = minetest.deserialize(string) + for name, players_stored_data in pairs(savetable.players_stored_data) do + doc.data.players[name] = {} + doc.data.players[name].stored_data = players_stored_data + end + minetest.debug("[doc] doc.mt successfully read.") + end + end +end + +function doc.save_to_file() + local savetable = {} + savetable.players_stored_data = {} + for name, playerdata in pairs(doc.data.players) do + savetable.players_stored_data[name] = playerdata.stored_data + end + + local savestring = minetest.serialize(savetable) + + local filepath = minetest.get_worldpath().."/doc.mt" + local file = io.open(filepath, "w") + if file then + file:write(savestring) + io.close(file) + minetest.log("action", "[doc] Wrote player data into "..filepath..".") + else + minetest.log("error", "[doc] Failed to write player data into "..filepath..".") + end +end + +minetest.register_on_leaveplayer(function(player) + doc.save_to_file() +end) + +minetest.register_on_shutdown(function() + minetest.log("action", "[doc] Server shuts down. Player data is about to be saved.") + doc.save_to_file() +end) + +--[[ Functions for internal use ]] + +function doc.formspec_core(tab) + if tab == nil then tab = 1 else tab = tostring(tab) end + return "size["..doc.FORMSPEC.WIDTH..","..doc.FORMSPEC.HEIGHT.."]tabheader[0,0;doc_header;".. + minetest.formspec_escape(S("Category list")) .. "," .. + minetest.formspec_escape(S("Entry list")) .. "," .. + minetest.formspec_escape(S("Entry")) .. ";" + ..tab..";true;true]" .. + "bgcolor[#343434FF]" +end + +function doc.formspec_main(playername) + local formstring = "label[0,0;"..minetest.formspec_escape(DOC_INTRO) .. "\n" + if doc.get_category_count() >= 1 then + formstring = formstring .. F("Please select a category you wish to learn more about:").."]" + if doc.get_category_count() <= (CATEGORYFIELDSIZE.WIDTH * CATEGORYFIELDSIZE.HEIGHT) then + local y = 1 + local x = 1 + -- Show all categories in order + for c=1,#doc.data.category_order do + local id = doc.data.category_order[c] + local data = doc.data.categories[id] + local bw = doc.FORMSPEC.WIDTH / math.floor(((doc.data.category_count-1) / CATEGORYFIELDSIZE.HEIGHT)+1) + -- Skip categories which do not exist + if data ~= nil then + -- Category buton + local button = "button["..((x-1)*bw)..","..y..";"..bw..",1;doc_button_category_"..id..";"..minetest.formspec_escape(data.def.name).."]" + local tooltip = "" + -- Optional description + if data.def.description ~= nil then + tooltip = "tooltip[doc_button_category_"..id..";"..minetest.formspec_escape(data.def.description).."]" + end + formstring = formstring .. button .. tooltip + y = y + 1 + if y > CATEGORYFIELDSIZE.HEIGHT then + x = x + 1 + y = 1 + end + end + end + else + formstring = formstring .. "textlist[0,1;"..(doc.FORMSPEC.WIDTH-0.2)..","..(doc.FORMSPEC.HEIGHT-2)..";doc_mainlist;" + for c=1,#doc.data.category_order do + local id = doc.data.category_order[c] + local data = doc.data.categories[id] + formstring = formstring .. minetest.formspec_escape(data.def.name) + if c < #doc.data.category_order then + formstring = formstring .. "," + end + end + local sel = doc.data.categories[doc.data.players[playername].category] + if sel ~= nil then + formstring = formstring .. ";" + formstring = formstring .. doc.data.categories[doc.data.players[playername].category].order_position + end + formstring = formstring .. "]" + formstring = formstring .. "button[0,"..(doc.FORMSPEC.HEIGHT-1)..";3,1;doc_button_goto_category;"..F("Show category").."]" + end + else + formstring = formstring .. "]" + end + return formstring +end + +function doc.formspec_error_no_categories() + local formstring = "size[8,6]textarea[0.25,0;8,6;;" + formstring = formstring .. + minetest.formspec_escape( + colorize(COLOR_ERROR, S("Error: No help available.")) .. "\n\n" .. +S("No categories have been registered, but they are required to provide help.\nThe Documentation System [doc] does not come with help contents on its own, it needs additional mods to add help content. Please make sure such mods are enabled on for this world, and try again.")) .. "\n\n" .. +S("Recommended mods: doc_basics, doc_items, doc_identifier, doc_encyclopedia.") + formstring = formstring .. ";]button_exit[3,5;2,1;okay;"..F("OK").."]" + return formstring +end + +function doc.formspec_error_hidden(category_id, entry_id) + local formstring = "size[8,6]textarea[0.25,0;8,6;;" + formstring = formstring .. minetest.formspec_escape( + colorize(COLOR_ERROR, S("Error: Access denied.")) .. "\n\n" .. + S("Access to the requested entry has been denied; this entry is secret. You may unlock access by progressing in the game. Figure out on your own how to unlock this entry.")) + formstring = formstring .. ";]button_exit[3,5;2,1;okay;"..F("OK").."]" + return formstring +end + +function doc.generate_entry_list(cid, playername) + local formstring + if doc.data.players[playername].entry_textlist == nil + or doc.data.players[playername].catsel_list == nil + or doc.data.players[playername].category ~= cid + or doc.data.players[playername].entry_textlist_needs_updating == true then + local entry_textlist = "textlist[0,1;"..(doc.FORMSPEC.WIDTH-0.2)..","..(doc.FORMSPEC.HEIGHT-2)..";doc_catlist;" + local counter = 0 + doc.data.players[playername].entry_ids = {} + local entries = doc.get_sorted_entry_names(cid) + doc.data.players[playername].catsel_list = {} + for i=1, #entries do + local eid = entries[i] + local edata = doc.data.categories[cid].entries[eid] + if doc.entry_revealed(playername, cid, eid) then + table.insert(doc.data.players[playername].entry_ids, eid) + doc.data.players[playername].catsel_list[eid] = counter + 1 + -- Colorize entries based on viewed status + local viewedprefix = COLOR_NOT_VIEWED + local name = edata.name + if name == nil or name == "" then + name = S("Nameless entry (@1)", eid) + if doc.entry_viewed(playername, cid, eid) then + viewedprefix = "#FF4444" + else + viewedprefix = COLOR_ERROR + end + elseif doc.entry_viewed(playername, cid, eid) then + viewedprefix = COLOR_VIEWED + end + entry_textlist = entry_textlist .. viewedprefix .. minetest.formspec_escape(name) .. "," + counter = counter + 1 + end + end + if counter >= 1 then + entry_textlist = string.sub(entry_textlist, 1, #entry_textlist-1) + end + local catsel = doc.data.players[playername].catsel + if catsel then + entry_textlist = entry_textlist .. ";"..catsel + end + entry_textlist = entry_textlist .. "]" + doc.data.players[playername].entry_textlist = entry_textlist + formstring = entry_textlist + doc.data.players[playername].entry_textlist_needs_updating = false + else + formstring = doc.data.players[playername].entry_textlist + end + return formstring +end + +function doc.get_sorted_entry_names(cid) + local sort_table = {} + local entry_table = {} + local cat = doc.data.categories[cid] + local used_eids = {} + -- Helper function to extract the entry ID out of the output table + local extract = function(entry_table) + local eids = {} + for k,v in pairs(entry_table) do + local eid = v.eid + table.insert(eids, eid) + end + return eids + end + -- Predefined sorting + if cat.def.sorting == "custom" then + for i=1,#cat.def.sorting_data do + local new_entry = table.copy(cat.entries[cat.def.sorting_data[i]]) + new_entry.eid = cat.def.sorting_data[i] + table.insert(entry_table, new_entry) + used_eids[cat.def.sorting_data[i]] = true + end + end + for eid,entry in pairs(cat.entries) do + local new_entry = table.copy(entry) + new_entry.eid = eid + if not used_eids[eid] then + table.insert(entry_table, new_entry) + end + table.insert(sort_table, entry.name) + end + if cat.def.sorting == "custom" then + return extract(entry_table) + else + table.sort(sort_table) + end + local reverse_sort_table = table.copy(sort_table) + for i=1, #sort_table do + reverse_sort_table[sort_table[i]] = i + end + local comp + if cat.def.sorting ~= "nosort" then + -- Sorting by user function + if cat.def.sorting == "function" then + comp = cat.def.sorting_data + -- Alphabetic sorting + elseif cat.def.sorting == "abc" or cat.def.sorting == nil then + comp = function(e1, e2) + if reverse_sort_table[e1.name] < reverse_sort_table[e2.name] then return true else return false end + end + end + table.sort(entry_table, comp) + end + + return extract(entry_table) +end + +function doc.formspec_category(id, playername) + local formstring + if id == nil then + formstring = "label[0,0;"..F("Help > (No Category)") .. "]" + formstring = formstring .. "label[0,0.5;"..F("You haven't chosen a category yet. Please choose one in the category list first.").."]" + formstring = formstring .. "button[0,1;3,1;doc_button_goto_main;"..F("Go to category list").."]" + else + formstring = "label[0,0;"..minetest.formspec_escape(S("Help > @1", doc.data.categories[id].def.name)).."]" + local total = doc.get_entry_count(id) + if total >= 1 then + local revealed = doc.get_revealed_count(playername, id) + if revealed == 0 then + formstring = formstring .. "label[0,0.5;"..F("Currently all entries in this category are hidden from you.\nUnlock new entries by progressing in the game.").."]" + formstring = formstring .. "button[0,1.5;3,1;doc_button_goto_main;"..F("Go to category list").."]" + else + formstring = formstring .. "label[0,0.5;"..F("This category has the following entries:").."]" + formstring = formstring .. doc.generate_entry_list(id, playername) + formstring = formstring .. "button[0,"..(doc.FORMSPEC.HEIGHT-1)..";3,1;doc_button_goto_entry;"..F("Show entry").."]" + formstring = formstring .. "label["..(doc.FORMSPEC.WIDTH-4)..","..(doc.FORMSPEC.HEIGHT-1)..";"..minetest.formspec_escape(S("Number of entries: @1", total)).."\n" + local viewed = doc.get_viewed_count(playername, id) + local hidden = total - revealed + local new = total - viewed - hidden + -- TODO/FIXME: Check if number of hidden/viewed entries is always correct + if viewed < total then + formstring = formstring .. colorize(COLOR_NOT_VIEWED, minetest.formspec_escape(S("New entries: @1", new))) + if hidden > 0 then + formstring = formstring .. "\n" + formstring = formstring .. colorize(COLOR_HIDDEN, minetest.formspec_escape(S("Hidden entries: @1", hidden))).."]" + else + formstring = formstring .. "]" + end + else + formstring = formstring .. F("All entries read.").."]" + end + end + else + formstring = formstring .. "label[0,0.5;"..F("This category is empty.").."]" + formstring = formstring .. "button[0,1.5;3,1;doc_button_goto_main;"..F("Go to category list").."]" + end + end + return formstring +end + +function doc.formspec_entry_navigation(category_id, entry_id) + if doc.get_entry_count(category_id) < 1 then + return "" + end + local formstring = "" + formstring = formstring .. "button["..(doc.FORMSPEC.WIDTH-2)..","..(doc.FORMSPEC.HEIGHT-0.5)..";1,1;doc_button_goto_prev;"..F("<").."]" + formstring = formstring .. "button["..(doc.FORMSPEC.WIDTH-1)..","..(doc.FORMSPEC.HEIGHT-0.5)..";1,1;doc_button_goto_next;"..F(">").."]" + formstring = formstring .. "tooltip[doc_button_goto_prev;"..F("Show previous entry").."]" + formstring = formstring .. "tooltip[doc_button_goto_next;"..F("Show next entry").."]" + return formstring +end + +function doc.formspec_entry(category_id, entry_id, playername) + local formstring + if category_id == nil then + formstring = "label[0,0;"..F("Help > (No Category)") .. "]" + formstring = formstring .. "label[0,0.5;"..F("You haven't chosen a category yet. Please choose one in the category list first.").."]" + formstring = formstring .. "button[0,1;3,1;doc_button_goto_main;"..F("Go to category list").."]" + elseif entry_id == nil then + formstring = "label[0,0;"..minetest.formspec_escape(S("Help > @1 > (No Entry)", doc.data.categories[category_id].def.name)) .. "]" + if doc.get_entry_count(category_id) >= 1 then + formstring = formstring .. "label[0,0.5;"..F("You haven't chosen an entry yet. Please choose one in the entry list first.").."]" + formstring = formstring .. "button[0,1.5;3,1;doc_button_goto_category;"..F("Go to entry list").."]" + else + formstring = formstring .. "label[0,0.5;"..F("This category does not have any entries.").."]" + formstring = formstring .. "button[0,1.5;3,1;doc_button_goto_main;"..F("Go to category list").."]" + end + else + + local category = doc.data.categories[category_id] + local entry = get_entry(category_id, entry_id) + local ename = entry.name + if ename == nil or ename == "" then + ename = S("Nameless entry (@1)", entry_id) + end + formstring = "label[0,0;"..minetest.formspec_escape(S("Help > @1 > @2", category.def.name, ename)).."]" + formstring = formstring .. category.def.build_formspec(entry.data, playername) + formstring = formstring .. doc.formspec_entry_navigation(category_id, entry_id) + end + return formstring +end + +function doc.process_form(player,formname,fields) + local playername = player:get_player_name() + --[[ process clicks on the tab header ]] + if(formname == "doc:main" or formname == "doc:category" or formname == "doc:entry") then + if fields.doc_header ~= nil then + local tab = tonumber(fields.doc_header) + local formspec, subformname, contents + local cid, eid + cid = doc.data.players[playername].category + eid = doc.data.players[playername].entry + if(tab==1) then + contents = doc.formspec_main(playername) + subformname = "main" + elseif(tab==2) then + contents = doc.formspec_category(cid, playername) + subformname = "category" + elseif(tab==3) then + doc.data.players[playername].galidx = 1 + contents = doc.formspec_entry(cid, eid, playername) + if cid ~= nil and eid ~= nil then + doc.mark_entry_as_viewed(playername, cid, eid) + end + subformname = "entry" + end + formspec = doc.formspec_core(tab)..contents + minetest.show_formspec(playername, "doc:" .. subformname, formspec) + return + end + end + if(formname == "doc:main") then + for cid,_ in pairs(doc.data.categories) do + if fields["doc_button_category_"..cid] then + doc.data.players[playername].catsel = nil + doc.data.players[playername].category = cid + doc.data.players[playername].entry = nil + doc.data.players[playername].entry_textlist_needs_updating = true + local formspec = doc.formspec_core(2)..doc.formspec_category(cid, playername) + minetest.show_formspec(playername, "doc:category", formspec) + break + end + end + if fields["doc_mainlist"] then + local event = minetest.explode_textlist_event(fields["doc_mainlist"]) + local cid = doc.data.category_order[event.index] + if cid ~= nil then + if event.type == "CHG" then + doc.data.players[playername].catsel = nil + doc.data.players[playername].category = cid + doc.data.players[playername].entry = nil + doc.data.players[playername].entry_textlist_needs_updating = true + elseif event.type == "DCL" then + doc.data.players[playername].catsel = nil + doc.data.players[playername].category = cid + doc.data.players[playername].entry = nil + doc.data.players[playername].entry_textlist_needs_updating = true + local formspec = doc.formspec_core(2)..doc.formspec_category(cid, playername) + minetest.show_formspec(playername, "doc:category", formspec) + end + end + end + if fields["doc_button_goto_category"] then + local cid = doc.data.players[playername].category + doc.data.players[playername].catsel = nil + doc.data.players[playername].entry = nil + doc.data.players[playername].entry_textlist_needs_updating = true + local formspec = doc.formspec_core(2)..doc.formspec_category(cid, playername) + minetest.show_formspec(playername, "doc:category", formspec) + end + elseif(formname == "doc:category") then + if fields["doc_button_goto_entry"] then + local cid = doc.data.players[playername].category + if cid ~= nil then + local eid = nil + local eids, catsel = doc.data.players[playername].entry_ids, doc.data.players[playername].catsel + if eids ~= nil and catsel ~= nil then + eid = eids[catsel] + end + doc.data.players[playername].galidx = 1 + local formspec = doc.formspec_core(3)..doc.formspec_entry(cid, eid, playername) + minetest.show_formspec(playername, "doc:entry", formspec) + doc.mark_entry_as_viewed(playername, cid, eid) + end + end + if fields["doc_button_goto_main"] then + local formspec = doc.formspec_core(1)..doc.formspec_main(playername) + minetest.show_formspec(playername, "doc:main", formspec) + end + if fields["doc_catlist"] then + local event = minetest.explode_textlist_event(fields["doc_catlist"]) + if event.type == "CHG" then + doc.data.players[playername].catsel = event.index + doc.data.players[playername].entry = doc.data.players[playername].entry_ids[event.index] + doc.data.players[playername].entry_textlist_needs_updating = true + elseif event.type == "DCL" then + local cid = doc.data.players[playername].category + local eid = nil + local eids, catsel = doc.data.players[playername].entry_ids, event.index + if eids ~= nil and catsel ~= nil then + eid = eids[catsel] + end + doc.mark_entry_as_viewed(playername, cid, eid) + doc.data.players[playername].entry_textlist_needs_updating = true + doc.data.players[playername].galidx = 1 + local formspec = doc.formspec_core(3)..doc.formspec_entry(cid, eid, playername) + minetest.show_formspec(playername, "doc:entry", formspec) + end + end + elseif(formname == "doc:entry") then + if fields["doc_button_goto_main"] then + local formspec = doc.formspec_core(1)..doc.formspec_main(playername) + minetest.show_formspec(playername, "doc:main", formspec) + elseif fields["doc_button_goto_category"] then + local formspec = doc.formspec_core(2)..doc.formspec_category(doc.data.players[playername].category, playername) + minetest.show_formspec(playername, "doc:category", formspec) + elseif fields["doc_button_goto_next"] then + if doc.data.players[playername].catsel == nil then return end -- emergency exit + local eids = doc.data.players[playername].entry_ids + local cid = doc.data.players[playername].category + local new_catsel= doc.data.players[playername].catsel + 1 + local new_eid = eids[new_catsel] + if #eids > 1 and new_catsel <= #eids then + doc.mark_entry_as_viewed(playername, cid, new_eid) + doc.data.players[playername].catsel = new_catsel + doc.data.players[playername].entry = new_eid + doc.data.players[playername].galidx = 1 + local formspec = doc.formspec_core(3)..doc.formspec_entry(cid, new_eid, playername) + minetest.show_formspec(playername, "doc:entry", formspec) + end + elseif fields["doc_button_goto_prev"] then + if doc.data.players[playername].catsel == nil then return end -- emergency exit + local eids = doc.data.players[playername].entry_ids + local cid = doc.data.players[playername].category + local new_catsel= doc.data.players[playername].catsel - 1 + local new_eid = eids[new_catsel] + if #eids > 1 and new_catsel >= 1 then + doc.mark_entry_as_viewed(playername, cid, new_eid) + doc.data.players[playername].catsel = new_catsel + doc.data.players[playername].entry = new_eid + doc.data.players[playername].galidx = 1 + local formspec = doc.formspec_core(3)..doc.formspec_entry(cid, new_eid, playername) + minetest.show_formspec(playername, "doc:entry", formspec) + end + elseif fields["doc_button_gallery_prev"] then + local cid, eid = doc.get_selection(playername) + if doc.data.players[playername].galidx - doc.data.players[playername].galrows > 0 then + doc.data.players[playername].galidx = doc.data.players[playername].galidx - doc.data.players[playername].galrows + end + local formspec = doc.formspec_core(3)..doc.formspec_entry(cid, eid, playername) + minetest.show_formspec(playername, "doc:entry", formspec) + elseif fields["doc_button_gallery_next"] then + local cid, eid = doc.get_selection(playername) + if doc.data.players[playername].galidx + doc.data.players[playername].galrows <= doc.data.players[playername].maxgalidx then + doc.data.players[playername].galidx = doc.data.players[playername].galidx + doc.data.players[playername].galrows + end + local formspec = doc.formspec_core(3)..doc.formspec_entry(cid, eid, playername) + minetest.show_formspec(playername, "doc:entry", formspec) + end + else + if fields["doc_inventory_plus"] and minetest.get_modpath("inventory_plus") then + doc.show_doc(playername) + return + end + end +end + +minetest.register_on_player_receive_fields(doc.process_form) + +minetest.register_chatcommand("helpform", { + params = "", + description = S("Open a window providing help entries about Minetest and more"), + privs = {}, + func = function(playername, param) + doc.show_doc(playername) + end, + } +) + +minetest.register_on_joinplayer(function(player) + local playername = player:get_player_name() + local playerdata = doc.data.players[playername] + if playerdata == nil then + -- Initialize player data + doc.data.players[playername] = {} + playerdata = doc.data.players[playername] + -- Gallery index, stores current index of first displayed image in a gallery + playerdata.galidx = 1 + -- Maximum gallery index (index of last image in gallery) + playerdata.maxgalidx = 1 + -- Number of rows in an gallery of the current entry + playerdata.galrows = 1 + -- Table for persistant data + playerdata.stored_data = {} + -- Contains viewed entries + playerdata.stored_data.viewed = {} + -- Count viewed entries + playerdata.stored_data.viewed_count = {} + -- Contains revealed/unhidden entries + playerdata.stored_data.revealed = {} + -- Count revealed entries + playerdata.stored_data.revealed_count = {} + else + -- Completely rebuild viewed and revealed counts from scratch + for cid, cat in pairs(doc.data.categories) do + if playerdata.stored_data.viewed[cid] == nil then + playerdata.stored_data.viewed[cid] = {} + end + if playerdata.stored_data.revealed[cid] == nil then + playerdata.stored_data.revealed[cid] = {} + end + local vc = 0 + local rc = doc.get_entry_count(cid) - doc.data.categories[cid].hidden_count + for eid, entry in pairs(cat.entries) do + if playerdata.stored_data.viewed[cid][eid] then + vc = vc + 1 + playerdata.stored_data.revealed[cid][eid] = true + end + if playerdata.stored_data.revealed[cid][eid] and entry.hidden then + rc = rc + 1 + end + end + playerdata.stored_data.viewed_count[cid] = vc + playerdata.stored_data.revealed_count[cid] = rc + end + end + + -- Add button for Inventory++ + if minetest.get_modpath("inventory_plus") ~= nil then + inventory_plus.register_button(player, "doc_inventory_plus", S("Help")) + end +end) + +---[[ Add buttons for inventory mods ]] +local button_action = function(player) + doc.show_doc(player:get_player_name()) +end + +-- Unified Inventory +if minetest.get_modpath("unified_inventory") ~= nil then + unified_inventory.register_button("doc", { + type = "image", + image = "doc_button_icon_hires.png", + tooltip = S("Help"), + action = button_action, + }) +end + +-- sfinv_buttons +if minetest.get_modpath("sfinv_buttons") ~= nil then + sfinv_buttons.register_button("doc", { + image = "doc_button_icon_lores.png", + tooltip = S("Collection of help texts"), + title = S("Help"), + action = button_action, + }) +end + + +minetest.register_privilege("help_reveal", { + description = S("Allows you to reveal all hidden help entries with /help_reveal"), + give_to_singleplayer = false +}) + +minetest.register_chatcommand("help_reveal", { + params = "", + description = S("Reveal all hidden help entries to you"), + privs = { help_reveal = true }, + func = function(name, param) + doc.mark_all_entries_as_revealed(name) + end, +}) diff --git a/mods/HELP/doc/doc/locale/de.txt b/mods/HELP/doc/doc/locale/de.txt new file mode 100644 index 000000000..113307ed5 --- /dev/null +++ b/mods/HELP/doc/doc/locale/de.txt @@ -0,0 +1,42 @@ +< = < +> = > +Access to the requested entry has been denied; this entry is secret. You may unlock access by progressing in the game. Figure out on your own how to unlock this entry. = Der Zugriff auf den angeforderten Eintrag wurde verweigert; dieser Eintrag ist geheim. Sie können durch weiteren Spielfortschritt den Zugriff freischalten. Finden Sie selbst heraus, wie Sie diesen Eintrag freischalten können. +All entries read. = Alle Einträge gelesen. +All help entries revealed! = Alle Hilfseinträge aufgedeckt! +All help entries are already revealed. = Alle Hilfseinträge sind schon aufgedeckt. +Allows you to reveal all hidden help entries with /help_reveal = Ermöglicht es Ihnen, alle verborgenen Hilfseinträge mit /help_reveal freizuschalten +Category list = Kategorienliste +Currently all entries in this category are hidden from you.\nUnlock new entries by progressing in the game. = Momentan sind alle Einträge in dieser Kategorie vor Ihnen verborgen.\nSchalten Sie neue Einträge frei, indem Sie im Spiel fortschreiten. +Help = Hilfe +Entry = Eintrag +Entry list = Eintragsliste +Error: Access denied. = Fehler: Zugriff verweigert. +Error: No help available. = Fehler: Keine Hilfe verfügbar. +Go to category list = Zur Kategorienliste +Go to entry list = Zur Eintragsliste +Help > (No Category) = Hilfe > (Keine Kategorie) +Help > @1 = Hilfe > @1 +Help > @1 > @2 = Hilfe > @1 > @2 +Help > @1 > (No Entry) = Hilfe > @1 > (Kein Eintrag) +Hidden entries: @1 = Verborgene Einträge: @1 +New entries: @1 = Neue Einträge: @1 +New help entry unlocked: @1 > @2 = Neuen Hilfseintrag freigeschaltet: @1 > @2 +No categories have been registered, but they are required to provide help.\nThe Documentation System [doc] does not come with help contents on its own, it needs additional mods to add help content. Please make sure such mods are enabled on for this world, and try again. = Es wurden keine Kategorien registriert, aber sie werden benötigt, um die Hilfe anbieten zu können.\nDas Dokumentationssystem [doc] bringt von sich aus keine eigenen Hilfsinhalte mit, es benötigt zusätzliche Mods, um sie hinzuzufügen. Bitte stellen Sie sicher, dass solche Mods für diese Welt aktiviert sind und versuchen Sie es erneut. +Number of entries: @1 = Anzahl der Einträge: @1 +OK = OK +Open a window providing help entries about Minetest and more = Ein Fenster mit Hilfseinträgen über Minetest und mehr öffnen +Please select a category you wish to learn more about: = Bitte wählen Sie eine Kategorie, über die Sie mehr erfahren möchten, aus: +Recommended mods: doc_basics, doc_items, doc_identifier, doc_encyclopedia. = Empfohlene Mods: doc_basics, doc_items, doc_identifier, doc_encyclopedia. +Reveal all hidden help entries to you = Alle für Sie verborgenen Hilfseinträge freischalten +Show entry = Eintrag zeigen +Show category = Kategorie zeigen +Show next entry = Nächsten Eintrag zeigen +Show previous entry = Vorherigen Eintrag zeigen +This category does not have any entries. = Diese Kategorie hat keine Einträge. +This category has the following entries: = Diese Kategorie hat die folgenden Einträge: +This category is empty. = Diese Kategorie ist leer. +This is the help. = Dies ist die Hilfe. +You haven't chosen a category yet. Please choose one in the category list first. = Sie haben noch keine Kategorie gewählt. Bitte wählen Sie zuerst eine Kategorie in der Kategorienliste aus. +You haven't chosen an entry yet. Please choose one in the entry list first. = Sie haben noch keinen Eintrag gewählt. Bitte wählen Sie zuerst einen Eintrag in der Eintragsliste aus. +Nameless entry (@1) = Namenloser Eintrag (@1) +Collection of help texts = Sammlung von Hilfstexten diff --git a/mods/HELP/doc/doc/locale/template.txt b/mods/HELP/doc/doc/locale/template.txt new file mode 100644 index 000000000..7d852e9a4 --- /dev/null +++ b/mods/HELP/doc/doc/locale/template.txt @@ -0,0 +1,42 @@ +< = +> = +Access to the requested entry has been denied; this entry is secret. You may unlock access by progressing in the game. Figure out on your own how to unlock this entry. = +All entries read. = +All help entries revealed! = +All help entries are already revealed. = +Allows you to reveal all hidden help entries with /help_reveal = +Category list = +Currently all entries in this category are hidden from you.\\nUnlock new entries by progressing in the game. = +Help = +Entry = +Entry list = +Error: Access denied. = +Error: No help available. = +Go to category list = +Go to entry list = +Help > @1 = +Help > @1 > @2 = +Help > @1 > (No Entry) = +Help > (No Category) = +Hidden entries: @1 = +Nameless entry (@1) = +New entries: @1 = +New help entry unlocked: @1 > @2 = +No categories have been registered, but they are required to provide help.\nThe Documentation System [doc] does not come with help contents on its own, it needs additional mods to add help content. Please make sure such mods are enabled on for this world, and try again. = +Number of entries: @1 = +OK = +Open a window providing help entries about Minetest and more = +Please select a category you wish to learn more about: = +Recommended mods: doc_basics, doc_items, doc_identifier, doc_encyclopedia. = +Reveal all hidden help entries to you = +Show entry = +Show category = +Show next entry = +Show previous entry = +This category does not have any entries. = +This category has the following entries: = +This category is empty. = +This is the help. = +You haven't chosen a category yet. Please choose one in the category list first. = +You haven't chosen an entry yet. Please choose one in the entry list first. = +Collection of help texts = diff --git a/mods/HELP/doc/doc/mod.conf b/mods/HELP/doc/doc/mod.conf new file mode 100644 index 000000000..5e2f43080 --- /dev/null +++ b/mods/HELP/doc/doc/mod.conf @@ -0,0 +1 @@ +name = doc diff --git a/mods/HELP/doc/doc/screenshot.png b/mods/HELP/doc/doc/screenshot.png new file mode 100644 index 000000000..90946a999 Binary files /dev/null and b/mods/HELP/doc/doc/screenshot.png differ diff --git a/mods/HELP/doc/doc/sounds/doc_reveal.ogg b/mods/HELP/doc/doc/sounds/doc_reveal.ogg new file mode 100644 index 000000000..3fbe176b6 Binary files /dev/null and b/mods/HELP/doc/doc/sounds/doc_reveal.ogg differ diff --git a/mods/HELP/doc/doc/textures/doc_awards_icon_generic.png b/mods/HELP/doc/doc/textures/doc_awards_icon_generic.png new file mode 100644 index 000000000..b33fa34ad Binary files /dev/null and b/mods/HELP/doc/doc/textures/doc_awards_icon_generic.png differ diff --git a/mods/HELP/doc/doc/textures/doc_button_icon_hires.png b/mods/HELP/doc/doc/textures/doc_button_icon_hires.png new file mode 100644 index 000000000..25c9fe4e9 Binary files /dev/null and b/mods/HELP/doc/doc/textures/doc_button_icon_hires.png differ diff --git a/mods/HELP/doc/doc/textures/doc_button_icon_lores.png b/mods/HELP/doc/doc/textures/doc_button_icon_lores.png new file mode 100644 index 000000000..3df6195c7 Binary files /dev/null and b/mods/HELP/doc/doc/textures/doc_button_icon_lores.png differ diff --git a/mods/HELP/doc/doc/textures/inventory_plus_doc_inventory_plus.png b/mods/HELP/doc/doc/textures/inventory_plus_doc_inventory_plus.png new file mode 100644 index 000000000..3df6195c7 Binary files /dev/null and b/mods/HELP/doc/doc/textures/inventory_plus_doc_inventory_plus.png differ diff --git a/mods/HELP/doc/doc_identifier/API.md b/mods/HELP/doc/doc_identifier/API.md new file mode 100644 index 000000000..fb7f88c3d --- /dev/null +++ b/mods/HELP/doc/doc_identifier/API.md @@ -0,0 +1,40 @@ +# Minimal API for `doc_identifier` +## Introduction +The tool can identify blocks and players natively, and also handles falling +nodes (`__builtin:falling_node`) and dropped items (`__builtin:item`) on its +own. + +However, the identifier can't “identify” (=open the appropriate entry) custom +objects because the mod doesn't know which help entry to open (if there is +any). One example would be the boat object (`boats:boat`) from the boats mod +in Minetest Game. +If the player tries to use the tool on an unknown object, an error message is +shown. + +Because of this, this mod provides a minimal API for mods to assign a help +entry to an object type: `doc_identifier.register_object`. + +## `doc.sub.identifier.register_object(object_name, category_id, entry_id)` +Registers the object/entity with the internal name `object_name` to the +entry `entry_id` in the category `category_id`. +It is in the modder's responsibility to make sure that both the category and +entry already exist (use `doc.entry_exists` or depend (optionally or not) on +the respective mods) at the time of the function call, otherwise, stability can +not be guaranteed. + +Returns `nil`. + +### Example +From `doc_minetest_game`: + + if minetest.get_modpath("doc_identifier") ~= nil then + doc.sub.identifier.register_object("boats:boat", "craftitems", "boats:boat") + end + +This enables the tool to be used on the boat object itself. The conditional is +an idiom to check for the existence of this mod. + +## Note on dependencies +If you just need `doc.sub.identifier.register_object` using only an **optional** +dependency for your mod is probably enough. + diff --git a/mods/HELP/doc/doc_identifier/README.md b/mods/HELP/doc/doc_identifier/README.md new file mode 100644 index 000000000..7620be7c5 --- /dev/null +++ b/mods/HELP/doc/doc_identifier/README.md @@ -0,0 +1,29 @@ +# Lookup Tool [`doc_identifier`] +Version: 1.2.1 + +## Description +The lookup tool is an useful little helper which can be used to quickly learn +more about about one's closer environment. It identifies blocks, dropped items +and other objects and it shows extensive information about the item on which it +is used, provided documentation is available. + +## How to use the lookup tool +Punch any block or item about you wish to learn more about. This will open up +the help entry of this particular item. +The tool comes in two modes which are changed by a right-click. In liquid mode +(blue) this tool points to liquids as well while in solid mode (red) this is not +the case. Liquid mode is required if you want to identify a liquid. + +## For modders +If you want the tool to identify nodes and (dropped) items, you probably don't +have to do anything, it is probably already supported. The only thing you have +to make sure is that all pointable blocks and items have a help entry, which +is already the case for most items, but you may want to do some testing on +“tricky” items. Consult the documentation of Documentation System [`doc`] +and Item Help [`doc_items`] for getting the item documentation right. + +For the lookup tool to be able to work on custom objects/entities, you have to +use the tiny API of this mod, see `API.md`. + +## License +Everything in this mod is licensed under the MIT License. diff --git a/mods/HELP/doc/doc_identifier/depends.txt b/mods/HELP/doc/doc_identifier/depends.txt new file mode 100644 index 000000000..b5ad06b06 --- /dev/null +++ b/mods/HELP/doc/doc_identifier/depends.txt @@ -0,0 +1,5 @@ +doc +doc_items +doc_basics? +default? +intllib? diff --git a/mods/HELP/doc/doc_identifier/description.txt b/mods/HELP/doc/doc_identifier/description.txt new file mode 100644 index 000000000..8294c740f --- /dev/null +++ b/mods/HELP/doc/doc_identifier/description.txt @@ -0,0 +1 @@ +Adds a tool which shows help entries about almost anything which it punches. diff --git a/mods/HELP/doc/doc_identifier/init.lua b/mods/HELP/doc/doc_identifier/init.lua new file mode 100644 index 000000000..5824d47a2 --- /dev/null +++ b/mods/HELP/doc/doc_identifier/init.lua @@ -0,0 +1,190 @@ +-- Boilerplate to support localized strings if intllib mod is installed. +local S +if minetest.get_modpath("intllib") then + S = intllib.Getter() +else + S = function(s) return s end +end + +local doc_identifier = {} + +doc_identifier.registered_objects = {} + +-- API +doc.sub.identifier = {} +doc.sub.identifier.register_object = function(object_name, category_id, entry_id) + doc_identifier.registered_objects[object_name] = { category = category_id, entry = entry_id } +end + +-- END OF API + +doc_identifier.identify = function(itemstack, user, pointed_thing) + local username = user:get_player_name() + local show_message = function(username, itype, param) + local vsize = 2 + local message + if itype == "error_item" then + message = S("No help entry for this item could be found.") + elseif itype == "error_node" then + message = S("No help entry for this block could be found.") + elseif itype == "error_unknown" then + vsize = vsize + 3 + local mod + if param ~= nil then + local colon = string.find(param, ":") + if colon ~= nil and colon > 1 then + mod = string.sub(param,1,colon-1) + end + end + message = S("Error: This node, item or object is undefined. This is always an error.\nThis can happen for the following reasons:\n• The mod which is required for it is not enabled\n• The author of the subgame or a mod has made a mistake") + message = message .. "\n\n" + + if mod ~= nil then + if minetest.get_modpath(mod) ~= nil then + message = message .. string.format(S("It appears to originate from the mod “%s”, which is enabled."), mod) + message = message .. "\n" + else + message = message .. string.format(S("It appears to originate from the mod “%s”, which is not enabled!"), mod) + message = message .. "\n" + end + end + if param ~= nil then + message = message .. string.format(S("Its identifier is “%s”."), param) + end + elseif itype == "error_ignore" then + message = S("This block cannot be identified because the world has not materialized at this point yet. Try again in a few seconds.") + elseif itype == "error_object" or itype == "error_unknown_thing" then + message = S("No help entry for this object could be found.") + elseif itype == "player" then + message = S("This is a player.") + end + minetest.show_formspec( + username, + "doc_identifier:error_missing_item_info", + "size[12,"..vsize..";]" .. + "label[0,0.2;"..minetest.formspec_escape(message).."]" .. + "button_exit[4.5,"..(-0.5+vsize)..";3,1;okay;"..minetest.formspec_escape(S("OK")).."]" + ) + end + if pointed_thing.type == "node" then + local pos = pointed_thing.under + local node = minetest.get_node(pos) + if minetest.registered_nodes[node.name] ~= nil then + local nodedef = minetest.registered_nodes[node.name] + if(node.name == "ignore") then + show_message(username, "error_ignore") + elseif doc.entry_exists("nodes", node.name) then + doc.show_entry(username, "nodes", node.name, true) + else + show_message(username, "error_node") + end + else + show_message(username, "error_unknown", node.name) + end + elseif pointed_thing.type == "object" then + local object = pointed_thing.ref + local le = object:get_luaentity() + if object:is_player() then + if minetest.get_modpath("doc_basics") ~= nil and doc.entry_exists("basics", "players") then + doc.show_entry(username, "basics", "players", true) + else + -- Fallback message + show_message(username, "player") + end + -- luaentity exists + elseif le ~= nil then + local ro = doc_identifier.registered_objects[le.name] + -- Dropped items + if le.name == "__builtin:item" then + local itemstring = ItemStack(minetest.deserialize(le:get_staticdata()).itemstring):get_name() + if doc.entry_exists("nodes", itemstring) then + doc.show_entry(username, "nodes", itemstring, true) + elseif doc.entry_exists("tools", itemstring) then + doc.show_entry(username, "tools", itemstring, true) + elseif doc.entry_exists("craftitems", itemstring) then + doc.show_entry(username, "craftitems", itemstring, true) + elseif minetest.registered_items[itemstring] == nil or itemstring == "unknown" then + show_message(username, "error_unknown", itemstring) + else + show_message(username, "error_item") + end + -- Falling nodes + elseif le.name == "__builtin:falling_node" then + local itemstring = minetest.deserialize(le:get_staticdata()).name + if doc.entry_exists("nodes", itemstring) then + doc.show_entry(username, "nodes", itemstring, true) + end + -- A known registered object + elseif ro ~= nil then + doc.show_entry(username, ro.category, ro.entry, true) + -- Undefined object (error) + elseif minetest.registered_entities[le.name] == nil then + show_message(username, "error_unknown", le.name) + -- Other object (undocumented) + else + show_message(username, "error_object") + end + else + --show_message(username, "error_object") + show_message(username, "error_unknown") + end + elseif pointed_thing.type ~= "nothing" then + show_message(username, "error_unknown_thing") + end + return itemstack +end + +function doc_identifier.solid_mode(itemstack, user, pointed_thing) + return ItemStack("doc_identifier:identifier_solid") +end + +function doc_identifier.liquid_mode(itemstack, user, pointed_thing) + return ItemStack("doc_identifier:identifier_liquid") +end + +minetest.register_tool("doc_identifier:identifier_solid", { + description = S("Lookup tool"), + _doc_items_longdesc = S("This useful little helper can be used to quickly learn more about about one's closer environment. It identifies and analyzes blocks, items and other things and it shows extensive information about the thing on which it is used."), + _doc_items_usagehelp = S("Punch any block, item or other thing about you wish to learn more about. This will open up the appropriate help entry. The tool comes in two modes which are changed by a rightclick. In liquid mode (blue) this tool points to liquids as well while in solid mode (red) this is not the case. Liquid mode is required if you want to identify a liquid."), + _doc_items_hidden = false, + tool_capabilities = {}, + range = 10, + wield_image = "doc_identifier_identifier.png", + inventory_image = "doc_identifier_identifier.png", + liquids_pointable = false, + on_use = doc_identifier.identify, + on_place = doc_identifier.liquid_mode, + on_secondary_use = doc_identifier.liquid_mode, +}) +minetest.register_tool("doc_identifier:identifier_liquid", { + description = S("Lookup tool"), + _doc_items_create_entry = false, + tool_capabilities = {}, + range = 10, + groups = { not_in_creative_inventory = 1, not_in_craft_guide = 1 }, + wield_image = "doc_identifier_identifier_liquid.png", + inventory_image = "doc_identifier_identifier_liquid.png", + liquids_pointable = true, + on_use = doc_identifier.identify, + on_place = doc_identifier.solid_mode, + on_secondary_use = doc_identifier.solid_mode, +}) + +minetest.register_craft({ + output = "doc_identifier:identifier_solid", + recipe = { {"group:stick", "group:stick" }, + {"", "group:stick"}, + {"group:stick", ""} } +}) + +if minetest.get_modpath("default") ~= nil then + minetest.register_craft({ + output = "doc_identifier:identifier_solid", + recipe = { { "default:glass" }, + { "group:stick" } } + }) +end + +minetest.register_alias("doc_identifier:identifier", "doc_identifier:identifier_solid") + +doc.add_entry_alias("tools", "doc_identifier:identifier_solid", "tools", "doc_identifier:identifier_liquid") diff --git a/mods/HELP/doc/doc_identifier/locale/de.txt b/mods/HELP/doc/doc_identifier/locale/de.txt new file mode 100644 index 000000000..996c369f3 --- /dev/null +++ b/mods/HELP/doc/doc_identifier/locale/de.txt @@ -0,0 +1,13 @@ +Error: This node, item or object is undefined. This is always an error.\nThis can happen for the following reasons:\n• The mod which is required for it is not enabled\n• The author of the subgame or a mod has made a mistake = Fehler: Dieser Node, Gegenstand oder dieses Objekt ist nicht definiert.\nDas ist immer ein Fehler.\nDies kann aus folgenden Gründen passieren:\n• Die Mod, die dafür benötigt wird, ist nicht aktiv\n• Der Subgame-Autor oder ein Mod-Autor machte einen Fehler +It appears to originate from the mod “%s”, which is enabled. = Es scheint von der Mod »%s« zu stammen. Sie ist aktiv. +It appears to originate from the mod “%s”, which is not enabled! = Es scheint von der Mod »%s« zu stammen. Sie ist nicht aktiv! +Its identifier is “%s”. = Der Identifkator ist »%s«. +Lookup tool = Nachschlagewerkzeug +No help entry for this block could be found. = Für diesen Block konnte kein Hilfseintrag gefunden werden. +No help entry for this item could be found. = Für diesen Gegenstand konnte kein Hilfseintrag gefunden werden. +No help entry for this object could be found. = Für dieses Objekt konnte kein Hilfseintrag gefunden werden. +OK = OK +Punch any block, item or other thing about you wish to learn more about. This will open up the appropriate help entry. The tool comes in two modes which are changed by a rightclick. In liquid mode (blue) this tool points to liquids as well while in solid mode (red) this is not the case. Liquid mode is required if you want to identify a liquid. = Schlagen Sie einen beliebigen Block, Gegenstand oder irgendwas, worüber Sie mehr erfahren wollen. Das wird den passenden Hilfseintrag öffnen. Das Werkzeug hat zwei Modi, welcher mit einem Rechtsklick gewechselt werden kann. Im Flüssigmodus (blau) zeigt das Werkzeug auch auf Flüssigkeiten. Im Festmodus (rot) ist das nicht der Fall. Der Flüssigmodis ist notwendig, wenn Sie eine Flüssigkeit identifizieren wollen. +This block cannot be identified because the world has not materialized at this point yet. Try again in a few seconds. = Dieser Block kann nicht identifiziert werden, weil sich die Welt an dieser Stelle noch nicht materialisiert hat. Versuch es in ein paar Sekunden erneut. +This is a player. = Dies ist ein Spieler. +This useful little helper can be used to quickly learn more about about one's closer environment. It identifies and analyzes blocks, items and other things and it shows extensive information about the thing on which it is used. = Dieser nützliche kleine Helfer kann benutzt werden, um schnell etwas über die nähere Umgebung zu erfahren. Er identifiziert und analysiert Blöcke, Gegenstände und andere Dinge und zeigt ausführliche Informationen über all das, worauf man ihn anwendet. diff --git a/mods/HELP/doc/doc_identifier/locale/template.txt b/mods/HELP/doc/doc_identifier/locale/template.txt new file mode 100644 index 000000000..b0ede6162 --- /dev/null +++ b/mods/HELP/doc/doc_identifier/locale/template.txt @@ -0,0 +1,13 @@ +Error: This node, item or object is undefined. This is always an error.\\nThis can happen for the following reasons:\\n• The mod which is required for it is not enabled\\n• The author of the subgame or a mod has made a mistake = +It appears to originate from the mod “%s”, which is enabled. = +It appears to originate from the mod “%s”, which is not enabled! = +Its identifier is “%s”. = +Lookup tool = +No help entry for this block could be found. = +No help entry for this item could be found. = +No help entry for this object could be found. = +OK = +Punch any block, item or other thing about you wish to learn more about. This will open up the appropriate help entry. The tool comes in two modes which are changed by a rightclick. In liquid mode (blue) this tool points to liquids as well while in solid mode (red) this is not the case. Liquid mode is required if you want to identify a liquid. = +This block cannot be identified because the world has not materialized at this point yet. Try again in a few seconds. = +This is a player. = +This useful little helper can be used to quickly learn more about about one's closer environment. It identifies and analyzes blocks, items and other things and it shows extensive information about the thing on which it is used. = diff --git a/mods/HELP/doc/doc_identifier/mod.conf b/mods/HELP/doc/doc_identifier/mod.conf new file mode 100644 index 000000000..df963a0cf --- /dev/null +++ b/mods/HELP/doc/doc_identifier/mod.conf @@ -0,0 +1 @@ +name = doc_identifier diff --git a/mods/HELP/doc/doc_identifier/screenshot.png b/mods/HELP/doc/doc_identifier/screenshot.png new file mode 100644 index 000000000..13b2540df Binary files /dev/null and b/mods/HELP/doc/doc_identifier/screenshot.png differ diff --git a/mods/HELP/doc/doc_identifier/textures/doc_identifier_identifier.png b/mods/HELP/doc/doc_identifier/textures/doc_identifier_identifier.png new file mode 100644 index 000000000..00b3147a0 Binary files /dev/null and b/mods/HELP/doc/doc_identifier/textures/doc_identifier_identifier.png differ diff --git a/mods/HELP/doc/doc_identifier/textures/doc_identifier_identifier_liquid.png b/mods/HELP/doc/doc_identifier/textures/doc_identifier_identifier_liquid.png new file mode 100644 index 000000000..9f3aef969 Binary files /dev/null and b/mods/HELP/doc/doc_identifier/textures/doc_identifier_identifier_liquid.png differ diff --git a/mods/HELP/doc/doc_items/API.md b/mods/HELP/doc/doc_items/API.md new file mode 100644 index 000000000..a683771c7 --- /dev/null +++ b/mods/HELP/doc/doc_items/API.md @@ -0,0 +1,357 @@ +# API documentation for `doc_items` +## Introduction +This document explains the API of `doc_items`. It contains a reference of +all functions. + +## Quick start +The most common use case for using this API requires only to set some +hand-written help texts for your items. + +The preferred way is to add the following optional fields to the +item definition when using `minetest.register_node`, etc.: + +* `_doc_items_longdesc`: Long description of this item. + Describe here what this item is, what it is for, its purpose, etc. +* `_doc_items_usagehelp`: Description of *how* this item can be used. + Only set this if needed, e.g. standard mining tools don't need this. + +Example: + + minetest.register_node("example:dice", { + description = "Dice", + _doc_items_longdesc = "A decorative dice which shows the numbers 1-6 on its sides.", + _doc_items_usagehelp = "Right-click the dice to roll it.", + tiles = { "example_dice.png" }, + is_ground_content = false, + --[[ and so on … ]] + }) + +When using this method, your mod does not need additional dependencies. + +See below for some recommendations on writing good help texts. + +If you need more customization, read ahead. ;-) + +## New item fields +This mod adds support for new fields of the item definition. They allow for +easy and quick manipulation of the item help entries. All fields are optional. + +* `_doc_items_longdesc`: Long description +* `_doc_items_usagehelp`: Usage help +* `_doc_items_image`: Entry image (default: inventory image) +* `_doc_items_hidden`: Whether entry is hidden (default: `false` for air and hand, `true` for everything else) +* `_doc_items_create_entry`: Whether to create an entry for this item (default: `true`) +* `_doc_items_entry_name`: The title of the entry. By default, this is the same as the `description` field + of the item. This field is required if the `description` is empty +* `_doc_items_durability`: This field is for describing how long a tool can be used before it breaks. Choose one data type: + * It it is a `number`: Fixed number of uses before it breaks + * If it is a `string`: Free-form text which explains how the durability works. Try to keep it short and only use it if the other types won't work + +A full explanation of these fields is provided below. + +## Concepts +This section explains the core concepts of an item help entry in-depth. + +### Factoids +Basically, a factoid is usually a single sentence telling the player a specific +fact about the item. The task of each factoid is to basically convert parts +of the item definition to useful, readable, understandable text. + +Example: It's a fact that `default:sand` has the group `falling_node=1`. +A factoid for this is basically just a simple conditional which puts the +the sentence “This block is affected to gravity and can fall.” into the +text if the node is member of said group. + +Factoids can be more complex than that. The factoid for node drops needs to +account for different drop types and probabilities, etc. + +`doc_items` has many predefined factoids already. This includes all “special” +groups (like `falling_node`), drops, mining capabilities, punch interval, +and much more. + +Custom factoids can be added with `doc.sub.items.register_factoid`. + +The idea behind factoids is to generate as much information as possible +automatically to reduce redundancy, inconsistencies and the workload of hand- +written descriptions. + +### Long description and usage help +Factoids are not always sufficient to describe an item. This is the case +for facts where the item definition can not be used to automatically +generate texts. Examples: Custom formspecs, ABMs, special tool action +on right-click. + +That's where the long description and usage help comes into play. +Those are two texts which are written manually for a specific item. + +Roughly, the long description is for describing **what** the item is, how it +acts, what it is for. The usage help is for explaining **how** the +item can be used. It is less important for standard mining tools and weapons. + +There is no hard length limit for the long description and the usage help. + +#### Recommendations for long description +The long description should roughly contain the following info: + +* What the item does +* What it is good for +* How it may be generated in the world +* Maybe some background info if you're in a funny mood +* Notable information which doesn't fit elsewhere + +The description should normally **not** contain: + +* Information which is already covered by factoids, like digging groups, + damage, group memberships, etc. +* How the item can be used +* Direct information about other items +* Any other redundant information +* Crafting recipes + +One exception from the rule may be for highlighting the most important +purpose of a simple item, like that coal lumps are primarily used as fuel. + +Sometimes, a long description is not necessary because the item is already +exhaustively explained by factoids. + +For very simple items, consider using one of the template texts (see below). + +Minimal style guide: Use complete sentences. + +#### Recommendations for usage help +The usage help should only be set for items which are in some way special +in their usage. Standard tools and weapons should never have an usage help. + +The rule of thumb is this: If a new player who already knows the Minetest +basics, but not this item, will not directly know how to use this item, +then the usage help should be added. If basic Minetest knowledge or +existing factoids are completely sufficient, usage help should not be added. + +The recommendations for what not to put into the usage help is the same +as for long descriptions. + +#### Template texts +For your convenience, a few template texts are provided for common texts +to avoid redundancy and to increase consistency for simple things. Read +`init.lua` to see the actual texts. + +##### Long description +* `doc.sub.items.temp.build`: For building blocks like the brick block in Minetest Game +* `doc.sub.items.temp.deco`: For other decorational blocks. +* `doc.sub.items.temp.craftitem`: For items solely or almost solely used for crafting + +##### Usage help +* `doc.sub.items.temp.eat`: For eatable items using the `on_use=minetest.item_eat(1)` idiom +* `doc.sub.items.temp.eat_bad`: Same as above, but eating them is considered a bad idea +* `doc.sub.items.temp.rotate_node`: For nodes with `on_place=minetest.rotate_node`, + explains placement and rotation + +### Entry creation +By default, an entry for each item is added automatically, except for items +without a description (`description == nil`). This behaviour can be changed +on a per-item basis. + +By setting the item definition's field `_doc_items_create_entry` to `true` +or `false`you can explicitly define whether this item should get its own +entry. + +Suppressing an entry is useful for items which aren't supposed to be directly +seen or obtained by the player or if they are only used for technical +and/or internal purposes. Another possible reason to suppress an entry is +to scrub the entry list of lots of very similar related items where the +difference is too small to justify two separate entries (e.g. +burning furnace vs inactive furnace, because the gameplay mechanics are +identical for both). + +### Hidden entries +Hidden entries are entries which are not visible in the list of entries. This +concept directly comes from the Documentation System. The entry will still be +created, it is just not selectable by normal means. Players might be able to +“unlock” an entry later. Refer to the API documentation of the Documentation +System to learn more. + +By default, all entries are hidden except air and the hand. + +To mark an entry as hidden, add the field `_doc_items_hidden=true` to its +item definition. To make sure an entry is never hidden, add +`_doc_items_hidden=false` instead (this rarely needs to be specified +explicitly). + +### Hand and air +The mod adds some default help texts for the hand and the air which are +written in a way that they probably are true for most subgames out of the +box, but especially the hand help text is kept intentionally vague. +If you want to change these help texts or the entry names or other +attributes, just add `_doc_items_*` fields to the item definition, either +by re-defining or overwriting these items (e.g. with +`minetest.override_item`). + +In the mod `doc_minetest_game`, the default hand help text is overwritten +to explain the hand in more detail, especially the hand behaviour in +Creative Mode. + +## Functions +This is the reference of all available functions in this API. + +### `doc.sub.items.register_factoid(category_id, factoid_type, factoid_generator)` +Add a custom factoid (see above) for the specified category. + +* `category_id`: The help category for which the factoid applies: + * `"nodes"`: Blocks + * `"tools"`: Tools and weapons + * `"craftitems"`: Misc. items + * `nil`: All of the above +* `factoid_type`: Rough categorization of the factoid's content, used to + optimize the final text display. This currently determines where in the + entry text the factoid appears. Possible values: + * For all items: + * `"use"`: It's about using the item in some way (written right after the fixed usage help) + * `"groups"`: Group-related factoid (very vague) + * `"misc"`: Factoid doesn't fit anywhere else, is shown near the end + * For nodes only: + * `damage`: Related to player/mob damage or health + * `movement`: Related to player movement on, in or at node + * `sound`: Related to node sounds + * `gravity`: Related to gravity (e.g. falling node) + * `drop_destroy`: Related to node being destroyed or node dropping as an item + * `light`: Related to node light (luminance) + * `mining`: Related to mining + * `drops`: Related to node drops +* `factoid_generator`: A function which turns item definition into a string + (see blow) + +#### `factoid_generator(itemstring, def)` +`itemstring` is the itemstring of the item to be documented, and `def` is the +complete item definition table (from Minetest). + +This function must return a helpful string which turns a part of the item's +definition into an useful sentence or text. The text can contain newlines, +but it must not end with a newline. + +This function must **always** return a string. If you don't want to add any text, +return the empty string. + +Style guide: Try to use complete sentences and avoid too many newlines. + +#### Example +This factoid will add the sentence “This block will extinguish nearby fire.” +to all blocks which are member of the group `puts_out_fire`. + + doc.sub.items.register_factoid("nodes", "groups", function(itemstring, def) + if def.groups.puts_out_fire ~= nil then + return "This block will extinguish nearby fire." + else + return "" + end + end) + + +### `doc.sub.items.disable_core_factoid(factoid_name)` +This function removes a core (built-in) factoid entirely, its text will never be displayed in any +entry then. + +#### Parameter +`factoid_name` chooses the factoid you want to disable. The following core factoids can be disabled: + +* `"node_mining"`: Mining properties of nodes +* `"tool_capabilities"`: Tool capabilities such as digging times +* `"groups"`: Group memberships +* `"fuel"`: How long the item burns as a fuel and if there's a leftover +* `"itemstring"`: The itemstring +* `"drops"`: Node drops +* `"connects_to"`: Tells to which nodes the node connects to +* `"light"`: Light and transparency information for nodes +* `"drop_destroy"`: Information about when the node causes to create its “drop” and if it gets destroyed by flooding +* `"gravity"`: Factoid for `falling_node` group +* `"sounds"`: Infos about sound effects related to the item +* `"node_damage"`: Direct damage and drowning damage caused by nodes +* `"node_movement"`: Nodes affecting player movement +* `"liquid"`: Liquid-related infos of a node +* `"basics"`: Collection of many basic factoids: The custom help texts, pointability, collidability, range, stack size, `liquids_pointable`, “punches don't work as usual”. Be careful with this one! + +#### Background +Normally, the core factoids are written in a very general-purpose style, so this function might +not be needed at all. But it might be useful for subgames and mods which radically break with +some of the underlying core assumptions in Minetest. For example, if your mod completely changes +the digging system, the help texts provided by `doc_items` are probably incorrect, so you can +disable `node_mining` and register a custom factoid as a replacement. + +Please do not use this function lightly because it touches the very core of `doc_items`. Try to +understand a core factoid before you consider to disable it. If you think a core factoid is just +broken or buggy in general, please file a bug instead. + + +### `doc.sub.items.add_friendly_group_names(groupnames)` +Use this function so set some more readable group names to show them +in the formspec, since the internal group names are somewhat cryptic +to players. + +`groupnames` is a table where the keys are the “internal” group names and +the values are the group names which will be actually shown in the +Documentation System. + +***Note***: This function is mostly there to work around a problem in +Minetest as it does not support “friendly” group names, which means exposing +groups to an interface is not pretty. Therefore, this function may be +deprecated when Minetest supports such a thing. + +### `doc.sub.items.get_group_name(internal_group_name)` +Returns the group name of the specified group as displayed by this mod. +If the setting `doc_items_friendly_group_names` is `true`, this might +return a “friendly” group name (see above). If no friendly group name +exists, `internal_group_name` is returned. +If `doc_items_friendly_group_names` is `false`, the argument is always +returned. + +### `doc.sub.items.add_notable_groups(groupnames)` +Add a list of groups you think are notable enough to be mentioned in the +“This item belongs to the following groups: (…)” factoid. This factoid +is intended to give a quick rundown of misc. groups which don't fit +to other factoids, yet they are still somewhat relevant to gameplay. + +`groupnames` is a table of group names you wish to add. + +#### What groups should be added +What is “notable” is subjective, but there are some guidelines: + +Do add a group if: + +* It is used in an ABM +* It is used for a custom interaction with another item +* It is simple enough for the player to know an item is member of this group +* You want to refer to this group in help texts +* The “don'ts” below don't apply + +Do not add a group if: + +* It is *only* used for crafting, `connects_to`, mining times or damage groups +* A factoid covering this group already exists +* The group membership itself requires an explanation (consider writing a factoid instead) +* The group has no gameplay relevance +* Group rating is important to gameplay (consider writing a factoid instead) + +Groups which are used for crafting or in the `connects_to` field of item +definitions are already automatically added to this factoid. + +##### Examples for good additions + +* A group where its members can be placed in bookshelves. + so this group meets the “custom interaction” criterion +* `water` in Minetest Game: Used for water nodes in the obsidian ABM +* `sand` in Minetest Game: Used for the cactus growth ABM, but also crafting. + Since it is not *only* used for crafting, it is OK to be added + +##### Examples for bad additions + +* `stick` in Minetest Game: This group appears in many crafting recipes and + has no other use. It is already added automatically +* A group in which members turn into obsidian when they touch water (ABM): + This group is not trivial and should be introduced in a factoid instead +* `cracky` in Min +* `dig_immediate`: This group is already covered by the default factoids of this + mod + +## Dependencies +If you only add the custom fields to your items, you do *not* need to depend +on this mod. If you use anything else from this mod (e.g. a function), you +probably *do* need to depend (optionally or mandatorily) on this mod. diff --git a/mods/HELP/doc/doc_items/README.md b/mods/HELP/doc/doc_items/README.md new file mode 100644 index 000000000..d18a62ea9 --- /dev/null +++ b/mods/HELP/doc/doc_items/README.md @@ -0,0 +1,68 @@ +# Item Help [`doc_items`] (Version 1.1.0) +## Description +Automatically generated help texts of blocks, tools, weapons, crafting +items and other items. + +The goal is to tell the player as much about basically almost all items as +possible, making it very convenient to look up simple things. + +The ultimate goal of this mod is that eventually all relevant items have +a complete in-game documentation so no item leaves you confused. + +This mod is useful to learn the hard facts about practically all items, like +how much damage weapon XYZ deals or whether you can dig that block. +This mod does *not* give you long explanations about how to use certain +nontrivial things, like the furnace from Minetest Game. This info might be +provided by other mods and insert it into the help. + +This mod provides 3 new help categories (using the +Documentation System [`doc`]): + +* Blocks (e.g. dirt, stone, wooden stair) +* Tools and weapons (e.g. wooden pickaxe, steel sword, screwdriver) +* Misc. items (e.g. dye, stick, flour) + +Entries are automatically added. The information in the entries is +mostly automatically generated. It contains information about a wide range +of topics: + +* Blocks + * Physics + * Digging properties + * Drops (including probabilities) + * Liquid information + * Pointability + * Luminance + * Much more +* Tools and weapons + * Mining capabilities + * Damage + * Durability + * More +* All items + * Range + * Stack size + * Group memberships + * Other information added by mods + +This mod also allows for mods to adding custom written description +and usage help texts in free-form and even custom automatically generated texts +for mod-specific information like flammability in Minetest Game. This is +one of the core features of this mod; the mod relies on other mods to +provide their custom help texts for a complete help. + +If you find a particular item which is lacking an explanation on usage, +request the mod author to add `doc_items` support. + +## API +This mod has an API so that modders can add their own custom help texts, +custom factoids (single pieces of information extracted from the +item definition) and more. + +For example, if your mods have some complex items which need +explanation, this mod can help you in adding help texts for them. + +Read `API.md` to learn more. + +## License +Everything in this mod is licensed under the MIT License. diff --git a/mods/HELP/doc/doc_items/depends.txt b/mods/HELP/doc/doc_items/depends.txt new file mode 100644 index 000000000..31aa39034 --- /dev/null +++ b/mods/HELP/doc/doc_items/depends.txt @@ -0,0 +1,2 @@ +doc +intllib? diff --git a/mods/HELP/doc/doc_items/description.txt b/mods/HELP/doc/doc_items/description.txt new file mode 100644 index 000000000..7291077e6 --- /dev/null +++ b/mods/HELP/doc/doc_items/description.txt @@ -0,0 +1 @@ +Adds automatically generated help texts for items. diff --git a/mods/HELP/doc/doc_items/init.lua b/mods/HELP/doc/doc_items/init.lua new file mode 100644 index 000000000..1776fdf9f --- /dev/null +++ b/mods/HELP/doc/doc_items/init.lua @@ -0,0 +1,1406 @@ +-- Boilerplate to support localized strings if intllib mod is installed. +local S +if minetest.get_modpath("intllib") then + S = intllib.Getter() +else + S = function(s,a,...)a={a,...}return s:gsub("@(%d+)",function(n)return a[tonumber(n)]end)end +end + +doc.sub.items = {} + +-- Template texts +doc.sub.items.temp = {} +doc.sub.items.temp.deco = S("This is a decorational block.") +doc.sub.items.temp.build = S("This block is a building block for creating various buildings.") +doc.sub.items.temp.craftitem = S("This item is primarily used for crafting other items.") + +doc.sub.items.temp.eat = S("Hold it in your hand, then leftclick to eat it.") +doc.sub.items.temp.eat_bad = S("Hold it in your hand, then leftclick to eat it. But why would you want to do this?") +doc.sub.items.temp.rotate_node = S("This block's rotation is affected by the way you place it: Place it on the floor or ceiling for a vertical orientation; place it at the side for a horizontal orientation. Sneaking while placing it leads to a perpendicular orientation instead.") + +doc.sub.items.settings = {} +doc.sub.items.settings.friendly_group_names = false +local setting = minetest.setting_getbool("doc_items_friendly_group_names") +if setting ~= nil then + doc.sub.items.settings.friendly_group_names = setting +end +doc.sub.items.settings.itemstring = false +setting = minetest.setting_getbool("doc_items_show_itemstrings") +if setting ~= nil then + doc.sub.items.settings.itemstring = setting +end + +-- Local stuff +local groupdefs = {} +local mininggroups = {} +local miscgroups = {} +local item_name_overrides = { + [""] = S("Hand"), + ["air"] = S("Air") +} +local suppressed = { + ["ignore"] = true, +} + +-- This table contains which of the builtin factoids must NOT be displayed because +-- they have been disabled by a mod +local forbidden_core_factoids = {} + +-- Helper functions +local yesno = function(bool) + if bool==true then return S("Yes") + elseif bool==false then return S("No") + else return "N/A" end +end + +local groups_to_string = function(grouptable, filter) + local gstring = "" + local groups_count = 0 + for id, value in pairs(grouptable) do + if (filter == nil or filter[id] == true) then + -- Readable group name + if groups_count > 0 then + -- List seperator + gstring = gstring .. S(", ") + end + if groupdefs[id] ~= nil and doc.sub.items.settings.friendly_group_names == true then + gstring = gstring .. groupdefs[id] + else + gstring = gstring .. id + end + groups_count = groups_count + 1 + end + end + if groups_count == 0 then + return nil, 0 + else + return gstring, groups_count + end +end + +-- Replaces all newlines with spaces +local scrub_newlines = function(text) + local new, x = string.gsub(text, "\n", " ") + return new +end + +--[[ Append a newline to text, unless it already ends with a newline. ]] +local newline = function(text) + if string.sub(text, #text, #text) == "\n" or text == "" then + return text + else + return text .. "\n" + end +end + +--[[ Make sure the text ends with two newlines by appending any missing newlines at the end, if neccessary. ]] +local newline2 = function(text) + if string.sub(text, #text-1, #text) == "\n\n" or text == "" then + return text + elseif string.sub(text, #text, #text) == "\n" then + return text .. "\n" + else + return text .. "\n\n" + end +end + + +-- Extract suitable item description for formspec +local description_for_formspec = function(itemstring) + if minetest.registered_items[itemstring] == nil then + -- Huh? The item doesn't exist for some reason. Better give a dummy string + minetest.log("warning", "[doc] Unknown item detected: "..tostring(itemstring)) + return S("Unknown item (@1)", tostring(itemstring)) + end + local description = minetest.registered_items[itemstring].description + if description == nil or description == "" then + return minetest.formspec_escape(itemstring) + else + return minetest.formspec_escape(scrub_newlines(description)) + end +end + +local get_entry_name = function(itemstring) + local def = minetest.registered_items[itemstring] + if def._doc_items_entry_name ~= nil then + return def._doc_items_entry_name + elseif item_name_overrides[itemstring] ~= nil then + return item_name_overrides[itemstring] + else + return def.description + end +end + +doc.sub.items.get_group_name = function(groupname) + if groupdefs[groupname] ~= nil and doc.sub.items.settings.friendly_group_names == true then + return groupdefs[groupname] + else + return groupname + end +end + +local burntime_to_text = function(burntime) + if burntime == nil then + return S("unknown") + elseif burntime == 1 then + return S("1 second") + else + return S("@1 seconds", burntime) + end +end + +--[[ Convert tool capabilities to readable text. Extracted information: +* Mining capabilities +* Durability (when mining +* Full punch interval +* Damage groups +]] +local factoid_toolcaps = function(tool_capabilities, check_uses) + if forbidden_core_factoids.tool_capabilities then + return "" + end + + local formstring = "" + if check_uses == nil then check_uses = false end + if tool_capabilities ~= nil and tool_capabilities ~= {} then + local groupcaps = tool_capabilities.groupcaps + if groupcaps ~= nil then + local miningcapstr = "" + local miningtimesstr = "" + local miningusesstr = "" + local caplines = 0 + local timelines = 0 + local useslines = 0 + for k,v in pairs(groupcaps) do + -- Mining capabilities + local minrating, maxrating + if v.times then + for rating, time in pairs(v.times) do + if minrating == nil then minrating = rating else + if minrating > rating then minrating = rating end + end + if maxrating == nil then maxrating = rating else + if maxrating < rating then maxrating = rating end + end + end + else + minrating = 1 + maxrating = 1 + end + local maxlevel = v.maxlevel + if not maxlevel then + -- Default from tool.h + maxlevel = 1 + end + miningcapstr = miningcapstr .. S("• @1: @2", doc.sub.items.get_group_name(k), maxlevel) + miningcapstr = miningcapstr .. "\n" + caplines = caplines + 1 + + for rating=3, 1, -1 do + if v.times ~= nil and v.times[rating] ~= nil then + local maxtime = v.times[rating] + local mintime + local mintimestr, maxtimestr + local maxlevel_calc = maxlevel + if maxlevel_calc < 1 then + maxlevel_calc = 1 + end + mintime = maxtime / maxlevel_calc + mintimestr = string.format("%.1f", mintime) + maxtimestr = string.format("%.1f", maxtime) + if mintimestr ~= maxtimestr then + miningtimesstr = miningtimesstr .. + S("• @1, rating @2: @3 s - @4 s", + doc.sub.items.get_group_name(k), rating, + mintimestr, maxtimestr) + else + miningtimesstr = miningtimesstr .. + S("• @1, rating @2: @3 s", + doc.sub.items.get_group_name(k), rating, + mintimestr) + end + miningtimesstr = miningtimesstr.. "\n" + timelines = timelines + 1 + end + end + + -- Number of mining uses + local base_uses = v.uses + if not base_uses then + -- Default from tool.h + base_uses = 20 + end + if check_uses and base_uses > 0 then + for level=0, maxlevel do + local real_uses = base_uses * math.pow(3, maxlevel - level) + if real_uses < 65535 then + miningusesstr = miningusesstr .. S("• @1, level @2: @3 uses", doc.sub.items.get_group_name(k), level, real_uses) + else + miningusesstr = miningusesstr .. S("• @1, level @2: Unlimited", doc.sub.items.get_group_name(k), level) + end + miningusesstr = miningusesstr .. "\n" + useslines = useslines + 1 + end + end + end + if caplines > 0 then + formstring = formstring .. S("This tool is capable of mining.") .. "\n" + formstring = formstring .. S("Maximum toughness levels:") .. "\n" + formstring = formstring .. miningcapstr + formstring = newline(formstring) + end + if timelines > 0 then + formstring = formstring .. S("Mining times:") .. "\n" + formstring = formstring .. miningtimesstr + end + if useslines > 0 then + formstring = formstring .. S("Mining durability:") .. "\n" + formstring = formstring .. miningusesstr + end + if caplines > 0 or useslines > 0 or timelines > 0 then + formstring = newline2(formstring) + end + end + + -- Weapon data + local damage_groups = tool_capabilities.damage_groups + if damage_groups ~= nil then + formstring = formstring .. S("This is a melee weapon which deals damage by punching.") .. "\n" + -- Damage groups + formstring = formstring .. S("Maximum damage per hit:") .. "\n" + for k,v in pairs(damage_groups) do + formstring = formstring .. S("• @1: @2 HP", doc.sub.items.get_group_name(k), v) + formstring = formstring .. "\n" + end + + -- Full punch interval + local punch = 1.0 + if tool_capabilities.full_punch_interval ~= nil then + punch = tool_capabilities.full_punch_interval + end + formstring = formstring .. S("Full punch interval: @1 s", string.format("%.1f", punch)) + formstring = formstring .. "\n" + end + + end + return formstring +end + +--[[ Factoid for the mining times properties of a node. Extracted infos: +- dig_immediate group +- Digging times/groups +- level group +]] +local factoid_mining_node = function(data) + if forbidden_core_factoids.node_mining then + return "" + end + + local datastring = "" + if data.def.pointable ~= false and (data.def.liquid_type == "none" or data.def.liquid_type == nil) then + -- Check if there are no mining groups at all + local nogroups = true + for groupname,_ in pairs(mininggroups) do + if data.def.groups[groupname] ~= nil or groupname == "dig_immediate" then + nogroups = false + break + end + end + -- dig_immediate + if data.def.drop ~= "" then + if data.def.groups.dig_immediate == 2 then + datastring = datastring .. S("This block can be mined by any mining tool in half a second.").."\n" + elseif data.def.groups.dig_immediate == 3 then + datastring = datastring .. S("This block can be mined by any mining tool immediately.").."\n" + -- Note: “unbreakable” is an unofficial group for undiggable blocks + elseif data.def.diggable == false or nogroups or data.def.groups.immortal == 1 or data.def.groups.unbreakable == 1 then + datastring = datastring .. S("This block can not be mined by ordinary mining tools.").."\n" + end + else + if data.def.groups.dig_immediate == 2 then + datastring = datastring .. S("This block can be destroyed by any mining tool in half a second.").."\n" + elseif data.def.groups.dig_immediate == 3 then + datastring = datastring .. S("This block can be destroyed by any mining tool immediately.").."\n" + elseif data.def.diggable == false or nogroups or data.def.groups.immortal == 1 or data.def.groups.unbreakable == 1 then + datastring = datastring .. S("This block can not be destroyed by ordinary mining tools.").."\n" + end + end + -- Expose “ordinary” mining groups (crumbly, cracky, etc.) and level group + -- Skip this for immediate digging to avoid redundancy + if data.def.groups.dig_immediate ~= 3 then + local mstring = S("This block can be mined by mining tools which match any of the following mining ratings and its toughness level.").."\n" + mstring = mstring .. S("Mining ratings:").."\n" + local minegroupcount = 0 + for group,_ in pairs(mininggroups) do + local rating = data.def.groups[group] + if rating ~= nil then + mstring = mstring .. S("• @1: @2", doc.sub.items.get_group_name(group), rating).."\n" + minegroupcount = minegroupcount + 1 + end + end + local level = data.def.groups.level + if not level then + level = 0 + end + mstring = mstring .. S("Toughness level: @1", level).."\n" + + if minegroupcount > 0 then + datastring = datastring .. mstring + end + end + end + return datastring +end + +-- Pointing range of itmes +local range_factoid = function(itemstring, def) + local handrange = minetest.registered_items[""].range + local itemrange = def.range + if itemstring == "" then + if handrange ~= nil then + return S("Range: @1", itemrange) + else + return S("Range: 4") + end + else + if handrange == nil then handrange = 4 end + if itemrange ~= nil then + return S("Range: @1", itemrange) + else + return S("Range: @1 (@2)", get_entry_name(""), handrange) + end + end +end + +-- Smelting fuel factoid +local factoid_fuel = function(itemstring, ctype) + if forbidden_core_factoids.fuel then + return "" + end + + local formstring = "" + local result, decremented = minetest.get_craft_result({method = "fuel", items = {itemstring}}) + if result ~= nil and result.time > 0 then + local base + local burntext = burntime_to_text(result.time) + if ctype == "tools" then + base = S("This tool can serve as a smelting fuel with a burning time of @1.", burntext) + elseif ctype == "nodes" then + base = S("This block can serve as a smelting fuel with a burning time of @1.", burntext) + else + base = S("This item can serve as a smelting fuel with a burning time of @1.", burntext) + end + formstring = formstring .. base + local replaced = decremented.items[1]:get_name() + if not decremented.items[1]:is_empty() and replaced ~= itemstring then + formstring = formstring .. S(" Using it as fuel turns it into: @1.", description_for_formspec(replaced)) + end + formstring = newline(formstring) + end + return formstring +end + +-- Shows the itemstring of an item +local factoid_itemstring = function(itemstring, playername) + if forbidden_core_factoids.itemstring then + return "" + end + + local privs = minetest.get_player_privs(playername) + if doc.sub.items.settings.itemstring or (privs.give or privs.debug) then + return S("Itemstring: \"@1\"", itemstring) + else + return "" + end +end + +local entry_image = function(data) + local formstring = "" + -- No image for air + if data.itemstring ~= "air" then + -- Hand + if data.itemstring == "" then + formstring = formstring .. "image["..(doc.FORMSPEC.ENTRY_END_X-1)..","..doc.FORMSPEC.ENTRY_START_Y..";1,1;".. + minetest.registered_items[""].wield_image.."]" + -- Other items + elseif data.image ~= nil then + formstring = formstring .. "image["..(doc.FORMSPEC.ENTRY_END_X-1)..","..doc.FORMSPEC.ENTRY_START_Y..";1,1;"..data.image.."]" + else + formstring = formstring .. "item_image["..(doc.FORMSPEC.ENTRY_END_X-1)..","..doc.FORMSPEC.ENTRY_START_Y..";1,1;"..data.itemstring.."]" + end + end + return formstring +end + +-- Stuff for factoids +local factoid_generators = {} +factoid_generators.nodes = {} +factoid_generators.tools = {} +factoid_generators.craftitems = {} + +--[[ Returns a list of all registered factoids for the specified category and type +* category_id: Identifier of the Documentation System category in which the factoid appears +* factoid_type: If set, oly returns factoid with a matching factoid_type. + If nil, all factoids for this category will be generated +* data: Entry data to parse ]] +local factoid_custom = function(category_id, factoid_type, data) + local ftable = factoid_generators[category_id] + local datastring = "" + -- Custom factoids are inserted here + for i=1,#ftable do + if factoid_type == nil or ftable[i].ftype == factoid_type then + datastring = datastring .. ftable[i].fgen(data.itemstring, data.def) + if datastring ~= "" then + datastring = newline(datastring) + end + end + end + return datastring +end + +-- Shows core information shared by all items, to be inserted at the top +local factoids_header = function(data, ctype) + local datastring = "" + if not forbidden_core_factoids.basics then + + local longdesc = data.longdesc + local usagehelp = data.usagehelp + if longdesc ~= nil then + datastring = datastring .. S("Description: @1", longdesc) + datastring = newline2(datastring) + end + if usagehelp ~= nil then + datastring = datastring .. S("Usage help: @1", usagehelp) + datastring = newline2(datastring) + end + datastring = datastring .. factoid_custom(ctype, "use", data) + datastring = newline2(datastring) + + if data.itemstring ~= "" then + datastring = datastring .. S("Maximum stack size: @1", data.def.stack_max) + datastring = newline(datastring) + end + datastring = datastring .. range_factoid(data.itemstring, data.def) + + datastring = newline2(datastring) + + if data.def.liquids_pointable == true then + if ctype == "nodes" then + datastring = datastring .. S("This block points to liquids.").."\n" + elseif ctype == "tools" then + datastring = datastring .. S("This tool points to liquids.").."\n" + elseif ctype == "craftitems" then + datastring = datastring .. S("This item points to liquids.").."\n" + end + end + if data.def.on_use ~= nil then + if ctype == "nodes" then + datastring = datastring .. S("Punches with this block don't work as usual; melee combat and mining are either not possible or work differently.").."\n" + elseif ctype == "tools" then + datastring = datastring .. S("Punches with this tool don't work as usual; melee combat and mining are either not possible or work differently.").."\n" + elseif ctype == "craftitems" then + datastring = datastring .. S("Punches with this item don't work as usual; melee combat and mining are either not possible or work differently.").."\n" + end + end + + end + + datastring = newline(datastring) + + -- Show tool capability stuff, including durability if not overwritten by custom field + local check_uses = false + if ctype == "tools" then + check_uses = data.def._doc_items_durability == nil + end + datastring = datastring .. factoid_toolcaps(data.def.tool_capabilities, check_uses) + datastring = newline2(datastring) + + return datastring +end + +-- Shows less important information shared by all items, to be inserted at the bottom +local factoids_footer = function(data, playername, ctype) + local datastring = "" + datastring = datastring .. factoid_custom(ctype, "groups", data) + datastring = newline2(datastring) + + -- Show other “exposable” groups + if not forbidden_core_factoids.groups then + local gstring, gcount = groups_to_string(data.def.groups, miscgroups) + if gstring ~= nil then + if gcount == 1 then + if ctype == "nodes" then + datastring = datastring .. S("This block belongs to the @1 group.", gstring) .. "\n" + elseif ctype == "tools" then + datastring = datastring .. S("This tool belongs to the @1 group.", gstring) .. "\n" + elseif ctype == "craftitems" then + datastring = datastring .. S("This item belongs to the @1 group.", gstring) .. "\n" + end + else + if ctype == "nodes" then + datastring = datastring .. S("This block belongs to these groups: @1.", gstring) .. "\n" + elseif ctype == "tools" then + datastring = datastring .. S("This tool belongs to these groups: @1.", gstring) .. "\n" + elseif ctype == "craftitems" then + datastring = datastring .. S("This item belongs to these groups: @1.", gstring) .. "\n" + end + end + end + end + datastring = newline2(datastring) + + -- Show fuel recipe + datastring = datastring .. factoid_fuel(data.itemstring, ctype) + datastring = newline2(datastring) + + -- Other custom factoids + datastring = datastring .. factoid_custom(ctype, "misc", data) + datastring = newline2(datastring) + + -- Itemstring + datastring = datastring .. factoid_itemstring(data.itemstring, playername) + + return datastring +end + +function doc.sub.items.register_factoid(category_id, factoid_type, factoid_generator) + local ftable = { fgen = factoid_generator, ftype = factoid_type } + if category_id == "nodes" or category_id == "tools" or category_id == "craftitems" then + table.insert(factoid_generators[category_id], ftable) + return true + elseif category_id == nil then + table.insert(factoid_generators.nodes, ftable) + table.insert(factoid_generators.tools, ftable) + table.insert(factoid_generators.craftitems, ftable) + return false + end +end + +function doc.sub.items.disable_core_factoid(factoid_name) + forbidden_core_factoids[factoid_name] = true +end + +doc.add_category("nodes", { + hide_entries_by_default = true, + name = S("Blocks"), + description = S("Item reference of blocks and other things which are capable of occupying space"), + build_formspec = function(data, playername) + if data then + local formstring = "" + local datastring = "" + + formstring = entry_image(data) + datastring = factoids_header(data, "nodes") + + if not forbidden_core_factoids.basics then + datastring = datastring .. S("Collidable: @1", yesno(data.def.walkable)) .. "\n" + local liquid + if data.def.liquidtype ~= "none" then liquid = true else liquid = false end + if data.def.pointable == true then + datastring = datastring .. S("Pointable: Yes") .. "\n" + elseif liquid then + datastring = datastring .. S("Pointable: Only by special items") .. "\n" + else + datastring = datastring .. S("Pointable: No") .. "\n" + end + end + datastring = newline2(datastring) + if not forbidden_core_factoids.liquid and liquid then + datastring = newline(datastring, false) + datastring = datastring .. S("This block is a liquid with these properties:") .. "\n" + local range, renew, viscos + if data.def.liquid_range then range = data.def.liquid_range else range = 8 end + if data.def.liquid_renewable ~= nil then renew = data.def.liquid_renewable else renew = true end + if data.def.liquid_viscosity then viscos = data.def.liquid_viscosity else viscos = 0 end + if renew then + datastring = datastring .. S("• Renewable") .. "\n" + else + datastring = datastring .. S("• Not renewable") .. "\n" + end + if range == 0 then + datastring = datastring .. S("• No flowing") .. "\n" + else + datastring = datastring .. S("• Flowing range: @1", range) .. "\n" + end + datastring = datastring .. S("• Viscosity: @1", viscos) .. "\n" + end + datastring = newline2(datastring) + + -- Global factoids + --- Direct interaction with the player + ---- Damage (very important) + if not forbidden_core_factoids.node_damage then + if data.def.damage_per_second ~= nil and data.def.damage_per_second > 1 then + datastring = datastring .. S("This block causes a damage of @1 hit points per second.", data.def.damage_per_second) .. "\n" + elseif data.def.damage_per_second == 1 then + datastring = datastring .. S("This block causes a damage of @1 hit point per second.", data.def.damage_per_second) .. "\n" + end + if data.def.drowning then + if data.def.drowning > 1 then + datastring = datastring .. S("This block decreases your breath and causes a drowning damage of @1 hit points every 2 seconds.", data.def.drowning) .. "\n" + elseif data.def.drowning == 1 then + datastring = datastring .. S("This block decreases your breath and causes a drowning damage of @1 hit point every 2 seconds.", data.def.drowning) .. "\n" + end + end + local fdap = data.def.groups.fall_damage_add_percent + if fdap ~= nil then + if fdap > 0 then + datastring = datastring .. S("The fall damage on this block is increased by @1%.", fdap) .. "\n" + elseif fdap <= -100 then + datastring = datastring .. S("This block negates all fall damage.") .. "\n" + else + datastring = datastring .. S("The fall damage on this block is reduced by @1%.", math.abs(fdap)) .. "\n" + end + end + end + datastring = datastring .. factoid_custom("nodes", "damage", data) + datastring = newline2(datastring) + + ---- Movement + if forbidden_core_factoids.node_movement then + if data.def.groups.disable_jump == 1 then + datastring = datastring .. S("You can not jump while standing on this block.").."\n" + end + if data.def.climbable == true then + datastring = datastring .. S("This block can be climbed.").."\n" + end + local bouncy = data.def.groups.bouncy + if bouncy ~= nil then + datastring = datastring .. S("This block will make you bounce off with an elasticity of @1%.", bouncy).."\n" + end + datastring = datastring .. factoid_custom("nodes", "movement", data) + datastring = newline2(datastring) + end + + ---- Sounds + if not forbidden_core_factoids.sounds then + local function is_silent(def, soundtype) + return type(def.sounds) ~= "table" or def.sounds[soundtype] == nil or def.sounds[soundtype] == "" or (type(data.def.sounds[soundtype]) == "table" and (data.def.sounds[soundtype].name == nil or data.def.sounds[soundtype].name == "")) + end + local silentstep, silentdig, silentplace = false, false, false + if data.def.walkable and is_silent(data.def, "footstep") then + silentstep = true + end + if data.def.diggable and is_silent(data.def, "dig") and is_silent(data.def, "dug") then + silentdig = true + end + if is_silent(data.def, "place") and is_silent(data.def, "place_failed") and data.itemstring ~= "air" then + silentplace = true + end + if silentstep and silentdig and silentplace then + datastring = datastring .. S("This block is completely silent when walked on, mined or built.").."\n" + elseif silentdig and silentplace then + datastring = datastring .. S("This block is completely silent when mined or built.").."\n" + else + if silentstep then + datastring = datastring .. S("Walking on this block is completely silent.").."\n" + end + if silentdig then + datastring = datastring .. S("Mining this block is completely silent.").."\n" + end + if silentplace then + datastring = datastring .. S("Building this block is completely silent.").."\n" + end + end + end + datastring = datastring .. factoid_custom("nodes", "sound", data) + datastring = newline2(datastring) + + -- Block activity + --- Gravity + if not forbidden_core_factoids.gravity then + if data.def.groups.falling_node == 1 then + datastring = datastring .. S("This block is affected by gravity and can fall.").."\n" + end + end + datastring = datastring .. factoid_custom("nodes", "gravity", data) + datastring = newline2(datastring) + + --- Dropping and destruction + if not forbidden_core_factoids.drop_destroy then + if data.def.buildable_to == true then + datastring = datastring .. S("Building another block at this block will place it inside and replace it.").."\n" + if data.def.walkable then + datastring = datastring .. S("Falling blocks can go through this block; they destroy it when doing so.").."\n" + end + end + if data.def.walkable == false then + if data.def.buildable_to == false and data.def.drop ~= "" then + datastring = datastring .. S("This block will drop as an item when a falling block ends up inside it.").."\n" + else + datastring = datastring .. S("This block is destroyed when a falling block ends up inside it.").."\n" + end + end + if data.def.groups.attached_node == 1 then + if data.def.paramtype2 == "wallmounted" then + datastring = datastring .. S("This block will drop as an item when it is not attached to a surrounding block.").."\n" + else + datastring = datastring .. S("This block will drop as an item when no collidable block is below it.").."\n" + end + end + if data.def.floodable == true then + datastring = datastring .. S("Liquids can flow into this block and destroy it.").."\n" + end + end + datastring = datastring .. factoid_custom("nodes", "drop_destroy", data) + datastring = newline2(datastring) + + -- Block appearance + --- Light + if not forbidden_core_factoids.light and data.def.light_source then + if data.def.light_source > 3 then + datastring = datastring .. S("This block is a light source with a light level of @1.", data.def.light_source).."\n" + elseif data.def.light_source > 0 then + datastring = datastring .. S("This block glows faintly with a light level of @1.", data.def.light_source).."\n" + end + if data.def.paramtype == "light" and data.def.sunlight_propagates then + datastring = datastring .. S("This block allows light to propagate with a small loss of brightness, and sunlight can even go through losslessly.").."\n" + elseif data.def.paramtype == "light" then + datastring = datastring .. S("This block allows light to propagate with a small loss of brightness.").."\n" + elseif data.def.sunlight_propagates then + datastring = datastring .. S("This block allows sunlight to propagate without loss in brightness.").."\n" + end + end + datastring = datastring .. factoid_custom("nodes", "light", data) + datastring = newline2(datastring) + + --- List nodes/groups to which this node connects to + if not forbidden_core_factoids.connects_to and data.def.connects_to ~= nil then + local nodes = {} + local groups = {} + for c=1,#data.def.connects_to do + local itemstring = data.def.connects_to[c] + if string.sub(itemstring,1,6) == "group:" then + groups[string.sub(itemstring,7,#itemstring)] = 1 + else + table.insert(nodes, itemstring) + end + end + + local nstring = "" + for n=1,#nodes do + local name + if item_name_overrides[nodes[n]] ~= nil then + name = item_name_overrides[nodes[n]] + else + name = description_for_formspec(nodes[n]) + end + if n > 1 then + nstring = nstring .. S(", ") + end + if name ~= nil then + nstring = nstring .. name + else + nstring = nstring .. S("Unknown Node") + end + end + if #nodes == 1 then + datastring = datastring .. S("This block connects to this block: @1.", nstring) .. "\n" + elseif #nodes > 1 then + datastring = datastring .. S("This block connects to these blocks: @1.", nstring) .. "\n" + end + + local gstring, gcount = groups_to_string(groups) + if gcount == 1 then + datastring = datastring .. S("This block connects to blocks of the @1 group.", gstring) .. "\n" + elseif gcount > 1 then + datastring = datastring .. S("This block connects to blocks of the following groups: @1.", gstring) .. "\n" + end + end + + datastring = newline2(datastring) + + -- Mining groups + datastring = datastring .. factoid_custom("nodes", "mining", data) + + datastring = newline(datastring) + + datastring = datastring .. factoid_mining_node(data) + datastring = newline2(datastring) + + -- Non-default drops + if not forbidden_core_factoids.drops and data.def.drop ~= nil and data.def.drop ~= data.itemstring and data.itemstring ~= "air" then + -- TODO: Calculate drop probabilities of max > 1 like for max == 1 + local get_desc = function(stack) + return description_for_formspec(stack:get_name()) + end + if data.def.drop == "" then + datastring = datastring .. S("This block won't drop anything when mined.").."\n" + elseif type(data.def.drop) == "string" then + local dropstack = ItemStack(data.def.drop) + if dropstack:get_name() ~= data.itemstring and dropstack:get_name() ~= 1 then + local desc = get_desc(dropstack) + local count = dropstack:get_count() + if count > 1 then + datastring = datastring .. S("This block will drop the following when mined: @1×@2.", count, desc).."\n" + else + datastring = datastring .. S("This block will drop the following when mined: @1.", desc).."\n" + end + end + elseif type(data.def.drop) == "table" and data.def.drop.items ~= nil then + local max = data.def.drop.max_items + local dropstring = "" + local dropstring_base = "" + if max == nil then + dropstring_base = S("This block will drop the following items when mined: %s.") + elseif max == 1 then + if #data.def.drop.items == 1 then + dropstring_base = S("This block will drop the following when mined: %s.") + else + dropstring_base = S("This block will randomly drop one of the following when mined: %s.") + end + else + dropstring_base = S("This block will randomly drop up to %d drops of the following possible drops when mined: %s.") + end + -- Save calculated probabilities into a table for later output + local probtables = {} + local probtable + local rarity_history = {} + for i=1,#data.def.drop.items do + local local_rarity = data.def.drop.items[i].rarity + local chance = 1 + local rarity = 1 + if local_rarity == nil then + local_rarity = 1 + end + if max == 1 then + -- Chained probability + table.insert(rarity_history, local_rarity) + chance = 1 + for r=1, #rarity_history do + local chance_factor + if r > 1 and rarity_history[r-1] == 1 then + chance = 0 + break + end + if r == #rarity_history then + chance_factor = 1/rarity_history[r] + else + chance_factor = (rarity_history[r]-1)/rarity_history[r] + end + chance = chance * chance_factor + end + if chance > 0 then + rarity = 1/chance + end + else + rarity = local_rarity + chance = 1/rarity + end + -- Exclude impossible drops + if chance > 0 then + probtable = {} + probtable.items = {} + for j=1,#data.def.drop.items[i].items do + local dropstack = ItemStack(data.def.drop.items[i].items[j]) + local itemstring = dropstack:get_name() + local desc = get_desc(dropstack) + local count = dropstack:get_count() + if not(itemstring == nil or itemstring == "" or count == 0) then + if probtable.items[itemstring] == nil then + probtable.items[itemstring] = {desc = desc, count = count} + else + probtable.items[itemstring].count = probtable.items[itemstring].count + count + end + end + end + probtable.rarity = rarity + if #data.def.drop.items[i].items > 0 then + table.insert(probtables, probtable) + end + end + end + -- Do some cleanup of the probability table + if max == 1 or max == nil then + -- Sort by rarity + local comp = function(p1, p2) + return p1.rarity < p2.rarity + end + table.sort(probtables, comp) + end + -- Output probability table + local pcount = 0 + for i=1, #probtables do + if pcount > 0 then + -- List seperator + dropstring = dropstring .. S(", ") + end + local probtable = probtables[i] + local icount = 0 + local dropstring_this = "" + for _, itemtable in pairs(probtable.items) do + if icount > 0 then + -- Final list seperator + dropstring_this = dropstring_this .. S(" and ") + end + local desc = S(itemtable.desc) + local count = itemtable.count + if count ~= 1 then + desc = S("@1×@2", count, desc) + end + dropstring_this = dropstring_this .. desc + icount = icount + 1 + end + + local rarity = probtable.rarity + local raritystring = "" + -- No percentage if there's only one possible guaranteed drop + if not(rarity == 1 and #data.def.drop.items == 1) then + local chance = (1/rarity)*100 + if rarity > 200 then -- <0.5% + -- For very low percentages + dropstring_this = S("@1 (<0.5%)", dropstring_this) + else + -- Add circa indicator for percentages with decimal point + local fchance = string.format("%.0f", chance) + if math.fmod(chance, 1) > 0 then + dropstring_this = S("@1 (ca. @2%)", dropstring_this, fchance) + else + dropstring_this = S("@1 (@2%)", dropstring_this, fchance) + end + end + end + dropstring = dropstring .. dropstring_this + pcount = pcount + 1 + end + if max ~= nil and max > 1 then + datastring = datastring .. string.format(dropstring_base, max, dropstring) + else + datastring = datastring .. string.format(dropstring_base, dropstring) + end + datastring = newline(datastring) + end + end + datastring = datastring .. factoid_custom("nodes", "drops", data) + datastring = newline2(datastring) + + datastring = datastring .. factoids_footer(data, playername, "nodes") + + formstring = formstring .. doc.widgets.text(datastring, nil, nil, doc.FORMSPEC.ENTRY_WIDTH - 1.2) + + return formstring + else + return "label[0,1;NO DATA AVALIABLE!]" + end + end +}) + +doc.add_category("tools", { + hide_entries_by_default = true, + name = S("Tools and weapons"), + description = S("Item reference of all wieldable tools and weapons"), + sorting = "function", + -- Roughly sort tools based on their capabilities. Tools which dig the same stuff end up in the same group + sorting_data = function(entry1, entry2) + local entries = { entry1, entry2 } + -- Hand beats all + if entries[1].eid == "" then return true end + if entries[2].eid == "" then return false end + + local comp = {} + for e=1, 2 do + comp[e] = {} + end + -- No tool capabilities: Instant loser + if entries[1].data.def.tool_capabilities == nil and entries[2].data.def.tool_capabilities ~= nil then return false end + if entries[2].data.def.tool_capabilities == nil and entries[1].data.def.tool_capabilities ~= nil then return true end + -- No tool capabilities for both: Compare by uses + if entries[1].data.def.tool_capabilities == nil and entries[2].data.def.tool_capabilities == nil then + for e=1, 2 do + if type(entries[e].data.def._doc_items_durability) == "number" then + comp[e].uses = entries[e].data.def._doc_items_durability + else + comp[e].uses = 0 + end + end + return comp[1].uses > comp[2].uses + end + for e=1, 2 do + comp[e].gc = entries[e].data.def.tool_capabilities.groupcaps + end + -- No group capabilities = instant loser + if comp[1].gc == nil then return false end + if comp[2].gc == nil then return true end + for e=1, 2 do + local groups = {} + local gc = comp[e].gc + local group = nil + local mintime = nil + local groupcount = 0 + local realuses = nil + for k,v in pairs(gc) do + local maxlevel = v.maxlevel + if maxlevel == nil then + -- Default from tool.h + maxlevel = 1 + end + if groupcount == 0 then + group = k + local uses = v.uses + if v.uses == nil then + -- Default from tool.h + uses = 20 + end + realuses = uses * math.pow(3, maxlevel) + end + if v.times and #v.times > 1 then + for rating, time in pairs(v.times) do + local realtime = time / maxlevel + if mintime == nil or realtime < mintime then + mintime = realtime + end + end + else + mintime = 0 + end + if groups[k] ~= true then + groupcount = groupcount + 1 + groups[k] = true + end + end + comp[e].count = groupcount + comp[e].group = group + comp[e].mintime = mintime + if realuses ~= nil then + comp[e].uses = realuses + elseif type(entries[e].data.def._doc_items_durability) == "number" then + comp[e].uses = entries[e].data.def._doc_items_durability + else + comp[e].uses = 0 + end + end + + -- We want to sort out digging tools with multiple capabilities + if comp[1].count > 1 and comp[1].count > comp[2].count then + return false + elseif comp[1].group == comp[2].group then + -- Tiebreaker 1: Minimum digging time + if comp[1].mintime == comp[2].mintime then + -- Tiebreaker 2: Use count + return comp[1].uses > comp[2].uses + else + return comp[1].mintime < comp[2].mintime + end + -- Final tiebreaker: Sort by group name + else + if comp[1].group and comp[2].group then + return comp[1].group < comp[2].group + else + return false + end + end + end, + build_formspec = function(data, playername) + if data then + local formstring = "" + local datastring = "" + + formstring = entry_image(data) + datastring = factoids_header(data, "tools") + + -- Overwritten durability info + if type(data.def._doc_items_durability) == "number" then + -- Fixed number of uses + datastring = datastring .. S("Durability: @1 uses", data.def._doc_items_durability) + datastring = newline2(datastring) + elseif type(data.def._doc_items_durability) == "string" then + -- Manually described durability + datastring = datastring .. S("Durability: @1", data.def._doc_items_durability) + datastring = newline2(datastring) + end + + datastring = datastring .. factoids_footer(data, playername, "tools") + + formstring = formstring .. doc.widgets.text(datastring, nil, nil, doc.FORMSPEC.ENTRY_WIDTH - 1.2) + + return formstring + else + return "label[0,1;NO DATA AVALIABLE!]" + end + end +}) + +doc.add_category("craftitems", { + hide_entries_by_default = true, + name = S("Miscellaneous items"), + description = S("Item reference of items which are neither blocks, tools or weapons (esp. crafting items)"), + build_formspec = function(data, playername) + if data then + local formstring = "" + local datastring = "" + + formstring = entry_image(data) + datastring = factoids_header(data, "craftitems") + datastring = datastring .. factoids_footer(data, playername, "craftitems") + + formstring = formstring .. doc.widgets.text(datastring, nil, nil, doc.FORMSPEC.ENTRY_WIDTH - 1.2) + + return formstring + else + return "label[0,1;NO DATA AVALIABLE!]" + end + end +}) + +-- Register group definition stuff +-- More (user-)friendly group names to replace the rather technical names +-- for better understanding +function doc.sub.items.add_friendly_group_names(groupnames) + for internal, real in pairs(groupnames) do + groupdefs[internal] = real + end +end + +-- Adds groups to be displayed in the generic “misc.” groups +-- factoid. Those groups should be neither be used as mining +-- groups nor as damage groups and should be relevant to the +-- player in someway. +function doc.sub.items.add_notable_groups(groupnames) + for g=1,#groupnames do + miscgroups[groupnames[g]] = true + end +end + +-- Collect information about all items +local function gather_descs() + -- Internal help texts for default items + local help = { + longdesc = {}, + usagehelp = {}, + } + + -- 1st pass: Gather groups of interest + for id, def in pairs(minetest.registered_items) do + -- Gather all groups used for mining + if def.tool_capabilities ~= nil then + local groupcaps = def.tool_capabilities.groupcaps + if groupcaps ~= nil then + for k,v in pairs(groupcaps) do + if mininggroups[k] ~= true then + mininggroups[k] = true + end + end + end + end + + -- ... and gather all groups which appear in crafting recipes + local crafts = minetest.get_all_craft_recipes(id) + if crafts ~= nil then + for c=1,#crafts do + for k,v in pairs(crafts[c].items) do + if string.sub(v,1,6) == "group:" then + local groupstring = string.sub(v,7,-1) + local groups = string.split(groupstring, ",") + for g=1, #groups do + miscgroups[groups[g]] = true + end + end + end + end + end + + -- ... and gather all groups used in connects_to + if def.connects_to ~= nil then + for c=1, #def.connects_to do + if string.sub(def.connects_to[c],1,6) == "group:" then + local group = string.sub(def.connects_to[c],7,-1) + miscgroups[group] = true + end + end + end + end + + -- 2nd pass: Add entries + + -- Set default air text + -- Custom longdesc and usagehelp may be set by mods through the add_helptexts function + if minetest.registered_items["air"]._doc_items_longdesc then + help.longdesc["air"] = minetest.registered_items["air"]._doc.items_longdesc + else + help.longdesc["air"] = S("A transparent block, basically empty space. It is usually left behind after digging something.") + end + if minetest.registered_items["ignore"]._doc_items_create_entry ~= nil then + suppressed["ignore"] = minetest.registered_items["ignore"]._doc_items_create_entry == true + end + + -- Add entry for the default tool (“hand”) + -- Custom longdesc and usagehelp may be set by mods through the add_helptexts function + local handdef = minetest.registered_items[""] + if handdef._doc_items_create_entry ~= false then + if handdef._doc_items_longdesc then + help.longdesc[""] = handdef._doc_items_longdesc + else + -- Default text + help.longdesc[""] = S("Whenever you are not wielding any item, you use the hand which acts as a tool with its own capabilities. When you are wielding an item which is not a mining tool or a weapon it will behave as if it would be the hand.") + end + if handdef._doc_items_entry_name then + item_name_overrides[""] = handdef._doc_items_entry_name + end + doc.add_entry("tools", "", { + name = item_name_overrides[""], + hidden = handdef._doc_items_hidden == true, + data = { + longdesc = help.longdesc[""], + usagehelp = help.usagehelp[""], + itemstring = "", + def = handdef, + } + }) + end + + local add_entries = function(deftable, category_id) + for id, def in pairs(deftable) do + local name, ld, uh, im + local forced = false + if def._doc_items_create_entry == true and def ~= nil then forced = true end + name = get_entry_name(id) + if not (((def.description == nil or def.description == "") and def._doc_items_entry_name == nil) or (def._doc_items_create_entry == false) or (suppressed[id] == true)) or forced then + if def._doc_items_longdesc then + ld = def._doc_items_longdesc + end + if help.longdesc[id] ~= nil then + ld = help.longdesc[id] + end + if def._doc_items_usagehelp then + uh = def._doc_items_usagehelp + end + if help.usagehelp[id] ~= nil then + uh = help.usagehelp[id] + end + if def._doc_items_image then + im = def._doc_items_image + end + local hidden + if id == "air" or id == "" then hidden = false end + if type(def._doc_items_hidden) == "boolean" then + hidden = def._doc_items_hidden + end + local custom_image + name = scrub_newlines(name) + local infotable = { + name = name, + hidden = hidden, + data = { + longdesc = ld, + usagehelp = uh, + image = im, + itemstring = id, + def = def, + } + } + doc.add_entry(category_id, id, infotable) + end + end + end + + -- Add node entries + add_entries(minetest.registered_nodes, "nodes") + + -- Add tool entries + add_entries(minetest.registered_tools, "tools") + + -- Add craftitem entries + add_entries(minetest.registered_craftitems, "craftitems") +end + +--[[ Reveal items as the player progresses through the game. +Items are revealed by: +* Digging, punching or placing node, +* Crafting +* Having item in inventory (not instantly revealed) ]] + +local function reveal_item(playername, itemstring) + local category_id + if itemstring == nil or itemstring == "" or playername == nil or playername == "" then + return false + end + if minetest.registered_nodes[itemstring] ~= nil then + category_id = "nodes" + elseif minetest.registered_tools[itemstring] ~= nil then + category_id = "tools" + elseif minetest.registered_craftitems[itemstring] ~= nil then + category_id = "craftitems" + elseif minetest.registered_items[itemstring] ~= nil then + category_id = "craftitems" + else + return false + end + doc.mark_entry_as_revealed(playername, category_id, itemstring) + return true +end + +local function reveal_items_in_inventory(player) + local inv = player:get_inventory() + local list = inv:get_list("main") + for l=1, #list do + reveal_item(player:get_player_name(), list[l]:get_name()) + end +end + +minetest.register_on_dignode(function(pos, oldnode, digger) + if digger == nil then return end + local playername = digger:get_player_name() + if playername ~= nil and playername ~= "" and oldnode ~= nil then + reveal_item(playername, oldnode.name) + reveal_items_in_inventory(digger) + end +end) + +minetest.register_on_punchnode(function(pos, node, puncher, pointed_thing) + if puncher == nil then return end + local playername = puncher:get_player_name() + if playername ~= nil and playername ~= "" and node ~= nil then + reveal_item(playername, node.name) + end +end) + +minetest.register_on_placenode(function(pos, newnode, placer, oldnode, itemstack, pointed_thing) + if placer == nil then return end + local playername = placer:get_player_name() + if playername ~= nil and playername ~= "" and itemstack ~= nil and not itemstack:is_empty() then + reveal_item(playername, itemstack:get_name()) + end +end) + +minetest.register_on_craft(function(itemstack, player, old_craft_grid, craft_inv) + if player == nil then return end + local playername = player:get_player_name() + if playername ~= nil and playername ~= "" and itemstack ~= nil and not itemstack:is_empty() then + reveal_item(playername, itemstack:get_name()) + end +end) + +minetest.register_on_item_eat(function(hp_change, replace_with_item, itemstack, user, pointed_thing) + if user == nil then return end + local playername = user:get_player_name() + if playername ~= nil and playername ~= "" and itemstack ~= nil and not itemstack:is_empty() then + reveal_item(playername, itemstack:get_name()) + if replace_with_item ~= nil then + reveal_item(playername, replace_with_item) + end + end +end) + +minetest.register_on_joinplayer(function(player) + reveal_items_in_inventory(player) +end) + +--[[ Periodically check all items in player inventory and reveal them all. +TODO: Check whether there's a serious performance impact on servers with many players. +TODO: If possible, try to replace this functionality by updating the revealed items as + soon the player obtained a new item (probably needs new Minetest callbacks). ]] +local checktime = 8 +local timer = 0 +minetest.register_globalstep(function(dtime) + timer = timer + dtime + if timer > checktime then + local players = minetest.get_connected_players() + for p=1, #players do + reveal_items_in_inventory(players[p]) + end + + timer = math.fmod(timer, checktime) + end +end) + +minetest.after(0, gather_descs) diff --git a/mods/HELP/doc/doc_items/locale/de.txt b/mods/HELP/doc/doc_items/locale/de.txt new file mode 100644 index 000000000..8bc67ad76 --- /dev/null +++ b/mods/HELP/doc/doc_items/locale/de.txt @@ -0,0 +1,140 @@ +\sUsing it as fuel turns it into: @1. = \sWird dieser Gegenstand als Brennstoff verwendet, verwandelt er sich zu: @1. +@1 seconds = @1 Sekunden +# Item count times item name +@1×@2 = @1×@2 +# Itemname (25%) +@1 (@2%) = @1 (@2%) +# Itemname (<0.5%) +@1 (<0.5%) = @1 (<0,5%) +# Itemname (ca. 25%) +@1 (ca. @2%) = @1 (ca. @2%) +# List separator (e.g. “one, two, three”) +,\s = ,\s +# Final list separator (e.g. “One, two and three”) +\sand\s = \sund\s +1 second = 1 Sekunde +A transparent block, basically empty space. It is usually left behind after digging something. = Ein transparenter Block, praktisch leerer Raum. Er wird üblicherweise hinterlassen, nachdem man etwas ausgegraben hat. +Air = Luft +Blocks = Blöcke +Building another block at this block will place it inside and replace it. = Wird ein anderer Block an diesem Block gebaut, wird dieser andere Block seine Stelle einnehmen. +Building this block is completely silent. = Das Bauen dieses Blocks ist völlig lautlos. +Collidable: @1 = Kollidiert: @1 +Description: @1 = Beschreibung: @1 +Falling blocks can go through this block; they destroy it when doing so. = Fallende Blöcke können diesen Block durchdringen; sie zerstören ihn dabei. +Full punch interval: @1 s = Schlagintervall: @1 s +Hand = Hand +Hold it in your hand, then leftclick to eat it. = Halten Sie es in Ihrer Hand, dann klicken Sie mit der linken Maustaste, um es zu essen. +Hold it in your hand, then leftclick to eat it. But why would you want to do this? = Halten Sie es in Ihrer Hand, dann klicken Sie mit der linken Maustaste, um es zu essen. Aber warum sollten Sie das tun wollen? +Item reference of all wieldable tools and weapons = Gegenstandsreferenz aller tragbaren Werkzeugen und Waffen +Item reference of blocks and other things which are capable of occupying space = Gegenstandsreferenz aller Blöcke und anderen Dingen, die Raum belegen +Item reference of items which are neither blocks, tools or weapons (esp. crafting items) = Gegenstandsreferenz aller Gegenstände, welche weder Blöcke, Werkzeuge oder Waffen sind (insb. Fertigungsgegenstände) +Liquids can flow into this block and destroy it. = Flüssigkeiten können in diesen Block hereinfließen und ihn zerstören. +Maximum stack size: @1 = Maximale Stapelgröße: @1 +Mining level: @1 = Grabestufe: @1 +Mining ratings: = Grabewertungen: +• @1, rating @2: @3 s - @4 s = • @1, Wertung @2: @3 s - @4 s +• @1, rating @2: @3 s = • @1, Wertung @2: @3 s +Mining times: = Grabezeiten: +Mining this block is completely silent. = Das Abbauen dieses Blocks ist völlig lautlos. +Miscellaneous items = Sonstige Gegenstände +No = Nein +Pointable: No = Zeigbar: Nein +Pointable: Only by special items = Zeigbar: Nur von besonderen Gegenständen +Pointable: Yes = Zeigbar: Ja +Punches with this block don't work as usual; melee combat and mining are either not possible or work differently. = Schläge mit diesem Block funktionieren nicht auf die übliche Weise; Nahkampf und Graben sind damit entweder nicht möglich oder funktionieren auf andere Weise. +Punches with this item don't work as usual; melee combat and mining are either not possible or work differently. = Schläge mit diesem Gegenstand funktionieren nicht auf die übliche Weise; Nahkampf und Graben sind damit entweder nicht möglich oder funktionieren auf andere Weise. +Punches with this tool don't work as usual; melee combat and mining are either not possible or work differently. = Schläge mit diesem Werkzeug funktionieren nicht auf die übliche Weise; Nahkampf und Graben sind damit entweder nicht möglich oder funktionieren auf andere Weise. +Range: @1 = Reichweite: @1 +# Range: () +Range: @1 (@2) = Reichweite: @1 (@2) +Range: 4 = Reichweite: 4 +# Rating used for digging times +Rating @1 = Wertung @1 +Rating @1-@2 = Wertung @1-@2 +The fall damage on this block is increased by @1%. = Der Fallschaden auf diesem Block ist um @1% erhöht. +The fall damage on this block is reduced by @1%. = Der Fallschaden auf diesem Block ist um @1% reduziert. +This block allows light to propagate with a small loss of brightness, and sunlight can even go through losslessly. = Dieser Block ist lichtdurchlässig mit einen geringfügigen Helligkeitsverlust; Sonnenlicht passiert jedoch ohne Verlust. +This block allows light to propagate with a small loss of brightness. = Dieser Block ist lichtdurchlässig mit einen geringfügigen Helligkeitsverlust. +This block allows sunlight to propagate without loss in brightness. = Dieser Block ist vollkommen durchlässig für Sonnenlicht. +This block belongs to the @1 group. = Dieser Block gehört zur Gruppe »@1«. +This block belongs to these groups: @1. = Dieser Block gehört zu den folgenden Gruppen: @1. +This block can be climbed. = Dieser Block kann beklettert werden. +This block can be destroyed by any mining tool immediately. = Dieser Block kann von einem beliebigen Grabewerkzeug sofort zerstört werden. +This block can be destroyed by any mining tool in half a second. = Dieser Block kann von einem beliebigen Grabewerkzeug in einer halben Sekunde zerstört werden. +This block can be mined by any mining tool immediately. = Dieser Block kann von einem beliebigen Grabewerkzeug sofort abgebaut werden. +This block can be mined by any mining tool in half a second. = Dieser Block kann von einem beliebigen Grabewerkzeug in einer halben Sekunde abgebaut werden. +This block can be mined by mining tools which match any of the following mining ratings and its toughness level. = Dieser Block kann von Grabewerkzeugen abgebaut werden, falls sie auf eine der folgenden Grabewertungen sowie seinem Härtegrad passen. +This block can not be destroyed by ordinary mining tools. = Dieser Block kann nicht von Grabewerkzeugen zerstört werden. +This block can not be mined by ordinary mining tools. = Dieser Block kann nicht von gewöhnlichen Grabewerkzeugen abgebaut werden. +This block can serve as a smelting fuel with a burning time of @1. = Dieser Block kann als Brennstoff mit einer Brenndauer von @1 dienen. +This block causes a damage of @1 hit point per second. = Dieser Block richtet einen Schaden von @1 Trefferpunkt pro Sekunde an. +This block causes a damage of @1 hit points per second. = Dieser Block richtet einen Schaden von @1 Trefferpunkten pro Sekunde an. +This block connects to blocks of the @1 group. = Dieser Block verbindet sich mit Blöcken der Gruppe »@1«. +This block connects to blocks of the following groups: @1. = Dieser Block verbindet sich mit Blöcken der folgenden Gruppen: @1. +This block connects to these blocks: @1. = Dieser Block verbindet sich mit den folgenden Blöcken: @1. +This block connects to this block: @1. = Dieser Block verbindet sich mit diesem Block: @1. +This block decreases your breath and causes a drowning damage of @1 hit point every 2 seconds. = Dieser Block reduziert Ihren Atem und verursacht beim Ertrinken einen Schaden von @1 Trefferpunkt alle 2 Sekunden. +This block decreases your breath and causes a drowning damage of @1 hit points every 2 seconds. = Dieser Block reduziert Ihren Atem und verursacht beim Ertrinken einen Schaden von @1 Trefferpunkten alle 2 Sekunden. +This block glows faintly. It is barely noticable. = Dieser Block leuchtet schwach. Es ist kaum merklich. +This block is a light source with a light level of @1. = Dieser Block ist eine Lichtquelle mit einer Helligkeitsstufe von @1. +This block glows faintly with a light level of @1. = Dieser Block leuchtet schwach mit einer Helligkeitsstufe von @1. +This block is a building block for creating various buildings. = Dieser Block ist für den Bau diverser Gebäude vorgesehen. +This block is a liquid with these properties: = Dieser Block ist eine Flüssigkeit mit folgenden Eigenschaften: +This block is affected by gravity and can fall. = Dieser Block wird von der Schwerkraft beeinflusst und kann fallen. +This block is completely silent when mined or built. = Dieser Block kann vollkommen lautlos gebaut oder abgebaut werden. +This block is completely silent when walked on, mined or built. = Es ist vollkommen lautlos, wenn man auf diesen Block geht, ihn baut oder abbaut. +This block is destroyed when a falling block ends up inside it. = Dieser Block wird zerstört, wenn ein fallender Block in ihm landet. +This block negates all fall damage. = Auf diesem Block gibt es keinen Fallschaden. +This block points to liquids. = Mit diesem Block zeigt man auf Flüssigkeiten. +This block will drop as an item when a falling block ends up inside it. = Dieser Block wird sich als Gegenstand abwerfen, wenn ein fallender Block in ihn landet. +This block will drop as an item when it is not attached to a surrounding block. = Dieser Block wird sich als Gegenstand abwerfen, wenn er nicht an einen benachbarten Block befestigt ist. +This block will drop as an item when no collidable block is below it. = Dieser Block wird sich als Gegenstand abwerfen, wenn kein kollidierender Block unter ihn liegt. +This block will drop the following items when mined: %s. = Dieser Block wird nach dem Abbauen die folgenden Gegenstände abwerfen: %s. +This block will drop the following when mined: @1×@2. = Dieser Block wird nach dem Abbauen folgendes abwerfen: @1×@2. +This block will drop the following when mined: @1. = Dieser Block wird nach dem Abbauen folgendes abwerfen: @1. +This block will drop the following when mined: %s. = Dieser Block wird nach dem Abbauen folgendes abwerfen: %s. +This block will make you bounce off with an elasticity of @1%. = Dieser Block wird Sie mit einer Elastizität von @1% abprallen lassen. +This block will randomly drop one of the following when mined: %s. = Dieser Block wird nach dem Abbauen zufällig eines von den folgenden Dingen abwerfen: %s. +This block will randomly drop up to %d drops of the following possible drops when mined: %s. = Dieser Block nach dem Abbauen wird zufällig bis zu %d Abwürfe von den folgenden möglichen Abwürfen abwerfen: %s. +This block won't drop anything when mined. = Dieser Block wird nach dem Abbauen nichts abwerfen. +This is a decorational block. = Dieser Block dient zur Dekoration. +This is a melee weapon which deals damage by punching. = Dies ist eine Nahkampfwaffe, welche Schaden durch Schläge verursacht. +Maximum damage per hit: = Maximaler Schaden pro Treffer: +This item belongs to the @1 group. = Dieser Gegenstand gehört zur Gruppe »@1«. +This item belongs to these groups: @1. = Dieser Gegenstand gehört zu den folgenden Gruppen: @1. +This item can serve as a smelting fuel with a burning time of @1. = Dieser Gegenstand kann als Brennstoff mit einer Brenndauer von @1 dienen. +This item is primarily used for crafting other items. = Dieser Gegenstand wird primär für die Fertigung von anderen Gegenständen benutzt. +This item points to liquids. = Mit diesem Gegenstand zeigt man auf Flüssigkeiten. +This tool belongs to the @1 group. = Dieses Werkzeug gehört zur Gruppe »@1«. +This tool belongs to these groups: @1. = Dieses Werkzeug gehört zu den folgenden Gruppen: @1. +This tool can serve as a smelting fuel with a burning time of @1. = Dieses Werkzeug kann als Brennstoff mit einer Brenndauer von @1 dienen. +This tool is capable of mining. = Dies ist ein Grabewerkzeug. +Maximum toughness levels: = Maximale Härtegrade: +This tool points to liquids. = Mit diesem Werkzeug zeigt man auf Flüssigkeiten. +Tools and weapons = Werkzeuge und Waffen +Unknown Node = Unbekannter Node +Usage help: @1 = Benutzung: @1 +Walking on this block is completely silent. = Auf diesem Block sind Schritte lautlos. +Whenever you are not wielding any item, you use the hand which acts as a tool with its own capabilities. When you are wielding an item which is not a mining tool or a weapon it will behave as if it would be the hand. = Wenn Sie keinen Gegenstand halten, benutzen Sie die Hand, welches als ein Werkzeug mit seinen eigenen Fägihkeiten dient. Wenn Sie einen Gegenstand halten, der kein Grabewerkzeug oder eine Waffe ist, wird er sich verhalten als wäre er die Hand. +Yes = Ja +You can not jump while standing on this block. = Man kann von diesem Block nicht abspringen. +any level = beliebige Stufe +level 0 = Stufe 0 +level 0-@1 = Stufen 0-@1 +unknown = unbekannt +Unknown item (@1) = Unbekannter Gegenstand (@1) +• @1: @2 = • @1: @2 +• @1: @2 HP = • @1: @2 TP +• @1: @2, @3 = • @1: @2, @3 +• Flowing range: @1 = • Fließweite: @1 +• No flowing = • Kein Fließen +• Not renewable = • Nicht erneuerbar +• Renewable = • Erneuerbar +• Viscosity: @1 = • Zähflüssigkeit: @1 +Itemstring: "@1" = Itemstring: »@1« +Durability: @1 uses = Haltbarkeit: @1 Benutzungen +Durability: @1 = Haltbarkeit: @1 +Mining durability: = Grabehaltbarkeit: +• @1, level @2: @3 uses = • @1, Stufe @2: @3 Benutzungen +• @1, level @2: Unlimited = • @1, Stufe @2: Unbegrenzt +This block's rotation is affected by the way you place it: Place it on the floor or ceiling for a vertical orientation; place it at the side for a horizontal orientation. Sneaking while placing it leads to a perpendicular orientation instead. = Die Rotation dieses Blocks hängt davon ab, wie sie ihn platzieren: Platzieren Sie ihn auf den Boden oder an die Decke, um ihn vertikal aufzustellen; platzieren Sie in an der Seite für eine horizontale Ausrichtung. Wenn Sie während des Bauens schleichen, wird der Block stattdessen senkrecht zur üblichen Ausrichtung rotiert. diff --git a/mods/HELP/doc/doc_items/locale/template.txt b/mods/HELP/doc/doc_items/locale/template.txt new file mode 100644 index 000000000..5f71c75a6 --- /dev/null +++ b/mods/HELP/doc/doc_items/locale/template.txt @@ -0,0 +1,140 @@ +\sUsing it as fuel turns it into: @1. = +@1 seconds = +# Item count times item name +%@1×@2 = +# Itemname (25%) +@1 (@2%) = +# Itemname (<0.5%) +@1 (<0.5%) = +# Itemname (ca. 25%) +@1 (ca. @2%) = +# List separator (e.g. “one, two, three”) +,\s = +# Final list separator (e.g. “One, two and three”) +\sand\s = +1 second = +A transparent block, basically empty space. It is usually left behind after digging something. = +Air = +Blocks = +Building another block at this block will place it inside and replace it. = +Building this block is completely silent. = +Collidable: @1 = +Description: @1 = +Falling blocks can go through this block; they destroy it when doing so. = +Full punch interval: @1 s = +Hand = +Hold it in your hand, then leftclick to eat it. = +Hold it in your hand, then leftclick to eat it. But why would you want to do this? = +Item reference of all wieldable tools and weapons = +Item reference of blocks and other things which are capable of occupying space = +Item reference of items which are neither blocks, tools or weapons (esp. crafting items) = +Liquids can flow into this block and destroy it. = +Maximum stack size: @1 = +Mining level: @1 = +Mining ratings: = +• @1, rating @2: @3 s - @4 s = +• @1, rating @2: @3 s = +Mining times: = +Mining this block is completely silent. = +Miscellaneous items = +No = +Pointable: No = +Pointable: Only by special items = +Pointable: Yes = +Punches with this block don't work as usual; melee combat and mining are either not possible or work differently. = +Punches with this item don't work as usual; melee combat and mining are either not possible or work differently. = +Punches with this tool don't work as usual; melee combat and mining are either not possible or work differently. = +Range: @1 = +# Range: () +Range: @1 (@2) = +Range: 4 = +# Rating used for digging times +Rating @1 = +# @1 is minimal rating, @2 is maximum rating +Rating @1-@2 = +The fall damage on this block is increased by @1%. = +The fall damage on this block is reduced by @1%. = +This block allows light to propagate with a small loss of brightness, and sunlight can even go through losslessly. = +This block allows light to propagate with a small loss of brightness. = +This block allows sunlight to propagate without loss in brightness. = +This block belongs to the @1 group. = +This block belongs to these groups: @1. = +This block can be climbed. = +This block can be destroyed by any mining tool immediately. = +This block can be destroyed by any mining tool in half a second. = +This block can be mined by any mining tool immediately. = +This block can be mined by any mining tool in half a second. = +This block can be mined by mining tools which match any of the following mining ratings and its toughness level. = +This block can not be destroyed by ordinary mining tools. = +This block can not be mined by ordinary mining tools. = +This block can serve as a smelting fuel with a burning time of @1. = +This block causes a damage of @1 hit point per second. = +This block causes a damage of @1 hit points per second. = +This block connects to blocks of the @1 group. = +This block connects to blocks of the following groups: @1. = +This block connects to these blocks: @1. = +This block connects to this block: @1. = +This block decreases your breath and causes a drowning damage of @1 hit point every 2 seconds. = +This block decreases your breath and causes a drowning damage of @1 hit points every 2 seconds. = +This block is a light source with a light level of @1. = +This block glows faintly with a light level of @1. = +This block is a building block for creating various buildings. = +This block is a liquid with these properties: = +This block is affected by gravity and can fall. = +This block is completely silent when mined or built. = +This block is completely silent when walked on, mined or built. = +This block is destroyed when a falling block ends up inside it. = +This block negates all fall damage. = +This block points to liquids. = +This block will drop as an item when a falling block ends up inside it. = +This block will drop as an item when it is not attached to a surrounding block. = +This block will drop as an item when no collidable block is below it. = +This block will drop the following items when mined: %s. = +This block will drop the following when mined: @1×@2. = +This block will drop the following when mined: @1. = +This block will drop the following when mined: %s. = +This block will make you bounce off with an elasticity of @1%. = +This block will randomly drop one of the following when mined: %s. = +This block will randomly drop up to %d drops of the following possible drops when mined: %s. = +This block won't drop anything when mined. = +This is a decorational block. = +This is a melee weapon which deals damage by punching. = +Maximum damage per hit: = +This item belongs to the @1 group. = +This item belongs to these groups: @1. = +This item can serve as a smelting fuel with a burning time of @1. = +This item is primarily used for crafting other items. = +This item points to liquids. = +This tool belongs to the @1 group. = +This tool belongs to these groups: @1. = +This tool can serve as a smelting fuel with a burning time of @1. = +This tool is capable of mining. = +Maximum toughness levels: = +This tool points to liquids. = +Tools and weapons = +Unknown Node = +Usage help: @1 = +Walking on this block is completely silent. = +Whenever you are not wielding any item, you use the hand which acts as a tool with its own capabilities. When you are wielding an item which is not a mining tool or a weapon it will behave as if it would be the hand. = +Yes = +You can not jump while standing on this block. = +any level = +level 0 = +level 0-@1 = +unknown = +Unknown item (@1) = +• @1: @2 = +• @1: @2 HP = +• @1: @2, @3 = +• Flowing range: @1 = +• No flowing = +• Not renewable = +• Renewable = +• Viscosity: @1 = +Itemstring: "@1" = +Durability: @1 uses = +Durability: @1 = +Mining durability: = +• @1, level @2: @3 uses = +• @1, level @2: Unlimited = +This block's rotation is affected by the way you place it: Place it on the floor or ceiling for a vertical orientation; place it at the side for a horizontal orientation. Sneaking while placing it leads to a perpendicular orientation instead. = diff --git a/mods/HELP/doc/doc_items/mod.conf b/mods/HELP/doc/doc_items/mod.conf new file mode 100644 index 000000000..74fa80dfc --- /dev/null +++ b/mods/HELP/doc/doc_items/mod.conf @@ -0,0 +1 @@ +name = doc_items diff --git a/mods/HELP/doc/doc_items/screenshot.png b/mods/HELP/doc/doc_items/screenshot.png new file mode 100644 index 000000000..8e7f5656c Binary files /dev/null and b/mods/HELP/doc/doc_items/screenshot.png differ diff --git a/mods/HELP/doc/doc_items/settingtypes.txt b/mods/HELP/doc/doc_items/settingtypes.txt new file mode 100644 index 000000000..8b9d635e8 --- /dev/null +++ b/mods/HELP/doc/doc_items/settingtypes.txt @@ -0,0 +1,16 @@ +#This feature is experimental! +#If enabled, the mod will show alternative group names which are a bit +#more readable than the internally used (but canonical) group names. For +#example, the group “wood” may be rendered as “Wood”, “leaves” as +#“Leaves and Needles”, “oddly_breakable_by_hand” as “Hand-breakable”, +#and so on. Note that these alternative names are only used for better +#understanding, they are not official. +#This feature might be removed in later versions if it becomes obsolete. +doc_items_friendly_group_names (Show “friendly” group names) bool false + +#If enabled, the mod will show the itemstring of the entry for each item to +#all players. If disabled, the itemstring will only be shown to players +#with the “give” or “debug” privilege. +#The itemstring is useful to power users and programmers and +#is used e.g. for the /give and /giveme commands. +doc_items_show_itemstrings (Show itemstrings) bool false diff --git a/mods/HELP/doc/modpack.txt b/mods/HELP/doc/modpack.txt new file mode 100644 index 000000000..e69de29bb