Roughly attempt to limit line length to 80
Wuzzy
parent
347f307119
commit
58018177f5
20
README.md
20
README.md
|
|
@ -1,20 +1,22 @@
|
|||
# Example mod for the Help modpack (`doc`, `doc_items`, etc.)
|
||||
This mod is for modders and useless for anyone else.
|
||||
It demonstrates the usage of the APIs of the Help mods. This should help you in getting
|
||||
started with this modpack.
|
||||
This example mod does not demonstrate everything, only the most frequently-needed features
|
||||
to help you get started. For most use cases, this knowledge might already suffice.
|
||||
Read `API.md` of the respective mods to learn how to use the Help mods properly.
|
||||
It demonstrates the usage of the APIs of the Help mods. This should help you
|
||||
in getting started with this modpack.
|
||||
This example mod does not demonstrate everything, only the most
|
||||
frequently-needed features to help you get started. For most use cases, this
|
||||
knowledge might already suffice. Read `API.md` of the respective mods to learn
|
||||
how to use the Help mods properly.
|
||||
|
||||
Using the APIs of the Help modpack helps to improve the overall quality and completeness
|
||||
of the entire help.
|
||||
Using the APIs of the Help modpack helps to improve the overall quality
|
||||
and completeness of the entire help.
|
||||
|
||||
This mod includes examples for the following mods:
|
||||
|
||||
* `doc_items`: In `doc_items.lua`, for item help. Start here!
|
||||
* `doc_items`: In `doc_items.lua` for item help. Start here!
|
||||
* `doc_identifier`: In `doc_identifier.lua`, for adding lookup tool support for custom entities.
|
||||
* `doc`: In `doc.lua`, for adding your own categories. For advanced modding.
|
||||
|
||||
Activate this mod in your world to see some example categories, entries and items added.
|
||||
Activate this mod in your world to see some example categories, entries and
|
||||
items added.
|
||||
|
||||
Read the source code files in this mod for some brief explanations.
|
||||
|
|
|
|||
86
doc.lua
86
doc.lua
|
|
@ -12,9 +12,10 @@ categories.
|
|||
doc.new_category("example1", {
|
||||
-- This is for humans and mandatory
|
||||
name = "Text Example",
|
||||
-- This category uses a preset formspec builder for displaying simple text
|
||||
-- This category uses a preset formspec builder for simple text
|
||||
build_formspec = doc.entry_builders.text
|
||||
-- Reminder: build_formspec determines how the entry data will be presented to the user
|
||||
--[[ Reminder: build_formspec determines how the entry data will be presented
|
||||
to the user ]]
|
||||
})
|
||||
|
||||
-- Entry for the aforementioned category. We add 2 entries
|
||||
|
|
@ -33,16 +34,17 @@ doc.new_entry("example1", "entity", {
|
|||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
-- Category with hidden entry.
|
||||
-- This is a category like the one before, but this time, we add one entry which starts hidden
|
||||
--[[ Category with hidden entry.
|
||||
This is a category like the one before, but this time, we add one entry
|
||||
which starts hidden. ]]
|
||||
doc.new_category("example_hide", {
|
||||
name = "Example Hidden",
|
||||
build_formspec = doc.entry_builders.text
|
||||
})
|
||||
|
||||
-- This entry will start hidden. The user will not see it until it gets revealed by using
|
||||
-- `doc.mark_entry_as_revealed`.
|
||||
-- TODO: Add example for that, too
|
||||
-- This entry will start hidden. The user will not see it until it gets
|
||||
-- revealed by using doc.mark_entry_as_revealed.
|
||||
-- TODO: Add example for that, too.
|
||||
doc.new_entry("example_hide", "hidden", {
|
||||
name = "Hidden Entry",
|
||||
hidden = true,
|
||||
|
|
@ -51,8 +53,8 @@ doc.new_entry("example_hide", "hidden", {
|
|||
|
||||
-------------------------------------------------------------------------------
|
||||
--[[ A simple category with 3 entries: Cities.
|
||||
Now we're getting somewhere! This time, we define a custom build_formspec function to display
|
||||
entry data dynamically. ]]
|
||||
Now we're getting somewhere! This time, we define a custom build_formspec
|
||||
function to display entry data dynamically. ]]
|
||||
doc.new_category("example2", {
|
||||
name = "Example: Cities",
|
||||
description = "Example category: Quick information about the cities of the world",
|
||||
|
|
@ -64,10 +66,12 @@ doc.new_category("example2", {
|
|||
end,
|
||||
|
||||
--[[ Sorting example ]]
|
||||
-- The entry data includes population as a number. This means we could (if we want to) define a custom sorting functino
|
||||
--[[ This affects the order of the entries. It makes sure that in the list of entries, the city with the highest population
|
||||
comes first. Custom sorting is entirely optional but it might make it easier for the user to navigate. But note that the
|
||||
default alphabetical sorting is often good enough. ]]
|
||||
--[[ The entry data includes population as a number. This means we could (if we
|
||||
want to) define a custom sorting functin. This affects the order of the entries.
|
||||
It makes sure that in the list of entries, the city with the highest population
|
||||
comes first. Custom sorting is entirely optional but it might make it easier
|
||||
for the user to navigate. But note that the default alphabetical sorting is
|
||||
often good as well. ]]
|
||||
sorting = "function",
|
||||
sorting_data = function(entry1, entry2)
|
||||
return entry1.data.population > entry2.data.population
|
||||
|
|
@ -98,17 +102,20 @@ doc.new_entry("example2", "tripoli", {
|
|||
})
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
--[[ Formspec category: This category shows how you can add widgets in entries and even interact with them ]]
|
||||
--[[ Formspec category: This category shows how you can add widgets in entries
|
||||
and even interact with them ]]
|
||||
doc.new_category("example3", {
|
||||
name="Example: Formspec",
|
||||
description="Example category for manual freeform formspec entries",
|
||||
-- This is a built-in formspec builder. In this case, the entry data is expected
|
||||
-- to contains the full formspec definition for any entry. This is useful if you want
|
||||
-- to build every entry by hand. The downside is that it doesn't allow for dynamic entries.
|
||||
--[[ This is a built-in formspec builder. In this case, the entry data
|
||||
is expected to contains the full formspec definition for any entry.
|
||||
This is useful if you want to build every entry by hand. The downside
|
||||
is that it doesn't allow for dynamic entries. ]]
|
||||
build_formspec = doc.entry_builders.formspec,
|
||||
|
||||
--[[ Sorting example ]]
|
||||
-- This demonstates the custom sorting type. In the entry list, the entries will appear in the exact order as specified
|
||||
--[[ This demonstates the custom sorting type. In the entry list, the
|
||||
entries will appear in the exact order as specified. ]]
|
||||
sorting = "custom",
|
||||
sorting_data = { "simple", "widgets", "testbutton" },
|
||||
})
|
||||
|
|
@ -133,10 +140,12 @@ doc.new_entry("example3", "testbutton", {
|
|||
-- … and here we react on the button event by writing something into the chat
|
||||
-- This demonstrates how you can use an entry widget for custom actions
|
||||
minetest.register_on_player_receive_fields(function(player, formname, fields)
|
||||
-- Condition 1: This checks if the player is even using the entry tab. This check is always the same
|
||||
-- Condition 1: This checks if the player is even using the entry tab.
|
||||
-- This check is always the same.
|
||||
if formname == "doc:entry" then
|
||||
local playername = player:get_player_name()
|
||||
-- Condition 2: this check is required to make sure we “listen” to the correct entry
|
||||
-- Condition 2: this check is required to make sure we “listen”
|
||||
-- to the correct entry
|
||||
local category_id, entry_id = doc.get_selection(playername)
|
||||
if category_id == "example3" and entry_id == "testbutton" then
|
||||
-- Condition 3: Has the widget we actually care about been pressed?
|
||||
|
|
@ -150,11 +159,13 @@ end)
|
|||
|
||||
-------------------------------------------------------------------------------
|
||||
--[[ This category shows off the gallery widget ]]
|
||||
-- FIXME: Depends on Minetest Game
|
||||
doc.new_category("example4", {
|
||||
name="Example: Galleries",
|
||||
build_formspec = function(data, playername)
|
||||
local formspec = ""
|
||||
-- Mostly using default values, but we want an aspect ratio of 1:1 (square).
|
||||
--[[ Mostly using default values, but we want an aspect ratio of
|
||||
1:1 (square). ]]
|
||||
formspec = formspec .. doc.widgets.gallery(data, playername, nil, nil, 1)
|
||||
return formspec
|
||||
end,
|
||||
|
|
@ -164,27 +175,50 @@ doc.new_category("example4", {
|
|||
doc.new_entry("example4", "gallery2", {
|
||||
name="Gallery with 2 images",
|
||||
-- The entry data will be also fed into `doc_widgets_gallery`
|
||||
data = {{image="default_grass.png"}, {image="default_book.png"}},
|
||||
data = {
|
||||
{image="default_grass.png"},
|
||||
{image="default_book.png"}
|
||||
},
|
||||
})
|
||||
|
||||
doc.new_entry("example4", "gallery3", {
|
||||
name="Gallery with 3 images",
|
||||
data = {{image="default_grass.png"}, {image="default_book.png"}, {image="default_papyrus.png"}},
|
||||
data = {
|
||||
{image="default_grass.png"},
|
||||
{image="default_book.png"},
|
||||
{image="default_papyrus.png"}},
|
||||
})
|
||||
|
||||
doc.new_entry("example4", "gallery4", {
|
||||
name="Gallery with 4 images",
|
||||
data = {{image="default_dirt.png"}, {image="default_leaves.png"}, {image="default_brick.png"}, {image="default_gold_block.png"}},
|
||||
data = {
|
||||
{image="default_dirt.png"},
|
||||
{image="default_leaves.png"},
|
||||
{image="default_brick.png"},
|
||||
{image="default_gold_block.png"}
|
||||
},
|
||||
})
|
||||
|
||||
doc.new_entry("example4", "gallery5", {
|
||||
name="Gallery with 5 images",
|
||||
data = {{image="default_dirt.png"}, {image="default_leaves.png"}, {image="default_brick.png"}, {image="default_gold_block.png"}, {image="default_bronze_block.png"}},
|
||||
data = {
|
||||
{image="default_dirt.png"},
|
||||
{image="default_leaves.png"},
|
||||
{image="default_brick.png"},
|
||||
{image="default_gold_block.png"},
|
||||
{image="default_bronze_block.png"}
|
||||
},
|
||||
})
|
||||
|
||||
doc.new_entry("example4", "gallery6", {
|
||||
name="Gallery with 6 images",
|
||||
data = {{image="default_grass.png"},{image="default_dirt.png"}, {image="default_leaves.png"}, {image="default_brick.png"}, {image="default_gold_block.png"}, {image="default_bronze_block.png"}},
|
||||
data = {
|
||||
{image="default_grass.png"},
|
||||
{image="default_dirt.png"},
|
||||
{image="default_leaves.png"},
|
||||
{image="default_brick.png"},
|
||||
{image="default_gold_block.png"},
|
||||
{image="default_bronze_block.png"}},
|
||||
})
|
||||
|
||||
doc.new_entry("example4", "gallery7", {
|
||||
|
|
|
|||
|
|
@ -9,14 +9,18 @@ minetest.register_entity("doc_example:entity", {
|
|||
collide_with_objects = true,
|
||||
visual = "cube",
|
||||
size = { x = 0.2, y = 0.2, z = 0.2 },
|
||||
textures = {"unknown_object.png", "unknown_object.png", "unknown_object.png", "unknown_object.png", "unknown_object.png", "unknown_object.png"},
|
||||
textures = {
|
||||
"unknown_object.png", "unknown_object.png",
|
||||
"unknown_object.png", "unknown_object.png",
|
||||
"unknown_object.png", "unknown_object.png"
|
||||
},
|
||||
hp_max = 1,
|
||||
})
|
||||
|
||||
--[[ This is the actual code you need to add doc_identifier support.
|
||||
The following code means, whenever you use the lookup tool on the example entity,
|
||||
the entry “entity” in category “example1” will be shown. ]]
|
||||
The following code means, whenever you use the lookup tool on the example
|
||||
entity, the entry “entity” in category “example1” will be shown. ]]
|
||||
doc.sub.identifier.register_object("doc_example:entity", "example1", "entity")
|
||||
|
||||
--[[ NOTE: If you don't do this, the lookup tool will show an error message when
|
||||
you use it on this entity. ]]
|
||||
--[[ NOTE: If you don't do this, the lookup tool will show an error message
|
||||
when you use it on this entity. ]]
|
||||
|
|
|
|||
|
|
@ -18,8 +18,9 @@ minetest.register_craftitem("doc_example:item1", {
|
|||
description = "doc_example test item 1",
|
||||
-- This is the typical way to add extended item descriptions.
|
||||
_doc_items_longdesc = "This is an useless example item. It does nothing.",
|
||||
-- This simple item is self-explanatory, so we can omit _doc_items_usagehelp
|
||||
-- For more fields, see API.md of doc_items
|
||||
--[[ This simple item is self-explanatory, so we can omit
|
||||
-- _doc_items_usagehelp.
|
||||
For more fields, see API.md of doc_items. ]]
|
||||
|
||||
-- Just an example group
|
||||
group = { example = 1 },
|
||||
|
|
@ -39,8 +40,9 @@ minetest.register_craftitem("doc_example:item3", {
|
|||
minetest.register_tool("doc_example:tool", {
|
||||
description = "doc_example chat tool",
|
||||
_doc_items_longdesc = "This tool is able to write something into the chat.",
|
||||
-- This tool has an unique non-standard use (i.e. not mining, not melee combat, etc.), so we should add this field as well
|
||||
-- Read API.md of doc_items for guidelines to write good help texts
|
||||
--[[ This tool has an unique non-standard use (i.e. not mining, not melee combat,
|
||||
etc.), so we should add this field as well
|
||||
Read API.md of doc_items for guidelines to write good help texts ]]
|
||||
_doc_items_usagehelp = "Punch to send a chat message.",
|
||||
-- The tool entry will be visible for everyone at start
|
||||
_doc_items_hidden = false,
|
||||
|
|
@ -50,14 +52,16 @@ minetest.register_tool("doc_example:tool", {
|
|||
})
|
||||
|
||||
--[[ FACTOIDS
|
||||
Reminder: A factoid is an automatically generated text based on the item definition.
|
||||
This section will demonstrate the use of factoids
|
||||
Reminder: A factoid is an automatically generated text based on the item
|
||||
definition. This section will demonstrate the use of factoids.
|
||||
]]
|
||||
|
||||
-- This adds an automatically generated text for all items which are a member of the example group
|
||||
--[[ This adds an automatically generated text for all items which are a member
|
||||
of the example group. ]]
|
||||
doc.sub.items.register_factoid("craftitems", "groups", function(category_id, def)
|
||||
if def.groups.example then
|
||||
return string.format("Example factoid: This item is member of the example group at rating %d.", def.groups.example)
|
||||
return string.format("Example factoid: This item is member of the example group at rating %d.",
|
||||
def.groups.example)
|
||||
else
|
||||
return ""
|
||||
end
|
||||
|
|
@ -65,23 +69,26 @@ end)
|
|||
|
||||
-- This factoid adds the drawtype for nodes
|
||||
doc.sub.items.register_factoid("nodes", "misc", function(category_id, def)
|
||||
return string.format("Example factoid: This item has the drawtype “%s”.", def.drawtype)
|
||||
return string.format("Example factoid: This item has the drawtype “%s”.",
|
||||
def.drawtype)
|
||||
end)
|
||||
|
||||
|
||||
--[[ USING ENTRY ALIASES
|
||||
Sometimes, mods register multiple items for basically the same thing in different “states”.
|
||||
One example is the furnace from Minetest Game (default:furnace and default:furnace_active).
|
||||
If the node in all “states” is similar enough, you might consider to suppress the entries
|
||||
of some of the entries in order to concentrate information on a single entry. If you do this, you
|
||||
also have to register aliases since the lookup tool will stop working on nodes with suppressed
|
||||
entries.
|
||||
Suppressing entries may also be useful to combine large lists of similar items, but be careful
|
||||
not to overdo it and throw away potentionally valuable information in the process.
|
||||
Sometimes, mods register multiple items for basically the same thing in
|
||||
different “states”. One example is the furnace from Minetest Game
|
||||
(default:furnace and default:furnace_active).
|
||||
If the node in all “states” is similar enough, you might consider to
|
||||
suppress the entries of some of the entries in order to concentrate
|
||||
information on a single entry. If you do this, you also have to register
|
||||
aliases since the lookup tool will stop working on nodes with suppressed
|
||||
entries. Suppressing entries may also be useful to combine large lists
|
||||
of similar items, but be careful not to overdo it and throw away
|
||||
potentionally valuable information in the process.
|
||||
|
||||
The following code shows two nodes which changes its textures when punched.
|
||||
For the player, doc_example:node2 is basically the same as doc_example:node1, only with a
|
||||
different textures. Only one entry is created for both nodes.
|
||||
The following code shows two nodes which changes its textures when punched.
|
||||
For the player, doc_example:node2 is basically the same as doc_example:node1,
|
||||
only with a different texture. Only one entry is created for both nodes.
|
||||
]]
|
||||
-- Node for the first “state”. This no
|
||||
minetest.register_node("doc_example:node1", {
|
||||
|
|
|
|||
Loading…
Reference in New Issue