openclonk/docs/sdk/definition/index.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE doc
  SYSTEM '../../clonk.dtd'>
<?xml-stylesheet type="text/xsl" href="../../clonk.xsl"?>
<doc>
  <title>Object Definitions</title>
  <h>Object Definitions</h>
  <part>
    <text>Object definitions are used for all game objects in clonk: the wooden hut, goal objects and the clonk himself. An object definition is a group file composed from the following components:</text>
    <h id="Properties">Object properties</h>
    <dl>
      <dt><img height="16" src="../../images/icon_text.png" width="16"/><emlink href="definition/defcore.html">DefCore.txt</emlink></dt>
      <dd>
        <text>Object properties.</text>
      </dd>
      <dt><img height="16" src="../../images/icon_text.png" width="16"/><emlink href="definition/actmap.html">ActMap</emlink></dt>
      <dd>
        <text>Table for activities, normally used for objects with animations. The ActMap is defined in the Script.c as a property list.</text>
      </dd>
	</dl>
	<h id="Script">Script</h>
	<dl>
      <dt><img height="16" src="../../images/icon_text.png" width="16"/><emlink href="definition/script.html">Script.c</emlink></dt>
      <dd>
        <text>The object script. See <emlink href="definition/script.html">object scripts</emlink> and <emlink href="lang.html">localization</emlink>.</text>
      </dd>
	</dl>
	<h id="RasterGraphics">Raster Graphics</h>
	<dl>
      <dt id="Graphicspng"><img height="16" src="../../images/icon_image.png" width="16"/>Graphics.png/Graphics.*.png</dt>
      <dd>
        <text>Graphics of the object. Base graphics, animation phases and a picture for display in menus are stored in a 32 bit picture with transparency channel (PNG format, 32 bit RGBA color, non interlaced). An optional zoom factor for high-resolution graphics can be provided in the '*'-portion of the name.</text>
      </dd>
      <dt id="Overlaypng"><img height="16" src="../../images/icon_image.png" width="16"/>Overlay.png</dt>
      <dd>
        <text>The part of the object's graphics which is to be colored in the player color (see ColorByOwner in <emlink href="definition/defcore.html">DefCore.txt</emlink>) can also be defined using a separate graphics file. In Overlay.png gray scales should be used instead of blue color.</text>
      </dd>
      <dt id="Normalpng"><img height="16" src="../../images/icon_image.png" width="16"/>Normal.png</dt>
      <dd>
        <text>An optional normal map for the object, where the red, green and blue components in the image correspond to the normal vectors to be used for the lighting of the object. If this file is not present, the normal vector at each pixel points straight into Z direction (outside of the screen).</text>
      </dd>
      <dt id="Graphicsex"><img height="16" src="../../images/icon_image.png" width="16"/>Graphics*.png/Overlay*.png (Graphics*.*.png/Overlay*.*.png)</dt>
      <dd>
        <text>Objects can also contain alternative sets of graphics which can be selected ingame using the script command <funclink>SetGraphics</funclink>(). The name corresponds to the file name portion following "Graphics". The matching overlay is automatically selected. For more information see <funclink>SetGraphics</funclink>().</text>
      </dd>
      <dt id="SolidMask"><img height="16" src="../../images/icon_image.png" width="16"/>SolidMask.png</dt>
      <dd>
        <text>Image describing areas in this object that are solid, so vertices of other objects will collide with it. Pixels are made solid if they are 50% or less transparent in this image. Source rectangle within this graphic and target position on the object must be set in <emlink href="definition/defcore.html">DefCore.txt</emlink> property "SolidMask" or using the script function <funclink>SetSolidMask</funclink>.</text>
      </dd>
	</dl>
	<h id="MeshGraphics">3D Graphics</h>
	<dl>
      <dt id="Graphicsmesh"><img height="16" src="../../images/icon_ogre_mesh.png" width="16"/><emlink href="definition/meshes.html">Graphics.mesh</emlink></dt>
      <dd>
        <text>A 3D model can be used as an object's graphics instead of a bitmap. It needs to be provided in OGRE format. There are exporters for most 3D modeling tools. All files that are required by the mesh (especially material scripts, textures and skeletons) need also to be present in the object.</text>
      </dd>
      <dt id="Graphicsskeleton"><img height="16" src="../../images/icon_ogre_mesh.png" width="16"/>*.skeleton</dt>
      <dd>
        <text>Skeleton files contain bones and animations for a 3D model. They are usually created by the exporter if bones and/or animations are used for the mesh.</text>
      </dd>
      <dt id="MaterialScripts"><img height="16" src="../../images/icon_ogre_mesh.png" width="16"/><emlink href="definition/meshes.html#MaterialScripts">*.material</emlink></dt>
      <dd>
        <text>OGRE material scripts are simple text files which contain information about the material of a 3D model. Each model is assigned a material which specifies how it is rendered. Normally these scripts are being generated by the exporter, but they can also be hand-edited afterwards (using a text editor) to apply additional effects.</text>
      </dd>
      <dt id="Textures"><img height="16" src="../../images/icon_image.png" width="16"/>*.png</dt>
      <dd>
        <text>Any number of textures defined in the OGRE material scripts.</text>
      </dd>
	</dl>
	<h id="Sound">Sounds</h>
	<dl>
      <dt id="wav"><img height="16" src="../../images/icon_sound.png" width="16"/>*.wav/*.ogg</dt>
      <dd>
        <text>Object local sounds. As these are always loaded and not dynamically unloaded as are scenario sounds you should use these sparingly and with small sound files only.</text>
        <text>Object local sounds within valid definitions are automatically put into a namespace with the ID of the object. They can be played using <funclink>Sound</funclink>("id::soundname").</text>
      </dd>
    </dl>
	<h id="CrewMembers">Additional files for crew members</h>
	<dl>
      <dt id="Ranktxt"><img height="16" src="../../images/icon_text.png" width="16"/>Rank.txt/Rank*.txt</dt>
      <dd>
        <text>For object definitions defining a clonk type you can specify custom rank names for this clonk type here. The rank names will then also replace rank names of existing crew members of this type. The file should contain a simple text list of names of maximum 30 characters each. By using the approriate language codes you can create language dependent sets of rank names.</text>
      </dd>
      <dt id="Rankbmppng"><img height="16" src="../../images/icon_image.png" width="16"/>Rank.png</dt>
      <dd>
        <text>You can also define custom rank symbols for clonk types which are then displayed in the game instead of the standard symbols from Graphics.ocg. A rank symbol should always be square and there should be enough many symbols for all ranks. See the global Rank.png in the Graphics.ocg for an example.</text>
      </dd>
	</dl>
  </part>
  <author>Sven2</author><date>2002-04</date>
  <author>matthes</author><date>2004-06</date>
</doc>