88 lines
3.1 KiB
Plaintext
88 lines
3.1 KiB
Plaintext
//unfortunately, have to wrap the docs in a C comment for doxygen
|
|
// vim:tw=74:formatoptions-=l
|
|
/**
|
|
\page mapformat Map (.map) File Format
|
|
|
|
"//" marks a comment which extends to the end of the current line
|
|
|
|
Note that () and {} characters require white space around them.
|
|
|
|
A map consists of a series of entities delineated by {}
|
|
|
|
An entity consists of a series of either epairs or brushes, one per "line".
|
|
|
|
An epair is a pair of quoted (via "quotes") strings. The first string of the
|
|
pair is the key, the second string the value. epairs are used to populate the
|
|
dictionary of the entity.
|
|
|
|
A brush is a simple, convex polytope delineated by {}. The format of a brush
|
|
is as follows:
|
|
\verbatim
|
|
{
|
|
[optional vertex list]
|
|
<plane spec> <texture name> <texcoord spec> [optional flags]
|
|
<plane spec> <texture name> <texcoord spec> [optional flags]
|
|
<plane spec> <texture name> <texcoord spec> [optional flags]
|
|
...
|
|
}
|
|
\endverbatim
|
|
That is, an optional vertex list followed by a number of surface specs, one
|
|
per line.
|
|
|
|
The optional vertex list, found in map files produced by Quest3d, is denoted
|
|
by a colon followed by a number indicating the number of vertexes in the list.
|
|
Following this, one per line, come the 3d coordinates of the vertexes, one
|
|
vertex per line. The vertex coordinates are listed in X Y Z order.
|
|
|
|
There are two formats for the plane spec, selected via the presence (vertex
|
|
mode) or absence (plane point mode) of the vertex list.
|
|
|
|
In vertex mode, the plane spec directly describes the shape of the surface
|
|
polygon. It is simply a number indicating the number of vertexes, followed by a
|
|
set of 0 based indexes, enclosed in (). The indexes indicate which of the
|
|
vertexes from the vertex list to use. When compiling the map, only the first 3
|
|
vertexes are significant: they are used as the 3 points for calculating the
|
|
plane.
|
|
|
|
In point plane mode, the plane spec consists of three point vectors, each
|
|
enclosed in ().
|
|
|
|
The three points (from either mode) are then used to calculate the plane
|
|
normal and offset:
|
|
\verbatim
|
|
n = (p0 - p1) x (p2 - p1) # normal
|
|
d = p1 . n # offset
|
|
\endverbatim
|
|
|
|
The texture name is just a simple string (no spaces) that specifies the name
|
|
of the texture within the wadfile.
|
|
|
|
The texcoord spec is black magic. :) It can be either:
|
|
(halflife style)
|
|
\verbatim
|
|
[ sx sy sz s ] [ tx ty tz t ] r s_scale t_scale
|
|
\endverbatim
|
|
or (quake style)
|
|
\verbatim
|
|
s t r s_scale t_scale
|
|
\endverbatim
|
|
In quake style, the basis vectors for s and t (sv and tv) are taken as the
|
|
most appropriate axial plane for the surface plane. In halflife style, they're
|
|
given directly via sv = (sx sy sz), tv = (tx ty tz). sv and tv are then
|
|
transformed by rotating around their perpendicular by r degrees. How this
|
|
interacts with halflife style is currently unknown. When rendering, the texture
|
|
coords (rs, rt) for vertex v are calculated as:
|
|
\verbatim
|
|
rs = v . sv + s
|
|
rt = v . tv + t
|
|
\endverbatim
|
|
|
|
The optional flags indicate various options for the surface. So far, the only
|
|
flag supported is "detail", indicating that the brush is a detail brush and not
|
|
to be used for visibility calculations. If any surface has the detail flag set,
|
|
the whole brush is affected.
|
|
|
|
Example map file (vertex mode):
|
|
\verbinclude cliptest.map
|
|
*/
|