quake 3场景源码分析

原文

http://www.mralligator.com/q3/#Leaffaces

Unofficial Quake 3 Map Specs

Introduction [top]

This document describes the Quake 3 BSP file format. This is an unofficialdocument. Quake 3 is a registered trademark of id Software, which does not sponsor,authorize, or endorse this document.

This document describes the Quake 3 BSP file format as the authorunderstands it. While every effort has been made to ensure that thecontents of this document are accurate, the author does not guarantee thatany portion of this document is actually correct. In addition, the authorcannot be held responsible the consequences of the any use or misuse of theinformation contained in this document.

Copyright © 2000 Kekoa Proudfoot. All rightsreserved.

Description [top]

File structure

Quake 3 BSP files are IBSP files, and therefore have a structure similar toprevious BSP files from id Software. Every IBSP file begins with a header,which in turn contains a lump directory. The lump directory describes thelayout of the rest of the file, which contains some number of lumps. Eachlump stores a particular kind of map data.

Header / Directory Lump Lump Lump ...

The layout of an IBSP file. An IBSP fileconsists of a header followed by a number of lumps. The header contains adirectory which identifies the locations and sizes of the lumps.

Data types

Quake 3 BSP files contains only four basic data types. They are:

Type	Description
ubyte	unsigned byte
int	4-byte integer, little-endian
float	4-byte IEEE float, little-endian
string[n]	string of n ASCII bytes, not necessarily null-terminated

All data in a BSP file is organized into records composed of these four datatypes.

Header and Directory

The header record looks like this:

header

string[4] magic	Magic number. Always "IBSP".
int version	Version number. 0x2e for the BSP files distributed with Quake 3.
direntry[17] direntries	Lump directory, seventeen entries.

Each direntry locates a single lump in the BSP file:

direntry

int offset	Offset to start of lump, relative to beginning of file.
int length	Length of lump. Always a multiple of 4.

Lumps

There are 17 lumps in a Quake 3 BSP file. In the order that theyappear in the lump directory, they are:

Index	Lump Name	Description
0	Entities	Game-related object descriptions.
1	Textures	Surface descriptions.
2	Planes	Planes used by map geometry.
3	Nodes	BSP tree nodes.
4	Leafs	BSP tree leaves.
5	Leaffaces	Lists of face indices, one list per leaf.
6	Leafbrushes	Lists of brush indices, one list per leaf.
7	Models	Descriptions of rigid world geometry in map.
8	Brushes	Convex polyhedra used to describe solid space.
9	Brushsides	Brush surfaces.
10	Vertexes	Vertices used to describe faces.
11	Meshverts	Lists of offsets, one list per mesh.
12	Effects	List of special map effects.
13	Faces	Surface geometry.
14	Lightmaps	Packed lightmap data.
15	Lightvols	Local illumination data.
16	Visdata	Cluster-cluster visibility data.

Entities

The entities lump stores game-related map information, includinginformation about the map name, weapons, health, armor, triggers, spawnpoints, lights, and .md3 models to be placed in the map. The lump containsonly one record, a string that describes all of the entities:

entities

string[length] ents

Entity descriptions, stored as a string.

The length of the entity string is given by the size of the lumpitself, as specified in the lump directory.

The meanings, formats, and parameters of the various entity descriptionsare currently outside the scope of this document. For more informationabout entity descriptions, see the documentation to Q3Radiant, the Quake 3level editor.

Textures

The textures lump stores information about surfaces and volumes, which arein turn associated with faces, brushes, and brushsides. There are a totalof length / sizeof(texture) records in the lump, wherelength is the size of the lump itself, as specified in the lumpdirectory.

texture

string[64] name	Texture name.
int flags	Surface flags.
int contents	Content flags.

Planes

The planes lump stores a generic set of planes that are in turn referencedby nodes and brushsides. There are a total of length /sizeof(plane) records in the lump, where length is the sizeof the lump itself, as specified in the lump directory.

plane

float[3] normal	Plane normal.
float dist	Distance from origin to plane along normal.

Note that planes are paired. The pair of planes withindices i and i ^ 1 are coincident planes with opposing normals.

Nodes

The nodes lump stores all of the nodes in the map's BSP tree. The BSP treeis used primarily as a spatial subdivision scheme, dividing the world intoconvex regions called leafs. The first node in the lump is the tree's rootnode. There are a total of length / sizeof(node) recordsin the lump, where length is the size of the lump itself, asspecified in the lump directory.

node

