[Modpack] Help [1.2.0] [doc]

[FaceDeer]

Hi, Wuzzy. This is an awesome mod that really should be a core feature of Minetest IMO, perhaps it'll make its way there someday. You can add Digtron and Breadcrumbs to the list of documented mods. :)

Anyway, a question. I'm trying to add documentation to a fork of the vines mod wherein I've got a rope ladder that's composed of multiple different node types "under the hood" (there's different nodes for the ladder top, the ladder hanging under it, and the lower end of the ladder that's still descending) but that the player should only need to perceive it as a single node type. I tried adding documentation just for the ropeladder_top node and using a series of

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

doc.add_entry_alias("nodes", "vines:ropeladder_top", "nodes", "vines:ropeladder")

calls to point all the other nodes to that one, but it doesn't seem to have worked - there are separate entries listed in the "Blocks" category for each of the different ropeladder nodes and using the inspector tool on ropeladder nodes doesn't give me the ropeladder_top entry as I was hoping.

Is there a best-practices way to accomplish this?

[Wuzzy]

The usual way to do this is like this:
First step: Add the field “_doc_items_create_entry=false” for all “under the hood” node types which you do NOT want to be exposed as individual entries. Those items won't have any entries.
Second step: Now since these nodes have no entries anymore, the lookup tool won't work on these. That's where the aliases come into play: Add aliases to the actual node you want to define.
Third step: Test. If done correctly, using the lookup tool on all node types should lead to the same entry, and all “fake” nodes should not be visible in the entry list (test with /help_reveal).
Hmm, I thought I wrote it down in the API help. I need to check this sooner or later.
If you don't understand, check out doc_examples, you might find an example there. Search the first post for it.


I will check out Digtron and Breadcrumbs later. I'm very glad this modpack API is being actively used by people who are not Wuzzy. ;-)

[FaceDeer]

That seems to be working, thanks! The "_doc_items_create_entry" property was the missing piece of the puzzle. It doesn't appear to be mentioned in API.md, and given the number of "fake" nodes I'm seeing from some of the other mods I've got installed I think it'll warrant a prominent mention. :)

Documentation is super important, I'm definitely going to be spraying this stuff all over any mod I touch and urging my users to install it.

[texmex]

I'm very glad this modpack API is being actively used by people who are not Wuzzy. ;-)

Perhaps there could be a team of writers of documentation. Not all of us have the ability to contribute in code anyway. The incentive to write would of course increase if the work would end up in minetest_game.

[FaceDeer]

Perhaps there could be a team of writers of documentation. Not all of us have the ability to contribute in code anyway. The incentive to write would of course increase if the work would end up in minetest_game.

For the mods that have significant amounts of documentation I've been putting all of the text for the entire mod into one "doc.lua" file that has minimal amounts of actual code in it. Hopefully that'll make it easier for non-lua-savvy people to still help out with the writing if they want to.

[bark]

When I click the "Tools and weapons" button in the main help screen, the server crashes with an internal error. I'm running 0.4.15 and the latest version of the doc modpack. I can reproduce the bug on separate minetest builds.

Crash log:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

2017-02-02 21:03:51: ERROR[Main]: ServerError: AsyncErr: ServerThread::run Lua: Runtime error from mod 'doc' in callback on_playerReceiveFields(): /home/me/.minetest/mods/doc/doc_items/init.lua:976: attempt to perform arithmetic on field 'uses' (a nil value)
2017-02-02 21:03:51: ERROR[Main]: stack traceback:
2017-02-02 21:03:51: ERROR[Main]:    /home/me/.minetest/mods/doc/doc_items/init.lua:976: in function </home/me/.minetest/mods/doc/doc_items/init.lua:932>
2017-02-02 21:03:51: ERROR[Main]:    [C]: in function 'sort'
2017-02-02 21:03:51: ERROR[Main]:    /home/me/.minetest/mods/doc/doc/init.lua:910: in function 'get_sorted_entry_names'
2017-02-02 21:03:51: ERROR[Main]:    /home/me/.minetest/mods/doc/doc/init.lua:817: in function 'generate_entry_list'
2017-02-02 21:03:51: ERROR[Main]:    /home/me/.minetest/mods/doc/doc/init.lua:932: in function 'formspec_category'
2017-02-02 21:03:51: ERROR[Main]:    /home/me/.minetest/mods/doc/doc/init.lua:1037: in function '?'
2017-02-02 21:03:51: ERROR[Main]:    /usr/local/share/minetest/builtin/game/register.lua:412: in function </usr/local/share/minetest/builtin/game/register.lua:392>


