rot-js/manual/pages/color.html

A roguelike toolkit in JavaScript

<h2>Color manipulations</h2>

<p>There is no dedicated <code>Color</code> data type in <strong>rot.js</strong>; passing strings around is sufficient in most cases (such as <code>ROT.Display::draw</code>). However, if you need to perform color adjustments and computations, it is suitable to represent them as arrays of numbers. For this case, the <code>ROT.Color</code> namespace offers a bunch of useful methods.</p>

<h3>Converting string &rarr; array</h3>

<div class="example">
SHOW(
	ROT.Color.fromString("rgb(10, 128, 230)"),
	ROT.Color.fromString("#faa"),
	ROT.Color.fromString("#83fcc4"),
	ROT.Color.fromString("goldenrod")
);</div>

<h3>Converting array &rarr; string</h3>

<div class="example">
SHOW(
	ROT.Color.toRGB([10, 128, 230]),
	ROT.Color.toHex([10, 128, 230])
);</div>

<h3>Converting between RGB and HSL</h3>

<div class="example">
SHOW(
	ROT.Color.rgb2hsl([51, 102, 51]),
	ROT.Color.hsl2rgb([0.333, 0.333, 0.3])
);</div>

<h3>Adding and mixing colors</h3>

<p>These methods accept a variable number of arguments. Methods whose names end with an underscore <strong>modify</strong> their first argument instead of returning a new array. Note that color values are not clamped to 0..255; this happens only when serializing to a string.</p>

<div class="example">
SHOW( /* addition = lightening */
	ROT.Color.add([10, 128, 230], [200, 10, 15], [30, 30, 100]),
	ROT.Color.add_([10, 128, 230], [200, 10, 15])
);
SHOW( /* multiplication = darkening */
	ROT.Color.multiply([10, 128, 230], [200, 10, 15]),
	ROT.Color.multiply_([10, 128, 230], [200, 10, 15])
);
</div>

<h3>Interpolating between two colors</h3>

<p>The third argument specifies the interpolation factor (0 = first color, 1 = last color, 0.5 = default = halfway between them).</p>

<div class="example">
SHOW(
	/* computed in RGB space */
	ROT.Color.interpolate([10, 128, 230], [30, 255, 255], 0.3),

	/* computed in HSL space */
	ROT.Color.interpolateHSL([10, 128, 230], [30, 255, 255], 0.3)
);</div>

<h3>Creating random variants</h3>

<p>You can create new colors by adjusting an exiting color by a (normally distributed) random value. Second argument is a set of standard deviations; note that ~95% of generated colors will fall within <code>2*stddev</code>.</p>

<div class="example">
SHOW(
	ROT.Color.randomize([100, 128, 230], [30, 10, 20]),
	ROT.Color.randomize([100, 128, 230], [30, 10, 20]),
	ROT.Color.randomize([100, 128, 230], [30, 10, 20])
);</div>