modolith/mods/xdecor/API.md

API for X-Decor-libre

X-Decor-libre is mostly self-contained but it allows for limited extension with a simple API. Not that extensibility is not the main goal of this mod.

The function documentation can be found in the respective source code files under the header "-- API FUNCTIONS ".

These are the features:

Add custom tool enchantments

You can register tools to be able to be enchanted at the enchanting table.

See src/enchanting.lua for details.

Add custom hammers

You can add a custom hammer for repairing tools at the workbench, using custom stats.

See src/workbench.lua for details.

Add cut nodes

You can register "cut" node variants of an existing node which can be created at the workbench. This will add thin stairs, half stairs, panels, microcubes, etc.

See src/workbench.lua for details.

Cauldron compatibility

The cauldron needs to interact with various items and nodes to work properly. It uses ingredients and bowls for soup, and fire nodes to get heated.

If your mod adds fire or hot nodes, bowls or food, this section is relevant for you.

Soup ingredients

The cauldron soup accepts a variety of food items as ingredients for the soup. It uses a heuristic to determine which items it accepts as ingredient.

This heuristic may sometimes fail and recognize strange items as ingredient. To explicitly mark any item as a soup ingredient for xdecor, add the group xdecor_soup_ingredient = 1 to it. To explicitly tell xdecor that an item is NOT a soup ingredient, use xdecor_soup_ingredient = -1 instead. The -1 should only be used if actually necessary.

Information about the heuristic

Any item without a valid xdecor_soup_ingredient group will be checked by against a heuristic to determine if it counts as a soup ingredient or not. Items that do have this group with a valid value are not subject to the heuristic.

First, the heuristic checks if the item is 'eatable'. This basically checks if the function core.item_eat or (minetest.item_eat) is called. If the item is eatable, it counts as ingredient.

If not, then the heuristic looks at the part of the technical itemname after the colon for certain keywords like 'apple', 'meat', 'potato' etc. (for the full list, see ingredients_list in src/cooking.lua). If a keyword was found, the item counts as an ingredient, otherwise not.

There is also a small blacklist that disqualifies a few items from Minetest Game.

Heater nodes

Cauldrons need a fire below to get heated. All nodes with the group fire or xdecor_cauldron_heater=1 will heat up the cauldron. You can use the latter group if adding the fire group would create problems.

Bowls

Players can use the xdecor:bowl item to collect soup from a cauldron. But other mods also have their own bowls which may not be recognized by X-Decor-libre.

The following items are recognized as bowls that can collect soup from the cauldron:

• Items with group xdecor_soup_bowl=1 (recommended)
• farming:bowl (hardcoded)
• x_farming:bowl (hardcoded)

If you want to make your bowl compatible with the cauldron, add the group xdecor_soup_bowl=1 to it. Only use this for empty bowls!

Please test your bowl!

When any valid bowl is used at the cauldron, it turns into xdecor:bowl_soup. If the soup is eaten, the item will become the original bowl again, even if it was a custom bowl. For custom bowls (not from X-Decor-libre), the xdecor:bowl_soup item remembers the name of the original bowl in the metadata under original_bowl. If original_bowl is the empty string, or contains the name of an unknown item, xdecor:bowl is the assumed default. (However, an unknown item in original_bowl will trigger a warning.)

Custom Chess bot (experimental)

You can replace the (very weak) Chess computer player with a custom one. See src/chess.lua for details (realchess.set_chessbot).

Note this feature is relatively experimental, but it has survived first initial tests.

Groups

This mod introduces the following groups:

• potted_flower=1: Potted flower
• food_bowl=1: Empty bowl
• lever=X: Lever (1 = off, 2 = on)
• pressure_plate=X: Pressure plate (1 = off, 2 = on)
• cauldron=X: Cauldron
  • 1: Empty cauldron
  • 2: Cauldron with cold liquid
  • 3: Cauldron with boiling liquid
• xdecor_cut=1: For nodes cut by the workbench (not the normal slab, normal stair, inner or outer stair). Cut nodes will also receive one of the following groups to specify the shape:
  • xdecor_cut_microslab=1: Microslab
  • xdecor_cut_nanoslab=1: Nanoslab
  • xdecor_cut_panel=1: Panel
  • xdecor_cut_doublepanel=1: Double panel
  • xdecor_cut_micropanel=1: Micropanel
  • xdecor_cut_cube=1: Cube
  • xdecor_cut_halfstair=1: Half stair
  • xdecor_cut_thinstair=1: Thin stair
• not_cuttable=1: Prevent this node from being cut by the workbench
• repair_hammer=1: A hammer that repairs tools (do not add this group manually, see src/workbench.lua)
• chess_piece=X: Chess piece for Chess (see src/chess.lua for details)
• enchanted_tool=1: Enchanted tool
  • enchantment_durable=1: Enchanted tool with Durability enchantment
  • enchantment_fast=1: Enchanted tool with Efficiency enchantment
  • enchantment_sharp=1: Enchanted tool with Sharpness enchantment

These groups are for cauldron features (please read the “Cauldron compatibility” section above before using them):

• xdecor_soup_ingredient=1: Add this item as a possible soup ingredient
• xdecor_soup_ingredient=-1: Exclude this item as a possible soup ingredient
• xdecor_cauldron_heater=1: If placed below cauldron, it will heat it up
• xdecor_soup_bowl=1: A bowl that can collect soup from the cauldron

These groups are reserved for internal use:

• xdecor_actuator=X: A node that can turned on and off and toggles neighboring doors. 1 = off, 2 = on. Used by lever and pressure plate
• sittable=1: Player can sit down on this node (also needs to call xdecor.sit to function)