update README, point user to forum for detailed usage info

2024-11-26 09:23:47 +01:00 · 2017-06-20 16:50:24 -04:00 · 2017-06-20 16:50:24 -04:00 · 9503386100
commit 9503386100
parent 40b836edf4
1 changed files with 6 additions and 240 deletions
--- a/246
+++ b/246
@ -1,248 +1,14 @@
 VanessaE's Unified Dyes
 =======================
-The purpose of this mod originally was to supply a complete set of colors for 
+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.  Since the advent of param2 colorization, it has also become a library for general color handling.
 Minetest mod authors to use in their recipes.  Since the default dyes mod that 
 is supplied with Minetest "common" is now usable (via flowers, also included in 
 "common"), this mod has become more of an extension pack.
-Unified Dyes expands the standard dye set from 15 to 90 colors.
+Unified Dyes expands the standard dye set from 15 colors to 32, 89, or 256 (see below).
-IMPORTANT: This mod is not intended to suggest that you should use the entire 
+Dependencies: Minetest engine version 0.4.16 or higher and a corresponding copy of minetest_game.
 palette.  Rather, I was hoping people would just choose maybe the dozen or so 
 most useful colors to use in their mods.
-Dependencies: default and dye from Minetest "common". This mod will NOT work 
+License: GPL 2.0 or higher.
 without these.  This mod will NOT work without these.  The default dye mod is 
 normally activated only in the standard "build" and "minetest_game" games, or perhaps if 
 someone has a modpack or game that includes them.
