Purpose

This meta-statement will specify the properties of a single LDraw colour code. This statement may appear at any time in an LDR file, but will probably be most useful in the file header.

In official LDraw.org materials, !COLOUR will appear in the ldconfig.ldr configuration file, to define the standard LDraw color set. It will not appear in any official part or primitive files.

The current version of ldconfig.ldr is distributed with the Official Library

The ldconfig.ldr file that contains the standard colour definitions will contain the following in its header:

0 !LDRAW_ORG Configuration UPDATE YYYY-MM-DD

Scope

It's recommended that colour definitions be limited in scope. A color definition will affect colors from the point it first appears, continuing through the end of the file. Commands preceding a colour definition will not be affected by the definition. Color definitions will expire at the end of the file in which they appear, effectively falling out of scope. Color definitions will be passed to subfiles.

The configuration file, ldconfig.ldr, is not affected by the scoping rules, in the sense that the definitions in ldconfig.ldr remain in effect after the renderer is finished processing ldconfig.ldr.

Syntax

The entire statement must appear on one line. It may be line-wrapped in this document for clarity.

0 !COLOUR name CODE x VALUE v EDGE e [ALPHA a] [LUMINANCE l] [ CHROME | PEARLESCENT | RUBBER | MATTE_METALLIC | METAL | MATERIAL <params> ]

Tags. CODE, VALUE, EDGE, ALPHA, DITHER, LUMINANCE, CHROME, PEARLESCENT, RUBBER, MATTE_METALLIC, METAL and MATERIAL are keyword tags. Some tags are followed by a single parameter value. Tags are case-insensitive. Numeric parameters, other than RGB color values, should be specified in decimal. RGB values must be specified in hexidecimal, and must be prefixed with # or 0x. Byte values are integers in the range 0-255.
Identifiers are strings of text. The allowable characters are alphanumerics from 7-bit ASCII set: a-zA-Z0-9_. Additionally, the first character in an identifier must an alphabetic (a-zA-Z). Identifiers are case-insensitive.

Definitions of Parameters

name

name - A short name for the color. Name may be any identifier. This item is provided mainly for human recognition. Name is a required element.

CODE x

CODE x - The LDraw color code. For LDraw compatibility, x is an integer 0-511. If strict LDraw compatibility is not required, x is any identifier recognized by a rendering program as a color code. Code is a required element.

VALUE v

VALUE v - The color value. v is a 24-bit RGB value. VALUE is a required element.

EDGE e

EDGE e - The contrasting edge color. e may be either a color code or an RGB value. EDGE is a required element.

ALPHA a

ALPHA a - The alpha channel (transparency) value. a is a byte value, where 0 is totally colorless and 255 is completely opaque. In official materials, standard transparent colors will specify ALPHA 128. A 0 value is useful for temporarily hiding sections of models. ALPHA is an optional element.

LUMINANCE l

LUMINANCE l - Brightness for colors that glow. l is a byte value. Luminance is not generally used by LDraw renderers, but may be used for translation to other rendering systems. LUMINANCE is optional.

Finishes

Only one of CHROME, PEARLESCENT, RUBBER, MATTE_METALLIC, METAL and MATERIAL may be specified for a single color. They all specify the finish/texture to be applied to an object being rendered. Other finish-tags may be defined over time.

CHROME

CHROME - A flag indicating that surfaces should have a mirror-like finish. Not currently used by LDraw-compatible programs, but may be implemented in the future. CHROME is optional, and may not appear with other finish tags.

PEARLESCENT

PEARLESCENT - A flag indicating that surfaces should have a finish like Lego's 'metallic' colors. These colors are commonly called 'pearlescent' by fans. Not currently implemented in LDraw-compatible programs. PEARLESCENT is optional, and and may not appear with other finish tags.

RUBBER

RUBBER - A flag indicating that surfaces should have a finish like rubber (typically rubber tubing or rubber tyres). RUBBER is optional, and may not appear with other finish tags.

MATTE_METALLIC

MATTE_METALLIC - A flag indicating that surfaces should have a finish that simulates brushed metal finishes. MATTE_METALLIC is optional, and may not appear with other finish tags.

METAL

METAL - A flag indicating that surfaces should have a finish like actual metal (not a simulation of a plastic simulation of metal). METAL is optional, and may not appear with other finish tags.

MATERIAL

MATERIAL [name ...]- Some other surface finish requiring customized parameter(s). Name is an identifier. MATERIAL is optional, and may not appear with other finish tags. Since it may have complex parameters that don't follow the standard syntax of the !COLOUR statement, MATERIAL should be the last tag in the !COLOUR statement.

The following MATERIAL definitions are official:

GLITTER VALUE v [ALPHA a] [LUMINANCE l] FRACTION f VFRACTION vf SIZE s | MINSIZE min MAXSIZE max
SPECKLE VALUE v [ALPHA a] [LUMINANCE l] FRACTION f SIZE s | MINSIZE min MAXSIZE max

GLITTER is used to specify a color that includes glitter mixed into the transparent plastic. Individual glitter grains are assumed to be flat squares, with arbitrary orientation.
SPECKLE is used to specify a color that has a speckled pattern of an alternate color on its surface. Individual speckle grains are assumed to be roughly round.

FRACTION f is the portion of the surface that uses the alternate color, expressed as a decimal number greater than 0.0 and less than 1.0.
VFRACTION vf is the portion of the volume that uses the alternate color, expressed as a decimal number greater than 0.0 and less than 1.0. Renderers that support volume rendering will use this value instead of the FRACTION value.
SIZE is the size of each speckle/glitter grain, in LDraw units. It must be greater than 0. This is mutually exclusive with MINSIZE and MAXSIZE.
MINSIZE and MAXSIZE provide a range of sizes for grains, in LDraw units. If either of these is specified, both must be specified, and they are mutually exclusive with SIZE.

Here is an example usage of SPECKLE:

0 !COLOUR Speckle_Black_Silver CODE 132 VALUE #000000 EDGE #595959 MATERIAL SPECKLE VALUE #595959 FRACTION 0.4 MINSIZE 1 MAXSIZE 3