4.16.4.3 Hints

Written by Jorrit Tyberghein, jorrit.tyberghein@gmail.com. Mathematical typesetting for TeX performed by Eric Sunshine, sunshine@sunshineco.com.

This section contains extra discussions and hints regarding the map file and the objects contained within it (this documentation is a little bit outdated but still useful for the general idea. However it should be moved to the thing mesh object description).

First, a little explanation about ‘LEN’ and ‘TEXLEN’. With these you can specify the size of the texture on the polygon. For example, let's say that you have a rectangular polygon which is 4 units wide and 6 units tall. A texture with ‘LEN’ set to 2 will be tiled 2 times horizontally and 3 times vertically. If this texture is 128x128 (for example) then the final texture on the polygon will be 256x384.

Using a ‘TEXTURE’ statement inside a ‘POLYGON’ or with a ‘PLANE’ statement you can obtain even more control over how the texture should be scaled across the polygon. This is most easily explained with an example. Say that you have a polygon like this:

VERTEX (0,2,3) VERTEX (2,2,3) VERTEX (2,0,3) VERTEX (0,0,3)
POLYGON 'poly' (VERTICES (0,1,2,3))

Let's say that you want to align the texture so that its origin is at (2,2,3). You can do this as follows:

POLYGON 'poly' (
  VERTICES (0,1,2,3)
  TEXTURE (
    ORIG (2,2,3)
    FIRST (0,2,3)
    SECOND (2,0,3)
    FIRST_LEN (1)
    SECOND_LEN (1)))

With ‘ORIG’, ‘FIRST’, and ‘SECOND’ you specify how the u/v coordinate system is located. The origin of u/v is at ‘ORIG’; the u-axis is at ‘FIRST-ORIG’; and the v-axis is at ‘SECOND-ORIG’. ‘FIRST_LEN’ and ‘SECOND_LEN’ are similar to ‘LEN’ and ‘TEXLEN’ except that you can control the u and v scaling separately here. Note that ‘ORIG’, ‘FIRST’, and ‘SECOND’ need not coincide with vertices of the polygon. They should just be on the same plane as the polygon. That way you can also create slanted textures.

‘TEXLEN’ in a ‘THING’ or ‘SECTOR’ is the default ‘LEN’ for all polygons following the ‘TEXLEN’ declaration. ‘TEXNR’ in a ‘THING’ or ‘SECTOR’ is the default ‘TEXNR’ for all following polygons. Note, however, that ‘TEXNR’ is considered obsolete and its use is deprecated.

Use of planes is recommended. A ‘PLANE’ provides a way to assign a name to a texture orientation. All polygons sharing the same ‘PLANE’ will have textures that fit perfectly at the borders. Crystal Space will also be able to do some optimizations on polygons that share the same plane (like backface culling an entire set of polygons in one operation). Note that even if a ‘PLANE’ is only used by one polygon it does not hurt. If you do not specify the ‘PLANE’, Crystal Space will create one anyway.

Currently Crystal Space assumes that there is a sector called ‘room’. It will use that as a starting place, and will always start at location (0,0,0) unless you use an ‘ORIGIN’ directive to instruct it otherwise.

Note that Sectors must be convex (unless you add a BSP tree). Things need not be convex.

Vertices in a ‘THING’ are specified in local object space. You can translate this object space to world space with the ‘MOVE’ directive.

When a ‘THING’ or ‘SPRITE’ is defined in the ‘WORLD’ statement and not in a ‘SECTOR’ or ‘ROOM’ then it defines a template. This template can then be used inside a ‘SECTOR’ or ‘ROOM’ by providing another ‘THING’ or ‘SPRITE’ statement and using the ‘TEMPLATE’ statement there. It is also possible to define the ‘THING’ or ‘SPRITE’ inside a ‘SECTOR’ or ‘ROOM’ directly, but using templates is preferable.

With ‘WARP’ you provide a matrix which will mirror or warp space. For example, when you want to make a mirroring floor the warping matrix should invert the Y-axis and leave the others intact. So the ‘WARP’ matrix would be:

/ 1  0 0 \
| 0 -1 0 |
\ 0  0 1 /

The vector should be a vector on the plane of the mirror. It is used to determine exactly where mirroring should start. For example, if the floor is at height -1, then (0,-1,0) is a good spot.

‘MATRIX (.5)’ is a shorthand for:

/ .5  0  0 \
|  0 .5  0 |
\  0  0 .5 /

Portals are unidirectional. If you need a ‘PORTAL’ that works in two directions (so that you can go back) then you'll also have to specify a ‘PORTAL’ in the other sector pointing back.

Note that even though a ‘PORTAL’ does not require a texture (unless it has alpha transparency) you still need to specify one, since Crystal Space currently assumes that every polygon has a texture.

The ‘ROOM’ and ‘SIXFACE’ interfaces are good for human editors but it not suited for computer generated output. Ignore ‘ROOM’ and ‘SIXFACE’ if you want to write an editor or converter and concentrate on ‘SECTOR’ and ‘THING’ instead.

This document was generated using texi2html 1.76.