242 lines
8.6 KiB
Markdown
242 lines
8.6 KiB
Markdown
# Farm Tools API
|
|
|
|
The `farmtools` mod exposes an API that makes it easy (as long as you understand Lua) to register new tools.
|
|
|
|
## 1. Scythes
|
|
|
|
The code related to scythes is available in `lib/scythes.lua`. However, scythes (along with other tools) are registered in `lib/tools.lua`.
|
|
|
|
### 1.1. `farmtools.register_scythe`
|
|
|
|
The function used for registering new scythes.
|
|
|
|
#### Usage
|
|
|
|
```lua
|
|
local S = core.get_translator("my_mod")
|
|
|
|
farmtools.register_scythe("my_mod:my_scythe", {
|
|
description = S("My Scythe"),
|
|
inventory_image = "my_mod_my_scythe.png",
|
|
level = 1,
|
|
max_uses = 200,
|
|
material = "my_mod:my_material_ingot"
|
|
})
|
|
```
|
|
|
|
#### Arguments
|
|
|
|
- **name**: the name of the item to register as a scythe (e.g. `"my_mod:my_scythe"`).
|
|
- **def**: the definition table, that can contain:
|
|
- **description**: the name of the item as shown to the user (default: `Scythe`).
|
|
- **inventory_image**: the image of the item to display in the game (default: `unknown_item.png`)
|
|
- **level**: the level of the scythe (`0` = the scythe will harvest the pointed node only, `1` = the scythe will harvest in a 3x3 area, `2` = the scythe will harvest in a 5x5 area, and so on) (default: `1`).
|
|
- **max_uses**: the number of times the scythe can be used (default: `90`, but you may want to use at least `200` here, otherwise the tool will wear out very fast). Note that unlike in the original `sickles` mod, _one use_ corresponds to _one node_ processed (i.e. if 9 nodes are processed, this will be considered _nine uses_).
|
|
- **material**: the material used for the default scythe recipe (no default: if not specified, the recipe won't be registered)
|
|
- **recipe**: alternatively, it is possible to specify the recipe directly (note that this will override any `material` specified)
|
|
|
|
#### Default recipe
|
|
|
|
The default recipe for scythes is as follow (it can be overriden using `recipe` in the definition table):
|
|
|
|
```text
|
|
----------------------------------
|
|
| | | |
|
|
| | material | material |
|
|
| | | |
|
|
----------------------------------
|
|
| | | |
|
|
| material | | stick |
|
|
| | | |
|
|
----------------------------------
|
|
| | | |
|
|
| | | stick |
|
|
| | | |
|
|
----------------------------------
|
|
```
|
|
|
|
### 1.2. `farmtools.scythe_on_use`
|
|
|
|
The function called when the scythe is used. This function should not be called directly unless you know what you are doing.
|
|
|
|
#### Usage
|
|
|
|
```lua
|
|
farmtools.scythe_on_use(itemstack, user, pointed_thing, uses)
|
|
```
|
|
|
|
#### Arguments
|
|
|
|
- **itemstack**: the ItemStack object (should be in the scythe group, otherwise it will not be able to harvest in an area bigger than a single node).
|
|
- **user**: the player using the scythe.
|
|
- **pointed_thing**: the pointed thing when the scythe is used.
|
|
- **uses**: the maximum number of times the scythe can be used.
|
|
|
|
#### Returns
|
|
|
|
- **ItemStack**: the ItemStack specified as an argument (worn-out, if it should be)
|
|
|
|
## 2. Rakes
|
|
|
|
The code related to rakes is available in `lib/rakes.lua`. However, rakes (along with other tools) are registered in `lib/tools.lua`.
|
|
|
|
### 2.1. `farmtools.register_rake`
|
|
|
|
The function used for registering new rakes.
|
|
|
|
#### Usage
|
|
|
|
```lua
|
|
local S = core.get_translator("my_mod")
|
|
|
|
farmtools.register_rake("my_mod:my_rake", {
|
|
description = S("My Rake"),
|
|
inventory_image = "my_mod_my_rake.png",
|
|
level = 1,
|
|
max_uses = 200,
|
|
material = "my_mod:my_material_ingot"
|
|
})
|
|
```
|
|
|
|
#### Arguments
|
|
|
|
- **name**: the name of the item to register as a rake (e.g. `"my_mod:my_rake"`).
|
|
- **def**: the definition table, that can contain:
|
|
- **description**: the name of the item as shown to the user (default: `Rake`).
|
|
- **inventory_image**: the image of the item to display in the game (default: `unknown_item.png`)
|
|
- **level**: the level of the rake (`0` = the rake will turn only the pointed node into soil (as long as it is possible to do so), `1` = the rake will turn dirt into soil in a 3x3 area, `2` = the rake will turn dirt into soil in a 5x5 area, and so on) (default: `1`).
|
|
- **max_uses**: the number of times the rake can be used (default: `90`). Note that unlike in the original `sickles` mod, _one use_ corresponds to _one node_ processed (i.e. if 9 nodes are processed, this will be considered _nine uses_).
|
|
- **material**: the material used for the default rake recipe (no default: if not specified, the recipe won't be registered)
|
|
- **recipe**: alternatively, it is possible to specify the recipe directly (note that this will override any `material` specified)
|
|
|
|
#### Default recipe
|
|
|
|
The default recipe for rakes is as follow (it can be overriden using `recipe` in the definition table):
|
|
|
|
```text
|
|
----------------------------------
|
|
| | | |
|
|
| material | material | material |
|
|
| | | |
|
|
----------------------------------
|
|
| | | |
|
|
| material | stick | material |
|
|
| | | |
|
|
----------------------------------
|
|
| | | |
|
|
| | stick | |
|
|
| | | |
|
|
----------------------------------
|
|
```
|
|
|
|
### 2.2. `farmtools.rake_on_use`
|
|
|
|
The function called when the rake is used. This function should not be called directly unless you know what you are doing.
|
|
|
|
#### Usage
|
|
|
|
```lua
|
|
farmtools.rake_on_use(itemstack, user, pointed_thing, uses)
|
|
```
|
|
|
|
#### Arguments
|
|
|
|
- **itemstack**: the ItemStack object (should be in the rake group, otherwise it will act as a regular hoe).
|
|
- **user**: the player using the rake.
|
|
- **pointed_thing**: the pointed thing when the rake is used.
|
|
- **uses**: the maximum number of times the ItemStack object can be used.
|
|
|
|
#### Returns
|
|
|
|
- **ItemStack**: the ItemStack specified as an argument (worn-out, if it should be)
|
|
|
|
## 3. Sickles
|
|
|
|
### 3.1. `farmtools.register_sickle`
|
|
|
|
The function used for registering new sickles.
|
|
|
|
#### Usage
|
|
|
|
```lua
|
|
local S = core.get_translator("my_mod")
|
|
|
|
farmtools.register_sickle("my_mod:my_sickle", {
|
|
description = S("My Sickle"),
|
|
inventory_image = "my_mod_my_sickle.png",
|
|
max_uses = 200,
|
|
material = "my_mod:my_material_ingot",
|
|
damage_groups = { fleshy = 2 },
|
|
groupcaps = {
|
|
snappy = { times = { [1] = 2.75, [2] = 1.30, [3] = 0.375 }, uses = 100, maxlevel = 2 }
|
|
}
|
|
})
|
|
```
|
|
|
|
#### Arguments
|
|
|
|
- **name**: the name of the item to register as a sickle (e.g. `"my_mod:my_sickle"`).
|
|
- **def**: the definition table, that can contain:
|
|
- **description**: the name of the item as shown to the user (default: `Sickle`).
|
|
- **inventory_image**: the image of the item to display in the game (default: `unknown_item.png`)
|
|
- **max_uses**: the number of times the rake can be used (default: `120`).
|
|
- **material**: the material used for the default sickle recipe (no default: if not specified, the recipe won't be registered)
|
|
- **recipe**: alternatively, it is possible to specify the recipe directly (note that this will override any `material` specified)
|
|
- **damage_groups**: a table containing the damage the item can do to different entity groups.
|
|
- **groupcaps**: a `groupcaps` table ([more information here](https://api.luanti.org/tool-capabilities/#uses-uses-tools-only)).
|
|
|
|
#### Default recipe
|
|
|
|
The default recipe for sickles is as follow (it can be overriden using `recipe` in the definition table):
|
|
|
|
```text
|
|
----------------------------------
|
|
| | | |
|
|
| material | | |
|
|
| | | |
|
|
----------------------------------
|
|
| | | |
|
|
| | material | |
|
|
| | | |
|
|
----------------------------------
|
|
| | | |
|
|
| stick | | |
|
|
| | | |
|
|
----------------------------------
|
|
```
|
|
|
|
### 3.2. `farmtools.register_cuttable`
|
|
|
|
The function used for registering nodes that can be cut with the sickle.
|
|
|
|
#### Usage
|
|
|
|
```lua
|
|
farmtools.register_cuttable(nodename, base, item)
|
|
-- e.g.:
|
|
farmtools.register_cuttable("default:mossycobble", "default:cobble", "farmtools:moss")
|
|
```
|
|
|
|
#### Arguments
|
|
|
|
- **nodename**: the node to register as cuttable
|
|
- **base**: the node that should be put in place of the cuttable node after it is cut
|
|
- **item**: the item that the player obtains when cutting the cuttable node
|
|
|
|
### 3.3. `farmtools.register_trimmable`
|
|
|
|
The function used for registering nodes that can be trimmed with the sickle.
|
|
|
|
#### Usage
|
|
|
|
```lua
|
|
farmtools.register_trimmable(node, base)
|
|
-- e.g.:
|
|
farmtools.register_trimmable("farming:wheat_8", "farming:wheat_2")
|
|
```
|
|
|
|
#### Arguments
|
|
|
|
- **node**: the node to register as trimmable
|
|
- **base**: the node that should be put in place of the trimmable node after it is trimmed
|