int plane	Plane index.
int[2] children	Children indices. Negative numbers are leaf indices: -(leaf+1).
int[3] mins	Integer bounding box min coord.
int[3] maxs	Integer bounding box max coord.

Leafs

The leafs lump stores the leaves of the map's BSP tree. Each leaf is aconvex region that contains, among other things, a cluster index (fordetermining the other leafs potentially visible from within the leaf), alist of faces (for rendering), and a list of brushes (for collisiondetection). There are a total of length / sizeof(leaf)records in the lump, where length is the size of the lump itself,as specified in the lump directory.

leaf

int cluster	Visdata cluster index.
int area	Areaportal area.
int[3] mins	Integer bounding box min coord.
int[3] maxs	Integer bounding box max coord.
int leafface	First leafface for leaf.
int n_leaffaces	Number of leaffaces for leaf.
int leafbrush	First leafbrush for leaf.
int n_leafbrushes	Number of leafbrushes for leaf.

If cluster is negative, the leaf is outside the map or otherwiseinvalid.

Leaffaces

The leaffaces lump stores lists of face indices, with one list per leaf.There are a total of length / sizeof(leafface) records inthe lump, where length is the size of the lump itself, asspecified in the lump directory.

leafface

int face

Face index.

Leafbrushes

The leafbrushes lump stores lists of brush indices, with one list per leaf.There are a total of length / sizeof(leafbrush) records inthe lump, where length is the size of the lump itself, asspecified in the lump directory.

leafbrush

int brush

Brush index.

Models

The models lump describes rigid groups of world geometry. The first modelcorreponds to the base portion of the map while the remaining modelscorrespond to movable portions of the map, such as the map's doors,platforms, and buttons. Each model has a list of faces and list ofbrushes; these are especially important for the movable parts of the map,which (unlike the base portion of the map) do not have BSP trees associatedwith them. There are a total of length / sizeof(models)records in the lump, where length is the size of the lump itself,as specified in the lump directory.

model

float[3] mins	Bounding box min coord.
float[3] maxs	Bounding box max coord.
int face	First face for model.
int n_faces	Number of faces for model.
int brush	First brush for model.
int n_brushes	Number of brushes for model.

Brushes

The brushes lump stores a set of brushes, which are in turn used forcollision detection. Each brush describes a convex volume as defined byits surrounding surfaces. There are a total of length /sizeof(brushes) records in the lump, where length is thesize of the lump itself, as specified in the lump directory.

brush

int brushside	First brushside for brush.
int n_brushsides	Number of brushsides for brush.
int texture	Texture index.

Brushsides

The brushsides lump stores descriptions of brush bounding surfaces. Thereare a total of length / sizeof(brushsides) records in thelump, where length is the size of the lump itself, as specified inthe lump directory.

brushside

int plane	Plane index.
int texture	Texture index.

Vertexes

The vertexes lump stores lists of vertices used to describe faces. Thereare a total of length / sizeof(vertex) records in the lump,where length is the size of the lump itself, as specified in thelump directory.

vertex

float[3] position	Vertex position.
float[2][2] texcoord	Vertex texture coordinates. 0=surface, 1=lightmap.
float[3] normal	Vertex normal.
ubyte[4] color	Vertex color. RGBA.

Meshverts

The meshverts lump stores lists of vertex offsets, used to describegeneralized triangle meshes. There are a total of length /sizeof(meshvert) records in the lump, where length is thesize of the lump itself, as specified in the lump directory.

meshvert

int offset

Vertex index offset, relative to first vertex ofcorresponding face.

Effects

The effects lump stores references to volumetric shaders (typically fog)which affect the rendering of a particular group of faces. There are atotal of length / sizeof(effect) records in the lump,where length is the size of the lump itself, as specified in thelump directory.

effect

string[64] name	Effect shader.
int brush	Brush that generated this effect.
int unknown	Always 5, except in q3dm8, which has one effect with -1.

Faces

The faces lump stores information used to render the surfaces of the map.There are a total of length / sizeof(faces) records in thelump, where length is the size of the lump itself, as specified inthe lump directory.

face

int texture	Texture index.
int effect	Index into lump 12 (Effects), or -1.
int type	Face type. 1=polygon, 2=patch, 3=mesh, 4=billboard
int vertex	Index of first vertex.
int n_vertexes	Number of vertices.
int meshvert	Index of first meshvert.
int n_meshverts	Number of meshverts.
int lm_index	Lightmap index.
int[2] lm_start	Corner of this face's lightmap image in lightmap.
int[2] lm_size	Size of this face's lightmap image in lightmap.
float[3] lm_origin	World space origin of lightmap.
float[2][3] lm_vecs	World space lightmap s and t unit vectors.
float[3] normal	Surface normal.
int[2] size	Patch dimensions.