And let me just say great work with this mod! In-game documentation is certainly an important and much needed feature. This is an elegant implementation in my humble opinion.

[Wuzzy]

Thanks for the bug report!
Version 1.0.1 released!

Item Help [doc_items] (version 1.0.1)

• Fix possible crash after selecting “Tools and weapons”. The crash happened when there's a tool with unknown usage count, maximum digging level or digging time

Documentation System [doc] (version 1.0.1)

• Fix inventory_plus not listed as optional dependency

[sys4]

My server crash when I click the "Tools and weapons" button in the main help screen with last version (1.0.1)

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

2017-02-11 06:48:45: ERROR[Main]: ServerError: Lua: Runtime error from mod 'doc' in callback on_playerReceiveFields(): ....4.15/bin/../games/sys4_game/mods/doc/doc_items/init.lua:1025: attempt to compare nil with number
2017-02-11 06:48:45: ERROR[Main]: stack traceback:
2017-02-11 06:48:45: ERROR[Main]:       ....4.15/bin/../games/sys4_game/mods/doc/doc_items/init.lua:1025: in function <....4.15/bin/../games/sys4_game/mods/doc/doc_items/init.lua:937>
2017-02-11 06:48:45: ERROR[Main]:       [C]: in function 'sort'
2017-02-11 06:48:45: ERROR[Main]:       ...test-0.4.15/bin/../games/sys4_game/mods/doc/doc/init.lua:910: in function 'get_sorted_entry_names'
2017-02-11 06:48:45: ERROR[Main]:       ...test-0.4.15/bin/../games/sys4_game/mods/doc/doc/init.lua:817: in function 'generate_entry_list'
2017-02-11 06:48:45: ERROR[Main]:       ...test-0.4.15/bin/../games/sys4_game/mods/doc/doc/init.lua:932: in function 'formspec_category'
2017-02-11 06:48:45: ERROR[Main]:       ...test-0.4.15/bin/../games/sys4_game/mods/doc/doc/init.lua:1037: in function <...test-0.4.15/bin/../games/sys4_game/mods/doc/doc/init.lua:1001>
2017-02-11 06:48:45: ERROR[Main]:       ...nt/jeux/minetest-0.4.15/bin/../builtin/game/register.lua:412: in function <...nt/jeux/minetest-0.4.15/bin/../builtin/game/register.lua:392>



Is this output is sufficient or may have to list all of my mods in use for better help ?

Another thing : When I download the modpack in this way...

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

git clone git://repo.or.cz/minetest_doc_modpack.git


...all the directories in it are empty.

Hope this help and great great work !

[Wuzzy]

Yes, a mod list would definitely help. It looks like one of your mods adds a tool with a weird tool definition.

This repository has Git submodules. Use this command after cloning:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

git submodule update --init --recursive

More about Git submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules

[sys4]

Ok, I have investigate a bit, the dump of the "comp" table show that when the error is triggered on line 1025:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

comp:{
        {
                gc = {
                        fleshy = {
                                times = {
                                },
                                uses = 10000,
                                maxlevel = 0
                        }
                },
                count = 1,
                uses = 10000,
                group = "fleshy"
        },
        {
                mintime = 0.2,
                group = "fleshy",
                gc = {
                        fleshy = {
                                times = {
                                        1.6,
                                        0.8,
                                        0.4
                                },
                                uses = 15,
                                maxlevel = 2
                        },
                        snappy = {
                                times = {
                                        [2] = 0.75,
                                        [3] = 0.35
                                },
                                uses = 30,
                                maxlevel = 1
                        },
                        choppy = {
                                times = {
                                        [3] = 0.8
                                },
                                uses = 30,
                                maxlevel = 0
                        }
                },
                count = 3,
                uses = 135
        }
}



