i3/API.md

240 lines
5.5 KiB
Markdown
Raw Normal View History

2020-12-30 23:21:05 +01:00
## API
2021-01-16 01:46:26 +01:00
### Custom tabs
Custom tabs can be added to the `i3` inventory as follow (example):
```Lua
i3.new_tab {
name = "stuff",
description = "Stuff",
image = "image.png", -- Optional, adds an image inside the tab
-- Determine if the tab is visible by a player, `false` or `nil` hide the tab
access = function(player, data)
local name = player:get_player_name()
if name == "singleplayer" then
return false
end
end,
formspec = function(player, data, fs)
fs("label[3,1;This is just a test]")
end,
fields = function(player, data, fields)
i3.set_fs(player)
end,
}
```
- `player` is an `ObjectRef` to the user.
- `data` are the user data.
- `fs` is the formspec table which is callable with a metamethod. Each call adds a new entry.
- `i3.set_fs(player)` must be called to update the formspec.
2020-12-30 23:21:05 +01:00
### Custom recipes
Custom recipes are nonconventional crafts outside the main crafting grid.
They can be registered in-game dynamically and have a size beyond 3x3 items.
**Note:** the registration format differs from the default registration format in everything.
The width is automatically calculated depending where you place the commas. Look at the examples attentively.
#### Registering a custom crafting type (example)
```Lua
2020-12-30 23:23:48 +01:00
i3.register_craft_type("digging", {
2020-12-30 23:21:05 +01:00
description = "Digging",
icon = "default_tool_steelpick.png",
})
```
#### Registering a custom crafting recipe (examples)
```Lua
2020-12-30 23:23:48 +01:00
i3.register_craft({
2020-12-30 23:21:05 +01:00
type = "digging",
result = "default:cobble 2",
items = {"default:stone"},
})
```
```Lua
2020-12-30 23:23:48 +01:00
i3.register_craft({
2020-12-30 23:21:05 +01:00
result = "default:cobble 16",
items = {
"default:stone, default:stone, default:stone",
"default:stone, , default:stone",
"default:stone, default:stone, default:stone",
}
})
```
Recipes can be registered in a Minecraft-like way:
```Lua
2020-12-30 23:23:48 +01:00
i3.register_craft({
2020-12-30 23:21:05 +01:00
grid = {
"X #",
" ## ",
"X#X#",
"X X",
},
key = {
['#'] = "default:wood",
['X'] = "default:glass",
},
result = "default:mese 3",
})
```
Multiples recipes can also be registered:
```Lua
2020-12-30 23:23:48 +01:00
i3.register_craft({
2020-12-30 23:21:05 +01:00
{
result = "default:mese",
items = {
"default:mese_crystal, default:mese_crystal",
"default:mese_crystal, default:mese_crystal",
}
},
big = {
result = "default:mese 4",
items = {
"default:mese_crystal, default:mese_crystal",
"default:mese_crystal, default:mese_crystal",
"default:mese_crystal, default:mese_crystal",
"default:mese_crystal, default:mese_crystal",
}
},
})
```
Recipes can be registered from a given URL containing a JSON file (HTTP support is required¹):
```Lua
2020-12-30 23:23:48 +01:00
i3.register_craft({
url = "https://raw.githubusercontent.com/minetest-mods/i3/master/test.json"
2020-12-30 23:21:05 +01:00
})
```
---
### Recipe filters
Recipe filters can be used to filter the recipes shown to players. Progressive
mode is implemented as a recipe filter.
2020-12-30 23:23:48 +01:00
#### `i3.add_recipe_filter(name, function(recipes, player))`
2020-12-30 23:21:05 +01:00
Adds a recipe filter with the given name. The filter function should return the
recipes to be displayed, given the available recipes and an `ObjectRef` to the
user. Each recipe is a table of the form returned by
`minetest.get_craft_recipe`.
Example function to hide recipes for items from a mod called "secretstuff":
```lua
2020-12-30 23:23:48 +01:00
i3.add_recipe_filter("Hide secretstuff", function(recipes)
2020-12-30 23:21:05 +01:00
local filtered = {}
for _, recipe in ipairs(recipes) do
if recipe.output:sub(1,12) ~= "secretstuff:" then
filtered[#filtered + 1] = recipe
end
end
return filtered
end)
```
2020-12-30 23:23:48 +01:00
#### `i3.set_recipe_filter(name, function(recipe, player))`
2020-12-30 23:21:05 +01:00
Removes all recipe filters and adds a new one.
2020-12-30 23:23:48 +01:00
#### `i3.remove_recipe_filter(name)`
2020-12-30 23:21:05 +01:00
Removes the recipe filter with the given name.
2020-12-30 23:23:48 +01:00
#### `i3.get_recipe_filters()`
2020-12-30 23:21:05 +01:00
Returns a map of recipe filters, indexed by name.
---
### Search filters
Search filters are used to perform specific searches inside the search field.
They can be used like so: `<optional name>+<filter name>=<value1>,<value2>,<...>`
Examples:
- `+groups=cracky,crumbly`: search for groups `cracky` and `crumbly` in all items.
- `sand+groups=falling_node`: search for group `falling_node` for items which contain `sand` in their names.
Notes:
- If `optional name` is omitted, the search filter will apply to all items, without pre-filtering.
- Filters can be combined.
- The `groups` filter is currently implemented by default.
2020-12-30 23:23:48 +01:00
#### `i3.add_search_filter(name, function(item, values))`
2020-12-30 23:21:05 +01:00
Adds a search filter with the given name.
The search function should return a boolean value (whether the given item should be listed or not).
Example function to show items which contain at least a recipe of given width(s):
```lua
2020-12-30 23:23:48 +01:00
i3.add_search_filter("widths", function(item, widths)
2020-12-30 23:21:05 +01:00
local has_width
local recipes = recipes_cache[item]
if recipes then
for i = 1, #recipes do
local recipe_width = recipes[i].width
for j = 1, #widths do
local width = tonumber(widths[j])
if width == recipe_width then
has_width = true
break
end
end
end
end
return has_width
end)
```
2020-12-30 23:23:48 +01:00
#### `i3.remove_search_filter(name)`
2020-12-30 23:21:05 +01:00
Removes the search filter with the given name.
2020-12-30 23:23:48 +01:00
#### `i3.get_search_filters()`
2020-12-30 23:21:05 +01:00
Returns a map of search filters, indexed by name.
---
### Miscellaneous
2020-12-30 23:23:48 +01:00
#### `i3.group_stereotypes`
2020-12-30 23:21:05 +01:00
This is the table indexing the item groups by stereotypes.
You can add a stereotype like so:
```Lua
2020-12-30 23:23:48 +01:00
i3.group_stereotypes.radioactive = "mod:item"
2020-12-30 23:21:05 +01:00
```
2020-12-30 23:23:48 +01:00
#### `i3.export_url`
2020-12-30 23:21:05 +01:00
If set, the mod will export all the cached recipes and usages in a JSON format
to the given URL (HTTP support is required¹).
---
2020-12-30 23:23:48 +01:00
**¹** Add `i3` to the `secure.http_mods` or `secure.trusted_mods` setting in `minetest.conf`.