There are four types of faces: polygons, patches, meshes, and billboards.

Several components have different meanings depending on the face type.

For type 1 faces (polygons), vertex and n_vertexesdescribe a set of vertices that form a polygon. The set always contains aloop of vertices, and sometimes also includes an additional vertex near thecenter of the polygon. For these faces, meshvert andn_meshverts describe a valid polygon triangulation. Every threemeshverts describe a triangle. Each meshvert is an offset from the firstvertex of the face, given by vertex.

For type 2 faces (patches), vertex and n_vertexesdescribe a 2D rectangular grid of control vertices with dimensions given bysize. Within this rectangular grid, regions of 3×3 verticesrepresent biquadratic Bezier patches. Adjacent patches share a line ofthree vertices. There are a total of(size[0] - 1) / 2 by(size[1] - 1) / 2 patches. Patches in the grid start at (i, j) given by:

i = 2n, n in [ 0 .. (size[0] - 1) / 2 ), and
j = 2m, m in [ 0 .. (size[1] - 1) / 2 ).

For type 3 faces (meshes), meshvert and n_meshverts areused to describe the independent triangles that form the mesh. As withtype 1 faces, every three meshverts describe a triangle, and each meshvertis an offset from the first vertex of the face, given by vertex.

For type 4 faces (billboards), vertex describes the single vertexthat determines the location of the billboard. Billboards are used foreffects such as flares. Exactly how each billboard vertex is to beinterpreted has not been investigated.

The lm_ variables are primarily used to deal with lightmap data.A face that has a lightmap has a non-negative lm_index. For sucha face, lm_index is the index of the image in the lightmaps lumpthat contains the lighting data for the face. The data in the lightmapimage can be located using the rectangle specified by lm_start andlm_size.

For type 1 faces (polygons) only, lm_origin and lm_vecscan be used to compute the world-space positions corresponding to lightmapsamples. These positions can in turn be used to compute dynamic lightingacross the face.

None of the lm_ variables are used to compute texture coordinatesfor indexing into lightmaps. In fact, lightmap coordinates need not becomputed. Instead, lightmap coordinates are simply stored with thevertices used to describe each face.

Lightmaps

The lightmaps lump stores the light map textures used make surface lightinglook more realistic. There are a total of length /sizeof(lightmap) records in the lump, where length is thesize of the lump itself, as specified in the lump directory.

lightmap

ubyte[128][128][3] map

Lightmap color data. RGB.

Lightvols

The lightvols lump stores a uniform grid of lighting information used toilluminate non-map objects. There are a total of length /sizeof(lightvol) records in the lump, where length is thesize of the lump itself, as specified in the lump directory.

Lightvols make up a 3D grid whose dimensions are:

nx = floor(models[0].maxs[0] / 64) - ceil(models[0].mins[0] / 64) + 1
ny = floor(models[0].maxs[1] / 64) - ceil(models[0].mins[1] / 64) + 1
nz = floor(models[0].maxs[2] / 128) - ceil(models[0].mins[2] / 128) + 1

lightvol

ubyte[3] ambient	Ambient color component. RGB.
ubyte[3] directional	Directional color component. RGB.
ubyte[2] dir	Direction to light. 0=phi, 1=theta.

Visdata

The visdata lump stores bit vectors that provide cluster-to-clustervisibility information. There is exactly one visdata record, with alength equal to that specified in the lump directory.

visdata

int n_vecs	Number of vectors.
int sz_vecs	Size of each vector, in bytes.
ubyte[n_vecs * sz_vecs] vecs	Visibility data. One bit per cluster per vector.

Cluster x is visible from cluster y if the (1 << y % 8) bit ofvecs[x * sz_vecs + y / 8] is set.

Note that clusters are associated with leaves.

Known Issues and Missing Items [top]

This document is very brief. I have gathered more information, but havenot had time to write it up. Occasionally, I add more information to thisdocument.

At some point I put together a page that describes triangle meshes and other q3 leaf elements. I forgetthe exact reason I created that page, but you might find it interesting.

Feel free to ask for clarification, but please accept my apologies if Ican't find the time to answer.

---

Copyright © 2000 KekoaProudfoot. All rights reserved.

Keywords: quake 3 quake3 q3 arena quake3arena q3arena map bsp file spec specs format