365 lines
16 KiB
Markdown
365 lines
16 KiB
Markdown
# 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 (discarding text after the first newline). 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 games 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 games 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
|
|
|
|
|
|
## Groups interpretations
|
|
Nodes which are technically a liquid will not be considered liquids by this mod
|
|
if the group `fake_liquid=1` is used. Useful for stuff like cobwebs.
|
|
|
|
|
|
|
|
## 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.
|