diff --git a/docs/doc-map-parsing.txt b/docs/doc-map-parsing.txt new file mode 100644 index 0000000..dcf1406 --- /dev/null +++ b/docs/doc-map-parsing.txt @@ -0,0 +1,82 @@ + +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 diff --git a/docs/doc-overview.txt b/docs/doc-overview.txt new file mode 100644 index 0000000..dac6f1e --- /dev/null +++ b/docs/doc-overview.txt @@ -0,0 +1,118 @@ +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. Meaning 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 entity conversion + + - Added test cases to verify correctness of operations pre-commit. diff --git a/reflex-mapping.txt b/docs/reflex-mapping.txt similarity index 100% rename from reflex-mapping.txt rename to docs/reflex-mapping.txt