//---------------------------------------------------------------------------
/**
 ** EFMap 2.0 - Level compiler for ST:V-EF
 **
 ** $File:        efmap2.html
 ** $Designer:    Bluehair <bluehair@libertysurf.fr>$
 ** $Date (US):   07-20-2002$
 ** $Revision:    08-29-2002$
 **
 **/
//---------------------------------------------------------------------------
/*
 * $Description : documentation$
 *
 */
//---------------------------------------------------------------------------
 Description

Here are the files included in the zip file (EFMap2-Final.zip):

    - ./doc/efmap2.html (this file)
    - q3map.exe (new EF map compiler; will replace your current q3map.exe)
    - glib-1.3.dll (10/26/2001); should be the same that comes with your GtkRadiant (1.2.7 for me)
    - iconv.dll (10/26/2001); same story as above
    - ./misc/EF.qe4.txt (default project file for EFRadiant with EFMap Console support)
    - ./misc/user0.qe4 (the project file I used with GtkRadiant 1.2.7 for regular EF maps)
    - ./misc/user0 (for a mod).qe4 (the "user0.qe4" file I am using with GtkRadiant 1.2.7 for my mod "uss_eisen")

The DLLs are just provided in case you don't own GtkRadiant. In such a situation, put them where you will put this
q3map.exe (see "Installation Instruction" for that). This q3map2 does no longer require libxml2: it has been compiled with it.

 Introduction

EFMap is a q3map.exe suitable for compiling EF maps under the latest releases of GtkRadiant (1.2.x). However, it still keeps a full compatibility with Q3A & RTCW. The core engine is based on a stable release of Ydnar's q3map2 that I have heavily customised (Windows look & feel now, but console mode still available) & somewhat optimized (variable & memory optimizations + some stuff here & there) in addition to have powered it with complete EF support. Q3A is the default game supported by this compiler, so you will be noticed every time you use it which configuration is actived:

picx/dos_screen.png

 Installation instructions

This is quite easy:

>>> EFRadiant <<<

picx/efradiant.jpg

..... Put q3map.exe + the dlls where is efradiant.exe; it will replace the existing one
..... Edit your EF.qe4 project file and add this entry:    "bsp EFMap Console" "!__QERPATH\q3map -con"

For your convenience, I have included a default .qe4 file with this entry in the zip.


>>> GtkRadiant <<<

picx/gtkradiant127-1.jpg

picx/gtkradiant127-2.png

..... Put q3map.exe + the dlls where is GtkRadiant-1.2.7-update.exe (or any other for an other version). This is important in order to EFMap to use suitably its various auto-setting files (i.e. EFMap.cmd, EFMap.fld, EFMap.mpf, EFMap.ofn). Normally, with GtkRadiant, q3map.exe is not in the same directory as its executable file. Because of this, you will have to edit your UserX.qe4 project file so GtkRadiant will know where is this q3map2.

..... Edit your UserX.qe4 project file and add this entry:
        "bsp_EFMap Console" "!__QERPATH\q3map -con" (do not forget the '_' after 'bsp')

For your convenience, I have included my own project file in the zip.

 Switch documentation

No bla bla, just visuals...

1/. EFMap main screen

picx/main_help.png

2/. BSP help screen

picx/bsp_help.png

3/. VIS help screen
picx/vis_help.png
 
4/. LIGHT help screen

picx/light_help.png

 Known problems

1/. When using the "EFMap Console", you may encounter from time to time - especially if you own a low end system - this error message: "Not enough memory to run q3map.exe" between the console relaunches. Actually, this is because of the way I have implemented the console in the existing code: I did not want to alter this one that much and this is the side effect... But that does happen that often.

2/. Normally, the "EFMap Console" automatically adds "-game ef" to your command-line (except if you have already typed it in). I have forgotten to make it add when "-fs_game" was used. So, if you use this general switch, you will be required to add yourself "-game ef" in your command-line; if not, this q3map2 will compile your map for Q3A, and you will get "WARNING: Missin shader texture...". Add it like in this pic:

picx/typical_cmdline.png

 Some useful references

You may have already encountered some errors related to variables beginning with "MAX_". These happen when you have too many of something in your map. This is below the values associated to those global variables & that are supported by this q3map2:

picx/max_values.png

Note that the memory allocated by q3map2 (below 30Mb for this one) is highly dependant of these values. I may, in a future release of this compiler, if you want, let you adjust these values to your needs; the main benefit of this is that you will be able to control thoroughly the amount of memory allocated by the compiler.

Below are some misc values you may find convenient to know:
picx/misc_values.png
 The bottom line

I did my best for this program. Some bugs may have escaped to my attention, but I got so much headaches worrying about them that they are likely not numerous now :) The most tricky part for me was to program the code behind the edit box control; I think I eventually succeeded in this task.

Just 1 statistic:

Compilation of "borg1.map" (3.44Mb) on a PIII-450/224Mb RAM (but tiny HDD):
    - BSP: about 4'30 (and 2'30 with -nopatchfix -notjunc -nosubdivide)
    - VIS -fast -merge -nopassage -nosort: about 4'30
    - LIGHT -fast -cheap -cheapgrid: almost 10'
    -----------------------------------------------------------------------
    So about 19' in all; not so bad for such a big map :) And it looks good
    in the game.

Advice: if you know that you will be short of memory for compiling a map, be sure to make use of performance switches over quality ones. For instance, I tried to VIS compile the above map with no switch. I saw on the screen that 94Mb were required for passage memory. At the end, I got a safe_malloc error (memory allocation) and my computer suddenly crashed. At this moment, RAMpage (see below) displayed 0Mb available... So, beware because this error did occur only after 5' of VIS!

PS: The memory problem - I tried out many configurations to optimize it. Well, I eventually made a flushing function for BSP & an other for VIS which are explicitly called at the end of BSP & VIS processes. Ydnar's q3map2 did not free the memory allocated for VIS; there was one for BSP but apparently it remained uncalled.

In addition, I use the dynamic memory managerRAMpage 1.6(freeware) whom I order to "Free memory automatically when RAM falls to, or below 35Mb". 35 because q3map2 allocates around 25Mb on startup. If you have such problems, you should test this.
There it is! Enjoy this build of Ydnar's q3map2. Bye!