The first entry of the "comp" table has a "gc.fleshy.times" empty which cause "comp[1].mintime" to be nil and produce the comparison error.

If I dump in amount the "entries" table located at the line 938 I can see this :

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

[...]
entries:{
        {
                eid = "technic:red_energy_crystal",
                name = "Red Energy Crystal",
                data = {
                        def = {
                                inventory_image = "[inventorycube{technic_diamond_block_red.png{technic_diamond_block_red.png{technic_diamond_block_red.png",
                                wear_represents = "technic_RE_charge",
                                tool_capabilities = {
                                        max_drop_level = 0,
                                        groupcaps = {
                                                fleshy = {
                                                        times = {
                                                        },
                                                        uses = 10000,
                                                        maxlevel = 0
                                                }
                                        }
                                },
                                on_refill = <function>,
                                mod_origin = "technic",
                                type = "tool",
                                stack_max = 1,
                                name = "technic:red_energy_crystal",
                                description = "Red Energy Crystal"
                        },
                        itemstring = "technic:red_energy_crystal"
                },
                hidden = true
        },
        {
                eid = "gloopblocks:sword_cement",
                name = "Cement Sword",
                data = {
                        def = {
                                inventory_image = "gloopblocks_cement_sword.png",
                                stack_max = 1,
                                mod_origin = "gloopblocks",
                                type = "tool",
                                tool_capabilities = {
                                        groupcaps = {
                                                fleshy = {
                                                        times = {
                                                                1.6,
                                                                0.8,
                                                                0.4
                                                        },
                                                        uses = 15,
                                                        maxlevel = 2
                                                },
                                                snappy = {
                                                        times = {
                                                                [2] = 0.75,
                                                                [3] = 0.35
                                                        },
                                                        uses = 30,
                                                        maxlevel = 1
                                                },
                                                choppy = {
                                                        times = {
                                                                [3] = 0.8
                                                        },
                                                        uses = 30,
                                                        maxlevel = 0
                                                }
                                        },
                                        max_drop_level = 1,
                                        full_punch_interval = 1,
                                        damage_groups = {
                                                fleshy = 6
                                        }
                                },
                                name = "gloopblocks:sword_cement",
                                description = "Cement Sword"
                        },
                        itemstring = "gloopblocks:sword_cement"
                },
                hidden = true
        }
}


The problem seems come from the "technic:red_energy_crystal" item with his "tool_capabilities.groupcaps.fleshy.times" defined as an empty table.

What is the best workaround for avoid this particularity ?

Thanks for your quick response.

[Wuzzy]

I just pushed a (possible) bugfix. Can you please grab the newest Git of doc_items and confirm that it doesn't crash anymore? If not, tell me if there's a different error. If everything is OK, I will make a release.
Thanks for the information and research.

[sys4]

No, always the same error :

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

