unifieddyes/README

VanessaE's Unified Dyes
=======================

This is a pretty extensive dyes mod, which has the sole purpose of supplying a 
complete set of colors and a few greys, all of which are intended to be used by 
other mods as needed to make colored objects.  It uses Ironzorg's Flowers mod 
as the source of the actual pigments.  Flowers can be had from one of the links 
below, or as part of neko259's Nature Pack.

In total, this mod provides 89 colors and greys.

Dependencies: flowers

Recommends: buckets, junglegrass

License:  For the buckets of paint, cc-by-sa 3.0.  For everything else, WTFPL.


Usage instructions, technical information
=========================================

Colors

Creating a particular color of dye is pretty simple - just harvest coal, 
cactus, or the appropriate flowers and start smelting them and crafting the 
results together to get the various colors.  There are 12 base colors, which 
are formed as follows (the degree figure is that color's hue on a standard HSV 
color wheel, and is what is used in the textures supplied with this mod):

Red (0°):  smelt one rose (yields 2 portions of red dye)
Orange (30°):  smelt one tulip (yields 2) or mix red+yellow (yields 2)
Yellow (60°):  smelt one yellow dandelion (yields 2)
Lime (90°):  mix yellow + green (yields 2)
Green (120°): smelt one cactus or one waterlily (yields 2), or mix 
              yellow + blue (yields 2)
Aqua (150°):  mix green + cyan (yields 2)
Cyan (180°):  green + blue (yields 2)
Sky blue (210°):  mix cyan + blue (yields 2)
Blue (240°): Smelt one viola (yields 2)
Violet (270°):  mix blue + magenta (yields 2) or mix 
                2 blues + 1 red (yields 3)
Magenta (300°):  Mix blue + red (yields 2)
Red-violet (330°):  mix magenta + red (yields 2)


Greys
-----

There are also three shades of grey plus pure black and pure white (figures in 
parenthesis indicate the intended brightness of the shade, relative to white):

Black (0%):  smelt one piece of coal (yields 2)
Dark grey (25%):  mix one portion of white paint with two portions of black
                  dye (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 (100%):  See below.


White Paint
-----------

To get the white paint mentioned above, first smelt some cobble into smooth 
stone as usual.  Then, smelt one smooth stone block to get 10 portions of 
Titanium Dioxide.  Finally, craft one portion of that with a bucket of water 
and one piece of jungle grass.  Yields one bucket of white paint.


Darker/lighter shades
---------------------

To obtain a dark (33% relative to the 'full' version) version of a given color,
use two portions of black dye along with the base color, which yields three
portions of the final color.

To obtain a medium-brightness (66%) version of a given color, mix the desired 
base color from the list above with one portion of black dye (for example, 
medium lime = lime + black).  All such mixtures yield two portions of the final 
color.

To obtain the light (150%) version of a color, mix one portion of the
desired base color with one portion of white paint, which yields two portions of
the final color.


Low-saturation colors
---------------------

Except for the "light" colors and the greys, all colors are available in a
reduced-saturation version  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 paint + color (yields 2), or two blacks + 1 
white + color (yields 4).  For example, dark, low-saturation red = red + dark 
grey paint, or red + two black + one white.

Medium brightness, low saturation: medium grey paint + color (yields 2), or 
black + white + color (yields 3).  For example, medium, low-saturation green = 
green + medium grey, or green + black + white.

Bright, low saturation: light grey + 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.


RGB values
----------

All RGB values and filenames for all colors and shades of grey are represented 
in the file "colors.txt" (which is generated with the bash script 
"listcolors.sh"), included in the distribution directory.


Misc. Notes
-----------

If you need to use /give commands, the node names are of the following format:

unifieddyes:{nothing or "medium_" or "dark_"}{color}{nothing or "_s50"}.

For example, low saturation dark yellow would be "unifieddyes:dark_yellow_s50", 
while bright, full-saturation red would simply be "unifieddyes:red".

See the texture filenames in the textures/ folder for further hints - all of 
the item names follow the same format as the filenames, save for having a colon 
(:) instead of the first underscore (_).


Semi-automatic generation of nodes, crafting recipes, and textures
==================================================================

The modding template
--------------------

Along with this mod, you should also download my modding template, which is 
quite easy to transform into whatever mod you want to create that needs 
unifieddyes.

It's just a skeleton, but all you should need to do to get started is to rename 
the folder to whatever your mod will be named, tweak a few variables near the 
start of the template's init.lua, and follow the above instructions regarding 
the creation of your textures.

If you do it right, you should end up with a very basic mod giving you craft 
and /give access to your various items.  After that part is confirmed working, 
just add whatever code you need to the end of the init.lua to define additional 
functions, items, crafts, and smelting recipes, etc., as needed by your mod, 
and start coding and testing like usual.

This template is not supplied as part of the unifieddyes mod, rather you need
fetch it separately from here:

Download Template:  https://github.com/VanessaE/modtemplate/zipball/master
...or browse the code:  https://github.com/VanessaE/modtemplate


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 that 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 with a filename of red_base_whatever.png, where
"whatever" is the one-word name of your mod.

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 transparency everywhere else.  Save it out using any 
filename you want.

Now, run the script (make it executable first, if necessary).

If you didn'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

If you want to use an overlay also, run the script with the base name as the 
first parameter, and the complete filename of your overlay as the second.  For 
example:

./gentextures.sh mymod myoverlay.png

The program will exit immediately if the image(s) you've supplied are invalid, 
missing, etc.

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/

Use your favorite image browser or file manager to review the results, and if
they're right, copy them over to the textures/ folder in your mod.