reflex2q3/docs/doc-map-parsing.txt

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