i3/API.md

442 lines
9.7 KiB
Markdown
Raw Normal View History

2023-01-19 17:30:57 +01:00
# API :screwdriver:
2023-01-19 16:47:50 +01:00
2023-01-19 17:30:57 +01:00
### Table of Contents
2023-01-19 16:47:50 +01:00
1. [**Tabs**](https://github.com/minetest-mods/i3/blob/main/API.md#tabs)
2. [**Recipes**](https://github.com/minetest-mods/i3/blob/main/API.md#recipes)
3. [**Minitabs**](https://github.com/minetest-mods/i3/blob/main/API.md#minitabs)
4. [**Recipe filters**](https://github.com/minetest-mods/i3/blob/main/API.md#recipe-filters)
5. [**Search filters**](https://github.com/minetest-mods/i3/blob/main/API.md#search-filters)
6. [**Sorting methods**](https://github.com/minetest-mods/i3/blob/main/API.md#sorting-methods)
7. [**Item list compression**](https://github.com/minetest-mods/i3/blob/main/API.md#item-list-compression)
8. [**Waypoints**](https://github.com/minetest-mods/i3/blob/main/API.md#waypoints)
9. [**Miscellaneous**](https://github.com/minetest-mods/i3/blob/main/API.md#miscellaneous)
2020-12-30 23:21:05 +01:00
2023-01-19 16:47:50 +01:00
---
### Tabs
2021-01-16 01:46:26 +01:00
2021-11-15 00:56:27 +01:00
#### `i3.new_tab(name, def)`
2021-01-16 04:44:25 +01:00
2021-11-19 19:35:41 +01:00
- `name` is the tab name.
- `def` is the tab definition.
2021-01-16 01:46:26 +01:00
Custom tabs can be added to the `i3` inventory as follow (example):
```Lua
i3.new_tab("stuff", {
2021-01-16 01:46:26 +01:00
description = "Stuff",
2022-11-12 19:40:06 +01:00
image = "image.png", -- Optional, add an image next to the tab description
2021-01-16 01:46:26 +01:00
2022-11-12 19:40:06 +01:00
--
-- The functions below are all optional
--
-- Determine if the tab is visible by a player, return false to hide the tab
2021-01-16 01:46:26 +01:00
access = function(player, data)
local name = player:get_player_name()
2022-03-23 03:52:08 +01:00
return name == "singleplayer"
2021-01-16 01:46:26 +01:00
end,
formspec = function(player, data, fs)
2022-11-12 19:40:06 +01:00
fs("label", 3, 1, "Just a test")
fs"label[3,2;Lorem Ipsum]"
-- No need to return anything
2021-01-16 01:46:26 +01:00
end,
2021-10-25 23:40:04 +02:00
-- Events handling happens here
2021-01-16 01:46:26 +01:00
fields = function(player, data, fields)
2022-09-15 12:23:44 +02:00
if fields.mybutton then
2022-11-12 19:40:06 +01:00
-- Do things
2022-09-15 12:23:44 +02:00
end
2022-11-12 19:40:06 +01:00
2023-01-19 17:30:57 +01:00
i3.set_fs(player) -- Update the formspec
2021-01-16 01:46:26 +01:00
end,
})
2021-01-16 01:46:26 +01:00
```
- `player` is an `ObjectRef` to the user.
- `data` are the user data.
2022-09-15 12:23:44 +02:00
- `fs` is the formspec table which is callable with a metamethod. Every call adds a new entry.
2021-01-30 23:21:20 +01:00
#### `i3.set_fs(player)`
2021-01-30 23:21:20 +01:00
2022-09-15 12:23:44 +02:00
Update the current formspec.
2021-01-16 01:46:26 +01:00
2021-06-30 21:54:18 +02:00
#### `i3.remove_tab(tabname)`
2021-01-16 04:44:25 +01:00
2022-09-15 12:23:44 +02:00
Delete a tab by name.
2021-01-16 04:44:25 +01:00
#### `i3.get_current_tab(player)`
2022-09-15 12:23:44 +02:00
Return the current player tab. `player` is an `ObjectRef` to the user.
2021-01-30 23:21:20 +01:00
#### `i3.set_tab(player[, tabname])`
2021-01-28 21:00:08 +01:00
Sets the current tab by name. `player` is an `ObjectRef` to the user.
2021-01-30 23:21:20 +01:00
`tabname` can be omitted to get an empty tab.
2021-01-28 21:00:08 +01:00
2021-01-29 02:51:46 +01:00
#### `i3.override_tab(tabname, def)`
2021-01-28 21:00:08 +01:00
2022-09-15 12:23:44 +02:00
Override a tab by name. `def` is the tab definition like seen in `i3.set_tab`
2021-01-28 21:00:08 +01:00
2021-10-19 03:56:37 +02:00
#### `i3.tabs`
2021-01-16 04:44:25 +01:00
2021-10-19 03:56:37 +02:00
A list of registered tabs.
2021-01-16 04:44:25 +01:00
---
2023-01-19 16:47:50 +01:00
### Recipes
2020-12-30 23:21:05 +01:00
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.
2022-09-15 12:23:44 +02:00
The width is automatically calculated depending where you place the commas.
Examples:
2020-12-30 23:21:05 +01:00
2022-09-15 12:23:44 +02:00
#### Registering a custom crafting type
2020-12-30 23:21:05 +01:00
```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",
})
```
2022-09-15 12:23:44 +02:00
#### Registering a custom crafting recipe
2020-12-30 23:21:05 +01:00
```Lua
2021-10-19 03:56:37 +02:00
i3.register_craft {
2020-12-30 23:21:05 +01:00
type = "digging",
result = "default:cobble 2",
items = {"default:stone"},
2021-10-19 03:56:37 +02:00
}
2020-12-30 23:21:05 +01:00
```
```Lua
2021-10-19 03:56:37 +02: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",
}
2021-10-19 03:56:37 +02:00
}
2020-12-30 23:21:05 +01:00
```
Recipes can be registered in a Minecraft-like way:
```Lua
2021-10-19 03:56:37 +02: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",
2021-10-19 03:56:37 +02:00
}
2020-12-30 23:21:05 +01:00
```
Multiples recipes can also be registered:
```Lua
2021-10-19 03:56:37 +02: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",
}
},
2021-10-19 03:56:37 +02:00
}
2020-12-30 23:21:05 +01:00
```
Recipes can be registered from a given URL containing a JSON file (HTTP support is required¹):
```Lua
2021-10-19 03:56:37 +02:00
i3.register_craft {
2021-06-26 03:10:05 +02:00
url = "https://raw.githubusercontent.com/minetest-mods/i3/main/tests/test_online_recipe.json"
2021-10-19 03:56:37 +02:00
}
2020-12-30 23:21:05 +01:00
```
---
2023-01-19 16:40:31 +01:00
### Minitabs
Manage the tabs on the right panel of the inventory.
Allow to make a sensible list sorted by specific groups of items.
#### `i3.new_minitab(name, def)`
Add a new minitab (limited to 6).
- `name` is the tab name.
- `def` is the definition table.
Example:
```Lua
2023-01-19 18:57:16 +01:00
i3.new_minitab("test", {
description = "Test",
-- Whether this tab is visible or not. Optional.
2023-01-19 16:40:31 +01:00
access = function(player, data)
return player:get_player_name() == "singleplayer"
end,
2023-01-19 18:57:16 +01:00
-- Whether a specific item is shown in the list or not.
2023-01-19 16:40:31 +01:00
sorter = function(item, data)
return item:find"wood"
end
})
```
- `player` is an `ObjectRef` to the user.
- `data` are the user data.
- `item` is an item name string.
#### `i3.remove_minitab(name)`
2023-01-19 18:57:16 +01:00
Remove a minitab by name.
- `name` is the name of the tab to remove.
2023-01-19 16:40:31 +01:00
#### `i3.minimap`
A list of registered minitabs.
---
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
2022-09-15 12:23:44 +02:00
Add a recipe filter with the given `name`. The filter function returns the
2020-12-30 23:21:05 +01:00
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
2022-09-15 12:23:44 +02:00
Remove all recipe filters and add a new one.
2020-12-30 23:21:05 +01:00
#### `i3.recipe_filters`
2020-12-30 23:21:05 +01:00
A map of recipe filters, indexed by name.
2020-12-30 23:21:05 +01:00
---
### Search filters
2021-10-25 23:40:04 +02:00
Search filters are used to perform specific searches from the search field.
The filters can be cumulated to perform a specific search.
They are used like so: `<optional_name> +<filter name>=<value1>,<value2>,<...>`
2020-12-30 23:21:05 +01:00
2021-01-23 20:11:28 +01:00
Example usages:
2020-12-30 23:21:05 +01:00
2021-10-25 05:31:58 +02:00
- `+groups=cracky,crumbly` -> search for groups `cracky` and `crumbly` in all items.
- `wood +groups=flammable` -> search for group `flammable` amongst items which contain
2021-06-26 06:22:03 +02:00
`wood` in their names.
2020-12-30 23:21:05 +01:00
Notes:
- If `optional_name` is omitted, the search filter will apply to all items, without pre-filtering.
2021-06-26 06:22:03 +02:00
- The `+groups` filter is currently implemented by default.
2020-12-30 23:21:05 +01:00
2020-12-30 23:23:48 +01:00
#### `i3.add_search_filter(name, function(item, values))`
2020-12-30 23:21:05 +01:00
2022-09-15 12:23:44 +02:00
Add a search filter.
The search function must return a boolean value (whether the given item should be listed or not).
2020-12-30 23:21:05 +01:00
2021-10-25 23:40:04 +02:00
- `name` is the filter name.
- `values` is a table of all possible values.
Example function sorting items by drawtype:
2020-12-30 23:21:05 +01:00
```lua
2021-01-24 23:08:49 +01:00
i3.add_search_filter("types", function(item, drawtypes)
local t = {}
for i, dt in ipairs(drawtypes) do
t[i] = (dt == "node" and reg_nodes[item] and 1) or
(dt == "item" and reg_craftitems[item] and 1) or
(dt == "tool" and reg_tools[item] and 1) or nil
2020-12-30 23:21:05 +01:00
end
2021-01-24 23:08:49 +01:00
return #t > 0
2020-12-30 23:21:05 +01:00
end)
```
#### `i3.search_filters`
2020-12-30 23:21:05 +01:00
A map of search filters, indexed by name.
2020-12-30 23:21:05 +01:00
---
### Sorting methods
Sorting methods are used to filter the player's main inventory.
2021-11-19 19:35:41 +01:00
#### `i3.add_sorting_method(name, def)`
2022-09-15 12:23:44 +02:00
Add a player inventory sorting method.
2021-11-19 19:35:41 +01:00
- `name` is the method name.
- `def` is the method definition.
Example:
```Lua
2021-11-19 19:35:41 +01:00
i3.add_sorting_method("test", {
description = "Cool sorting method",
func = function(list, data)
-- `list`: inventory list
-- `data`: player data
table.sort(list)
-- A list must be returned
return list
end,
2021-11-19 19:35:41 +01:00
})
```
#### `i3.sorting_methods`
A table containing all sorting methods.
---
2021-10-25 23:40:04 +02:00
### Item list compression
2021-10-25 00:14:21 +02:00
2021-10-25 23:40:04 +02:00
`i3` can reduce the item list size by compressing a group of items.
2021-10-25 00:14:21 +02:00
#### `i3.compress(item, def)`
2022-09-15 12:23:44 +02:00
Add a new group of items to compress.
2021-10-25 00:14:21 +02:00
2022-01-31 18:09:53 +01:00
- `item` is the item which represent the group of compressed items.
2021-10-25 00:14:21 +02:00
- `def` is a table specifying the substring replace patterns to be used.
Example:
```Lua
i3.compress("default:diamondblock", {
replace = "diamond",
by = {"bronze", "copper", "gold", "steel", "tin"}
})
```
2021-10-25 05:31:58 +02:00
#### `i3.compress_groups`
2021-10-25 00:14:21 +02:00
2021-10-25 05:31:58 +02:00
A map of all compressed item groups, indexed by stereotypes.
2021-10-25 00:14:21 +02:00
---
2023-01-07 12:28:07 +01:00
### Waypoints
`i3` allows you to manage the waypoints of a specific player.
#### `i3.add_waypoint(player_name, def)`
Add a waypoint to specific player.
- `player_name` is the player name.
- `def` is the waypoint definition table.
Example:
```Lua
i3.add_waypoint("Test", {
player = "singleplayer",
pos = {x = 0, y = 2, z = 0},
color = 0xffff00,
-- image = "heart.png" (optional)
})
```
#### `i3.remove_waypoint(player_name, waypoint_name)`
Remove a waypoint for specific player.
- `player_name` is the player name.
- `waypoint_name` is the waypoint name.
Example:
```Lua
i3.remove_waypoint("singleplayer", "Test")
```
#### `i3.get_waypoints(player_name)`
Return a table of all waypoints of a specific player.
- `player_name` is the player name.
---
2020-12-30 23:21:05 +01:00
### Miscellaneous
2021-11-26 03:32:04 +01:00
#### `i3.hud_notif(name, msg[, img])`
2022-09-15 12:23:44 +02:00
Show a Steam-like HUD notification on the bottom-right corner of the screen (experimental).
2021-11-26 03:32:04 +01:00
- `name` is the player name.
- `msg` is the HUD message to show.
- `img` (optional) is the HUD image to show (preferably 16x16 px).
2021-10-18 21:21:33 +02:00
#### `i3.get_recipes(item)`
2022-09-15 12:23:44 +02:00
Return a table of recipes and usages of `item`.
2021-10-18 21:21:33 +02: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¹).
2021-11-09 01:36:20 +01:00
#### `groups = {bag = <1-4>}`
2021-10-18 21:11:07 +02:00
The `bag` group in the item definition allows to extend the player inventory size
2021-11-09 01:36:20 +01:00
given a number between 1 and 4.
2021-10-18 21:11:07 +02:00
2020-12-30 23:21:05 +01:00
---
2020-12-30 23:23:48 +01:00
**¹** Add `i3` to the `secure.http_mods` or `secure.trusted_mods` setting in `minetest.conf`.