<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE doc
  SYSTEM '../../clonk.dtd'>
<?xml-stylesheet type="text/xsl" href="../../clonk.xsl"?>
<doc>
  <title>Material Definitions</title>
  <h>Material Definitions</h>
  <part>
    <text>Using material definitions you can specify looks and behaviour of the landscape materials.</text>
    <h id="MaterialdefinitionsKomponentenMaterialocg">Material Definition Components (Material.ocg)</h>
    <dl>
      <dt id="TexMaptxt"><img height="16" src="../../images/icon_text.png" width="16"/>TexMap.txt</dt>
      <dd>
        <text>Lookup table for color indices in static and dynamic landscapes. Colors 0-255 are matched to a material-texture-reference, except in Map.bmp static landscapes, where colors 0-127 are matched to a material-texture reference, and 128-255 are matched to the same list of references, except they are marked 'underground'.</text>
        <text>Each line may contain one material-texture-entry in the format Index=Material-Texture. For example, 12=Earth-earth-topsoil would define color index 12 as earth material with the texture taken from a file called earth-topsoil.png.</text>
        <text>The engine will draw materials in the order they are defined in the TexMap file, irrespective of assigned palette indices. Materials drawn late overwrite materials drawn early so that, e.g. using the standard table, rough chunks of earth will overlap water which has a smooth border. Mineral resources have an even higher index so that their rough border overlaps the earth and not the other way around. For this reason, there might be differing numbers of total pixels of a given material drawn than you might expect just from calculating the square sizes of the unzoomed map materials.</text>
        <text>If a custom map fails with the message 'texture n undefined' you should define the specified texture in the TexMap. You should always use a paint program capable of editing indexed color palettes without modifying the palette (MS Paint is not suited for this).</text>
      </dd>
      <dt id="ocm"><img height="16" src="../../images/icon_material.png" width="16"/><emlink href="material/ocm.html">*.ocm</emlink></dt>
      <dd>
        <text>The engine will accept up to 252 material definitions at a time. OCM files a simple text files. The materials Vehicle, Tunnel, Water, Snow, Granite, Sand, and Earth must always be available.</text>
      </dd>
      <dt id="bmp"><img height="16" src="../../images/icon_image.png" width="16"/>*.png, *.jpg</dt>
      <dd>
        <text>There can be any number of textures in any material group. Width and height of each bitmap must be powers of 2 (that is 16, 32, 64, 128, 256, etc.).</text>
        <text>Each texture may optionally have a normal map named texturename_NRM.jpg and a shape texture named texturename_Shape.png (see section below).</text>
      </dd>
    </dl>
    <h id="MaterialTexturReferenzen">Material-Texture-References</h>
    <text>At numerous places in scenario definitions materials are specified with additional information on texture and amounts.</text>
    <text>
      <table>
        <row>
          <col>Material using an specified texture:</col>
          <col><code>Earth-Rough</code></col>
        </row>
        <row>
          <col>Material and texture with specified amount:</col>
          <col><code>Gold-Rough=100</code></col>
        </row>
        <row>
          <col>Multiple material definitions:</col>
          <col><code>Earth-Smooth=10; Rock-Rough=5</code></col>
        </row>
      </table>
    </text>
    <h id="TextureShapes">Texture shapes</h>
    <text>Shape textures may be used to denote individual objects like rocks or bricks within a texture. When zooming the map to the landscape, the engine tries to zoom such that only complete objects from the shape texture are used in the final landscape. This is achieved by completing all shapes that have a minimum coverage from the map pixels zoomed at flat shape. The minimum coverage can be set per material using the MinShapeOverlap setting.</text>
    <text>Texture files should be named [Texturename]_Shape.png and use one distinct color per shape. Shapes may (and should) wrap around borders, but must not exceed 25% of the total texture size in each dimension. Areas outside a shape must be made fully transparent. All shape colors must be exact, i.e. no anti-aliasing between shapes or to transparency may be used. Shape files should have be sized as a whole multiple of the corresponding texture size divided by its scaler (usually 4). A maximum of 255 shapes may be defined in each texture. See granite_Shape.png in the original Materials.ocg for an example.</text>
    <text>For debugging purposes, e.g. for finding problems with spurious single pixels, a summary of all loaded shape textures can be printed to the startup log by setting DebugShapeTextures in the [Developers] section of the configuration to a nonzero unsigned integer.</text>
  </part>
  <author>Sven2</author><date>2015-10</date>
  <author>matthes</author><date>2004-04</date>
</doc>
