diff options
| -rw-r--r-- | API.md | 19 | ||||
| -rw-r--r-- | API.md.bak | 321 |
2 files changed, 338 insertions, 2 deletions
@@ -160,7 +160,7 @@ 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. +difference is too small to justify two separate entries (e.g. burning furnace vs inactive furnace, because the gameplay mechanics are identical for both). @@ -174,7 +174,22 @@ 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 mark an entry +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. diff --git a/API.md.bak b/API.md.bak new file mode 100644 index 0000000..226792f --- /dev/null +++ b/API.md.bak @@ -0,0 +1,321 @@ +# 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. |