-Recommends: flowers from common.
+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.
-License: GPL 2.0 or above
+Usage: for detailed usage information, please see [the Unified Dyes Thread](https://forum.minetest.net/viewtopic.php?f=11&t=2178&p=28399) on the Minetest forum.
 Install: Unzip the distribution file, rename the resultant 
 VanessaE-unifieddyes-blahblah folder to just "unifieddyes", and move it into 
 Minetest's mods folder.
 The Palette:
 [ http://digitalaudioconcepts.com/vanessa/hobbies/minetest/screenshots/color-swatches.png ] 
 [ The official palette, showing 84 colors and 5 greys. ]
 In the image above, the "50%" markings on the left next to each shade mean 50% 
 saturation for all hues in that shade line.  Note that the "light" shades don't 
 have (or need) that variant.  For the greys, the percentages shown are of 
 brightness relative to pure white.  There are three special cases: Light red 
 has been aliased to default pink dye, and dark green has been aliased to 
 default dark greey dye.  Brown dye also exists in the default set, it's just 
 not shown in the palette above.
 Usage instructions, technical information 
 =========================================
 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.
 [ http://digitalaudioconcepts.com/vanessa/hobbies/minetest/screenshots/unifieddyes1.png ]
 [ The 8 base colors directly obtainable from a material in the world. ]
 Simply place one of the above materials into the crafting grid to obtain four 
 portions of dye in that color From those initial 8 colors, you can directly 
 fashion another 11, for a total of 19 standard colors (including the various 
 greys):
 [ http://digitalaudioconcepts.com/vanessa/hobbies/minetest/screenshots/unifieddyes2.png ]
 [ The complete 19-color standard set. ]
 The standardized colors and their crafting methods are as follows:
 * Red (0°): one rose
 * Orange (30°): one tulip, or put one red dye and one yellow dye into the
  crafting grid to mix them (yields 2)
 * Yellow (60°): one yellow dandelion
 * Lime (90°): mix yellow + green (yields 2)
 * Green (120°): one cactus, or mix yellow + blue (yields 2)
 * Aqua (150°): mix green + cyan (yields 2)
 * Cyan (180°): mix green + blue (yields 2)
 * Sky blue (210°): mix cyan + blue (yields 2)
 * Blue (240°): one geranium
 * Violet (270°): one viola, or mix blue + magenta (yields 2).
 * Magenta (300°): mix blue + red (yields 2)
 * Red-violet (330°): mix magenta + red (yields 2)
 * Black (7.5%): one piece of coal
 * Dark grey (25%): mix one white + two black (yields 3)
 * Medium grey (50%): mix one white and one black (yields 2)
 * Light grey (75%): Mix two white and one black (yields 3)
 * White (95%): one white dandelion.
 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 intended brightness of the shade, relative to 
 white.  Note that black and white don't go all the way to the bottom/top of the 
 scale, as doing so may crush some details in textures made in those shades (see 
 below, regarding semi-automatic texture generation).
 Darker/Lighter colors
 ---------------------
 To obtain a dark (33%) version of a given color, use two portions of black dye 
 along with the base color from the list above, which yields three portions of 
 the final color.
 To obtain a medium-brightness (66%) version of a given color, mix one portion 
 the base color with one portion of black dye (for example, medium lime = lime + 
 black).  All such mixtures yield two portions of the final color.
 To obtain a light (150% over full) version of a given color, mix one portion of 
 the base color with one portion of white dye.  Yields 2 portions of the final 
 color.
 Low-saturation colors
 ---------------------
 To get the low saturation (50%) version of one of the base colors, mix one or 
 more of white, black, or a shade of grey with the desired base color:
 Dark, low saturation: dark grey dye + color (yields 2), or two blacks + 1 white 
 + color (yields 4).  For example, dark, low-saturation red = red + dark grey, 
 or red + two black + one white.
 Medium brightness, low saturation: medium grey dye + color (yields 2), or black 
 + white + color (yields 3).  For example, medium, low-saturation green = green 
 + medium grey, or green + black + white.
 Full, low saturation: light grey dye + color (yields 2), or 1 black + 2 whites 
 + color (yields 4).  For example, bright, low-saturation blue = blue + light 
 grey, or blue + black + 2 white.
 There is no low-saturation version of the "light" colors.
 Red + white always returns default pink dye, and black + green always returns 
 default dark green dye.
 RGB values
 ----------
 All RGB values and filenames for all colors and shades of grey are represented 
 in the file "colors.txt" (which was generated with the bash script 
 "listcolors.sh"), included in the distribution directory.  Note that 
 listcolors.sh is an example only and was written for a different set of 
 textures than what Unified Dyes includes now.
 Misc. Notes
 -----------
 If you need to use /give commands, the item names for the standard set of 12 
 regular "full" colors (plus pink, brown, and dark green) is simply "dye:color", 
 e.g. "dye:red", "dye:pink", or "dye:skyblue".  Greys have a similar naming 
 convention: dye:white, dye:light_grey, dye:grey, dye:dark_grey, or dye:black.
 For everything beyond those initial 19 colors, the item names are of the 
 following format:
 unifieddyes:{"light_" or "medium_" or "dark_"}{color}{nothing or "_s50"}.
 For example, low saturation dark yellow is "unifieddyes:dark_yellow_s50", while 
 light normal-saturation red-violet would be "unifieddyes:light_redviolet".
 See the texture filenames in the textures/ folder for further hints - all of 
 the item names follow the same format as the corresponding filenames, save for 
 having a colon (:) instead of the first underscore (_).
 Semi-automatic generation of textures 
 =====================================
 The texture generator script
 ----------------------------
 Obviously, in order for this mod or the above template to be useful, you'll 
 need textures.  If you plan to support the entire range of colors offered by 
 Unified Dyes, there is a BASH script included with this mod as well with the 
 above template named gentextures.sh, which will, with an appropriately- colored 
 and appropriately-named source texture, and possibly an overlay texture, 
 generate a complete set of colored and greyscale textures.
 The script requires bc (the calculator program) to handle some basic math 
 regarding the hue adjustments, and Imagemagick's "convert" program handles all 
 of the actual conversions.
 First thing's first though - you need source textures.  Using your favorite 
 image editor, create a single version of your desired texture.  Draw it in the 
 brightest, deepest shade of RED you can muster without losing any detail, and 
 save it out.  Ideally, you will want the average color of the texture, when 
 taking into account all bright and dark areas, to be as close as possible to 
 the hex value #FF0000 (0 degrees, 100% saturation, pure red) without losing any 
 appreciable #detail.
 Save this source texture out as a PNG image, with a filename of 
 "whatever_base.png", where "whatever" is the one-word name of your mod - for 
 example, mymod_base.png.
 If you want to add an image on top of the colored blocks, such as a frame, 
 which you want to be the same color throughout all of the textures, create it 
 now.  It should consist only of those parts of the textures that you want to 
 leave unchanged, with some level of alpha transparency everywhere else, 
 depending on how much of the image needs to remain unchanged.  Save it out as a 
 PNG image, using any filename you want, for example myoverlay.png.
 Now, use chmod to make the script executable, if necessary, and run it.
 If you don't need the overlay, you just need to supply one command line 
 argument: the base name of your mod.  The script will use that parameter as the 
 basis of its texture filenames. For example:
 ./gentextures.sh mymod
 The script will then look for mymod_base.png and copy and convert it into 
 things like mymod_red.png, mymod_dark_blue.png, and so on.
 If you want to use an overlay also, skip the above step and run the script with 
 the base name as the first parameter, and the complete filename of your overlay 
 as the second instead.  For example:
 ./gentextures.sh mymod myoverlay.png
 Otherwise, the program will iterate through all of the hues and shades that are 
 supported by unifieddyes (though this is done manually, not by reading anything 
 from the mod), compositing your overlay image in after the recolor step, if 
 you're using that option.
 All of the output files will be placed in a new folder, generated-textures/ in 
 the current directory.  Note that the script looks for the above files in the 
 current directory also.
 The script has a third mode as well:
 ./gentextures.sh -t mymod myoverlay.png
 In this mode, the script will leave the base texture mymod_base.png unchanged, 
 and instead will rotate the colors of the overlay image and then composite that 
 onto the base texture.  The same color changes will happen with the overlay in 
 this mode, so it's a good idea to make the overlay some fairly saturated shade 
 of red.  Along with that, the base image should be some neutral color; any 
 color is fine as long as the result is what you wanted.
 The program attempts to verify that the files you've asked it to use will 
 actually work, and will exit immediately if the any are invalid, missing, etc.
 Use your favorite image browser or file manager to review the results in 
 generated-textures/, and if they're right, copy them over to the textures/ 
 folder in your mod.
 Note that this script does not generate brown and pink variations of your base 
 texture - you'll have to do those two manually.