diff options
Diffstat (limited to 'API.md.bak')
| -rw-r--r-- | API.md.bak | 321 |
1 files changed, 0 insertions, 321 deletions
diff --git a/API.md.bak b/API.md.bak deleted file mode 100644 index 226792f..0000000 --- a/API.md.bak +++ /dev/null @@ -1,321 +0,0 @@ -# API documentation for `doc_items` -## Introduction -This document explains the API of `doc_items`. It contains a reference of -all functions. - -***Warning***: This mod is still in alpha stage, expect bugs and missing -features! - -## 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 - -### 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 seperate 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 -* `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.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. |