2016-12-19 05:52:49 -08:00
--[[ Example for Documentation System [`doc`].
2016-12-20 09:47:35 -08:00
Reminder : This mod is the core of the Help modpack . It is thus rather low - level .
Use this to add your very own categories and entries , and to use some utility
functions .
2016-12-19 05:52:49 -08:00
This example demonstrates how to add categories and how to add entries into them .
2016-12-20 09:47:35 -08:00
It also demonstrates the versatility of the very important ` build_formspec `
function used in category definitions . ] ]
2016-12-19 05:52:49 -08:00
2016-12-20 09:47:35 -08:00
-- Let's start with a very simple text-based category.
-- This category only contains simple text.
2016-12-28 06:48:27 -08:00
doc.add_category ( " example1 " , {
2016-12-20 09:47:35 -08:00
-- This name is for humans and mandatory
2016-12-20 10:08:45 -08:00
name = " Example: Text " ,
2016-12-20 04:48:16 -08:00
-- This category uses a preset formspec builder for simple text
2016-12-15 14:27:11 -08:00
build_formspec = doc.entry_builders . text
2016-12-20 04:48:16 -08:00
--[[ Reminder: build_formspec determines how the entry data will be presented
to the user ] ]
2016-12-15 14:27:11 -08:00
} )
2016-12-28 06:48:27 -08:00
doc.add_category ( " sexample " , {
name = " Example: Empty " ,
} )
2016-12-20 09:47:35 -08:00
-- Entries for the aforementioned category. We add 2 entries.
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example1 " , " text " , {
2016-12-20 09:47:35 -08:00
-- This is for the entry title in the user interface, it's mandatory.
2016-12-15 14:27:11 -08:00
name = " Text example " ,
2016-12-19 05:52:49 -08:00
-- For this category, the entry data is simply the text to be displayed
2016-12-15 14:27:11 -08:00
data = " Lorem Minetest dolor sit amet. Bla bla bla bla Minetest bla bla bla bla Mese bla. Bla bla bla bla bla, celeron55 bla bla, bla. " ,
} )
2016-12-19 10:00:52 -08:00
-- We will use this entry in doc_identifier.lua
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example1 " , " entity " , {
2016-12-19 10:00:52 -08:00
name = " Entity entry " ,
2016-12-20 09:47:35 -08:00
data = " This is the entry for the entity (added in doc_identifier.lua). The example entity is just a simple cube which floats in the air. Punch it to destroy it. " ,
2016-12-19 10:00:52 -08:00
} )
2016-12-19 05:52:49 -08:00
-------------------------------------------------------------------------------
2016-12-20 04:48:16 -08:00
--[[ Category with hidden entry.
2016-12-20 09:47:35 -08:00
This is a category like the one before , but this time , we add a hidden entry .
] ]
2016-12-28 06:48:27 -08:00
doc.add_category ( " example_hide " , {
2016-12-20 10:08:45 -08:00
name = " Example: Hidden entry " ,
2016-12-15 14:27:11 -08:00
build_formspec = doc.entry_builders . text
} )
2016-12-20 04:48:16 -08:00
-- This entry will start hidden. The user will not see it until it gets
2016-12-20 04:57:50 -08:00
-- revealed by using doc.mark_entry_as_revealed. Note that you should
-- NOT hide entries if there is no way for the player to reveal them.
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example_hide " , " hidden " , {
2016-12-15 14:27:11 -08:00
name = " Hidden Entry " ,
2016-12-19 05:52:49 -08:00
hidden = true ,
2016-12-15 14:27:11 -08:00
data = " This entry is hidden. " ,
} )
2016-12-20 04:57:50 -08:00
-- This chat command demonstrates how to use `doc.mark_entry_as_revealed`.
minetest.register_chatcommand ( " doc_example_reveal " , {
param = " " ,
description = " Reveal the hidden entry of the doc_example mod " ,
privs = { } ,
func = function ( playername , params )
-- This reveals the previously created entry
doc.mark_entry_as_revealed ( playername , " example_hide " , " hidden " )
2016-12-20 09:47:35 -08:00
2016-12-20 04:57:50 -08:00
minetest.chat_send_player ( playername , " The hidden doc_example entry has been revealed! Look into the category “Example Hidden” to see it. " )
end ,
} )
2016-12-20 09:47:35 -08:00
--[[ In actual games, you would probably want to invent more engaging ways to
2016-12-20 04:57:50 -08:00
reveal entries . ; - ) ] ]
2016-12-19 05:52:49 -08:00
-------------------------------------------------------------------------------
--[[ A simple category with 3 entries: Cities.
2016-12-20 04:48:16 -08:00
Now we ' re getting somewhere! This time, we define a custom build_formspec
function to display entry data dynamically . ] ]
2016-12-28 06:48:27 -08:00
doc.add_category ( " example2 " , {
2016-12-19 05:52:49 -08:00
name = " Example: Cities " ,
description = " Example category: Quick information about the cities of the world " ,
2016-12-20 09:47:35 -08:00
--[[ This is a manual formspec builder: This will parse the entry data and
turns it into nice formspec widgets .
Reminder : We MUST return a valid formspec string ! ] ]
2016-12-15 14:27:11 -08:00
build_formspec = function ( data )
return " label[0,1;Description: " .. minetest.formspec_escape ( data.description ) .. " ] " ..
" label[0,2;Population: " .. data.population .. " ] "
end ,
2016-12-19 05:52:49 -08:00
2016-12-20 09:47:35 -08:00
--[[ ADVANCED: Sorting example ]]
2016-12-20 04:48:16 -08:00
--[[ The entry data includes population as a number. This means we could (if we
2016-12-20 09:25:17 -08:00
want to ) define a custom sorting function . This affects the order of the entries .
2016-12-20 04:48:16 -08:00
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 . ] ]
2016-12-19 05:52:49 -08:00
sorting = " function " ,
sorting_data = function ( entry1 , entry2 )
return entry1.data . population > entry2.data . population
end ,
2016-12-15 14:27:11 -08:00
} )
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example2 " , " london " , {
2016-12-15 14:27:11 -08:00
name = " London " ,
2016-12-19 05:52:49 -08:00
-- Reminder: This data is put into the previous build_formspec function
2016-12-15 14:27:11 -08:00
data = {
description = " London is the capital of the United Kingdom. " ,
population = 8538689 ,
} ,
} )
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example2 " , " shanghai " , {
2016-12-15 14:27:11 -08:00
name = " Shanghai " ,
data = {
description = " Shanghai lies in China and is one of the biggest cities in the world. " ,
population = 23019148 ,
} ,
} )
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example2 " , " tripoli " , {
2016-12-15 14:27:11 -08:00
name = " Tripoli " ,
data = {
description = " Tripoli is the capital of Lybia. " ,
population = 1780000 ,
} ,
} )
2016-12-19 05:52:49 -08:00
-------------------------------------------------------------------------------
2016-12-20 04:48:16 -08:00
--[[ Formspec category: This category shows how you can add widgets in entries
and even interact with them ] ]
2016-12-28 06:48:27 -08:00
doc.add_category ( " example3 " , {
2016-12-15 14:27:11 -08:00
name = " Example: Formspec " ,
2016-12-20 09:25:17 -08:00
description = " Example category for manual free-form formspec entries " ,
2016-12-20 04:48:16 -08:00
--[[ 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. ]]
2016-12-15 14:27:11 -08:00
build_formspec = doc.entry_builders . formspec ,
2016-12-19 05:52:49 -08:00
--[[ Sorting example ]]
2016-12-20 09:25:17 -08:00
--[[ This demonstrates the custom sorting type. In the entry list, the
2016-12-20 04:48:16 -08:00
entries will appear in the exact order as specified . ] ]
2016-12-19 05:52:49 -08:00
sorting = " custom " ,
2016-12-20 10:06:28 -08:00
sorting_data = { " simple_bad " , " simple_good " , " multi " , " testbutton " } ,
2016-12-15 14:27:11 -08:00
} )
2016-12-20 10:06:28 -08:00
-- Just an entry with a label (BAD example)
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example3 " , " simple_bad " , {
2016-12-15 14:27:11 -08:00
name = " Label " ,
2016-12-20 10:06:28 -08:00
-- Please note the coordinates are shoddily chosen here, the don't respect
-- the Documention System formspec boundaries at all, so this is just a guess.
data = " label[5,5;Just a bad, bad label.] "
2016-12-15 14:27:11 -08:00
} )
2016-12-20 10:06:28 -08:00
-- Just an entry with a label (good example)
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example3 " , " simple_good " , {
2016-12-20 10:06:28 -08:00
name = " Label " ,
--[[ This is the proper way to add widgets (this is also how you should do it in build_formspec):
Defining the coordinates relative to the Documentation System ' s boundaries. In this case,
the label will be at the top right . ] ]
data = " label[ " .. doc.FORMSPEC . ENTRY_START_X .. " , " .. doc.FORMSPEC . ENTRY_START_Y .. " ;Just a good label.] "
} )
-- Now let's get crazy with MULTIPLE formspec entries. How awesome is that?
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example3 " , " multi " , {
2016-12-20 10:06:28 -08:00
name = " Label " ,
-- Label, just like before
data = " label[ " .. doc.FORMSPEC . ENTRY_START_X .. " , " .. doc.FORMSPEC . ENTRY_START_Y .. " ;Just another label.] " ..
-- Note the different Y offsets
" button[ " .. doc.FORMSPEC . ENTRY_START_X .. " , " .. ( doc.FORMSPEC . ENTRY_START_Y + 1 ) .. " ;5,1;example_useless;Useless button] " ..
" button[ " .. doc.FORMSPEC . ENTRY_START_X .. " , " .. ( doc.FORMSPEC . ENTRY_START_Y + 2 ) .. " ;5,1;example_useless;Useless button 2] " ..
" button[ " .. doc.FORMSPEC . ENTRY_START_X .. " , " .. ( doc.FORMSPEC . ENTRY_START_Y + 3 ) .. " ;5,1;example_useless;Useless button 3] "
-- As you see, it's special at all. It's a normal formspec string, just longer.
2016-12-15 14:27:11 -08:00
} )
2016-12-20 10:06:28 -08:00
-- This entry will be interactive.
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example3 " , " testbutton " , {
2016-12-15 14:27:11 -08:00
name = " Event Button " ,
-- This button actually will be used for an event …
2016-12-20 10:06:28 -08:00
data = " button[ " .. doc.FORMSPEC . ENTRY_START_X .. " , " .. doc.FORMSPEC . ENTRY_START_Y .. " ;5,1;example_button;Event] " ,
2016-12-15 14:27:11 -08:00
} )
2016-12-19 05:52:49 -08:00
-- … 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
2016-12-15 14:27:11 -08:00
minetest.register_on_player_receive_fields ( function ( player , formname , fields )
2016-12-20 04:48:16 -08:00
-- Condition 1: This checks if the player is even using the entry tab.
-- This check is always the same.
2016-12-15 14:27:11 -08:00
if formname == " doc:entry " then
local playername = player : get_player_name ( )
2016-12-20 04:48:16 -08:00
-- Condition 2: this check is required to make sure we “listen”
-- to the correct entry
2016-12-15 14:27:11 -08:00
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?
if fields.example_button then
-- All conditions are met! Now the custom action can be executed
minetest.chat_send_player ( playername , " You have pressed the event button! " )
end
end
end
end )
2016-12-19 05:52:49 -08:00
-------------------------------------------------------------------------------
2016-12-20 10:07:59 -08:00
--[[ This category demonstrates the use of the gallery widget. ]]
2016-12-20 04:48:16 -08:00
-- FIXME: Depends on Minetest Game
2016-12-28 06:48:27 -08:00
doc.add_category ( " example4 " , {
2016-12-15 14:27:11 -08:00
name = " Example: Galleries " ,
build_formspec = function ( data , playername )
2016-12-20 10:07:59 -08:00
-- The trick here is to include doc.widgets.gallery into the custom
-- build_formspec definition.
2016-12-15 14:27:11 -08:00
local formspec = " "
2016-12-20 04:48:16 -08:00
--[[ Mostly using default values, but we want an aspect ratio of
1 : 1 ( square ) . ] ]
2016-12-15 14:27:11 -08:00
formspec = formspec .. doc.widgets . gallery ( data , playername , nil , nil , 1 )
return formspec
end ,
} )
-- Several gallery entries
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example4 " , " gallery2 " , {
2016-12-15 14:27:11 -08:00
name = " Gallery with 2 images " ,
2016-12-19 05:52:49 -08:00
-- The entry data will be also fed into `doc_widgets_gallery`
2016-12-20 04:48:16 -08:00
data = {
{ image = " default_grass.png " } ,
{ image = " default_book.png " }
} ,
2016-12-15 14:27:11 -08:00
} )
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example4 " , " gallery3 " , {
2016-12-15 14:27:11 -08:00
name = " Gallery with 3 images " ,
2016-12-20 04:48:16 -08:00
data = {
{ image = " default_grass.png " } ,
{ image = " default_book.png " } ,
{ image = " default_papyrus.png " } } ,
2016-12-15 14:27:11 -08:00
} )
2016-12-28 06:48:27 -08:00
--[[ The default gallery size is 3. But this gallery has 4 images.
The Documentation System automatically adds “ scroll buttons ”
if the number of images exceeds the gallery size ] ]
doc.add_entry ( " example4 " , " gallery4 " , {
2016-12-15 14:27:11 -08:00
name = " Gallery with 4 images " ,
2016-12-20 04:48:16 -08:00
data = {
{ image = " default_dirt.png " } ,
{ image = " default_leaves.png " } ,
{ image = " default_brick.png " } ,
{ image = " default_gold_block.png " }
} ,
2016-12-15 14:27:11 -08:00
} )
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example4 " , " gallery5 " , {
2016-12-15 14:27:11 -08:00
name = " Gallery with 5 images " ,
2016-12-20 04:48:16 -08:00
data = {
{ image = " default_dirt.png " } ,
{ image = " default_leaves.png " } ,
{ image = " default_brick.png " } ,
{ image = " default_gold_block.png " } ,
{ image = " default_bronze_block.png " }
} ,
2016-12-15 14:27:11 -08:00
} )
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example4 " , " gallery6 " , {
2016-12-15 14:27:11 -08:00
name = " Gallery with 6 images " ,
2016-12-20 04:48:16 -08:00
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 " } } ,
2016-12-15 14:27:11 -08:00
} )
2016-12-19 04:31:59 -08:00
2016-12-28 06:48:27 -08:00
doc.add_entry ( " example4 " , " gallery7 " , {
2016-12-15 14:27:11 -08:00
name = " Gallery with 7 item images " ,
data = {
2016-12-19 04:31:59 -08:00
-- You can use this syntax to display item images instead of normal textures
2016-12-15 14:27:11 -08:00
{ image = " default:bookshelf " , imagetype = " item " } ,
{ image = " default:grass_5 " , imagetype = " item " } ,
{ image = " default:dirt " , imagetype = " item " } ,
{ image = " default:fence_wood " , imagetype = " item " } ,
{ image = " default:flint " , imagetype = " item " } ,
{ image = " default:goldblock " , imagetype = " item " } ,
{ image = " default:bronzeblock " , imagetype = " item " } } ,
} )