API.md

   1 # API documentation
   2 The L-System Tree Utility provides a set of simple functions to mess around with the tree database, generate trees from saplings and more.
   3
   4
   5 ## Variables
   6 The table `ltool.VERSION` exports version information. This mod uses [Semantic Versioning](http://semver.org/).
   7 This information comes in handy if you need to do some compability work.
   8
   9 * `ltool.VERSION.STRING`: Full version as string
  10 * `ltool.VERSION.MAJOR`: Major (=first) version number, as number
  11 * `ltool.VERSION.MINOR`: Minor (=second) version number, as number
  12 * `ltool.VERSION.PATCH`: Patch (=third) version number, as number
  13
  14 ## Data structures
  15 ### `treedef`
  16 This is identical to the `treedef` parameter of `minetest.spawn_tree`.
  17
  18 ### `tree`
  19 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:
  20
  21 #### `tree_id`
  22 A tree ID, an identifier of a `tree`. This is an unique number. Many functions require a tree ID.
  23
  24 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.
  25
  26 #### `name`
  27 An unique name of the tree, assigned by the user.
  28
  29 #### `author`
  30 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.
  31
  32
  33
  34 ## Functions
  35 ### `ltool.get_tree(tree_id)`
  36 Tries to return a `tree` for a given `tree_id`.
  37
  38 #### Parameter
  39 * `tree_id`: Identifier of `tree` to be received.
  40
  41 #### Return value
  42 A `tree` on success, `false` on success (happens if no tree with this `tree_id` exists).
  43
  44
  45
  46 ### `ltool.get_tree_ids()`
  47 Returns a sorted table containing all tree IDs.
  48
  49 #### Parameters
  50 None.
  51
  52 #### Return value
  53 A sorted table containing all tree IDs, sorted by ID.
  54
  55
  56
  57 ### `ltool.add_tree(name, author, treedef)`
  58 Adds a tree to the tree table.
  59
  60 #### Parameters
  61 * `name`: The tree’s name.
  62 * `author`: The author’s / owners’ name
  63 * `treedef`: The full tree definition, see `lua_api.txt`
  64
  65 #### Return value
  66 The tree ID of the new tree.
  67
  68
  69
  70 ### `ltool.remove_tree(tree_id)`
  71 Removes a tree from the tree database.
  72
  73 #### Parameter
  74 * `tree_id`: ID of the tree to be removed
  75
  76 #### Return value
  77 Always `nil`.
  78
  79
  80 ### `ltool.rename_tree(tree_id, new_name)`
  81 Renames a tree in the database
  82
  83 #### Parameters
  84 * `tree_id`: ID of the tree to be renamed
  85 * `new_name`: The name of the tree
  86
  87 #### Return value
  88 Always `nil`.
  89
  90
  91
  92 ### `ltool.copy_tree(tree_id)`
  93 Creates a copy of a tree in the database.
  94
  95 #### Parameter
  96 * `tree_id`: ID of the tree to be copied
  97
  98 #### Return value
  99 The ID of the copy on success,
 100 `false` on failure (tree does not exist).
 101
 102
 103
 104 ### `ltool.generate_sapling(tree_id, seed)`
 105 Generates a sapling as an `ItemStack` to mess around later with.
 106
 107 #### Parameter
 108 * `tree_id`: ID of tree the sapling will grow
 109 * `seed`: Seed of the tree the sapling will grow (optional, can be nil)
 110
 111 #### Return value
 112 An `ItemStack` which contains one sapling of the specified `tree`, on success.
 113 Returns `false` on failure (happens if tree does not exist).
 114
 115
 116
 117 ### `ltool.give_sapling(tree_id, seed, player_name, ignore_priv)`
 118 Gives a L-system tree sapling to a player.
 119
 120 #### Parameters
 121  * `tree_id`: ID of tree the sapling will grow
 122  * `seed`: Seed of the tree (optional; can be nil)
 123  * `playername`: name of the player to which
 124  * `ignore_priv`: if `true`, player’s `lplant` privilige is not checked (optional argument; default: `false`)
 125
 126 #### Return value
 127 It depends:
 128
 129 * `true` on success
 130 * `false, 1` if player does not have `lplant` privilege
 131 * `false, 2` if player’s inventory is full
 132 * `false, 3` if `tree` does not exist
 133
 134
 135
 136 ### `ltool.plant_tree(tree_id, pos, seed)`
 137 Plants a tree as the specified position.
 138
 139 #### Parameters
 140 * `tree_id`: ID of tree to be planted
 141 * `pos`: Position of tree, in the format `{x=?, y=?, z=?}`
 142 * `seed`: Optional randomness seed, equal seed creates equal trees
 143
 144 #### Return value
 145 `false` on failure, `nil` otherwise.
 146
 147
 148
 149 ### `ltool.show_treeform(playername)`
 150 Shows the main tree form to the given player, starting with the "Edit" tab.
 151
 152 #### Parameters
 153 * `playername`: Name of the player to whom the formspec should be shown to
 154
 155 #### Return value
 156 Always `nil.`