<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE doc
  SYSTEM '../../clonk.dtd'>
<?xml-stylesheet type="text/xsl" href="../../clonk.xsl"?>
<doc>
  <title>Map Generator</title>
  <h>Map Generator</h>
  <part>
    <text>Besides simple dynamic maps defined in Scenario.txt there is also a powerful dynamic map generator for highly complex yet fully random maps.</text>
    <text>This generator works with nested layers that can be combined using various operators and to which a material value and various attributes can be assigned to describe their resulting shape. The map generator will generate a map using these layers. The map is then later zoomed to the landscape as a static map would be.</text>
    <text>The structure of maps, layers, and attributes is stored in the component Landscape.txt in the scenario.</text>
    <h id="Syntax">Syntax</h>
    <text>The language describing this structure works with objects, attributes, and operators and is case sensitive. Objects are defined as follows:</text>
    <code>Object_type [Name] { Attribute };</code>
    <text>The name is optional. Current objects types are map, overlay, and point (for the poly algorithm). If an object is known it can later be used for another instance which is defined with:</text>
    <code>Name { Attribute };</code>
    <text>Here, the previously defined object 'Name' is copied and optionally extended by the given attributes. If no additional attributes are defined, the brackets can be omitted.</text>
    <text>General attribute syntax is:</text>
    <code>Attribut=Value;</code>
    <text>Attributes can be defined in any order within the object. They can optionally have % or px as unit and can be specified as single value or range of values (val1 - val2). In case of a duplicate assignment the last value is evaluated.</text>
    <text>In addition to attributes there can be nested sub-objects which can be combined using operators:</text>
    <code>Object1 Operator Object2;</code>
    <text>Operator statements can have any length and control the combination of layers. Operators are: | (OR), &amp; (AND), ^ (XOR).</text>
    <text>You will find several examples in the Dynamic Worlds folder.</text>
    <h id="Attributes">Attributes</h>
    <part>
      <h id="Attr_overlay">Layers (overlay)</h>
      <text>The following attributes are defined:</text>
      <text>
        <table>
          <rowh>
            <col>Attribute</col>
            <col>Type</col>
            <col>Description</col>
          </rowh>
          <row>
            <col>mat</col>
            <col>Material</col>
            <col>Material. The material must be defined in the active Material.ocg. Default is Sky.</col>
          </row>
          <row>
            <col>tex</col>
            <col>Texture</col>
            <col>Texture. The material-texture combination should be defined in the active TexMap.</col>
          </row>
          <row>
            <col>x, y, wdt, hgt</col>
            <col>Integer</col>
            <col>Size of the specified layer as a percentage of the layer above.</col>
          </row>
          <row>
            <col>algo</col>
            <col>Algorithm</col>
            <col>Area fill type. For a list of available fill types see <a href="#Algos">fill algorhythms</a>.</col>
          </row>
          <row>
            <col>zoomX, zoomY</col>
            <col>Integer</col>
            <col>Specifies the scale applied to the fill pattern. -100 to +99.</col>
          </row>
          <row>
            <col>ox, oy</col>
            <col>Integer</col>
            <col>Offset to the fill pattern in percent. You can use this e.g. to shift a sine curve.</col>
          </row>
          <row>
            <col>a, b</col>
            <col>Integer</col>
            <col>Additional parameters for the fill pattern.</col>
          </row>
          <row>
            <col>turbulence</col>
            <col>Integer</col>
            <col>10 to 10,000; layer deformation</col>
          </row>
          <row>
            <col>rotate</col>
            <col>Integer</col>
            <col>-180 to +180; rotation of the layer.</col>
          </row>
          <row>
            <col>invert</col>
            <col>Boolean</col>
            <col>0 or 1; if 1 the layer filling is inverted.</col>
          </row>
          <row>
            <col>seed</col>
            <col>Integer</col>
            <col>Random seed for layer generation. Each seed will create a unique random layer.</col>
          </row>
          <row>
            <col>loosebounds</col>
            <col>Boolean</col>
            <col>Determines whether the area limits are also affected by rotate, turbulence, ox, and oy.</col>
          </row>
          <row>
            <col>mask</col>
            <col>Boolean</col>
            <col>0 or 1; if 1 the layer is never drawn. This does not affect sub-layers.</col>
          </row>
          <row>
            <col>grp</col>
            <col>b</col>
            <col>0 or 1; if 1 the layer is considered set if the local algorithm or the algorithm of one of the sub-layers returns true. If an operator follows, the layer itself is not drawn.</col>
          </row>
          <row>
            <col>sub</col>
            <col>Boolean</col>
            <col>0 or 1; if 1 the material is considered underground (default)</col>
          </row>
          <row>
            <col>lambda</col>
            <col>Integer</col>
            <col>0 to 20; additional turbulence iterations</col>
          </row>
        </table>
      </text>
      <h id="Attr_map">Maps</h>
      <text>Maps generally can have the same attributes as layers. However, only mat, tex, and sub are really useful for maps and determine the background filling.</text>
    </part>
    <h id="Algos">Fill Algorithms</h>
    <text>To decide whether a point on a map hits a given layer, it is first transformed (zoom, turbulence, rotate, ox/oy) and then processed in the layer's algorithm. Also it is checked against the mask boundaries (x, y, wdt, hgt). This is usually done before, but with loosebounds after the transformation.</text>
    <dl>
      <dt id="Algo_solid">solid</dt>
      <dd>
        <text>Default algorithm. Always true.</text>
      </dd>
      <dt id="Algo_random">random</dt>
      <dd>
        <text>Random points. The parameter specifies probability. The higher a, the less likely the point is set.</text>
      </dd>
      <dt id="Algo_checker">checker</dt>
      <dd>
        <text>Alternating boxes of size 10 (at normal zoom).</text>
      </dd>
      <dt id="Algo_bozo">bozo</dt>
      <dd>
        <text>Specks. Parameter a can be used to reduce speck size.</text>
      </dd>
      <dt id="Algo_sin">sin</dt>
      <dd>
        <text>Horizontal sine curve. In standard zoom the amplitude is 10, the period 20 pixels.</text>
      </dd>
      <dt id="Algo_boxes">boxes</dt>
      <dd>
        <text>Orderly boxes. Parameter a defines block size, b the distance of block centers.</text>
      </dd>
      <dt id="Algo_rndchecker">rndchecker</dt>
      <dd>
        <text>As checker, but not in alternating but in random order.</text>
      </dd>
      <dt id="Algo_lines">lines</dt>
      <dd>
        <text>Vertical lines. Parameter a defines line width, b defines distance between lines.</text>
      </dd>
      <dt id="Algo_border">border</dt>
      <dd>
        <text>Draws an inner border in the parent layer (or the whole operator chain respectively). a and b are the horizontal and vertical border width. Because the superior layer needs to be accessed for calculation, it cannot be defined as a group (grp).</text>
      </dd>
      <dt id="Algo_mandel">mandel</dt>
      <dd>
        <text>Draws the Mandel fractal into the target area. Parameter a specifies iteration depth (default 1000). With no zoom, the complete "Apfelmännchen" is drawn (corresponding to -2-2i to 2+2i).</text>
      </dd>
      <dt id="Algo_rndall">rndall</dt>
      <dd>
        <text>The complete area is filled, or not filled, with probability a (in percent). Using this algorithm you could for example specify multiple maps as sub maps of a mask=1 layer and one of these maps would be randomly chosen.</text>
      </dd>
      <dt id="Algo_script">script</dt>
      <dd>
        <text>This algorithm is defined via a <emlink href="scenario/script.html">scenario script</emlink> function of the following form:</text>
        <code>func ScriptAlgo[Overlay-Name](x, y, alpha, beta)</code>        <text>The script function's return value should be 0 (no material) or 1 (material). x and y are the pixel coordinates for which the function is called. iAlpha and iBeta correspond to parameters a and b.</text>
        <text>If the layer has no name, the function "ScriptAlgo" is used.</text>
      </dd>
      <dt id="Algo_poly">poly</dt>
      <dd>
        <text>Returns true for pixels within the specified polygon. Points are specifed using</text>
        <code>point { x=&lt;X-Coordinate of the vertex&gt;&lt;Unit&gt;; y=&lt;Y-Coordinate&gt;&gt;&lt;Unit&gt;; };</code>        <text>Example:</text>
        <code>overlay { algo=poly; mat=Earth;
  point { x=10px; y=25%; };  
  point { x=20px; y=25%; };  
  point { x=10px; y=75%; };  
  point { x=20px; y=75%; };  
  point { x=30px; y=50%; };
};</code>      </dd>
    </dl>
    <h id="Operators">Operators</h>
    <text>Multiple layers can be combined using operators. This are evaluated from top to bottom and only the bottom most result of the chain is drawn. In a group (grp) the child layers are taken into the calculation but not actually drawn. Operators are | (OR), &amp; (AND), ^ (XOR).</text>
  </part>
  <author>Sven2</author><date>2001-07</date>
</doc>
