Knowledge Documentation

Materials

Materials are one of the most important part of knowledge, through them you can define how an object will display. A material can be defined inside a script (a file with the extension .material) and have the following format:

material globalTerrain
{
	cull none
	texture
	{
		filename common/terrain.png
		texcoord uv
	}

	texture
	{
		filename common/shadows.png
		texcoord uv
		blendfunc srcalpha invsrcalpha
		texEnv modulate
	}
}

First, you define the material name after the keyword "material" (keep in mind that EVERY keyword in knowledge is case sensitive, so "MaTeRiAl" is very different from "material"). Every material name is unique and can't be duplicated, in case of duplication only the first named material will be created and an error will be written to the log. The next thing you might be interested are the material properties, wich are the follow:

Material properties

nodraw
The object is ignored by the renderer and its not drawn.

receiveLight (default is on, options are: off | false | no)
When lights are enabled, the object automatically receives light, if you specify this parameter to one of the options object will ignore lights and will be fully lit.

ambient (default is "0 0 0")
Set the material ambient property to the color specified (example: "255 0 0" - for red, "255 255 255" - for white)

specular (default is "0 0 0")
Set the material specular property to the color specified (example: "255 0 0" - for red, "255 255 255" - for white)

diffuse (default is "0 0 0")
Set the material diffuse property to the color specified (example: "255 0 0" - for red, "255 255 255" - for white)

cull (default is "back", options are: "back" | "front" | "none" or "disabled" | "both")
Cull the specified faces so they are not drawn, let "back" if you want maximum performance.

depthTest (default is "on", options are: "true", "on" or "yes" | "false", "off" or "no")
Forces the renderer to compare the depth of objects when drawing.

depthWrite (default is "on", options are: "true", "on" or "yes" | "false", "off" or "no")
Forces the renderer to write to the depth buffer when drawing the object with this material.

texture {}
Define a new material stage (up to 8)

Texture Section

The texture section is where you will define the texture layers (up to 8 layers) and how they will blend between themselves. There are some keywords on this section that define how the texture will behave and blend.

filename (options are: "a string with the path of the texture, related to the resources.cfg file" - example: "common/test.png")
The filename of the texture to be loaded.

animname (options are: "baseFileName numberOfImages frameRate" | "fileName fileName2 ... fileName3 frameRate")
There are two ways you can define animated textures:

1) You define a base filename, the number of images and the framerate: super/ballRolling0.png 10 16 - Will load the images super/ballRolling0.png, super/ballRolling1.png ... super/ballRolling9.png and will animate through those 10 frames at the rate of 16 frames per second. You can specify at max 16 frames per animation. 2) You define all the images of the animation and at the end, specify the frameRate: test/3Frames0.png test/3Frames1.png test/3Frames2.png 3 - Will load the three images and at the end will animate through those 3 frames at the rate of 3 frames per second. You can specify at max 16 frames per animation. cubename (options are: "the base filename for the cube faces")
The base filename to load the cube faces. Example: (test/cube.png - Will load the cube faces like test/cube_front.png, test/cube_up.png ... test/cube_left.png)

texenv (default is "replace", options are: "replace" | "modulate" | "add" | "decal" | "blend")
Define the type of texture generation for the texture. Those functions should work like the OpenGL ones, from the manual:

Internal Format	modulate	decal	blend	replace
RGB	Cv = CtCf Av = Af	Cv = Ct Av = Af	Cv = (1 - Ct) Cf+CtCc Av = Af	Cv = Ct Av = Af
RGBA	Cv = CtCf Av = Af	Cv = (1 - At) Cf + AtCt Av = Af	Cv = (1 - Ct) Cf+CtCc Av = AtAf	Cv = Ct Av = Af

scale (default is: "0 0", options are: "a two component vector with the desired scale" - example: "5 10")
Defines the scalling of the texture, first parameter is the Horizonte scalling, second is the Vertical one.

scroll (default is: "0 0", options are: "a two component vector with the desired scrolling" - example: "20 10")
Defines the amount of pixels the texture is scrolling per frame, first parameter is the Horizonte scrolling, second is the Vertical one.

rotate (default is: 0, options are: "the angular velocity of the texture")
Defines the angular velocity of the texture, making it rotate by frame.

texcoord (default is: "uv", options are: "uv" | "pos" | "sphere" | "cubemap" | "eyeLinear" | "normal" | "binormal" | "tangent")
Defines the texture coordinate generation. Each option is explained below:

Function	Details
"uv"	Coordinate follows the defined UVW coordinates on the model.
"sphere"	Coordinates are generated from a sphere map.

All other coordinate functions are not implemented yet or are work in progress.

blendfunc
Defines the blending function on the texture. Each blending function is explained below as a scale factor to the image colors:

kr, kg, kb and ka - Are defined as kc = 2^(mc) - 1, where mc is the number of the color bitplanes (mr for red, mg for green, mb for blue, ma for alpha)
Rs, Gs, Bs, As -> Source Colors
Rd, Gd, Bd, Ad -> Destination Colors

Component	Scale
"zero"	0, 0, 0
"one"	(1, 1, 1)
"srcclr"	(Rs/kr, Gs/kg, Bs/kb, As/ka)
"invsrcclr"	(1, 1, 1, 1) - (Rs/kr, Gs/kg, Bs/kb, As/ka)
"dstclr"	(Rd/kr, Gd/kg, Bd/kb, Ad/ka)
"invdstclr"	(1, 1, 1, 1) - (Rd/kr, Gd/kg, Bd/kb, Ad/ka)
"srcalpha"	(As/ka, As/ka, As/ka, As/ka)
"invscralpha"	(1, 1, 1, 1) - (As/ka, As/ka, As/ka, As/ka)
"dstalpha"	(Ad/ka, Ad/ka, Ad/ka, Ad/ka)
"invdstalpha"	(1, 1, 1, 1) - (Ad/ka, Ad/ka, Ad/ka, Ad/ka)

You can check more about those functions on the OpenGL documentation, on the glBlendFunc() function. If you just want to use transparent images (with alpha channel), you better use "blendfunc srcalpha invsrcalpha"