Materials in Oolite

This section applies to Oolite 1.69 and later.

Traditionally, the surface appearance of ships in Oolite has been defined entirely by textures specified in the ship’s model file and the smooth attribute. Test release 1.67 added support for shaders, and test release 1.69 expands this to a more flexible material model. Under the new model, the texture file names in model files have been repurposed as material keys. A material key specifies an entry in the ship’s material dictionary, specified in the ship’s shipdata.plist entry. For backwards compatibility, if no material of a given name is found, a material is generated using the material key as a diffuse texture name – providing the same functionality as previous versions of Oolite.

The materials and shaders dictionary

The material dictionary is actually specified as two separate dictionaries in the shipdata.plist entry. The first is called materials, the second shaders. If shader support is available and enabled, the entries in shaders are used in preference to those in materials. Otherwise, shaders is ignored. The entries in the two dictionaries take exactly the same form, however; it is possible to specify a shader in the materials dictionary, and it will simply be ignored if shader support is not available. The rest of this article shall refer to the merged materials and shaders dictionaries as “the material dictionary”.

Material attributes dictionaries

The material dictionary is a property list dictionary whose keys are material keys as defined above, and whose values are material attribute dictionaries. Currently-supported material attribute dictionary keys are listed here; “texture specifier” and similar are defined below.

General material attribues

Name	Type	Description
ambient	colour specifier	The ambient colour of the entity, that is, the colour reflected evenly in all directions by starlight. By default, this is the same as diffuse.
diffuse	colour specifier	Overall diffuse colour of the entity; that is, the colour reflected in a “non-shiny” way on the sunlit side of the entity. If both diffuse and diffuse_map are specified, the texture is “dyed” with this colour. Default: white (1.0, 1.0, 1.0, 1.0).
diffuse_map	texture specifier	A texture specifying the basic colour of the material. This is a “normal” texture, the same as you get without a material dictionary. If not specified, the material key will be used. To specify no texture, use an empty string for diffuse_map. Ignored when using shaders.
emission	colour specifier	The emitted (glow) colour of the material. Default: black (0.0, 0.0, 0.0, 1.0).
shininess	integer	The “tightness” of specular reflect, ranging from 0 to 128. 0 means no specular highlight. Default: 0, may change in future.
specular	colour specifier	The specular (shiny reflection) colour of the material. This is ignored if shininess is not 1 or more. Default: black (0.0, 0.0, 0.0, 1.0), may change in future.
textures	array of texture specifiers	Textures to use in shader program.

The following attributes are only supported if shader support is active:

Shader material attribues

Name	Type	Description
fragment_shader	file name	name of GLSL fragment program to use.
textures	array of texture specifiers	Textures to use in shader program.
uniforms	dictionary of uniform variable specifiers	uniform variables to use in shader program. See Shaders in Oolite: uniforms.
vertex_shader	file name	name of GLSL vertex program to use.

Colour specifiers

Colour specifiers are used to declare colours in material attribute dictionaries, and in other contexts such as lasers in shipdata.plist. Colour specifiers take any of several forms:

Named colours

The simplest form of colour specifier is a string containing a colour name. The following names are supported:

Colour names

Name	RGBA value
blackColor	0, 0, 0, 1.0
darkGrayColor	1/3, 1/3, 1/3, 1.0
lightGrayColor	1/6, 1/6, 1/6, 1.0
whiteColor	1, 1, 1, 1
grayColor	1/2, 1/2, 1/2, 1
redColor	1, 0, 0, 1
greenColor	0, 1, 0, 1
blueColor	0, 0, 1, 1
cyanColor	0, 1, 1, 1
yellowColor	1, 1, 0, 1
magentaColor	1, 0, 1, 1
orangeColor	1, 1/2, 0, 1
purpleColor	1/2, 0, 1/2, 1
brownColor	0.6, 0.4, 0.2, 1
clearColor	0, 0, 0, 0

RGBA tuples

Colours may also be specified in RGB or RGBA (red, green, blue, alpha [transparency]). RGB or RGBA tuples may be specified as arrays or as strings separated by spaces. The values may range from 0 to 1 or 0 to 255. (If no value is greater than 1, 0–1 is assumed, otherwise 0–255.) Examples:

• <string>1 1 0</string> <!-- yellow -->
• <string>0 128 0 128</string> <!-- medium green at 50% opacity -->
• <array><real>1</real> <real>0</real> <real>0</real></array> <!-- red -->

RGBA dictionaries

Just in case you’re unsure of the order the RGB[A] components come in, you can use a dictionary:

<dict>
    <key>blue</key> <real>0.8</real>
    <key>green</key> <real>0.8</real>
</dict>

Accepted keys are red, green, blue and alpha (or opacity), all optional (default: 0.0 for red, green and blue, 1.0 for alpha).

HSBA dictionaries

But wait, there’s more! Colours may also be specified as dictionaries in the HSB colour space. Accepted keys are hue' (hue angle in degrees, required), saturation, brightness (or value) and alpha (or opacity). The default for the optional keys is 1.0.

<dict>
    <!-- Pale magenta -->
    <key>hue</key> <real>300</real>
    <key>saturation</key> <real>0.3</real>
</dict>