reflex2q3/docs/doc-map-parsing.txt

83 lines
2.9 KiB
Plaintext
Raw Normal View History

oopless-parser.hpp / oopless-parser.cpp
Parses Reflex's .map file, both version 6 and version 8.
Reflex Map Format
Reflex maps are plain text files featuring keywords and indentation levels.
Reflex map keywords:
Ordered by indentation level (outer to inner).
"global"
"prefab"
"entity"
"brush"
"vertices"
"faces"
"vertices" and "faces", sharing the level, are contained in brushes.
"brush" and "entity", sharing the level are contained in prefabs.
"global" largely behaves the same as prefabs.
There are two distinct map formats from Reflex- V6 and V8.
V6 was the map format before the addition of prefabs (V8 feature).
As far as the conversion process is concerned:
'global' and 'prefab' are containers for map objects.
'entity' and 'brush' are map objects (but entity may contain a brush).
'vertices' and 'faces' are details of brushes.
Brush Data
Brushes contain faces and vertices.
A brush's faces and vertices are listed in its "faces" and "vertices".
Vertex Data
A vertex contains 3 floats representing a coordinate.
Reflex uses a right-handed coordinate system while idTech engine uses left.
Face Data
Faces contain the texture definition, indices, & the texture to be applied.
Each field in the line, being the entire face, is separated by space.
The first 5 fields are always data for the texture definition.
In order,
* texture x offset
* texture y offset
* texture x scale
* texture y scale
* texture rotation
The next fields are integers being indices for the list of vertices for
the brush.
Followed by an hex digit for the color code in sRGB to apply to the face.
Then followed by the path to the texture asset.
Parsing States
GLOBAL or PREFAB -> {BRUSH, ENTITY}
BRUSH -> {FACES, VERTICES}
VERTICES -> {FACES, BRUSH, ENTITY}
FACES -> {VERTICES, BRUSH, ENTITY, PREFAB}
ENTITY -> {ENTITY, BRUSH, PREFAB}
In all observations, VERTICES are defined before FACES.
Entities may contain brushes as a part of its data; however it is not
reflected in indentation levels in Reflex. Thus for the conversion,
brushes must be contained in the entity string, and converted in a
different phase (because the worldspawn entity in idTech excludes
entity-brushes). The parser transitions out of handling the entity when
it hits the brush keyword and the entity's type does not match is not of
a specific set of types.
Implementation Overview
Each parsing function:
- assumes by the time it is called, the respective keyword has already
been advanced past.
- retrieves the next line from the input stream
- detects next possible parsing states
- will output its respective data structure