Helper methods for hardware colorization (#5870)

2 files changed, 30 insertions, 3 deletions

diff --git a/builtin/game/item.lua b/builtin/game/item.lua
index f6de2c339..59ec5ff65 100644
--- a/builtin/game/item.lua
+++ b/builtin/game/item.lua
@@ -572,6 +572,18 @@ function core.node_dig(pos, node, digger)
 	end
 end
 
+function core.itemstring_with_palette(item, palette_index)
+	local stack = ItemStack(item) -- convert to ItemStack
+	stack:get_meta():set_int("palette_index", palette_index)
+	return stack:to_string()
+end
+
+function core.itemstring_with_color(item, colorstring)
+	local stack = ItemStack(item) -- convert to ItemStack
+	stack:get_meta():set_string("color", colorstring)
+	return stack:to_string()
+end
+
 -- This is used to allow mods to redefine core.item_place and so on
 -- NOTE: This is not the preferred way. Preferred way is to provide enough
 --       callbacks to not require redefining global functions. -celeron55
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 664ad960a..540bbe118 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -541,10 +541,8 @@ to itself (without metadata).
 Craft recipes only support item strings, but fortunately item strings
 can also contain metadata. Example craft recipe registration:
 
-    local stack = ItemStack("wool:block")
-    dyed:get_meta():set_int("palette_index", 3) -- add index
     minetest.register_craft({
-        output = dyed:to_string(), -- convert to string
+        output = minetest.itemstring_with_palette("wool:block", 3),
         type = "shapeless",
         recipe = {
             "wool:block",
@@ -552,6 +550,8 @@ can also contain metadata. Example craft recipe registration:
         },
     })
 
+To set the `color` field, you can use `minetest.itemstring_with_color`.
+
 Metadata field filtering in the `recipe` field are not supported yet,
 so the craft output is independent of the color of the ingredients.
 
@@ -2728,6 +2728,21 @@ and `minetest.auth_reload` call the authetification handler.
       digger's inventory
     * Can be overridden to get different functionality (e.g. dropping items on
       ground)
+* `minetest.itemstring_with_palette(item, palette_index)`: returns an item string
+    * Creates an item string which contains palette index information
+      for hardware colorization. You can use the returned string
+      as an output in a craft recipe.
+    * `item`: the item stack which becomes colored. Can be in string,
+      table and native form.
+    * `palette_index`: this index is added to the item stack
+* `minetest.itemstring_with_color(item, colorstring)`: returns an item string
+    * Creates an item string which contains static color information
+      for hardware colorization. Use this method if you wish to colorize
+      an item that does not own a palette. You can use the returned string
+      as an output in a craft recipe.
+    * `item`: the item stack which becomes colored. Can be in string,
+      table and native form.
+    * `colorstring`: the new color of the item stack
 
 ### Rollback
 * `minetest.rollback_get_node_actions(pos, range, seconds, limit)`: