reflex2q3/docs/doc-overview.txt

reflex2q3
A tool to convert Reflex Arena maps to idTech .maps for use in map editors.
Forked from chronokun's ReflexToQ3.

Features, and Responsibilities of the Program: For Mappers
    The converter is equipped with the following features:
        - Converts map geometry from Reflex
        - Converts entities such as, but not limited to
            - player spawn points
            - item pickups
            - teleporters and respective targets
            - race checkpoints

    During the conversion process, face related data (texture & color) are 
    preserved. This is both because of the differences between engines and the
    numerous games built in idTech engines. That is, the map converter does not
    attempt to retexture the map with generic idTech engine equivalents or 
    per-game equivalents. It is the individual mappers' responsibility to 
    appropriately adapt the map for the target game. Some of the following 
    tasks for mappers remain:

        - Redesigning specific map geometry so meta/gameplay tricks work.
        - Sealing leaks allowed by Reflex Arena, but illegal in idTech.
        - Texturing the map.
            * Extends to applying lava and slime effects to brushes.
        - Providing light to the map.
            * The converter handles Point Lights; however some entities and 
            textures in Reflex emit light while target game equivalents
            do not.

Program Design: For Programmers
    The program can be summarized as two distinct phases:
        1. Converting worldspawn (map geometry).
        2. Converting entities.

    These are split into two distinct phases because of the difference between
    engines. While it is acceptable for worldspawn brushes and game entites to
    be in which ever order in Reflex, worldspawn in IdTech engines must not have
    entities with in it. Entities must be handled separately after worldspawn.

    Both phases will write to the output file, the format determined by a 
    function pointer to the outputting function- the function to call being a
    "variable" determined in main. Both phases convert and write to file single 
    instance of a game object (brush or entity) at a time.

    Converting Worldspawn
        This is the phase that passes through the input file, parses Reflex's 
        .map format, and converts brushes for the idTech format.

        Functions pertaining to this phase are written to be easily changed to
        deal with either from-memory or from-file operations. For example, 
        functions for parsing brushes for the first phase will deal with input 
        and output file streams, but later in the next phase they are used to 
        deal with stringstream. If for any reason, the entire contents of the 
        input file should be stored in memory, no major rewrites are needed.

        The parsing functions for each game object (brush, faces, vertices) 
        expect and operate on the contents underneath the respective keywords.

        As the two engines are very different, entities must be converted and
        written to file at a different phase. The converter will store the 
        strings of an entity to a vector of vector of strings (STL). A vector
        was chosen because the entity converter needs to prescan the container
        for teleporters and targets. The vector permitting multiple passes FIFO
        and pass by reference; where instead STL queue is either destructive or
        requires copying the queue. 

    Converting Entities
        This is the phase that operates on the container of entity strings, 
        converts, and writes them to file. Entity names for pick up items will
        vary per target game; to easily adapt to multiple games, a plain text 
        file is used, containing Reflex map entity id's corresponding to the 
        target game entity names.

        In order to determine the teleporters and the corresponding target 
        locations, the entity container is prescanned.

Major Code Changes in Forking
    - Can be compiled for g++ and by extension mingw, and Linux systems.
        The original project was for Microsoft Visual Studio; however even
        manually compiling the source resulted in errors from syntax acceptable
        by Visual Studio, but rejected by g++.

    - Removal of ckmath, original author's custom C++ library for linear 
    algebra
        This was because the attempt to compile ckmath results in several 
        warnings and errors. Addressing the compilation errors would have 
        warranted its own tests to see if the output is unchanged. 
        This was scrapped for Eigen.

    - Addition of Reflex version 8 map parsing
        The original code had a reported Issue where it did not parse V8, the
        current format of map files for the game.

    - Addition of output to Net Radiant's brush definition
        The original code's output was the legacy brush definition used by GTK
        Radiant or older map editors.

    - Addition of converting map entities.

    - Addition of translating texture definitions.
        Previously these were kept as placeholder values.

    - Severe bug fixes
        The old converter crashed on converting Pocket Infinity, and had 
        distorted geometry for certain maps e.g Sky Temples. The main cause
        for such issues have been addressed and will not occur on maps 
        featuring similar cases.

Minor Code Changes
    - Improved memory usage

    - Added new command line arguments and robust handling of.
        -h, --help, displays help
        -gtk        switch to output to GTK's map format
        -e <FILE>   entity conversion

    - Added test cases to verify correctness of operations pre-commit.