Meshes

It is possible to directly use 3D models (meshes) as object graphics. To do so they need to be in OGRE format. For most modeling tools there exist exporter tools, a list can be found on the OGRE Wiki. Both the OGRE binary format (*.mesh) and the OGRE XML format(*.mesh.xml) are supported, however it is recommended to always use the binary format whenever possible since it is smaller in size and can be loaded more quickly by the engine. The tool OgreXMLConverter can convert between the two formats.
The exporter normally creates a mesh file (*.mesh or *.mesh.xml), a skeleton file (*.skeleton or *.skeleton.xml) if the mesh contains bones, a material script (*.material) and potentially used textures. To use the mesh as a Clonk object all generated files need to be copied into the object definition and the mesh file needs to be renamed to Graphics.mesh or Graphics.mesh.xml, respectively. Textures are supported in PNG, JPG and BMP format.
The mesh is not automatically scaled to the shape (i.e. the width and height values specified in DefCore.txt) of the object. Instead one unit in the modeling tool corresponds to one pixel in Clonk. This simplifies using the same magnitude of object sizes for all objects which is especially helpful for attaching meshes (see below). Also pay attention to the coordinate frame: The X axis in the mesh coordinate frame points out of the screen in Clonk, the Y axis points to the right and the Z axis points upwards.

Material scripts

All material scripts (*.material files) are loaded by the engine before the mesh in the same directory is loaded. Material scripts are simple text files which specify the material properties (material colors, textures, etc.) that can be used by meshes. Each material is assigned a name that can normally be specified in the modeling tool. It should be taken care that names are unique (for example by prefixing all material names with the object name of the object they are supposed to be used with) since all loaded materials can directly be used by any mesh so otherwise they could be naming conflicts.
Material scripts can also be crafted or edited by hand. The format is described in the OGRE manual. However not all of the features described there are supported (yet): Especially usage of LOD (Level of Detail) is not yet possible. The usage of pixel, vertex and geometry shaders has some restrictions, as discussed in the section below. For the source1 and source2 fields in the colour_op_ex field in texture units the additional value src_player_colour can be specified to refer to the player color of the object's owner. This can be used to colorize objects (partly) by the player color.
At runtime the material script can be changed using the C4Script function SetMeshMaterial.

Shaders

Pixel, vertex and geometry Shaders can be used to customize the appearance of an object beyond what is possible by the declarations in OGRE passes and texture units. The OGRE manual should be consulted to learn how shaders can be used, however, there are some restrictions in OpenClonk.
First and foremost, only shaders written in the GLSL are supported at the moment. None of the automatic parameters are available for shaders, however, some of these are implicitly available as GLSL variables.
When a custom fragment shader is used, then that shader is responsible for applying the player color and color modulation to the object, since in that case the engine cannot take care of that. The additional parameters mentioned above can be used for that purpose. Also, when a custom fragment shader is used, the colour_op, colour_op_ex, alpha_op and alpha_op_ex directives in all texture units are ignored.
When a fragment shader or a vertex shader (or both) are not specified, then standard shaders are generated. The standard shaders expect certain GLSL varying variables to be propagated from the vertex shader to the fragment shader, so if you implement a vertex shader but not a fragment shader, make sure to create the following varying variables:
Varying variables used by the standard shader
Variable name Type Description
normalDir vec3 The interpolated normal vector for lighting calculations.
texcoord vec2 The interpolated texture coordinate, based on the texture coordinates specified in the mesh.
The standard fragment shader uses these values and possibly processes them with what is specified in the texture unit declarations. The standard vertex shader creates these values from the GL state, and is independent of the texture units or other declarations. If no custom vertex shader is provided, the following shader is used:
varying vec3 normalDir;
varying vec2 texcoord;

