trees_lib

[Sokomine]

This mod/lib is not yet finished. It is a work in progress, and some feedback would be welcome.

Trees are very popular elements in Minetest-like games, and modders frequently want to add some trees. People even ask for advice here on the forum as to how to create new types. There are multiple ways to do so. And it is a pain to keep track of all trees out there when trying to maintain compatibility with them from withhin other mods (villages, tree cutting tools, letting trunks grow through leaves, new nodes for all wood types, ...).

For the sake of this mod/library, a tree is a structure that can be cut down for renewable ressources; it provides saplings of some kind which allow to reproduce either the exact same structure or a very similar one.

The api of the trees_lib ought to contain the following:
1. Easy way to add new tree types.
2. A function that allows to react to new tree types beeing registered (i.e. for adding furniture for the new wood it comes with).
3. A function that allows to react to a tree growing at a certain position (i.e. for putting a lumberjack hut or mob next to it).
4. Functions that determine weather or not a tree can/will grow at a certain position. This may go so far as to change how the tree will grow/look like.
5. Trees failing to grow won't trigger further abm calls; they just mutate into dry shrub, thus turning dry shrub into a renewable ressource.
6. The same way of growing (i.e. a function or schematic) can be used for multiple tree types (good for fruit trees).
7. Tree-related nodes (trunk, wood, leaves, further leaves and fruits) can be registered automaticly if the nodes don't exist yet. Advantage: Just change one function if you want your leaves to be climbable, your trunks round or whatever - instead of having to hunt down each tree mod.

All other things tree-related (leafdecay) also ought to be part of it. But not the initial placement of the trees at mapgen time - because that's really too dependant on the mapgen and not the job of this lib.

Registering a tree will require information about the nodes the tree ought to consist of, an (optional) list of node types on which it grows, an (optional) function that is called whenever a sapling wants to grow (it can deny tree growth, change how the tree grows or just allow it), and an (optional) function that chooses how the tree ought to grow.

Methods of growing a tree are either a function (that's how the old trees/apple trees in mapgen v6 grew), a schematic (that's how they grow now) or a table containing the information for L-system tree growth.

The current implementation already contains a "silly" tree as an example (use "/giveme trees_lib:silly_sapling"). It will randomly grow like a normal apple tree, like an acacia from the same schematic, or like a beech from moretrees.

The mod in its current form can be found at https://github.com/Sokomine/trees_lib.

I'm not yet satisfied with my implementation, and it's not finished yet. But I do think that we need a common tree lib. Right now, I do need to keep a copy of an old version of minetest_game/mods/default/trees.lua in mg_villages just to be able to place trees around villages. That can't go on indefinitely as cut&paste really is not a good idea regarding maintenance. And more and more diffrent tree types keep showing up.

[Nathan.S]

This is perfect timing as I need to add fruit trees to my subgame and wasn't sure where to begin. I'll have to take a look at this.

[Ivà]

This is a very good idea Sokomine.

Methods of growing a tree are either a function (that's how the old trees/apple trees in mapgen v6 grew), a schematic (that's how they grow now) or a table containing the information for L-system tree growth.

