Bzw 2.0 texturing howto

Materials

To have a texture, you need a material. According to bzw manpage, a material object is defined as follows:

material
	name example_material
	addtexture filename  # add texture (without PNG extension)
	notextures           # specify that no textures are to be used
	notexcolor           # the color is not applied to the texture
	notexalpha           # don't use the texture's alpha channel
	# if a texture is specified, but not found, the default texture
	# will be used. if the default texture is also not available, then
	# the color will be used (untextured)
	texmat -1                 # texture matrix  (-1 for none)
	dyncol -1                 # dynamic color  (-1 for none)
	ambient  0.2 0.2 0.2 1.0  # ambient color
	diffuse  1.0 1.0 1.0 1.0  # diffuse color (main color)
	color    1.0 1.0 1.0 1.0  # synonym for 'diffuse'
	specular 0.0 0.0 0.0 1.0  # specular color
	emission 0.0 0.0 0.0 1.0  # emission color
	shininess 0.0             # shininess
	resetmat                  # restore default values
end

Not all combinations and uses of those options will be descibed in this tutorial, but it should give you a basic idea about materials and textures.

Most basic material is as follows:

material
	name red
	diffuse 0.8 0.2 0.2 1
end

As you may guess, it is red. Diffuse and other color definitions in bzw are RGB in 0..1 range. In most programs, RGB is in range 0..255. To convert values from bzw to other programs or vice versa (for choosing colors etc.), use:

RGB = BZWColor * 255
BZWColor = RGB / 255

Simple, huh? So, if we want to know what diffuse 0.8 0.2 0.2 1 is in RGB, we do:

0.8 * 255 , 0.2 * 255 , 0.2 * 255 , 1 * 255
And the result is:
204 , 51 , 51 , 255
As color:

Four values, why? The fourth number is the alpha channel, transparency that is. 1 is fully opaque, and 0 would be invisible. 0.9 is slightly transparent and 0.1 almost invisible.

But, a material needs to be applied on a object before we can even see it. Only "new" objects support materials. Objects that do are:

meshbox (like ordinary box)

meshpyr (like pyramid)

arc (circles, arcs, cylinders)

cone (round pyramid)

sphere (ball)

mesh (custom form)

tetra ("tetrapak")

Defining texture can be done either for all faces:

meshbox
	position 0 0 0
	size 10 10 5
	matref red
end

Note that the material (in this case, red) has to be defined _before_ using it in a object. Material can also be defined for just one side:

meshbox
	position 0 0 0
	size 10 10 5
	matref red
	top matref blue
end

That first defines all faces as red, and then changes top of the box to blue. Order is important!

Textures

This far, we havent used any textures. Client has to have the textures used on the map. You can make your own textures with any image editor capable of saving as ".png", but you have to make them available in internet and players have to download and install them to see your map right! There are some builtin textures in bzflag, though:

boxwall (the ordinary texture for walls)

clouds (on the sky)

mesh

pyrwall (ordinary pyramids)

roof (ordinary box roof)

std_ground (grass)

telelink (teleport texture)

tetrawall

wall (outer wall, rocks)

water

There are some others, but these are the most usable ones. With diffuse and creative mind, you can usually get almost anything from them.

Textures are added with addtexture-keyword. If we wanted to add a texture to our red meshbox, the complete code would look like:

material
	name red
	diffuse 0.8 0.2 0.2 1
	addtexture boxwall
end

meshbox
	position 0 0 0
	size 10 10 5
	matref red
end

Texture scaling

Example of texsize use:

meshbox
	position 0 0 0
	size 10 10 5
	texsize 0.5 0.5 0.5 0.5
	matref red
end

Values after the texsize keyword are specific to the object. Usually the order is sides first, top/bottom after that. Two values specify the size of the texture. If value is positive, it is relational to the size of the object. In our example, 0.5 means there will be 0.5 texture-tiles per face, ie. whole tile is twice as big as the side of the box. Negative values specify size in bzmap units, -8 -8 -8 -8 seems to be the default size that means each tile will be 8x8 bzmap units. For arc, there seems to be no top/bottom values. If you want more detailed control over textures, trepan recommends to use textureMatrix.

Dynamic colors

I will discuss dynamic colors very briefly, since they are quite complicated and out of the scope of this tutorial. Dynamic colors are colors that change. And no, they do not change at the same time for all the clients, so you can't have traffic lights etc.

According to bzw man page, there are five dynamic color commands: limits, sinusoid, clampUp, clampDown and sequence. Of these, only sinusoid and limits are used here.

dynamicColor
	name flash
	red sinusoid 8 0 1 #8 seconds cycle, from 0 to 1
	blue limits 0 0 #always 0
	green limits 0 0 # always 0
end
material
	name red
	dyncol flash
end

<Object that material is used in>