diff options
| -rw-r--r-- | API.md | 162 | ||||
| -rw-r--r-- | init.lua | 73 |
2 files changed, 49 insertions, 186 deletions
@@ -33,12 +33,25 @@ When using this method, your mod does not need additional dependencies. See below for some recommendations on writing good help texts. -If you need to set the help texts of nodes you don't register, or you -want to overwrite existing help texts, use `doc.sub.items.set_items_longdesc` -and `doc.sub.items.set_items_longdesc` (see below). 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, or “Nameless entry” if it is `nil`. + +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 @@ -131,28 +144,22 @@ to avoid redundancy and to increase consistency for simple things. Read * `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 -### Forced and suppressed items -By default, an entry for each item is added, except for items without a -description (`description == nil`). This default behaviour can be changed. - -Entries can be forced, which means they will be forcefully added, against the -default behaviour. Entries can be suppressed which means they will not -be added at all. - -The default behaviour can be overridden by two ways: Groups and a function call. +### 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. -Use groups when you can directly define an item (in other words, in **your** -mods). +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. -To force the entry of an item, add the item to the group `in_doc = 1`. -To suppress the entry of an item, add the item to the group `not_in_doc = 1`. - -There are also the functions `doc.sub.items.add_forced_item_entries` and -`doc.sub.items.add_suppressed_item_entries` which forces or suppress certain -item entries. You should **only** use these functions when you can not use groups. - -When there are contradictions, forcing a group takes precedence over suppressing -a group. +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 @@ -161,62 +168,16 @@ 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. -To hide an entry, add the item in question to the group `hidden_from_doc = 1`. -If this is not possible, use `doc.sub.items.add_hidden_item_entries`. +By default, all entries are hidden except air and the hand. -## New item fields -This mod adds support for new fields of the item definition: - -* `_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, `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, or “Nameless entry” if it is `nil`. +To mark an entry as hidden, add the field `_doc_items_hidden=true` to its +item definition. To mark an entry ## Functions This is the reference of all available functions in this API. -### `doc.sub.items.set_items_longdesc(longdesc_table)` -Sets the long description of items. `longdesc_table` is -a table where the keys are the itemstrings and the values -are the the description strings for each item. - -Note the preferred method to set the long description is by using -the item definition field `_doc_items_longdesc`. - -This function is intended to be used to set the long description -for items which your mods do not register by themselves. - -#### Default long descriptions -`doc_items` registers two long descriptions by default: For air -and the hand (default tool). -By using this function, you can overwrite these default descriptions. - -The default hand description is kept very generic, but it might miss -some information on more complex subgames. In this case, the hand's -long description might need overwriting. - -#### Example - doc.sub.items.set_items_longdesc({ - ["example:painter"] = "Paints blocks.", - ["example:flower"] = "Likes to grow on grass when it is near water.", - }) - -### `doc.sub.items.set_items_usagehelp(usagehelp_table)` -Sets the usage help texts of items. The function is completely analog -to `doc.sub.items.set_items_longdesc` and has the same syntax, it -only differs in semantics. - -#### Example - doc.sub.items.set_items_usagehelp({ - ["example:painter"] = "Punch any block to paint it red.", - }) - ### `doc.sub.items.register_factoid(category_id, factoid_type, factoid_generator)` -***Note***: This function not fully implemented. It currently supports only -factoids for nodes. +***Note***: This function not fully implemented. It currently supports group-based factoids. Add a custom factoid (see above) for the specified category. @@ -309,56 +270,9 @@ The intention of this function is to give a short rundown of the groups which are notable as they are important to gameplay in some way yet don't deserve a full-blown factoid. -### `doc.sub.items.add_forced_item_entries(itemstrings)` -Adds items which will be forced to be added to the entry list, even if -the item is not in creative inventory. - -`itemstrings` is a table of itemstrings of items to force the entries for. - -***Note***: The recommended way to force item entries is by adding the item -to the group `in_doc=1` (see above). Only use this function when you can -not use groups. - -### `doc.sub.items.add_suppressed_item_entries(itemstrings)` -Adds items which will be forced to **not** be added to the entry list. - -`itemstrings` is a table of itemstrings of items to force the entries for. - -***Note***: The recommended way to suppress item entries is by adding the -item to the group `not_in_doc=1` (see above). Only use this function when you -can not use groups. - -### `doc.sub.items.add_hidden_item_entries(itemstrings)` -Adds items which will be hidden from the entry list initially. Note the -entries still exist and might be unlocked later. - -`itemstrings` is a table of itemstrings of items for which their entries should -be hidden. - -***Note***: The recommended way to hide item entries is by adding the -item to the group `hide_from_doc=1` (see above). Only use this function when you -can not use groups. - -### `doc.sub.items.add_item_name_overrides(itemstrings)` -Overrides the entry names of entries to the provided names. By default, -each entry name equals the item's `description` field. - -`itemstrings` is a table in which the keys are itemstrings and the values -are the entry titles you want to use for those items. - -#### Preset overrides -The following item name overrides are defined by default: - - { [""] = "Hand", - ["air"] = "Air" } - -It is possible to override **these** names, just use the function normally. - -#### Example - doc.sub.items.add_item_name_overrides({ - ["air"] = "Air", -- original description: “Air (You hacker you!)” - ["farming:wheat_8"] = "Wheat Plant", -- Item description was empty - ["example:node"] = "My Custom Name", - }) +## 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. @@ -33,11 +33,6 @@ end local groupdefs = {} local mininggroups = {} local miscgroups = {} --- List of forcefully added (true) and hidden (false) items -local forced_items = { - ["ignore"] = false -} -local hidden_items = {} local item_name_overrides = { [""] = S("Hand"), ["air"] = S("Air") @@ -911,25 +906,6 @@ doc.sub.items.help.longdesc = {} doc.sub.items.help.usagehelp = {} doc.sub.items.help.image = {} --- Sets the long description for a table of items -function doc.sub.items.set_items_longdesc(longdesc_table) - for k,v in pairs(longdesc_table) do - doc.sub.items.help.longdesc[k] = v - end -end --- Sets the usage help texts for a table of items -function doc.sub.items.set_items_usagehelp(usagehelp_table) - for k,v in pairs(usagehelp_table) do - doc.sub.items.help.usagehelp[k] = v - end -end - -function doc.sub.items.add_item_image_overrides(image_overrides) - for itemstring, new_image in pairs(image_overrides) do - doc.sub.items.help.image[itemstring] = new_image - end -end - -- Register group definition stuff -- More (user-)friendly group names to replace the rather technical names -- for better understanding @@ -949,37 +925,6 @@ function doc.sub.items.add_notable_groups(groupnames) end end --- Add items which will be forced to be added to the item list, --- even if the item is not in creative inventory -function doc.sub.items.add_forced_item_entries(itemstrings) - for i=1,#itemstrings do - forced_items[itemstrings[i]] = true - end -end - --- Add items which will be forced *not* to be added to the item list -function doc.sub.items.add_suppressed_item_entries(itemstrings) - for i=1,#itemstrings do - forced_items[itemstrings[i]] = false - end -end - --- Add items which will be hidden from the entry list, but their entries --- are still created. -function doc.sub.items.add_hidden_item_entries(itemstrings) - for i=1,#itemstrings do - hidden_items[itemstrings[i]] = true - end -end - --- Register a list of entry names where the entry name should differ --- from the original item description -function doc.sub.items.add_item_name_overrides(itemstrings) - for internal, real in pairs(itemstrings) do - item_name_overrides[internal] = real - end -end - local function gather_descs() local help = doc.sub.items.help @@ -1004,7 +949,7 @@ local function gather_descs() -- 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 - elseif help.longdesc["air"] == nil then + else help.longdesc["air"] = S("A transparent block, basically empty space. It is usually left behind after digging something.") end @@ -1013,7 +958,7 @@ local function gather_descs() for id, def in pairs(deftable) do local name, ld, uh, im local forced = false - if (forced_items[id] == true or def.groups.in_doc or def._doc_items_create_entry == true) and def ~= nil then forced = true end + if (def._doc_items_create_entry == true) and def ~= nil then forced = true end if def._doc_items_entry_name ~= nil then name = def._doc_items_entry_name end @@ -1023,7 +968,7 @@ local function gather_descs() if name == nil then name = def.description end - if not (((def.description == nil or def.description == "") and def._doc_items_entry_name == nil) or def.groups.not_in_doc or forced_items[id] == false or def._doc_items_create_entry == false) or forced then + if not (((def.description == nil or def.description == "") and def._doc_items_entry_name == nil) or def._doc_items_create_entry == false) or forced then if def._doc_items_longdesc then ld = def._doc_items_longdesc end @@ -1072,12 +1017,16 @@ local function gather_descs() -- Add entry for the default tool (“hand”) -- Custom longdesc and usagehelp may be set by mods through the add_helptexts function - if minetest.registered_items[""]._doc_items_longdesc then - help.longdesc[""] = minetest.registered_items[""]._doc_items_longdesc - elseif help.longdesc[""] == nil then + local handdef = minetest.registered_items[""] + 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.new_entry("tools", "", { name = item_name_overrides[""], hidden = false, @@ -1085,7 +1034,7 @@ local function gather_descs() longdesc = help.longdesc[""], usagehelp = help.usagehelp[""], itemstring = "", - def = minetest.registered_items[""] + def = handdef, } }) -- Add tool entries |