View source for MAP (file format)

{{non-valve engine|engine|This page covers all major variants of the MAP file format, beyond that which is used by {{gldsrc|2}}, to provide a comprehensive overview of the file format as a whole and explain why compatibility isn't trivial.}}
{{stub}}
The '''MAP''' file format is a plain-text file format used by {{gldsrc|4.1}}, {{idtech2|4.1}}, {{idtech3|4.1}}, and {{idtech4|4.1}}, which stores entities and level geometry in a format which can be understood by the map compilers (and in the case of {{idtech4|3.1}}, the game itself). {{src|4.1|addtext='s}} [[VBSP]] also has residual support for compiling from MAP files.

At its core, the format consists of several [[entities]], each of which is optionally capable of storing one or more [[brush]]es, {{only|{{idtech3}}{{idtech4}}}} [[#Patch meshes|patch meshes]], and {{src|only}} [[#Displacements|displacements]].

{{warning|Compatibility isn't trivial. GoldSrc compilers exclusively use the Quake 1 Valve220 format, but MAP files exist in a multitude of variants; see [[#Variants]].
}}
== Variants ==
{| class="wikitable"
|-
! Header text !! Supported by !! Information
|-
| {{Quake|4|nt=0}} (Legacy) || Most tools, except {{hammer4|4.1}} || The original format.
|-
| {{Quake|4|nt=0}} (Valve220) || All {{gldsrc|4.1}} tools, most modern {{quakeengine|4.1}} tools, and {{hammer4|4.1}} || Variant of the Quake 1 (Legacy) format with additional texture UV precision.<br>Introduced by {{worldcraft|4.1|addtext={{nbsp}}2.0}}; now standard.
|-
| {{Quake2|4}} (Legacy) || All {{quake2engine|4}} tools, and most {{idtech3|4}} tools || Variant of Quake 1 (Legacy) format which optionally stores three additional [[WAL]] metadata flags.
|-
| {{Quake2|4}} (Valve220) || {{jack|4}}, {{nrc|4}}, and {{trenchbroom|4}} || Variant of Quake 2 (Legacy) format with Valve220-style UVs.<br>Introduced by {{jack|4.1}}; now standard.
|-
| {{Quake3|4}} (Axial Projection) || All {{idtech3|4}} tools 
| rowspan=2 | Variant of Quake 2 (Legacy) format with support for patch meshes (analogous to [[displacement]]s, but use Bézier curves instead of an array of vertices).

While Quake 3 MAP files can technically store both standard brushes and [[#Brush primitives|brush primitives]], map editors usually require selecting one or the other to write the file as.

The Quake 3 MAP format still supports the metadata flags from Quake 2, including on patch meshes and brush primitives, although only the detail flag ({{mono|0x08000000}}) is ordinarily used; this information is instead usually stored in the [[material]] definitions.
|-
| {{Quake3|4}} (Brush Primitives) || Most {{idtech3|4}} tools, except {{q3r|4}} and {{trenchbroom|4}} 
|-
| {{Quake3|4}} (Valve220) || {{jack|4}}, {{nrc|4}}, {{trenchbroom|4}} || Variant of Quake 3 format with Valve220-style UVs.<br>Introduced by {{jack|4.1}}; not yet standard.
|-
| {{Doom3|4}} (Axial Projection) || All {{idtech4|4}} tools
| rowspan=2 | Variant of Quake 3 format which can store patch meshes and brush primitives differently {{elaborate}}.

Like Quake 3, a map can technically store both standard brushes and brush primitives, but editors write the files as one or the other. Standard brushes are generally considered deprecated in favor of brush primitives.
|-
| {{Doom3|4}} (Brush Primitives) || Most {{idtech4|4}} tools, except '''TrenchBroomBFG'''
|- 
| {{doom3|4}} (Valve220) || '''TrenchBroomBFG''' || Variant of Doom 3 format with Valve220-style UVs for standard brushes.<br>Introduced by [https://github.com/RobertBeckebans/TrenchBroomBFG TrenchbroomBFG]; not standard.
|-
| {{src|4}} (Valve400) || None || Variant of Quake I Valve220 format with support for [[displacement]]s.
|-
| {{w|Doom Eternal}} || '''[https://idstudio.idsoftware.com/ idStudio]''' || Variant of Doom 3 brush primitives format with additional metadata ([https://github.com/jmarshall23/Doom3ToDoomEternalConverter Converter]).
|}

== Entities ==
{{stub}}
=== KeyValues ===
== Geometry ==
=== Brushes ===
In most versions of the format, brushes are stored as a set of ''[[plane]]s'', rather than a set of [[vertex|vertices]]. Each plane is defined via three points, and the intersection of these planes determines where edges and vertices lay. Due to this, brushes cannot be concave, and a missing face will result in other faces continuing infinitely, causing compiler errors.
==== Quake I ====
A simple 6-sided brush in the original Quake 1 format would look like this:
<pre>
{
    ( -16 -64 -16 ) ( -16 -63 -16 ) ( -16 -64 -15 ) mmetal1_2 -0 -0 -0 1 1
    ( -64 -16 -16 ) ( -64 -16 -15 ) ( -63 -16 -16 ) mmetal1_2 -0 -0 -0 1 1
    ( -64 -64 -16 ) ( -63 -64 -16 ) ( -64 -63 -16 ) mmetal1_2 0 0 0 1 1
    ( 64 64 16 ) ( 64 65 16 ) ( 65 64 16 ) mmetal1_2 0 0 0 1 1
    ( 64 16 16 ) ( 65 16 16 ) ( 64 16 17 ) mmetal1_2 -0 -0 -0 1 1
    ( 16 64 16 ) ( 16 64 17 ) ( 16 65 16 ) mmetal1_2 -0 -0 -0 1 1
}
</pre>

Each plane can be summed up like so:
<pre>
( x1 y1 z1 ) ( x2 y2 z2 ) ( x3 y3 z3 ) TEXTURENAME Uoffset Voffset rotation Uscale Vscale
</pre>

* {{code|( x1 y1 z1 ) ( x2 y2 z2 ) ( x3 y3 z3 )}} is the set of three points in 3D space that define the plane.
* {{code|TEXTURENAME}} is the name of the [[texture]] (or in later engines, the [[material]]) that appears on the face. This is case insensitive, and never includes a file extension.
* {{code|Uoffset Voffset}} offsets the UV coordinates of the plane, resulting in shifting the texture on the U and/or V axis. These are projected onto the face using axial projection.
* {{code|rotation}} stores the rotation of the texture.
* {{code|Uscale Vscale}} stores the texture scale. 1 means the texture is displayed at 1 texel per quake unit.

{{note|The original Quake I compilers only supported integer coordinates, but most forks and all subsequent compilers support floating point coordinates in addition to integer coordinates. Nonetheless, it is preferable to only store brushes using floating point when necessary, to avoid floating point precision loss errors. This is less important for point entities, which cause fewer issues when off-grid.}}

==== Valve220 ====
The original Quake MAP format uses axial projection to apply textures onto faces. This results in undesirably stretched textures on slanted surfaces. To rectify this, Valve came up with the Valve220 format, which stores the texture offsets as 1-dimensional arrays, instead of singular numbers, as so:
<pre>
( x1 y1 z1 ) ( x2 y2 z2 ) ( x3 y3 z3 ) TEXTURENAME [ Ux Uy Uz Uoffset ] [ Vx Vy Vz Voffset ] rotation Uscale Vscale
</pre>
* The first three values of each texture offset array are the normal vectors of the U and V axes.
* The third value is the offset itself, like the axial projection format.
{{modernImportant|In Valve220 projection, the {{code|rotation}} value should match the orientation of the UV normal vectors. Not doing so will result in editor bugs, compiler errors, and/or invalid brushes!}}

A simple 6-sided brush in the Quake 1 format using Valve220 projection would look like this:
<pre>
{
    ( -16 -64 -16 ) ( -16 -63 -16 ) ( -16 -64 -15 ) mmetal1_2 [ 0 -1 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
    ( -64 -16 -16 ) ( -64 -16 -15 ) ( -63 -16 -16 ) mmetal1_2 [ 1 0 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
    ( -64 -64 -16 ) ( -63 -64 -16 ) ( -64 -63 -16 ) mmetal1_2 [ -1 0 0 0 ] [ 0 -1 0 0 ] 0 1 1
    ( 64 64 16 ) ( 64 65 16 ) ( 65 64 16 ) mmetal1_2 [ 1 0 0 0 ] [ 0 -1 0 0 ] 0 1 1
    ( 64 16 16 ) ( 65 16 16 ) ( 64 16 17 ) mmetal1_2 [ -1 0 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
    ( 16 64 16 ) ( 16 64 17 ) ( 16 65 16 ) mmetal1_2 [ 0 1 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
}
</pre>

The Valve220 format was introduced for Half-Life, and is required for GoldSrc compilers. Since the BSP format used by all IdTech engine games store UV coordinates that are at least as accurate as Valve220 (and sometimes moreso), the Valve220 format has mostly supplanted the legacy axial projection format by mappers, as many modern compilers for IdTech engines support Valve220.

The {{ent|worldspawn}} [[keyvalue]] pair {{code|"mapversion" "220"}} indicates that a MAP file uses Valve220 texture projection. Map converters and decompilers that output to Valve220 should add the KV if it is not already present.

==== Quake II ====
Quake II's format optionally allows for three additional values to be stored as the 
<pre>
( x1 y1 z1 ) ( x2 y2 z2 ) ( x3 y3 z3 ) path/texturename Uoffset Voffset rotation Uscale Vscale SurfaceFlag ContentsFlag Value
</pre>
These represent the same values as in a [[WAL]] file, and are stored as Base 10 integers (unlike in code, where they are usually declared in hexadecimal form). These values are optional, however. If not present, the compilers will use the values stored in the WALs themselves.
{{note|Due to Quake II storing its textures as separate files (usually packed inside a [[PAK]]) instead of combined into [[WAD]]s, the path to the texture is stored. The Quake I map format technically supports storing the path, but this isn't used due to to WADs not having subdirectories.}}
A brush in the original Quake II format could look like this: 
{{todo|Insert example here}}

{{jack|4}} introduced a modified version of the format which uses Valve220 notation, as such:
<pre>
( x1 y1 z1 ) ( x2 y2 z2 ) ( x3 y3 z3 ) path/texturename [ Ux Uy Uz Uoffset ] [ Vx Vy Vz Voffset ] rotation Uscale Vscale SurfaceFlag ContentsFlag Value
</pre>
A brush in this modified version of the format could therefore look like this:
{{todo|inset example here}}
Most modern editors (ex: {{jack}}{{trenchbroom}}{{nrc}}) and compilers ([[ericw-tools]], [https://cdn.discordapp.com/attachments/360596986392739840/1140802047181070508/kmqbsp_114_test10.zip KMBSP 1.14], [https://github.com/qbism/q2tools-220 q2tools220]) support this modified format.

Since the Quake II MAP format is largely unchanged from the Quake I format, it can be converted to the older format without losing any geometry by simply stripping the extra flags. This can be done either with [[ericw-tools]] ({{code|maputil.exe --strip_extended_info input.map}}) or by opening the file in {{jack|4.1}} using a game profile configured for the Quake I/Hexen II or Half-Life/TFC "Map Type". It is not necessary to do any conversions to go from Quake I to Quake II.
{{note|Due to Quake II textures being stored as separate files in folders, it will be necessary to batch remove the preceding path from the texture string if porting to Quake I or GoldSrc. Additionally, any textures with names longer than 15 characters will need to be renamed.<br>If using the Quake I format as an intermediary for porting to Source, these additional steps are not necessary.}}

==== Brush primitives ====
{{gtkr|4}} and its forks allow storing brushes as "brush primitives" ({{mono|brushdef}}) instead of standard brushes. This method allows for more control over brush texture alignment than standard brushes. Additionally, unlike standard brushes, the texture UVs of brush primitives are normalized to a 0 to 1 range, so texture scale is independent of texture resolution.

A map can be converted between standard brushes and brush primitives using maputil from [[ericw-tools]]. To convert to brush primitives:
: {{codeblock|maputil.exe --convert bp input.map}}
To convert to regular brushes, using Valve220 texture projection:
: {{codeblock|maputil.exe --convert valve input.map}}
Note that conversion requires the tools to be able to access the textures to properly convert UV coordinates; if maputil cannot find a given texture, it will assume a 64x64 resolution. If a map makes use of textures from [[PK3]] files or materials from {{mono|.shader}} files that don't match the name of a texture, it may be preferable to use {{nrc|4}} to convert the map instead{{how}}, to preserve proper UV coordinates.

=== Patch meshes ===
{{stub}}
Patch meshes are stored in the MAP file as a set of {{w|Bézier curve|Bézier curves}}, which dictate how the mesh is automatically tessellated at runtime.

=== Displacements ===
{{stub}}
MAP files can store {{src|nt=0|2}} [[displacements]]{{how}}, as [[VBSP]] still supports for compiling MAP files. The "mapversion" keyvalue should be 400. Some forks of Q3Map2 also support compiling these displacements into {{quake3|2}} BSPs.

== See also ==
* [[VERC/MAP file format]] - casual explanation of the Quake 1 Valve220 MAP format
* [[VMF]]
* [[RMF]]

== External links ==
* {{quakewiki|Quake Map Format}}
* [https://quark.sourceforge.io/infobase/src.topics.html Quark Documentation] - Discusses the way the MAP file format stores brush faces and Bézier curves 

[[Category:File formats]]