2017-02-11 20:03:22: ERROR[Main]: ServerError: Lua: Runtime error from mod 'doc' in callback on_playerReceiveFields(): ...n/../games/sys4_game/mods/doc_modpack/doc_items/init.lua:1026: attempt to compare nil with number
2017-02-11 20:03:22: ERROR[Main]: stack traceback:
2017-02-11 20:03:22: ERROR[Main]:       ...n/../games/sys4_game/mods/doc_modpack/doc_items/init.lua:1026: in function <...n/../games/sys4_game/mods/doc_modpack/doc_items/init.lua:938>
2017-02-11 20:03:22: ERROR[Main]:       [C]: in function 'sort'
2017-02-11 20:03:22: ERROR[Main]:       ....15/bin/../games/sys4_game/mods/doc_modpack/doc/init.lua:910: in function 'get_sorted_entry_names'
2017-02-11 20:03:22: ERROR[Main]:       ....15/bin/../games/sys4_game/mods/doc_modpack/doc/init.lua:817: in function 'generate_entry_list'
2017-02-11 20:03:22: ERROR[Main]:       ....15/bin/../games/sys4_game/mods/doc_modpack/doc/init.lua:932: in function 'formspec_category'
2017-02-11 20:03:22: ERROR[Main]:       ....15/bin/../games/sys4_game/mods/doc_modpack/doc/init.lua:1037: in function <....15/bin/../games/sys4_game/mods/doc_modpack/doc/init.lua:1001>
2017-02-11 20:03:22: ERROR[Main]:       ...nt/jeux/minetest-0.4.15/bin/../builtin/game/register.lua:412: in function <...nt/jeux/minetest-0.4.15/bin/../builtin/game/register.lua:392>


Dump of entries table:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

[...]
entries:{
        {
                eid = "technic:red_energy_crystal",
                name = "Red Energy Crystal",
                data = {
                        def = {
                                inventory_image = "[inventorycube{technic_diamond_block_red.png{technic_diamond_block_red.png{technic_diamond_block_red.png",
                                wear_represents = "technic_RE_charge",
                                tool_capabilities = {
                                        max_drop_level = 0,
                                        groupcaps = {
                                                fleshy = {
                                                        times = {
                                                        },
                                                        uses = 10000,
                                                        maxlevel = 0
                                                }
                                        }
                                },
                                on_refill = <function>,
                                mod_origin = "technic",
                                type = "tool",
                                stack_max = 1,
                                name = "technic:red_energy_crystal",
                                description = "Red Energy Crystal"
                        },
                        itemstring = "technic:red_energy_crystal"
                },
                hidden = true
        },
        {
                eid = "gloopblocks:sword_cement",
                name = "Cement Sword",
                data = {
                        def = {
                                inventory_image = "gloopblocks_cement_sword.png",
                                stack_max = 1,
                                mod_origin = "gloopblocks",
                                type = "tool",
                                tool_capabilities = {
                                        groupcaps = {
                                                fleshy = {
                                                        times = {
                                                                1.6,
                                                                0.8,
                                                                0.4
                                                        },
                                                        uses = 15,
                                                        maxlevel = 2
                                                },
                                                snappy = {
                                                        times = {
                                                                [2] = 0.75,
                                                                [3] = 0.35
                                                        },
                                                        uses = 30,
                                                        maxlevel = 1
                                                },
                                                choppy = {
                                                        times = {
                                                                [3] = 0.8
                                                        },
                                                        uses = 30,
                                                        maxlevel = 0
                                                }
                                        },
                                        max_drop_level = 1,
                                        full_punch_interval = 1,
                                        damage_groups = {
                                                fleshy = 6
                                        }
                                },
                                name = "gloopblocks:sword_cement",
                                description = "Cement Sword"
                        },
                        itemstring = "gloopblocks:sword_cement"
                },
                hidden = true
        }
}


Dump of comp table:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.

Code: Select all

comp:{
        {
                gc = {
                        fleshy = {
                                times = {
                                },
                                uses = 10000,
                                maxlevel = 0
                        }
                },
                count = 1,
                uses = 10000,
                group = "fleshy"
        },
        {
                mintime = 0.2,
                group = "fleshy",
                gc = {
                        fleshy = {
                                times = {
                                        1.6,
                                        0.8,
                                        0.4
                                },
                                uses = 15,
                                maxlevel = 2
                        },
                        snappy = {
                                times = {
                                        [2] = 0.75,
                                        [3] = 0.35
                                },
                                uses = 30,
                                maxlevel = 1
                        },
                        choppy = {
                                times = {
                                        [3] = 0.8
                                },
                                uses = 30,
                                maxlevel = 0
                        }
                },
                count = 3,
                uses = 135
        }
}


[bell07]

