GameTools material.xml

The game engine's view of what a "material" represents is far more complex than most 3D art programs represent in their file formats. Hence, we take the common approach of using the texture map name in the incoming model and using that to look up an external table of detailed material properties. Generally, one of the properties of that material will be the texture that matches up with the one on the incoming artwork - but this is not necessarily the case.

The file 'material.xml' (in the 'data' directory) lists the names of materials - which must match the root name of the textures in the model. So if you make a 3D model in AC3D or blender or whatever and texture it with "images/bricks.rgb", then that model will be stripped of it's texture and have the material named "bricks" assigned to it. Typically, the "bricks" material will include the texture "images/bricks.rgb" - but that's not a requirement - so perhaps not.

For example - the game needs to know that water polygons are special because some objects such as boats can float on water and others cannot. There is no clear way to know what's water and what isn't from the data we get from the modeller so we look up the name of the texture map in this 'material.xml' file and see if it's marked as being special.

Texture maps that are not listed as materials here are treated as plain, ordinary surfaces with the 'default' material property but with the texture you specified.

So in principle, you only have to list the special stuff.

Example

Here is an example of a 'material.xml' file:

 <?xml version="1.0" ?>
 <matlist>
   <material name="leaves" collide="false" shader="vegetation" >
     <uniform name="foliage_texture" value="leaf" type="sampler2D" />
     <uniform name="color" value="0,1,0" type="vec3" />
   </material>
   <material name="ocean"  collide="false" water_surface="true" />
 </matlist>

In this case, any polygons that have the texture named "leaves.jpg" (or "images/leaves.png" or whatever) will use the texture map "images/leaf.rgb" which will be bound to the variable "uniform sampler2D foliage_texture" in the shader named "vegetation.vs"/"vegetation.fs".

Polygons that have the texture "whatever/ocean.whatever" will pick up the shader that defaults to "ocean.vs"/"ocean.fs" (or if those do not exist, "default.vs"/"default.fs") and use the texture "images/ocean.rgb" (or if that doesn't exist, "default.rgb"). Inside the shader, the texture will be attached to "uniform sampler2D texture" - which is probably where most single-texture shaders should expect it to be.

Structure

Since this is an XML 'material' file, the first three lines must always be:

 <?xml version="1.0" ?>
 <matlist>

...and the last line is always:

 </matlist>

Between those tags are a number of material setup commands:

 <material name="XXX" ... />

XXX is the name of the texture map - without its path-name and without a file extension. Any polygons with a texture that matches that name will take on whatever properties are listed in this record:

collide="boolean" 

Can this object pose an obstacle to things moving through it. Leaves, smoke, water do not and should be set to "false" - the default is "true".

water_surface="boolean" 

Set "true" if these polygons represent a water surface. Since these will generally have collide="false" set, objects will only collide with them if the object is floating.

Within the <material...>...</material> tags, you may list a number of 'uniform' variable to pass to the shaders:

 <uniform name="XXX" value="YYY" type="TTT" />

XXX is the name of the variable inside the shader.

YYY is the value of the variable - which can either be the filename of a texture map - or actual numerical data.

TTT is the type of the variable, one of the following:

• float - A single floating point variable (this is the default if the 'value' contains a number of some kind).
• float2 or vec2 - Two floating point numbers.
• float3 or vec3 - Three floating point numbers.
• float4 or vec4 - Four floating point numbers.
• int - A single integer.
• int2 or ivec2 - Two integers.
• int3 or ivec3 - Three integers.
• int4 or ivec4 - Four integers.
• bool, bvec2, bvec3, bvec4 - One, two three or four booleans.
• texture1D or sampler1D - A one-dimensional texture.
• texture2D or sampler2D - A two-dimensional texture (this is the default if 'value' doesn't start with a number).
• texture3D or sampler3D - A three-dimensional texture.
• textureCube or samplerCube - A cube-map.
• texture1Dshadow or sampler1Dshadow - A one-dimensional shadow map(?!)
• texture2Dshadow or sampler2Dshadow - A two-dimensional shadow map.

Wikiid Pages relating to gameTools ()

gameTools - Main page

gameTools - Support Tools : plb_to_ac3d, mklevel, mktile, mktree, tiled, autogen_java, mk3dgallery

gameTools - File Formats : title_screen.rgb, ultimate.xml, material.xml, decoration.xml, physics.xml tiled.xml, tiled_autotiles.xml, Level files, Tile naming scheme, PLB files

gameTools - Source Code : Game functions: gameCamera, gameClock, gameChecksum/gameHashTable, gameHTTP, gameIsect, gameJoystick, gameParticleManager, gameScreen/gameMouse, gameSky, gameStarter, gameStrokeFont, gameUtils Material database: MatList/MatEntry Tile map handling: TileObject/MapFlag/MapEntry/Map Java Interfacing: JavaLink Image file loading: liImage/liImageFactory 3D Model file loading: loadPLB, PLB exporter Physics: Sabot, Bullet, gameTools - Use with Blender, PLB exporter Object management: Object