LDraw.org Colour Definition Language Extension :: LDraw.org :: The Central Site for the LDraw Family of LEGO® CAD Software

Maintained by: The LDraw.org Standards Committee
Writer: Steve Bliss, Tim Gould
Revision: 4, 28-April-07

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 can be found here [4]

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.

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 - 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 - 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 - The color value. v is a 24-bit RGB value. VALUE is a required element.
EDGE e - The contrasting edge color. e may be either a color code or an RGB value. EDGE is a required element.
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 - 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.

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 - 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 - 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 - 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 - 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 - 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 [name <params> ...]</params> - Some other surface finish requiring customized parameter(s). Name is an identifier. MATERIAL is not used for official LDraw.org color definitions, it has been made available for use by programs. 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.

Note: This document is an offical LSC specification and/or language extension. Material changes can only be made after ratification by the LSC.

Standard [1]: LDraw.org Colour Definition Language Extension [2]