About that point, look at what duane did in his valleys_c mod (as an example look at https://github.com/duane-r/valleys_c/bl ... banana.lua). If I understood well his code, He is building a schematic from a function, and I hope that it can be used to build a schematic from an L-system too. So with that you may use only an schematic method to put a tree in the world and simplify a bit the mod.

[duane]

Very nice work, Sokomine.

About that point, look at what duane did in his valleys_c mod (as an example look at https://github.com/duane-r/valleys_c/bl ... banana.lua). If I understood well his code, He is building a schematic from a function, and I hope that it can be used to build a schematic from an L-system too. So with that you may use only an schematic method to put a tree in the world and simplify a bit the mod.

I haven't done anything with L-trees yet. I don't think there's any easy way to convert the one to the other, without writing your own L-code interpreter (which might not be all that difficult).

Sokomine, you could also check out vlapsley/demonboy's praiseworthy work on VMG's trees. He put in a lot of the automation you have here, and added new stair and slab types automagically, when the stair mod is available. Another thing we did is support different trunk diameters for skinny trees like birch.

[Sokomine]

This is perfect timing as I need to add fruit trees to my subgame and wasn't sure where to begin. I'll have to take a look at this.

The old apple tree is really nice as a fruit tree: Easy to harvest, convenient size. trees_lib comes with the latest code for those trees from minetest_game. They can vary a bit more in height and size than the older implementations.

About that point, look at what duane did in his valleys_c mod (as an example look at https://github.com/duane-r/valleys_c/bl ... banana.lua). If I understood well his code, He is building a schematic from a function, and I hope that it can be used to build a schematic from an L-system too. So with that you may use only an schematic method to put a tree in the world and simplify a bit the mod.

Ah yes, that way of creating trees by defining a lua table that is then used as a schematic has also been employed by paramat for trees recently. Perhaps I ought to support such a table/schem format as well. L-system is implemented inside the engine - that's a diffrent approach and not directly accessible inside lua. For my vilalges mod, I do need functions that work on a lua voxelmanip area instead of schematics that are placed by the engine. minetest.place_schematic does not work well in this situation. Duanes valleys_c mod/patch might be of intrest to my villages mod as well. Doing all that terrain flattening and placing of schematics inside the engine could save the time currently needed to pass the data on to lua and back to the engine. But that's only of partial intrest to the trees_lib. The lib's purpose is to present the same interface/api to users (=modders who want to register trees) no matter how it's actually implemented in the end.

I haven't done anything with L-trees yet. I don't think there's any easy way to convert the one to the other, without writing your own L-code interpreter (which might not be all that difficult).

Same here.

Sokomine, you could also check out vlapsley/demonboy's praiseworthy work on VMG's trees. He put in a lot of the automation you have here, and added new stair and slab types automagically, when the stair mod is available. Another thing we did is support different trunk diameters for skinny trees like birch.

I saw that code too late. By then, I had already written the node registration based on minetest_game tree nodes. Could have saved me some work if I'd seen it earlier. In essence, it boils down to the same functionality with few differences. trees_lib can't rely on node names following a naming convention as vmg does. Trees may be composed out of nodes that have been used on maps already and where the mod creator had no idea about what a naming convention is. Textures may be composed ones where an existing texture is colored diffrently. Diffrent trunk size sounds like a good idea. I think I'll change it so that the nodes can be created by modname and treename alone, with the option ot override definitions (like the trunk size).

The second (and probably even more important) part of trees_lib is what can also be found to a degree in valleys_mapgen/trees.lua - namely registering an abm for each tree and actually placing one (*.grow_TREE functions). When registering a tree with trees_lib, only the vmg.make_TREE function plus the offset (information about how much space the tree will need) will be required. Loading the voxelmanip area and writing it back is part of the lib's job. Information about which nodes the function (vmg.make_TREE) ought to use is also passed on. The parameters height and radious would be a problem - there's no support for extra parameters yet. Adapting vmg's trees to current trees_lib would boild down to re-writing the parameter list for the actual growing functions mostly.

Adding stairs and slabs could be done by the stairs mod itshelf. It could register a function that is then called whenever any mod registers a new tree.

The major problems I'm currently facing is first to make the node definition part easier for modders to handle. Most of it can be created automaticly from modname and treename, and only if there's something not following the naming convention the table with further information will be required. Beeing able to override all parts of the node's definition might handle that diffrent trunk size idea already.

The next problem is that there has to be some basic definition of a tree, wood, leaves and fruits before the very first tree is registered. That conflicts a bit with the idea of the lib beeing very general. Any mod willing to change something about the nodes (i.e. making leaves climbable, having round trunks, fire-resistant leaves, diffrent draw types, ...) would have to make those changes known before the first tree is registered - thus requiring trees_lib to depend on it. Does anyone have any good ideas in that regard?

[Sokomine]

I consider trees_lib mostly ready for usage now. trees_lib will register all the nodes typically required for a tree (trunk, wood, leaves, sapling, fruit), create an abm to let saplings grow and actually turn the sapling into a tree using a variety of methods. It's an easy way to add a new tree to a game and to react to things tree-like. The mod does not create any trees at mapgen time.


Please see trees_lib/trees.lua, which is based on default/trees.lua for an example as to how it can be applied to the trees and related nodes from the default mod.


Another example can be found in trees_lib/example_tree.lua. The example tree registered there demonstrates the diffrent growing methods supported by the mod: On grass or dirt, it will grow like the old apple tree (using a function); on desert sand, it'll grow like the acacia tree (using a schematic from a file); on normal sand, it'll grow like the banana tree from valleys mapgen (using a schematic in table format); on other types of soil, it'll grow like one of the birches from moretrees (randomly selected); and on group:stone, it'll be a very unhappy tree and use a function that places a very small tree. Other grounds like the mese lamp above lead to the sapling turning into dry shrub (which becomes a renewable ressource with this mod).

The absolute minimum to register a new tree would be calling trees_lib.register_tree( "treename" ) from somewhere withhin your mod. You'd then have to create the following textures:

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

MODNAME/textures/MODNAME_TREENAME_tree_top.png
MODNAME/textures/MODNAME_TREENAME_tree.png
MODNAME/textures/MODNAME_TREENAME_wood.png
MODNAME/textures/MODNAME_TREENAME_sapling.png
MODNAME/textures/MODNAME_TREENAME_leaves.png
MODNAME/textures/MODNAME_TREENAME_fruit.png


and, of course, your mod needs to depend on trees_lib. The register_tree function accepts quite a lot of further parameters:
trees_lib.register_tree(tree_name, nodes, growing_methods, grows_on_node_type_list, can_grow_function, select_how_to_grow_function, interval, chance )

• tree_name needs to be unique withhin each mod, but not necessarily withhin the entire game. This parameter is required.
• nodes may contain further information about the nodes the tree is composed of (tree, wood, leaves, leaves2, leaves3, leaves4, leaves5, sapling and fruit). Specify everything you want to override here (i.e. diffrent node name, textures, drawtype, ...). Specify node_name = "air" (see trees.lua) if you don't want a particular node to be created (mostly used for trees that have no fruit).
• growing_methods is a list of how the sapling can be grown into a full tree. Each entry needs exactly one of the following entries:
  
  • use_function = function_to_grow_the_sapling
  • or use_schematic = path_to_the_schematic_file
  • or use_schematic = table_containing_the_schematic
  • or use_lsystem = table_containing_lsystem_growth_data
  In addition, the following values are usually needed: xoff = x_offset, zoff = z_offset, yoff = y_offset (how deep burried) and height = height (total height of the tree). These values describe which area the Voxelmanip needs to load or how far away from the sapling's position the schematic ought to be placed.
• grows_on_node_type_list is a list of nodenames (or groups in the form of i.e "group:stone") on which the sapling will grow.
• can_grow_function will be called when the abm for a sapling fires: if can_grow( pos, node, ground_found ) returns 1, the tree will grow; if it returns 0, the tree will try again next time (i.e. too dark); and if it returns -1, then the tree really doesn't like this place and fails to grow, usually turning into dry shrub.
• select_how_to_grow_function can modify the way a tree will grow. It is called like this: select_how_to_grow( pos, node, growing.how_to_grow, ground_found ) The function can either return a number (thus choosing one of the growing methods from the growing_methods parameter), or its own new growing method.
• interval The interval parameter for the abm for the growing of the sapling. Default value is 10.
• chance The chance parameter for the abm for the growing of the sapling. Default value is 50.

Sometimes you may want to do something for each tree, i.e. register special furniture or craft receipes. The function trees_lib.register_on_new_tree_type( new_tree_type_function ) exists for that purpose. Once you've registered your function new_tree_type_function that way, your function will be called for each registered tree type once in the following way: new_tree_type_function( tree_name, mod_prefix, nodes ). See trees.lua for an example regarding crafting tree to wood. If trees have allready been registered when the new function is registered, it will be called for each known tree once, and of course for all subsequently registered trees.

trees_lib.failed_to_grow( pos, node ) is called when a tree failed to grow (i.e. because it does not like the ground it is placed on). The default action is to turn the sapling into dry shrub.

trees_lib.a_tree_has_grown( pos, node, how_to_grow ) is called whenever a tree has successfully grown. Useful i.e. for logging (see trees.lua), or for other purposes (like placing a house or lumberjack next to the newly grown tree).

trees_lib.tree_abm_grow_tree( pos, node, sapling_data, how_to_grow, force_grow ) actually grows the sapling into the tree.

A common library for trees will make it easier for other mods to handle them. Right now there are lots of diffrent implementations of trees which all boil down to the same basic mechanisms. It's a nightmare to support all these mods with their diffrent - sometimes even hidden(!) - functions for tree growing. I want to get rid of that old copy of default/trees.lua I had to keep inside mg_villages because the default trees use local functions and create their own voxelmanip area - whereas there's already one at hand at mapgen time and only the functionality for placing the tree missing.

Further advantages of this mod/library are that registration of new trees becomes easier (people often ask on the forum) - there really is no need for everyone writing his/her own code for the abm and the tree growing. And having to change each tree-related mod in order to i.e. make players be able to walk/climb through leaves or in order to change the drawtype of leaves isn't nice either. Tree registration gets easier the more these greenish things follow some sort of naming convention - which isn't bad either.

Leafdecay and group based craft receipes for fuel (so that you can burn all tree parts in a furnace) are currently not covered and up to the game to handle. Maybe leafdecay ought to be covered in the future.

Download: https://github.com/Sokomine/trees_lib/a ... master.zip
Browse code: https://github.com/Sokomine/trees_lib
Version: 0.1 (alpha)
Licence: GPLv3 for my part/trees_lib.lua; the examples are partly from other mods
Depends on: nothing

My goal is to get trees_lib.lua to be accepted by other modders who are using trees and eventually to be part of some form of standard library for Minetest so that all games can rely on its existence. Even if you don't like this particular implementation or would prefer to have something done differently, please make a suggestion how it could be better - and support the development of a standard library. Another part that ought to be included there is basic saving and restoring of table values into a file.

[Don]

Nice work! Trees have been an issue for many. This makes it so much better. Thanks

[firefox]

this mod is great!

i manged to get my first tree into my subgame.
i like the feature that turns saplings into something else when they can't grow.
although here comes my first problem:

the tree i made is a frozen tree.
instead of becoming a dry shrub, i would like to have it become snow when it can't grow.

i managed to do this for my frozen flower by copying the code and making an extra ABM for the frozen flower.
how can i make an extra function for the frozen tree?
(maybe i could copy the entire trees_lib and run an alternate version just for the ice tree, but i would prefer a smarter solution, if possible)

[Sokomine]

Instead of becoming a dry shrub, i would like to have it become snow when it can't grow.

i managed to do this for my frozen flower by copying the code and making an extra ABM for the frozen flower.
how can i make an extra function for the frozen tree?

There's an extra function for when the tree fails to grow. It is called trees_lib.failed_to_grow. You can do something like 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

old_trees_lib_failed_to_grow = trees_lib.failed_to_grow
trees_lib.failed_to_grow = function( pos, node )
        if( node and node.name="mymod:mysapling" ) then
             minetest.set_node( pos, {name="default:snow"} )
        else
              old_trees_lib_failed_to_grow( pos, node )
        end
end


[firefox]

i got a lua error message, so i tried some variations.
then it worked when i used 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

if ( node and node.name == "mymod:mysapling" ) then

thanks a lot =(^.^)=

EDIT: another problem
the trees_lib.sound function plays sounds when tree nodes are dug, but not when stepped on.
also the leaves have no sound at all.
i couldn't figure out how it works, so i overwrote the settings by adding the default.sound into the node definition and it worked.

[Sokomine]

i got a lua error message, so i tried some variations. then it worked when i used this:

Ah, so I missed a = in the example code. Good that you spotted it.

the trees_lib.sound function plays sounds when tree nodes are dug, but not when stepped on.
also the leaves have no sound at all.

Strange. I usually play with sound off so I only mirrored what minetest_game/mods/default/nodes.lua does in this case. Will have to look at that.