2014-10-16 08:30:23 -07:00
# API documentation
The L-System Tree Utility provides a set of simple functions to mess around with the tree database, generate trees from saplings and more.
2014-10-16 09:17:36 -07:00
## Variables
The table `ltool.VERSION` exports version information. This mod uses [Semantic Versioning ](http://semver.org/ ).
2015-02-07 15:40:40 -08:00
This information comes in handy if you need to do some compability work.
2014-10-16 09:17:36 -07:00
* `ltool.VERSION.STRING` : Full version as string
* `ltool.VERSION.MAJOR` : Major (=first) version number, as number
* `ltool.VERSION.MINOR` : Minor (=second) version number, as number
* `ltool.VERSION.PATCH` : Patch (=third) version number, as number
2014-10-16 08:30:23 -07:00
## Data structures
### `treedef`
This is identical to the `treedef` parameter of `minetest.spawn_tree` .
### `tree`
A `tree` is the basic data structure. It is basically a wrapper around `treedef` , with some additional fields relevant for the L-System-Tree-Utility, which are listed here:
#### `tree_id`
A tree ID, an identifier of a `tree` . This is an unique number. Many functions require a tree ID.
No identifier is used twice, once an identifier is taken, it won’ t be occupied again, even if the `tree` occupying the slot has been deleted.
#### `name`
An unique name of the tree, assigned by the user.
#### `author`
The name of the player who created the `tree` . The author is also the “owner” of the `tree` and is the only one who can edit it in the mod.
## Functions
2014-10-16 09:04:42 -07:00
### `ltool.get_tree(tree_id)`
Tries to return a `tree` for a given `tree_id` .
#### Parameter
* `tree_id` : Identifier of `tree` to be received.
#### Return value
A `tree` on success, `false` on success (happens if no tree with this `tree_id` exists).
### `ltool.get_tree_ids()`
2014-10-16 08:46:19 -07:00
Returns a sorted table containing all tree IDs.
2014-10-16 08:30:23 -07:00
#### Parameters
2014-10-16 08:46:19 -07:00
None.
2014-10-16 08:30:23 -07:00
#### Return value
2014-10-16 08:46:19 -07:00
A sorted table containing all tree IDs, sorted by ID.
2014-10-16 08:30:23 -07:00
### `ltool.add_tree(name, author, treedef)`
Adds a tree to the tree table.
#### Parameters
* `name` : The tree’ s name.
* `author` : The author’ s / owners’ name
2018-05-17 05:02:14 -07:00
* `treedef` : The full tree definition, see `lua_api.txt`
2014-10-16 08:30:23 -07:00
#### Return value
The tree ID of the new tree.
2014-10-16 08:46:19 -07:00
2014-10-16 08:30:23 -07:00
### `ltool.remove_tree(tree_id)`
Removes a tree from the tree database.
#### Parameter
* `tree_id` : ID of the tree to be removed
#### Return value
Always `nil` .
### `ltool.rename_tree(tree_id, new_name)`
Renames a tree in the database
#### Parameters
* `tree_id` : ID of the tree to be renamed
* `new_name` : The name of the tree
#### Return value
Always `nil` .
### `ltool.copy_tree(tree_id)`
Creates a copy of a tree in the database.
#### Parameter
* `tree_id` : ID of the tree to be copied
#### Return value
The ID of the copy on success,
`false` on failure (tree does not exist).
### `ltool.generate_sapling(tree_id, seed)`
Generates a sapling as an `ItemStack` to mess around later with.
#### Parameter
* `tree_id` : ID of tree the sapling will grow
* `seed` : Seed of the tree the sapling will grow (optional, can be nil)
#### Return value
An `ItemStack` which contains one sapling of the specified `tree` , on success.
Returns `false` on failure (happens if tree does not exist).
2014-10-16 08:46:19 -07:00
### `ltool.give_sapling(tree_id, seed, player_name, ignore_priv)`
2014-10-16 08:30:23 -07:00
Gives a L-system tree sapling to a player.
#### Parameters
* `tree_id` : ID of tree the sapling will grow
* `seed` : Seed of the tree (optional; can be nil)
* `playername` : name of the player to which
* `ignore_priv` : if `true` , player’ s `lplant` privilige is not checked (optional argument; default: `false` )
#### Return value
It depends:
* `true` on success
* `false, 1` if player does not have `lplant` privilege
* `false, 2` if player’ s inventory is full
* `false, 3` if `tree` does not exist
2014-10-16 08:46:19 -07:00
2017-02-09 04:30:31 -08:00
### `ltool.plant_tree(tree_id, pos, seed)`
2014-10-16 08:46:19 -07:00
Plants a tree as the specified position.
#### Parameters
* `tree_id` : ID of tree to be planted
* `pos` : Position of tree, in the format `{x=?, y=?, z=?}`
2017-02-09 04:30:31 -08:00
* `seed` : Optional randomness seed, equal seed creates equal trees
2014-10-16 08:46:19 -07:00
#### Return value
`false` on failure, `nil` otherwise.
### `ltool.show_treeform(playername)`
2016-11-05 11:21:23 -07:00
Shows the main tree form to the given player, starting with the "Edit" tab.
2014-10-16 08:46:19 -07:00
#### Parameters
* `playername` : Name of the player to whom the formspec should be shown to
#### Return value
Always `nil.`