Unified Dyes
The purpose of this mod originally was to supply a complete set of colors for Minetest mod authors to use for colorized nodes, or to reference in recipes. Since the advent of the default dyes mod in minetest_game, this mod has become more of an extension of the default mod and a library for general color handling.
Unified Dyes expands the standard dye set from 15 colors to 32, 89, or 256 (see below).
Dependencies: Minetest engine build newer than 2017-01-23 and a corresponding copy of minetest_game.
Recommends: default flowers mod.
License: GPL 2.0 or higher.
Download: https://github.com/VanessaE/unifieddyes/zipball/master
...or browse the code: https://github.com/VanessaE/unifieddyes
For the 0.4.15-stable version (no hardware coloring or auto-coloring support), get this ZIP file. If you use this version, ALL mods that use Unified Dyes must also be 0.4.15-compatible.
Install: Unzip the distribution file, rename the resultant folder to just "unifieddyes", move it into Minetest's mods folder, and enable it in your world configuration.
Changelog:
Just look at the git commit history: https://github.com/minetest-mods/unifieddyes/commits/master
Used By:
+
"Show list..."
+
"Show images..."
In these images, the "-50%" markings on the left next to some shades mean 50% saturation for all hues in that shade line. Note that the shades above "full" don't have (or need) this variation, since they're already lower-saturation by having been generated by brightening the full colors. For the greys, the percentages shown are of brightness relative to pure white. For the extended and 89-color palettes, there are two special cases: pink is aliased to light red and brown is aliased to dark orange. I got the names for the more esoteric colors from this site: http://www.procato.com/rgb+index/
This is the official "extended" palette, showing 240 colors, arranged as 24 hues with 10 brightness/saturation combinations for each, plus 16 greys. For an example of how this palette is used, see Stained Glass mod. If you happen to examine the palette file, you'll notice several bright green pixels in one corner, so-colored to remind me (or you) that these are unused pixels that will be discarded by the engine. If you notice a warning about this palette not having exactly 256 pixels, ignore it.
This is the "classic" 89-color palette. It works the same as the 256-color palette, it's just arranged differently and has fewer color entries. Should you choose to examine the palette, the actual image file is arranged rather different from the above.
This is the "colorwallmounted" palette, which contains an abridged version of the above palette, since the engine only allows 32 color slots with that mode. This palette contains eight of the standard hues, three shades each (full, medium, dark), plus the standard 5-shades of greyscale, along with pink, brown, and light blue. Take a look at my Industrial Lights mod for an example of how this palette is used.
In addition to those is a set of "cut up" palettes, based on the 89-color palette, where each of the 12 hues in that palette has its own file, with each file containing 7 shades of that hue, plus one more containing the 5 levels of greyscale. These palettes are used when you need the "colorfacedir" mode, especially when you need to define a whole bunch of alternate shapes from your base node. You define a single base node, as usual, then 13 copies of each of your alternate shapes, one suitably-named copy per hue. Take a look at my Colored Wood mod for examples of how this is done (you can also see examples of the "extended" palette in that mod).
This is the official "extended" palette, showing 240 colors, arranged as 24 hues with 10 brightness/saturation combinations for each, plus 16 greys. For an example of how this palette is used, see Stained Glass mod. If you happen to examine the palette file, you'll notice several bright green pixels in one corner, so-colored to remind me (or you) that these are unused pixels that will be discarded by the engine. If you notice a warning about this palette not having exactly 256 pixels, ignore it.
This is the "classic" 89-color palette. It works the same as the 256-color palette, it's just arranged differently and has fewer color entries. Should you choose to examine the palette, the actual image file is arranged rather different from the above.
This is the "colorwallmounted" palette, which contains an abridged version of the above palette, since the engine only allows 32 color slots with that mode. This palette contains eight of the standard hues, three shades each (full, medium, dark), plus the standard 5-shades of greyscale, along with pink, brown, and light blue. Take a look at my Industrial Lights mod for an example of how this palette is used.
In addition to those is a set of "cut up" palettes, based on the 89-color palette, where each of the 12 hues in that palette has its own file, with each file containing 7 shades of that hue, plus one more containing the 5 levels of greyscale. These palettes are used when you need the "colorfacedir" mode, especially when you need to define a whole bunch of alternate shapes from your base node. You define a single base node, as usual, then 13 copies of each of your alternate shapes, one suitably-named copy per hue. Take a look at my Colored Wood mod for examples of how this is done (you can also see examples of the "extended" palette in that mod).
+
"Show details..."
Getting Started
First thing's first: you're going to need to harvest some materials to make the dyes from. For this, you need one or more of the following: roses (red), tulips (orange), yellow dandelions (yellow), cactus (green), geraniums (blue), violas (purple), coal (black), or white dandelions (white). Simply wander around your world and collect whichever of the above you need to get your colors.
Simply place one of the above materials into the crafting grid to obtain four portions of dye in that color. From those 8 "base" colors, you can directly fashion the rest. In some cases, you can also craft one or more interim colors and then use those to craft the main colors, as outlined below (for example, you can make azure with two blue and one green, or one cyan and one blue).
Here you can see the 24 standard hues and 16 levels of greyscale. All of the colors were created by directly crafting the 6 "base" hues, while black and white were used to create some greys, then those were combined together or with more black and/or white to create the rest of the greys. These crafting recipes are all "shapeless" (i.e. it doesn't matter how you arrange the dyes), and all of them yield 2 unless otherwise stated. They are as follows:
██ (0°) Red: 1 rose flower (not the dye color, yields 4)
██ (15°) Vermilion: red + orange
██ (30°) Orange: 1 tulip, or mix red + yellow dye
██ (45°) Amber: orange + yellow
██ (60°) Yellow: 1 yellow dandelion (yields 4)
██ (75°) Lime: yellow + chartreuse, or 2 yellow + 1 green (yields 3)
██ (90°) Chartreuse: yellow + green
██ (105°) Harlequin: chartreuse + green, or 1 yellow + 2 green (yields 3)
██ (120°) Green: 1 cactus (yields 4), or mix yellow + blue
██ (135°) Malachite: green + spring, or 2 green + 1 cyan (yields 3), or 3 green + 1 cyan (yields 4)
██ (150°) Spring: green + cyan, or 2 green + 1 blue (yields 3)
██ (165°) Turquoise: spring + cyan, or 1 green + 2 cyan (yields 3), or 3 green + 2 blue (yields 5)
██ (180°) Cyan: green + blue
██ (195°) Cerulean: cyan + azure, or 2 cyan + 1 blue (yields 3), or 2 green + 3 blue (yields 5)
██ (210°) Azure: cyan + blue, or 1 green + 2 blue (yields 3)
██ (235°) Sapphire: azure + blue, or 1 cyan + 2 blue (yields 3)
██ (240°) Blue: 1 geranium
██ (255°) Indigo: 1 blue + violet
██ (270°) Violet: 1 viola (yields 4), or mix blue + magenta
██ (285°) Mulberry: violet + magenta, or violet + blue + red (yields 3)
██ (300°) Magenta: blue + red
██ (315°) Fuchsia: magenta + rose, or blue + red + rose dye (yields 3), or red + violet
██ (330°) Rose dye: magenta + red, or 2 red + 1 blue (yields 3)
██ (345°) Crimson: rose dye + red, or 1 magenta + 2 red (yields 3), or 1 blue + 3 red (yields 4)
██ (0%) Black: 1 piece of coal (yields 4)
██ (6.7%) Grey #1: 3 black + 1 dark grey (yields 4)
██ (13.3%) Grey #2: 2 black + 1 dark grey (yields 3)
██ (20%) Grey #3: black + dark grey
██ (26.7%) Grey #4 ("Dark Grey"): 1 white + 2 black (yields 3)
██ (33.3%) Grey #5: 2 dark grey + 1 grey (yields 3)
██ (40%) Grey #6: dark grey + grey
██ (46.7%) Grey #7: 1 dark grey + 2 grey (yields 3)
██ (53.3%) Grey #8 (just "Grey"): white + black
██ (60%) Grey #9: 2 grey + 1 light grey (yields 3)
██ (66.7%) Grey #10: 1 grey + 2 light grey (yields 3)
██ (73.3%) Grey #11 ("Light Grey"): 2 white + 1 black (yields 3)
██ (80%) Grey #12: 2 light grey + 1 white (yields 3)
██ (86.7%) Grey #13: light grey + white
██ (93.3%) Grey #14: 1 light grey + 2 white (yields 3)
▏▕ (100%) White: 1 white dandelion (yields 4)
The list above has one exception: If you have Technic mod installed, it overrides the cactus recipe, making it yield 1 dye. You must use its "extractor" device to get 4.
The degree figures are the colors' hues on a standard HSV color wheel, and are what I used in the textures supplied with this mod. For the greys, the figures in parenthesis indicate the ideal brightness of the shade, relative to white, but note that they're not exactly on target, depending on which palette you're using. In the 32- and 89-color palettes, black doesn't go all the way to the bottom of the scale, since there just aren't many greyscale levels to work with there, and pure black would crush out all of the details in your textures. The 256-color palette has a pure black shade, but you probably won't want to use it that much.
Darker/Lighter colors, low-saturation variations
To obtain lighter or darker shades, simply mix one or two portions of the hue from the list above with black or white as outlined below.
Faint: base color + 3 white (yields 4)
Pastel: base color + 2 white (yields 3)
Light: base color + 1 white
Bright: two base color + 1 white (yields 3)
Medium: base color + 1 black
Dark: base color + 2 black (yields 3)
Low saturation: base color + light grey, or base color + one black + two white (yields 4)
Low saturation, Medium: base color + grey, or base color + one black + one white (yields 3)
Low saturation, Dark: base color + dark grey, or base color + two black + one white (yields 4)
Applying dye to a node
Now that you have some color, you surely want to use it. There are two ways this is done:
For programming information, see the "API" link below.
Misc. Notes
If you need to use /give commands, the item names are simply "dye:color", e.g. "dye:red", "dye:pink", or "dye:yellow". Greys have a similar naming convention: dye:white, dye:light_grey, dye:grey, dye:dark_grey, or dye:black, or "dye:grey_" followed by a number from 1 to 14 (1 being the darkest shade, aside from black).
For everything beyond the initial "full" hues, the item names are of the following format:
unifieddyes:[brightness]_[hue]_[saturation]
Where "brightness" can be "faint", "pastel", "light", "bright", nothing at all (e.g. full), medium, or dark. "Hue" is exactly as in the tables and images above, e.g. red, green, yellow, etc. "Saturation" can be either nothing or "s50". Omit trailing and leading underscores.
For example, low saturation dark yellow is "unifieddyes:dark_yellow_s50", while light normal-saturation violet would be "unifieddyes:light_violet".
First thing's first: you're going to need to harvest some materials to make the dyes from. For this, you need one or more of the following: roses (red), tulips (orange), yellow dandelions (yellow), cactus (green), geraniums (blue), violas (purple), coal (black), or white dandelions (white). Simply wander around your world and collect whichever of the above you need to get your colors.
Simply place one of the above materials into the crafting grid to obtain four portions of dye in that color. From those 8 "base" colors, you can directly fashion the rest. In some cases, you can also craft one or more interim colors and then use those to craft the main colors, as outlined below (for example, you can make azure with two blue and one green, or one cyan and one blue).
Here you can see the 24 standard hues and 16 levels of greyscale. All of the colors were created by directly crafting the 6 "base" hues, while black and white were used to create some greys, then those were combined together or with more black and/or white to create the rest of the greys. These crafting recipes are all "shapeless" (i.e. it doesn't matter how you arrange the dyes), and all of them yield 2 unless otherwise stated. They are as follows:
██ (0°) Red: 1 rose flower (not the dye color, yields 4)
██ (15°) Vermilion: red + orange
██ (30°) Orange: 1 tulip, or mix red + yellow dye
██ (45°) Amber: orange + yellow
██ (60°) Yellow: 1 yellow dandelion (yields 4)
██ (75°) Lime: yellow + chartreuse, or 2 yellow + 1 green (yields 3)
██ (90°) Chartreuse: yellow + green
██ (105°) Harlequin: chartreuse + green, or 1 yellow + 2 green (yields 3)
██ (120°) Green: 1 cactus (yields 4), or mix yellow + blue
██ (135°) Malachite: green + spring, or 2 green + 1 cyan (yields 3), or 3 green + 1 cyan (yields 4)
██ (150°) Spring: green + cyan, or 2 green + 1 blue (yields 3)
██ (165°) Turquoise: spring + cyan, or 1 green + 2 cyan (yields 3), or 3 green + 2 blue (yields 5)
██ (180°) Cyan: green + blue
██ (195°) Cerulean: cyan + azure, or 2 cyan + 1 blue (yields 3), or 2 green + 3 blue (yields 5)
██ (210°) Azure: cyan + blue, or 1 green + 2 blue (yields 3)
██ (235°) Sapphire: azure + blue, or 1 cyan + 2 blue (yields 3)
██ (240°) Blue: 1 geranium
██ (255°) Indigo: 1 blue + violet
██ (270°) Violet: 1 viola (yields 4), or mix blue + magenta
██ (285°) Mulberry: violet + magenta, or violet + blue + red (yields 3)
██ (300°) Magenta: blue + red
██ (315°) Fuchsia: magenta + rose, or blue + red + rose dye (yields 3), or red + violet
██ (330°) Rose dye: magenta + red, or 2 red + 1 blue (yields 3)
██ (345°) Crimson: rose dye + red, or 1 magenta + 2 red (yields 3), or 1 blue + 3 red (yields 4)
██ (0%) Black: 1 piece of coal (yields 4)
██ (6.7%) Grey #1: 3 black + 1 dark grey (yields 4)
██ (13.3%) Grey #2: 2 black + 1 dark grey (yields 3)
██ (20%) Grey #3: black + dark grey
██ (26.7%) Grey #4 ("Dark Grey"): 1 white + 2 black (yields 3)
██ (33.3%) Grey #5: 2 dark grey + 1 grey (yields 3)
██ (40%) Grey #6: dark grey + grey
██ (46.7%) Grey #7: 1 dark grey + 2 grey (yields 3)
██ (53.3%) Grey #8 (just "Grey"): white + black
██ (60%) Grey #9: 2 grey + 1 light grey (yields 3)
██ (66.7%) Grey #10: 1 grey + 2 light grey (yields 3)
██ (73.3%) Grey #11 ("Light Grey"): 2 white + 1 black (yields 3)
██ (80%) Grey #12: 2 light grey + 1 white (yields 3)
██ (86.7%) Grey #13: light grey + white
██ (93.3%) Grey #14: 1 light grey + 2 white (yields 3)
▏▕ (100%) White: 1 white dandelion (yields 4)
The list above has one exception: If you have Technic mod installed, it overrides the cactus recipe, making it yield 1 dye. You must use its "extractor" device to get 4.
The degree figures are the colors' hues on a standard HSV color wheel, and are what I used in the textures supplied with this mod. For the greys, the figures in parenthesis indicate the ideal brightness of the shade, relative to white, but note that they're not exactly on target, depending on which palette you're using. In the 32- and 89-color palettes, black doesn't go all the way to the bottom of the scale, since there just aren't many greyscale levels to work with there, and pure black would crush out all of the details in your textures. The 256-color palette has a pure black shade, but you probably won't want to use it that much.
Darker/Lighter colors, low-saturation variations
To obtain lighter or darker shades, simply mix one or two portions of the hue from the list above with black or white as outlined below.
Faint: base color + 3 white (yields 4)
Pastel: base color + 2 white (yields 3)
Light: base color + 1 white
Bright: two base color + 1 white (yields 3)
Medium: base color + 1 black
Dark: base color + 2 black (yields 3)
Low saturation: base color + light grey, or base color + one black + two white (yields 4)
Low saturation, Medium: base color + grey, or base color + one black + one white (yields 3)
Low saturation, Dark: base color + dark grey, or base color + two black + one white (yields 4)
Applying dye to a node
Now that you have some color, you surely want to use it. There are two ways this is done:
- The standard way for recent mods that support Unified Dyes is to first obtain whatever node it is that the mod in question uses or provides. For example, Colored Woods directly redefines and uses default:wood and default:fence_wood, while Bob Blocks has a few nodes you must craft first. Then, place that neutral-colored node on the ground, switch to/wield some dye, and then just punch the node you just placed.
The node, or some feature about it, will then take on the new color. If the mod supports it, Unified Dyes will print an appropriate message and start automatically performing the same colorization action on each successive node of the same kind (according to the name of the base, neutral-colored node in your inventory). You can switch colors at any time, just punch one of the nodes you just placed, with the new color. Note that while you can actually punch any random colorable node, it's best to punch one of the kind you were already placing (as the other random one will also take on the new color).
Once auto-coloring is activated, you can move the active dye out of your hotbar and put it somewhere else in your inventory, if you want, to keep it out of the way until you need it again.
Auto-coloring remains active until you place some other colorable node (but not a non-colorable node), or sign off/quit the game. If you're in survival mode, one portion of dye is consumed per colorized node, so auto-coloring mode will turn off if you run out of whatever color you were using. In any case, Unified Dyes will display an appropriate message and leave the auto-coloring turned off until the next time you explicitly dye a node.
This enables you to build large structures with only one or a few explicit "dye the node" actions, even if you're switching between some main, colorable node (such as for the walls of a building) and a bunch of non-colorable nodes (most of the building's furnishings, perhaps).
Note that if you place a node, and punch to color it, then place some other colorable node, and then immediately place the first kind again without coloring either one, auto-coloring will still be turned off, since you did switch nodes (the idea is that you should be placing and auto-coloring one kind of node at a time).
If you want to cancel the auto-coloring early, shift-punch any random node while wielding some dye.
When a node can't take on a color (for example if a node uses one of the smaller palettes that doesn't contain your desired color), Unified Dyes will drop a warning message into the chat area. Unified Dyes will also warn you if a node can't take on any color at all, or if it's already been colored with the dye you're wielding.
In any case, if you punch a node that's already colored with a different dye than the one you're wielding, the node will change color and you'll get back the dye it had previously.
A colorized node (whether it was auto-colored or punched) gives back the neutral-colored version if you dig it, plus the dye that was used to color it. - The older way is to use the dye in a crafting recipe as provided by the supporting mod, such as a Home Decor painting, then place the node as usual. This is also the case for mods where you need a few white or grey dyes to craft a "base" node that then gets re-colored by placing and punching (for example, Unified Bricks' "multicolor" brick blocks).
For programming information, see the "API" link below.
Misc. Notes
If you need to use /give commands, the item names are simply "dye:color", e.g. "dye:red", "dye:pink", or "dye:yellow". Greys have a similar naming convention: dye:white, dye:light_grey, dye:grey, dye:dark_grey, or dye:black, or "dye:grey_" followed by a number from 1 to 14 (1 being the darkest shade, aside from black).
For everything beyond the initial "full" hues, the item names are of the following format:
unifieddyes:[brightness]_[hue]_[saturation]
Where "brightness" can be "faint", "pastel", "light", "bright", nothing at all (e.g. full), medium, or dark. "Hue" is exactly as in the tables and images above, e.g. red, green, yellow, etc. "Saturation" can be either nothing or "s50". Omit trailing and leading underscores.
For example, low saturation dark yellow is "unifieddyes:dark_yellow_s50", while light normal-saturation violet would be "unifieddyes:light_violet".
+
"Show details..."
This section details the Unified Dyes API and how to use it with your mods.
In your node definition, you must include a few things to interface with Unified Dyes. Here is an example:
paramtype2 must be one of:
"color": this is an 89-color or 256-color node
"colorwallmounted": this is a 32-color node using "wallmounted" mode
"colorfacedir": this node uses one of the "split" 89-color palettes.
palette must be set to match the paramtype2 setting, and must be one of:
"unifieddyes_palette.png"
"unifieddyes_palette_extended.png"
"unifieddyes_palette_colorwallmounted.png"
or one of the "split" hues palettes (see below).
place_param2 generally is only needed for the 256-color palette, and should usually be set to 240 (which corresponds to white).
groups: If your node can be colored by punching it with dye, its groups entry must contain the key ud_param2_colorable = 1, among whatever else you'd normally put there. If the node is software-controlled, as might be the case for some mesecons-digilines aware node, then this group key should be omitted.
on_construct see below.
after_place_node see below.
after_dig_node see below.
Function calls
unifieddyes.recolor_on_place(pos, placer, itemstack, pointed_thing)
Call this within your node's after_place_node callback to allow Unified Dyes to automatically color the node using the dye you last used on that kind of node The feature will remain active until the dye runs out, or the user places a different kind of colorable node, or the user cancels the feature.
unifieddyes.fix_rotation(pos, placer, itemstack, pointed_thing)
unifieddyes.fix_rotation_nsew(pos, placer, itemstack, pointed_thing)
These two are used to re-orient wallmounted nodes after placing. The former allows positioning to floor, ceiling, and four walls, while the latter restricts the rotation to just the four walls. The latter is most often used with a node whose model is designed so that the four wall positions actually place the model "upright", facing +/- X or Z. This is a hacky way to make a node look like it has basic facedir capability, while being able to use the 32-color palette.
unifieddyes.fix_after_screwdriver_nsew(pos, node, user, mode, new_param2)
This serves the same purpose as the "fix_rotation_nsew", but is used to restrict the node's rotation after it's been hit with the screwdriver.
unifieddyes.select_node(pointed_thing)
Just what it says on the tin. :-) This function returns a position and node definition of whatever is being pointed at.
unifieddyes.is_buildable_to(placer_name, ...)
Again, another obvious one, returns whether or not the pointed node is buildable_to (can be overwritten by another node).
unifieddyes.get_hsv(name)
Accepts an item name, and returns the corresponding hue, saturation, and value (in that order), as strings.
If the item name is a color (not greyscale), then hue will be the basic hue for that color, saturation will be empty string for high saturation or "_s50" for low, and value will be "dark_", "medium_", "light_", or an empty string if it's full color.
If the item name is greyscale, then hue will contain "white", "light_grey", "grey", "dark_grey", or "black", saturation will (ironically) be an empty string, and value will be "light_", "dark_", or empty string if it's medium grey.
For example:
"mymod:mynode_red" would return ("red", "", "")
"mymod:mynode_light_blue" would return ("blue", "", "light_")
"mymod:mynode_dark_yellow_s50" would return ("yellow", "_s50", "dark_")
"mymod:mynode_dark_grey" would return ("dark_grey", "", "dark_")
unifieddyes.getpaletteidx(color, palette_type)
When given a color string (in the form of "dye:foo" or "unifieddyes:foo") and palette_type (either a boolean or string), this function returns the numerical index into that palette, and the hue name as a string.
false or nil: the 89-color palette
true: 89 color "split" palette mode, for nodes that need full facedir support. In this case, the hue field would match whichever of the 13 "split" palettes the node is using, and the index will be 1-7, representing the shade within that palette. See my coloredwoods mod for more information on how this mode is used.
"wallmounted": the 32-color palette, for nodes using colorwallmounted mode.
"extended": the 256-color "extended" palette
unifieddyes.on_construct(pos)
This function, called in your node definition's on_construct, just sets the palette = "ext" metadata key for the node after it's been placed. This can then be read in an LBM to determine if this node needs to be converted from the old 89-color palette to the extended 256-color palette. Although it is good practice to call this for any node that uses the 256-color palette, it isn't strictly necessary as long as the node has never used the 89-color palette and won't be subjected to an LBM that changes its color.
unifieddyes.after_dig_node(pos, oldnode, oldmetadata, digger)
This function handles returning dyes to the user when a node is dug. All colorized nodes need to call this in after_dig_node.
unifieddyes.on_use(itemstack, player, pointed_thing)
This function is used internally by Unfiied Dyes to actually make a dye able to colorize a node when you wield and punch with it. Unified Dyes redefines the minetest_game default dye items to call this function.
Tables
In addition to the above API calls, Unified Dyes provides a couple of of useful tables
unifieddyes.HUES contains a list of the 12 hues used by the 89-color palette.
unifieddyes.HUES_EXTENDED contains a list of the 24 hues in the 256-color palette. Each line contains the color name and its RGB value expressed as three numbers (rather than the usual "#RRGGBB" string).
unifieddyes.base_color_crafts contains a condensed list of crafting recipes for all 24 basic hues, plus black and white, most of which have multiple alternative recipes. Each line contains the name of the color, up to five dye itemstrings (with nils for the unused spaces), and the yield for that craft.
unifieddyes.shade_crafts contains recipes for each of the 10 shades a hue can take on, used with one or two portions of the dye corresponding to that hue. Each line contains the shade name with trailing "_", the saturation name (either "_s50" or empty string), up to three dye itemstrings, and the yield for that craft.
unifieddyes.greymixes contains the recipes for the 14 shades of grey. Each line contains the grey shade number from 1-14, up to four dye item names, and the yield for that craft.
Take a look at the Unified Dyes source code for more detailed information on these tables.
In your node definition, you must include a few things to interface with Unified Dyes. Here is an example:
Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.
- Code: Select all
minetest.register_node("mymod:colored_node", {
description = "My custom colored node",
tiles = { "mymod_custom_colored_node.png" },
paramtype = "light",
paramtype2 = "color",
palette = "unifieddyes_palette_extended.png",
place_param2 = 240,
groups = {snappy = 1, cracky = 2, ud_param2_colorable = 1}
on_construct = unifieddyes.on_construct,
after_place_node = unifieddyes.recolor_on_place,
after_dig_node = unifieddyes.after_dig_node,
})
paramtype2 must be one of:
"color": this is an 89-color or 256-color node
"colorwallmounted": this is a 32-color node using "wallmounted" mode
"colorfacedir": this node uses one of the "split" 89-color palettes.
palette must be set to match the paramtype2 setting, and must be one of:
"unifieddyes_palette.png"
"unifieddyes_palette_extended.png"
"unifieddyes_palette_colorwallmounted.png"
or one of the "split" hues palettes (see below).
place_param2 generally is only needed for the 256-color palette, and should usually be set to 240 (which corresponds to white).
groups: If your node can be colored by punching it with dye, its groups entry must contain the key ud_param2_colorable = 1, among whatever else you'd normally put there. If the node is software-controlled, as might be the case for some mesecons-digilines aware node, then this group key should be omitted.
on_construct see below.
after_place_node see below.
after_dig_node see below.
Function calls
unifieddyes.recolor_on_place(pos, placer, itemstack, pointed_thing)
Call this within your node's after_place_node callback to allow Unified Dyes to automatically color the node using the dye you last used on that kind of node The feature will remain active until the dye runs out, or the user places a different kind of colorable node, or the user cancels the feature.
unifieddyes.fix_rotation(pos, placer, itemstack, pointed_thing)
unifieddyes.fix_rotation_nsew(pos, placer, itemstack, pointed_thing)
These two are used to re-orient wallmounted nodes after placing. The former allows positioning to floor, ceiling, and four walls, while the latter restricts the rotation to just the four walls. The latter is most often used with a node whose model is designed so that the four wall positions actually place the model "upright", facing +/- X or Z. This is a hacky way to make a node look like it has basic facedir capability, while being able to use the 32-color palette.
unifieddyes.fix_after_screwdriver_nsew(pos, node, user, mode, new_param2)
This serves the same purpose as the "fix_rotation_nsew", but is used to restrict the node's rotation after it's been hit with the screwdriver.
unifieddyes.select_node(pointed_thing)
Just what it says on the tin. :-) This function returns a position and node definition of whatever is being pointed at.
unifieddyes.is_buildable_to(placer_name, ...)
Again, another obvious one, returns whether or not the pointed node is buildable_to (can be overwritten by another node).
unifieddyes.get_hsv(name)
Accepts an item name, and returns the corresponding hue, saturation, and value (in that order), as strings.
If the item name is a color (not greyscale), then hue will be the basic hue for that color, saturation will be empty string for high saturation or "_s50" for low, and value will be "dark_", "medium_", "light_", or an empty string if it's full color.
If the item name is greyscale, then hue will contain "white", "light_grey", "grey", "dark_grey", or "black", saturation will (ironically) be an empty string, and value will be "light_", "dark_", or empty string if it's medium grey.
For example:
"mymod:mynode_red" would return ("red", "", "")
"mymod:mynode_light_blue" would return ("blue", "", "light_")
"mymod:mynode_dark_yellow_s50" would return ("yellow", "_s50", "dark_")
"mymod:mynode_dark_grey" would return ("dark_grey", "", "dark_")
unifieddyes.getpaletteidx(color, palette_type)
When given a color string (in the form of "dye:foo" or "unifieddyes:foo") and palette_type (either a boolean or string), this function returns the numerical index into that palette, and the hue name as a string.
false or nil: the 89-color palette
true: 89 color "split" palette mode, for nodes that need full facedir support. In this case, the hue field would match whichever of the 13 "split" palettes the node is using, and the index will be 1-7, representing the shade within that palette. See my coloredwoods mod for more information on how this mode is used.
"wallmounted": the 32-color palette, for nodes using colorwallmounted mode.
"extended": the 256-color "extended" palette
unifieddyes.on_construct(pos)
This function, called in your node definition's on_construct, just sets the palette = "ext" metadata key for the node after it's been placed. This can then be read in an LBM to determine if this node needs to be converted from the old 89-color palette to the extended 256-color palette. Although it is good practice to call this for any node that uses the 256-color palette, it isn't strictly necessary as long as the node has never used the 89-color palette and won't be subjected to an LBM that changes its color.
unifieddyes.after_dig_node(pos, oldnode, oldmetadata, digger)
This function handles returning dyes to the user when a node is dug. All colorized nodes need to call this in after_dig_node.
unifieddyes.on_use(itemstack, player, pointed_thing)
This function is used internally by Unfiied Dyes to actually make a dye able to colorize a node when you wield and punch with it. Unified Dyes redefines the minetest_game default dye items to call this function.
Tables
In addition to the above API calls, Unified Dyes provides a couple of of useful tables
unifieddyes.HUES contains a list of the 12 hues used by the 89-color palette.
unifieddyes.HUES_EXTENDED contains a list of the 24 hues in the 256-color palette. Each line contains the color name and its RGB value expressed as three numbers (rather than the usual "#RRGGBB" string).
unifieddyes.base_color_crafts contains a condensed list of crafting recipes for all 24 basic hues, plus black and white, most of which have multiple alternative recipes. Each line contains the name of the color, up to five dye itemstrings (with nils for the unused spaces), and the yield for that craft.
unifieddyes.shade_crafts contains recipes for each of the 10 shades a hue can take on, used with one or two portions of the dye corresponding to that hue. Each line contains the shade name with trailing "_", the saturation name (either "_s50" or empty string), up to three dye itemstrings, and the yield for that craft.
unifieddyes.greymixes contains the recipes for the 14 shades of grey. Each line contains the grey shade number from 1-14, up to four dye item names, and the yield for that craft.
Take a look at the Unified Dyes source code for more detailed information on these tables.