== Quake Engine .MAP ==

Quake Engine maps are simple text files describing entities and their brushes. Brushes are solid components (walls, floors, crates, etc.) while entities are more or less "behaviors" (doors, elevators, item pickups, and so on).

Every brush must be part of an entity. The main entity containing the whole static world geometry is called "worldspawn". There must always be one and only one "worldspawn" per map.

Brushes are formed by several non-collinear intersecting planes. A plane is like a "slice", or an "infinite sheet of paper". They are non-collinear because they "meet" in some points eventually, but never entirely overlap.

Think of a big block of ice you can only shape using an infinite light saber: whenever a cut is made, a chunk of the ice is removed entirely, while the chunk located on the left side of the cut is preserved. That's how planes work. It means that you can only obtain convex (or "plain") shapes.

Each plane is defined by three 3D coordinates, and all of these points are part of the plane. Put a sheet of paper under the palm of your hand (that's the plane) and make a "L" with your thumb and index (the 1st point would be the tip of your index, the 2nd point would be the angle formed by your index and thumb, and the 3rd point would be the tip of your thumb). All three points "belong" to the space of that sheet of paper, thus "defining" the plane. If you tilt your wrist (assuming the sheet is sticking to your fingers), all three points would move in space, describing another plane. Planes are sorted in counter-clockwise order, cutting space to encase the brush on the left side (or the inside of all the intersecting planes). For instance, a Hexahedron ("a box") is defined by six planes; a tetrahedron ("a triangular pyramid") is defined by 4 planes, etc.

Quake Maps store a plane by line, starting with three 3D coordinates, and then describing the texture applied to the face. While Quake 1 only has a texture name, an X and Y offset, an X and Y scale, and a rotation angle, Quake II also includes three new values: a surface flag, a content flag, and a multi-purpose value (it is more often used to describe light intensity of light-emitting faces). Quake III Arena seem to use the same format as Quake II, but also features a new type of surface: curve patches (which are not described here).

Structure
The information is stored in scopes:
{
  {
  Entity definition (fields)
    {
    Brush definition (planes)
    }
    {
    Brush definition (planes)
    }
  }
  {
  Entity definition (fields)
  }
}

Entities are defined by a set of fields. A field is made of two parts: a key and a value. Keys can be seen as members of a custom type or variables: "classname", "origin", "light", etc. These are defined by the game code and sometimes used by compilation tools. Values are directly applied to the key: "worldspawn", "100 50 7", "100". What they represent may look pretty abstract if you're unfamiliar with the game for which the map was designed.

While some entities don't need brushes (point entities like starting points, weapons, items, monsters, etc), others need at least one brush to work (doors, elevators, buttons...) Just remember that one entity may contain multiple brushes (after all, that's the case for "worldspawn").

Here's how a plane is defined in Quake 1:
( p1.x p1.y p1.z ) ( p2.x p2.y p2.z ) ( p3.x p3.y p3.z ) TextureName OffsetX OffsetY Rotation ScaleX ScaleY

In Quake II, the line is slightly longer:
( p1.x p1.y p1.z ) ( p2.x p2.y p2.z ) ( p3.x p3.y p3.z ) TextureName OffsetX OffsetY Rotation ScaleX ScaleY SurfaceFlag ContentFlag Value

All texture parameters (OffsetX, OffsetY, Rotation, ScaleX and ScaleY) are relative to the origin of the coordinate system (point 0, 0, 0), not relative to the brush. SurfaceFlags and ContentFlags vary from game to game.