At the first thank you for the great work!
Particularly I am impressed by the "revealed" logic, so I deep-integrated it to the smart_inventory's crafting page. So the "crafting helpers" reveal only recipes if all recipe items are revealed. Of course there is a doc_lookup button if an revealed item is selected in the list. It is really pretty gameplay that [doc] enriched.

As usual I have some suggestions for improvement :-)
1. The lookup-tool should display information about the pointed thing only, and not the whole encyclopedia.
2. In addition to 1 maybe the encyclopedia can lookup using right-click like the lookup-tool before with possibility to switch to other items.
3. "eatable" factoid (I like this word) - currently if you try to analyze something eatable like apple you get the message

Punches with this item don't work as usual; melee combat and mining are either not possible or work differently.

That is confusing. A better way I found in https://forum.minetest.net/viewtopic.php?f=47&t=16302 and already implemented in smart_inventory filters system. Maybe you can integrate it to the doc_items and check if other factoids can be get using proposed "function-testing" method.

In general I see we have the same goals in doc's factoids and smart_inventory's filters (https://github.com/bell07/minetest-smart_inventory/blob/master/filter.lua) so maybe we take a reusable way for both? (+trm_generic to classify the treasurers ;-) I think about a "libclassify" mod that should analyze and classify the items by logic in a way reusable in mentioned 3 mods.

[admicos]

I got the following error on a server:

2017-03-02 19:55:31: ERROR[Main]: ServerError: Lua: Runtime error from mod 'doc' in callback on_playerReceiveFields(): /home/admicos/.minetest/mods/doc/doc_items/init.lg
2017-03-02 19:55:31: ERROR[Main]: stack traceback:
2017-03-02 19:55:31: ERROR[Main]: /home/admicos/.minetest/mods/doc/doc_items/init.lua:1029: in function </home/admicos/.minetest/mods/doc/doc_items/init.lua:937>
2017-03-02 19:55:31: ERROR[Main]: [C]: in function 'sort'
2017-03-02 19:55:31: ERROR[Main]: /home/admicos/.minetest/mods/doc/doc/init.lua:910: in function 'get_sorted_entry_names'
2017-03-02 19:55:31: ERROR[Main]: /home/admicos/.minetest/mods/doc/doc/init.lua:817: in function 'generate_entry_list'
2017-03-02 19:55:31: ERROR[Main]: /home/admicos/.minetest/mods/doc/doc/init.lua:932: in function 'formspec_category'
2017-03-02 19:55:31: ERROR[Main]: /home/admicos/.minetest/mods/doc/doc/init.lua:1037: in function </home/admicos/.minetest/mods/doc/doc/init.lua:1001>
2017-03-02 19:55:31: ERROR[Main]: /usr/share/minetest/builtin/game/register.lua:412: in function </usr/share/minetest/builtin/game/register.lua:392>

Minetest info:

Minetest 0.4.15 (Linux)
Using Irrlicht 1.8.3
Build info: VER=0.4.15 BUILD_TYPE=None RUN_IN_PLACE=0 USE_GETTEXT=1 USE_SOUND=1 USE_CURL=1 USE_FREETYPE=1 USE_LUAJIT=1 STATIC_SHAREDIR="/usr/share/minetest"

Installed mods:

announce charcoal doc_minetest_game item_drop MinetestAmbience minetest-mods-awards mobs_monster moreores technic
areas crops fishing itemframes minetest_hudbars minetest-mods-pipeworks mobs_redo playeranim under_sky
booty doc intllib minetest-3d_armor minetest-mod-mesecons mobs_animal moreblocks sprint unified_inventory

[Wuzzy]

Okay, people, I've releasedd version 1.0.2.

doc_items (1.0.2):
- Fix possible crash with some tools from Technic or Gloopblocks (tools where the tool times table was empty)

doc_identifier (1.2.1):
- Hide the “liquid mode” lookup tool from crafting guides which support repairing recipes


I hope this release fixes the crashes reported previously. Everyone who had the crashes, please test again.


Replies:

1. The lookup-tool should display information about the pointed thing only, and not the whole encyclopedia.

This would basically be showing a single entry, but without the tabs or the “next/previous” buttons. It would be easy to do but I don't know what's the point of it. It only makes it less convenient to use for no reason.

2. In addition to 1 maybe the encyclopedia can lookup using right-click like the lookup-tool before with possibility to switch to other items.

The problem with that is that it won't work with liquids. Since this is a modpack, you can always disable the encyclopedia mod. I know this item does not make sense for some subgames with special interface requirements, so I made it as easy as possible to get rid of the encyclopedia.

The encyclopedia was also only born as an easy way to always guarantee access to the help, regardless of subgame. The downside is that it is an item. I was never happy with its existance. The prime solution would be to add a button (or something like that) into the interface, but this needs most likely to be done at subgame level. And if the subgame interface has a proper button, the encyclopedia item can be removed.

Besides, I'm planning to add this modpack to MineClone 2 in one form or another. :-)

3. "eatable" factoid (I like this word) - currently if you try to analyze something eatable like apple you get the message

Yes, I know. This is because of the arcane way how Minetest handles food. Sadly, the only way to make food is to use a function, which means nothing can be parsed automatically.
Your link demonstrates a hack, but not a real solution. I think I will complain to the Minetest issue tracker soon, because it's really dumb that it is so hard to find out whether an item is food.

I think about a "libclassify" mod that should analyze and classify the items by logic in a way reusable in mentioned 3 mods.

First, you have not outlined a concept, so I'm not interested. Second, MineClone 2 currently gets most of my attention, so a project like this is currently out of question for me. Third, the proliferation of wrappers around wrappers around wrappers around wrappers worries me. At some point, the real stuff needs to be done. doc_items is already 3 levels deep in the API tree (doc_items → doc → Minetest Lua API) and provides an API itself. I don't indend to make it even more complex. Your suggestion sound generic enough that it could maybe go directly into the Lua API itself. You should talk to the core developers about this.

[sys4]

Good it's working now :)

[Wuzzy]

Version 1.1.0 released! Just a small update.

Changelog:
Item Help [doc_items] 1.1.0

• New API function doc.sub.items.disable_core_factoid. This function can be used to remove one of the built-in help texts, such as digging times. Useful for modders who want to change the item help to its core
• Bugfix: The block help showing help for blocks which connect to each other (connects_to) showed the item name incorrectly in particular situations

PS: I updated the list of mods and subgames utilizing this modpack.

[Wuzzy]

Great news!
Some mods of the Help modpack version 1.1.0 have been included in MineClone 2 version 0.16.0, so this subgame now includes a proper in-game help about basic concepts and all the items.



The mods doc and doc_items have been included verbatim (that is, with no changes to the code).
doc_basics has been forked and adapted for MineClone 2 since MineClone 2 naturally differs in many core aspects.
doc_identifier has also been included with minor changes (mostly item name and crafting recipe).

I feel very proud today.

[BBmine]

I think I have this on my server to help noobs. I just need to fix my inventory. Oh, how easy is it to use the sfinv mod for this?

[Wuzzy]

I think I have this on my server to help noobs.

Yes, you do. I saw it.

Oh, how easy is it to use the sfinv mod for this?

Very easy.

If you use sfinv_buttons, you will get a new tab with buttons for special menus:
viewtopic.php?f=9&t=16079&p=243235#p243235

The help button will be added by the Help mod, so you don't even need to code.

sfinv_buttons is also useful to add buttons for all sorts of special extra menus. :-)
If you think a mod should have an extra button, make a request to the mod author.

[Wuzzy]

Version 1.2.0 released! Just another small update.

Changelog:
Documentation System [doc] 1.1.0

• The strange “blob” notification sound (and message, if you have central_message active) which occours whenever a new entry got revealed can now be disabled manually with a checkbox in the “Category list” tab
• This notification is disabled by default

Reason: I think this sound can be a bit irritating and its meaning is not obvious.