diff --git a/API.md b/API.md new file mode 100644 index 0000000..b73893d --- /dev/null +++ b/API.md @@ -0,0 +1,72 @@ +## API + +### Custom recipes + +#### Registering a custom crafting type (example) + +```Lua +craftguide.register_craft_type("digging", { + description = "Digging", + icon = "default_tool_steelpick.png", +}) +``` + +#### Registering a custom crafting recipe (example) + +```Lua +craftguide.register_craft({ + type = "digging", + width = 1, + output = "default:cobble 2", + items = {"default:stone"}, +}) +``` + +### Recipe filters + +Recipe filters can be used to filter the recipes shown to players. Progressive +mode is implemented as a recipe filter. + +#### `craftguide.add_recipe_filter(name, function(recipes, player))` + +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 +craftguide.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) +``` + +#### `craftguide.remove_recipe_filter(name)` + +Removes the recipe filter with the given name. + +#### `craftguide.set_recipe_filter(name, function(recipe, player))` + +Removes all recipe filters and adds a new one. + +#### `craftguide.get_recipe_filters()` + +Returns a map of recipe filters, indexed by name. + +### Miscellaneous + +#### `craftguide.show(player_name, item, show_usages)` + +Opens the Crafting Guide with the current filter applied. + + * `player_name`: string param. + * `item`: optional, string param. If set, this item is pre-selected. If the item does not exist or has no recipe, use the player's previous selection. By default, player's previous selection is used + * `show_usages`: optional, boolean param. If true, show item usages. diff --git a/README.md b/README.md index 203f717..00f7e8e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ This crafting guide is a blue book named *"Crafting Guide"* or a wooden sign. This crafting guide features a **progressive mode**. -The progressive mode is a Terraria-like system that only shows recipes you can craft +The progressive mode is a Terraria-like system that shows recipes you can craft from items you ever had in your inventory. To enable it: `craftguide_progressive_mode = true` in `minetest.conf`. `craftguide` is also integrated in `sfinv` (Minetest Game inventory). To enable it: @@ -14,80 +14,8 @@ from items you ever had in your inventory. To enable it: `craftguide_progressive Use the command `/craft` to show the recipe(s) of the pointed node. +For developers, `craftguide` also has a [modding API](https://github.com/minetest-mods/craftguide/blob/master/API.md). + + ![Preview2](https://i.imgur.com/bToFH38.png) ---- - -## API - -### Custom recipes - -#### Registering a custom crafting type (example) - -```Lua -craftguide.register_craft_type("digging", { - description = "Digging", - icon = "default_tool_steelpick.png", -}) -``` - -#### Registering a custom crafting recipe (example) - -```Lua -craftguide.register_craft({ - type = "digging", - width = 1, - output = "default:cobble 2", - items = {"default:stone"}, -}) -``` - -### Recipe filters - -Recipe filters can be used to filter the recipes shown to players. Progressive -mode is implemented as a recipe filter. - -#### `craftguide.add_recipe_filter(name, function(recipes, player))` - -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 -craftguide.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) -``` - -#### `craftguide.remove_recipe_filter(name)` - -Removes the recipe filter with the given name. - -#### `craftguide.set_recipe_filter(name, function(recipe, player))` - -Removes all recipe filters and adds a new one. - -#### `craftguide.get_recipe_filters()` - -Returns a map of recipe filters, indexed by name. - -### Miscellaneous - -#### `craftguide.show(player_name, item, show_usages)` - -Opens the Crafting Guide with the current filter applied. - - * `player_name`: string param. - * `item`: optional, string param. If set, this item is pre-selected. If the item does not exist or has no recipe, use the player's previous selection. By default, player's previous selection is used - * `show_usages`: optional, boolean param. If true, show item usages. -