void main()
{
  normalDir = normalize(gl_NormalMatrix * gl_Normal);
  texcoord = gl_MultiTexCoord0.xy;
  gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
}
Shaders for OpenClonk are composed of various shader slices. This allows to add openclonk-specific code to the shaders, such as applying color modulation for objects, or lighting. A slice is specified by slice(position) { ... } in the shader code, and the code within the slice is then used for composing the whole shader code. Uniform variables should be declared outside of any slices. The following position values for slices are defined, and slices are inserted from lower to higher values:
Defined shader slice positions
Slice position Value Description
texcoord 50 Vertex shader: Should be used to set the texcoord varying variable.
normal 60 Vertex shader: Should be used to set the normalDir varying variable.
position 80 Vertex shader: Should be used to set the gl_Position variable.
init 0 Fragment shader: Should be used for initializing required variables. The standard slices set the initial color value from the mesh material properties here.
coordinate 20 Fragment shader: Should be used for calculating custom texture coordinates.
texture 40 Fragment shader: Should be used for texture lookups.
material 60 Fragment shader: Used by the landscape shader to query the material pixel.
normal 80 Fragment shader: Should be used to compute the normal vector.
light 100 Fragment shader: Should be used for lighting calculations.
color 120 Fragment shader: Should be used for setting the output color value.
finish 140 Fragment shader: Final slice position, can be used for debug code overwriting any previous output, for example.
A slice position can also have a relative constant offset with a plus or minus sign, such as texture+1. The fragment shader slices should modify the implicitly defined value color of type vec4.
In order to make sure that other OGRE mesh viewers can still display the mesh, it is suggested to wrap the slice definitions into corresponding #ifdef blocks. This also allows to, for example, set default light conditions when the mesh is shown in a standalone OGRE mesh viewer. An example is given here:
#ifndef OPENCLONK
#define slice(x)
#define color gl_FragColor
varying vec2 texcoord;
void main()
{
  color = vec4(1.0, 1.0, 1.0, 1.0); // or gl_FrontMaterial.ambient;
#endif

// Shader slices go here.
slice(XXX) { ... }

#ifndef OPENCLONK
  // Custom lighting code for standalone mesh viewers can go here
}
#endif
If the uniform variable oc_PlayerColor is defined with type vec3, it is automatically set by OpenClonk to the player color of ColorByOwner objects.

Animations

As for bitmap based graphics an object can play an animation while executing an action. To do so first a rig for the model and then an animation needs to be created. When exporting it is saved in the *.skeleton (or *.skeleton.xml for the OGRE XML format) file. To play it during an action the Animation field of the action needs to be set in the ActMap. The Facet fields are ignored for mesh graphics.
It is also possible, via script, to play multiple animations at the same time or to specify transitions between animations. To learn more about this possibility see Animations.
Just as scripts, animations can be appended or included to certain definitions. For this purpose the *.skeleton file has to match a certain pattern: appendto.Definition.skeleton adds the animations in that skeleton to the skeleton that was loaded by Definition. Existing animations will not be overloaded. Similarly, include.Definition.skeleton includes animations. Make sure to name your skeleton accordingly when rigging the mesh, if you want to include animations. Obviously, animations from only one definition can be included, but skeletons from multiple animations can be appended.

Attachment of meshes

Meshes can be attached to each other so that they always move together. This allows the clonk to carry objects or to aim with the bow. To attach two meshes the C4Script function AttachMesh can be used, or DetachMesh to detach them again. When attaching a bone of both meshes needs to be specified. The attached mesh is then aligned so that its bone has always the same position and orientation as the one to which it is attached.
However it needs to be taken care of the fact that only the meshes, that is the graphics of the objects, are attached. The real position of the attached object (so what is returned by the functions GetX and GetY or the area in which the object is found by the functions Find_AtPoint, Find_InRect or Find_AtRect) is not affected.

Picture graphics.

If an object uses a mesh then the Picture entry of the DefCore.txt remains without effect. Instead a perspective projection of the mesh will be used. The camera will be placed in the front of the object at a distance so that the mesh is totally covered.
The position and orientation of the mesh with respect to the camera can be changed by making use of the "PictureTransformation" property. This way it can be shown displaced, rotated or scaled. The property should be assigned an array with 12 integer entries which make up a 3x4 matrix. The first four values specify the first row, the next four values specify the second row and the last four entries specify the third one. Those matrices can be conveniently created using the script functions Trans_Identity, Trans_Translate, Trans_Rotate, Trans_Scale and Trans_Mul.
As with SetObjDrawTransform the individual matrix elements are specified in per thousand (1000 = 100%) since there are no floating point numbers in Clonk.
As an example we show the transformation of the tool workshop:
SetProperty("PictureTransformation", Trans_Mul(Trans_Translate(0,0,7000), Trans_Rotate(-20,1,0,0), Trans_Rotate(30,0,1,0)), def);
First the workshop is rotated by 30 degrees counter-clockwise around the Y axis, then by 20 degrees clockwise around the X axis. Finally it is moved 7 units in positive Z direction so that it is nearer to the camera.

MeshTransformation

The same way the "PictureTransformation" property affects the presentation of the picture graphics the "MeshTransformation" property is applied for ingame graphics. The results are very similar to what can be done with SetObjDrawTransform, however there are a few subtle differences:
Clonk-Karl, 2010-04
Marky, 2015-01