509 lines
11 KiB
Markdown
509 lines
11 KiB
Markdown
# API :screwdriver:
|
||
|
||
### Table of Contents
|
||
1. [**Tabs**](#tabs)
|
||
2. [**Footer buttons**](#footer-buttons)
|
||
3. [**Recipes**](#recipes)
|
||
4. [**Minitabs**](#minitabs)
|
||
5. [**Recipe filters**](#recipe-filters)
|
||
6. [**Search filters**](#search-filters)
|
||
7. [**Sorting methods**](#sorting-methods)
|
||
8. [**Item list compression**](#item-list-compression)
|
||
9. [**Waypoints**](#waypoints)
|
||
10. [**Miscellaneous**](#miscellaneous)
|
||
|
||
---
|
||
|
||
### Tabs
|
||
|
||
|
||
|
||
#### `i4.new_tab(name, def)`
|
||
|
||
- `name` is the tab name.
|
||
- `def` is the tab definition.
|
||
|
||
Custom tabs can be added to the `i4` inventory as follow (example):
|
||
|
||
```Lua
|
||
i4.new_tab("stuff", {
|
||
description = "Stuff",
|
||
image = "speech_icon.png", -- Optional, add an image next to the tab description
|
||
slots = true, -- Optional, whether the inventory slots are shown or not. Disabled by default.
|
||
|
||
--
|
||
-- The functions below are all optional
|
||
--
|
||
|
||
-- Determine if the tab is visible by a player, return false to hide the tab
|
||
access = function(player, data)
|
||
local name = player:get_player_name()
|
||
return name == "singleplayer"
|
||
end,
|
||
|
||
-- Build the formspec
|
||
formspec = function(player, data, fs)
|
||
fs("label", 3, 1, "Just a test")
|
||
fs"label[3,2;Lorem Ipsum]"
|
||
-- No need to return anything
|
||
end,
|
||
|
||
-- Events handling happens here
|
||
fields = function(player, data, fields)
|
||
if fields.mybutton then
|
||
-- Do things
|
||
end
|
||
|
||
-- To prevent a formspec update, return false.
|
||
-- Otherwise: no need to return anything, it's automatic.
|
||
end,
|
||
})
|
||
```
|
||
|
||
- `player` is an `ObjectRef` to the user.
|
||
- `data` are the user data.
|
||
- `fs` is the formspec table which is callable with a metamethod. Every call adds a new entry.
|
||
|
||
#### `i4.set_fs(player)`
|
||
|
||
Update the current formspec.
|
||
|
||
#### `i4.remove_tab(tabname)`
|
||
|
||
Delete a tab by name.
|
||
|
||
#### `i4.get_current_tab(player)`
|
||
|
||
Return the current player tab. `player` is an `ObjectRef` to the user.
|
||
|
||
#### `i4.set_tab(player[, tabname])`
|
||
|
||
Set the current tab by name. `player` is an `ObjectRef` to the user.
|
||
`tabname` can be omitted to get an empty tab.
|
||
|
||
#### `i4.override_tab(tabname, def)`
|
||
|
||
Override a tab by name. `def` is the tab definition like seen in `i4.set_tab`
|
||
|
||
#### `i4.tabs`
|
||
|
||
A list of registered tabs.
|
||
|
||
---
|
||
|
||
### Footer buttons
|
||
|
||
|
||
`i4.new_footer_button(name, def)`
|
||
|
||
* `name` is the footer button’s name.
|
||
* `def` is the button defintion.
|
||
|
||
Custom footer buttons can be added beside the trash, sort, and settings buttons. For example:
|
||
|
||
```Lua
|
||
i4.new_footer_button("broadcast_msg", {
|
||
description = "Broadcast message",
|
||
image = "speech_icon.png", -- Required, this is the button’s icon.
|
||
|
||
--
|
||
-- The functions below are all optional
|
||
--
|
||
|
||
-- Determine if the button is visible by a player, return false to hide the button.
|
||
access = function(player, data)
|
||
return true
|
||
end,
|
||
|
||
-- Build the formspec
|
||
formspec = function(player, data, fs)
|
||
-- Button style nicked from i4 directly.
|
||
fs([[
|
||
style[send_msg_button,confirm_trash_no,set_home;noclip=true;font_size=16;
|
||
bgimg=i4_btn9.png;bgimg_hovered=i4_btn9_hovered.png;
|
||
bgimg_pressed=i4_btn9_pressed.png;bgimg_middle=4,6]
|
||
]])
|
||
|
||
fs("image[5,10.65;3,0.5;i4_bg_goto.png]")
|
||
fs("field[5,10.65;3,0.5;chat_msg_field;;]")
|
||
fs("button[8,10.65;1,0.5;send_msg_button;Send]")
|
||
-- No need to return anything
|
||
end,
|
||
|
||
-- Events handling happens here
|
||
fields = function(player, data, fields)
|
||
if fields.key_enter_field == "chat_msg_field" or fields.send_msg_button then
|
||
minetest.chat_send_all("Broadcast: " .. fields.chat_msg_field)
|
||
return false -- To close a footer button’s dialogue, return false.
|
||
end
|
||
return true -- To keep a footer button active, return true.
|
||
end,
|
||
})
|
||
```
|
||
#### `i4.remove_footer_button(button_name)`
|
||
|
||
Delete a footer button by name.
|
||
|
||
#### `i4.override_footer_button(button_name, def)`
|
||
|
||
Override a footer button by name. `def` is the button definition like seen in `i4.new_footer_button`
|
||
|
||
#### `i4.footer_buttons`
|
||
|
||
A list of registered footer buttons.
|
||
|
||
### 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.
|
||
|
||
Examples:
|
||
|
||
#### Registering a custom crafting type
|
||
|
||
```Lua
|
||
i4.register_craft_type("digging", {
|
||
description = "Digging",
|
||
icon = "default_tool_steelpick.png",
|
||
})
|
||
```
|
||
|
||
#### Registering a custom crafting recipe
|
||
|
||
```Lua
|
||
i4.register_craft {
|
||
type = "digging",
|
||
result = "default:cobble 2",
|
||
items = {"default:stone"},
|
||
}
|
||
```
|
||
|
||
```Lua
|
||
i4.register_craft {
|
||
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
|
||
i4.register_craft {
|
||
grid = {
|
||
"X #",
|
||
" ## ",
|
||
"X#X#",
|
||
"X X",
|
||
},
|
||
key = {
|
||
['#'] = "default:wood",
|
||
['X'] = "default:glass",
|
||
},
|
||
result = "default:mese 3",
|
||
}
|
||
```
|
||
|
||
Multiple recipes can also be registered at once:
|
||
|
||
```Lua
|
||
i4.register_craft {
|
||
{
|
||
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
|
||
i4.register_craft {
|
||
url = "https://raw.githubusercontent.com/minetest-mods/i4/main/tests/test_online_recipe.json"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Minitabs
|
||
|
||
Manage the tabs on the right panel of the inventory.
|
||
Allow to make a sensible list sorted by specific groups of items.
|
||
|
||
#### `i4.new_minitab(name, def)`
|
||
|
||
Add a new minitab (limited to 6).
|
||
|
||
- `name` is the tab name.
|
||
- `def` is the definition table.
|
||
|
||
Example:
|
||
|
||
```Lua
|
||
i4.new_minitab("test", {
|
||
description = "Test",
|
||
|
||
-- Whether this tab is visible or not. Optional.
|
||
access = function(player, data)
|
||
return player:get_player_name() == "singleplayer"
|
||
end,
|
||
|
||
-- Whether a specific item is shown in the list or not.
|
||
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.
|
||
|
||
#### `i4.remove_minitab(name)`
|
||
|
||
Remove a minitab by name.
|
||
|
||
- `name` is the name of the tab to remove.
|
||
|
||
#### `i4.minitabs`
|
||
|
||
A list of registered minitabs.
|
||
|
||
---
|
||
|
||
### Recipe filters
|
||
|
||
Recipe filters can be used to filter the recipes shown to players. Progressive
|
||
mode is implemented as a recipe filter.
|
||
|
||
#### `i4.add_recipe_filter(name, function(recipes, player))`
|
||
|
||
Add a recipe filter with the given `name`. The filter function returns 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
|
||
i4.add_recipe_filter("Hide secretstuff", function(recipes)
|
||
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)
|
||
```
|
||
|
||
#### `i4.set_recipe_filter(name, function(recipe, player))`
|
||
|
||
Remove all recipe filters and add a new one.
|
||
|
||
#### `i4.recipe_filters`
|
||
|
||
A map of recipe filters, indexed by name.
|
||
|
||
---
|
||
|
||
### Search filters
|
||
|
||
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>,<...>`
|
||
|
||
Example usages:
|
||
|
||
- `+groups=cracky,crumbly` -> search for groups `cracky` and `crumbly` in all items.
|
||
- `wood +groups=flammable` -> search for group `flammable` amongst items which contain
|
||
`wood` in their names.
|
||
|
||
Notes:
|
||
- If `optional_name` is omitted, the search filter will apply to all items, without pre-filtering.
|
||
- The `+groups` filter is currently implemented by default.
|
||
|
||
#### `i4.add_search_filter(name, function(item, values))`
|
||
|
||
Add a search filter.
|
||
The search function must return a boolean value (whether the given item should be listed or not).
|
||
|
||
- `name` is the filter name.
|
||
- `values` is a table of all possible values.
|
||
|
||
Example function sorting items by drawtype:
|
||
|
||
```lua
|
||
i4.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
|
||
end
|
||
|
||
return #t > 0
|
||
end)
|
||
```
|
||
|
||
#### `i4.search_filters`
|
||
|
||
A map of search filters, indexed by name.
|
||
|
||
---
|
||
|
||
### Sorting methods
|
||
|
||
Sorting methods are used to filter the player's main inventory.
|
||
|
||
#### `i4.add_sorting_method(name, def)`
|
||
|
||
Add a player inventory sorting method.
|
||
|
||
- `name` is the method name.
|
||
- `def` is the method definition.
|
||
|
||
Example:
|
||
|
||
```Lua
|
||
i4.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,
|
||
})
|
||
|
||
```
|
||
|
||
#### `i4.sorting_methods`
|
||
|
||
A table containing all sorting methods.
|
||
|
||
---
|
||
|
||
### Item list compression
|
||
|
||
`i4` can reduce the item list size by compressing a group of items.
|
||
|
||
#### `i4.compress(item, def)`
|
||
|
||
Add a new group of items to compress.
|
||
|
||
- `item` is the item which represent the group of compressed items.
|
||
- `def` is a table specifying the substring replace patterns to be used.
|
||
|
||
Example:
|
||
|
||
```Lua
|
||
i4.compress("default:diamondblock", {
|
||
replace = "diamond",
|
||
by = {"bronze", "copper", "gold", "steel", "tin"}
|
||
})
|
||
|
||
```
|
||
|
||
#### `i4.compress_groups`
|
||
|
||
A map of all compressed item groups, indexed by stereotypes.
|
||
|
||
---
|
||
|
||
### Waypoints
|
||
|
||
`i4` allows you to manage the waypoints of a specific player.
|
||
|
||
#### `i4.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
|
||
i4.add_waypoint("Test", {
|
||
player = "singleplayer",
|
||
pos = {x = 0, y = 2, z = 0},
|
||
color = 0xffff00,
|
||
-- image = "heart.png" (optional)
|
||
})
|
||
```
|
||
|
||
#### `i4.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
|
||
i4.remove_waypoint("singleplayer", "Test")
|
||
```
|
||
|
||
#### `i4.get_waypoints(player_name)`
|
||
|
||
Return a table of all waypoints of a specific player.
|
||
|
||
- `player_name` is the player name.
|
||
|
||
---
|
||
|
||
### Miscellaneous
|
||
|
||
#### `i4.hud_notif(name, msg[, img])`
|
||
|
||
Show a Steam-like HUD notification on the bottom-left corner of the screen.
|
||
|
||
- `name` is the player name.
|
||
- `msg` is the HUD message to show.
|
||
- `img` (optional) is the HUD image to show (preferably 16x16 px).
|
||
|
||
#### `i4.get_recipes(item)`
|
||
|
||
Return a table of recipes and usages of `item`.
|
||
|
||
#### `i4.export_url`
|
||
|
||
If set, the mod will export all the cached recipes and usages in a JSON format
|
||
to the given URL (HTTP support is required¹).
|
||
|
||
#### `groups = {bag = <1-4>}`
|
||
|
||
The `bag` group in the item definition allows to extend the player inventory size
|
||
given a number between 1 and 4.
|
||
|
||
---
|
||
|
||
**[1]** Add `i4` to the `secure.http_mods` or `secure.trusted_mods` setting in `minetest.conf`.
|