This document describes the DETLEF server format, as used by Descent Manager DETLEF32.

These specifications were defined and written by Heiko Herrmann. Thanks a lot to Jeff "ZappaFan" Guynn for the great support.

Get Descent Manager DETLEF32 client software
Go to *.DET specs for advanced level information on DETLEF server sites
Support for DETLEF servers

A DETLEF server provides several (text) data files for the DETLEF client application plus a logo file. These files can be anywhere on a HTTP or FTP server, but of course the client application has to know the location. For Descent Level Network this is the directory http://www.descent2.com/levels/detlef/ . Although not necessary it is recommended to put these files -as we do- in an own directory, like /detlef. Please note, that these files do not need to be on the same server as the level files. You can even switch protocols here (DETLEF on HTTP, the levels on FTP) and you can spread your level files on several servers.

The client application now downloads these files (the logo will only be loaded if needed) which contain the main information for each level available on the server. The search query etc. is made by the client application using these files, the DETLEF server has nothing to do with the search itself. This also means, that after these files are downloaded, the search query can be made off-line as long as you don't do an advanced search query.

Advanced search queries however need additional files. These files have the extension .DET, standing for DETLEF or also DETails. This file has to be in the download directory with the levels, not the DETLEF directory. However a DET file is not necessary, the client application will just ignore levels that contain no DET file. (These just cannot be queried, when doing Advanced search queries.) The DET files will be downloaded then, when an advanced search query was initiated. To speed the thing up, only those files are actually downloaded, that match non-advanced search settings. So if you want to search for D2 anarchy levels by "Luke Schneider", newer than 100 days, that contain 0 earthshakers, then only the DET files will be downloaded, that are actually D2 anarchy levels by Luke Schneider, newer than 100 days. This pre-search is made using the main DETLEF files. Also DET files are cached. So the next time the client application needs a specific DET file, that is already downloaded, it uses the cache copy. Of course this option can be turned off and also you can delete the current cache at any time in the client application.

Summary: The DETLEF server does not need any special requirements. It just must be able to get HTTP or FTP files. Not more. So you don't need any Java, CGI or FrontPage rights on your server...

The DETLEF 02 file format is an extension of the original DETLEF 01 file format, adding new features. Both specs are combined on this page. As soon as something DETLEF 01 or 02 specific comes up it will be enclosed by lines looking like this:

Note that only DETLEF Beta 02 clients and higher are able to read DETLEF 02 files. DETLEF 01 files can be read by all versions of DETLEF.

The detlef.inf file uses the common Windows-INI-format. Please note that all caption-names and keywords are case-sensitive! Here is the description of the sections:

Note: DETLEF Beta 02 and higher clients can both read from both DETLEF 01 and DETLEF 02 servers, while DETLEF Beta 01-01d clients can only read from DETLEF 01 sites.

These lines define the command-line to launch for extracting files, in dependancy of the file extension. %f stands for the file including the path. Please note that the dearchiver needs to be in the [DETLEF32]\UNPACK directory, and the DETLEF32 client application only installs PKUNZIP and RAR there. So if you want to use a different one, you need to let the user install it in that directory, OR ask us to include it next time.

As you might see we use RAR to extract EXE files. Of course we could use "exe=%f" also, but this way a virus can't get active...

The extension is case-sensitive, so if you upload "eXe" files, then you need to define "eXe"... Files types that are not defined here force an error when trying to download them...

Also note that you should provide all switches to make the unextracting automatic - deactivate all user inputs etc. . In our example we use "-c-" switch for RAR to skip our comments we display for every download. Don't forget: DETLEF32 is easily able to download and install 2000 missions, and you wouldn't want it as user to press 2000x a key, do ya ;)?

This section provides information about you and your web-server. Enter your name at "WebAdmin", the name of your homepage at "Name", your direct URL to the homepage at "Homepage" and your eMail-adress at "eMail". Please note, that you don't need to specify the page which contains actually the levels you provide. The information here is only used with the menu commands "View informations about the site", "Visit homepage" and "eMail web admin" with your server active.

Very important is the "ShortName" key: Here you specify which sub-directory will be used for list, cache and query files for your server. Let's say someone has installed DETLEF32 to its default dir: C:\DMTOOLS\DETLEF32! Now if you have set "ShortName=XYZ", the files will be saved into the directory C:\DMTOOLS\DETLEF32\SITES\XYZ for default (the user can still change it). So it is important a) to specify a directory name, that the chance is low that no other DETLEF site wants to have and b) that the name has a maximum length of 8 characters and contains no special characters like "\,./?*"!

The "Logo" key specifies the size of your logo file. It must be exact and the logo must be in the DETLEF directory with the name "detlef.jpg".

Here you can specify a short description for your web-site, that will be displayed when you click on "View informations of site" in the "Sites" menu. You can specify up to 65535 characters here (including spaces and carriage returns).

You can also provide a logo. Name it "detlef.jpg" and put it in your DETLEF directory. The logo has to be of size 400x100, so you might first need to resize it to that size.

The files detlef.d1a to detlef.d2d contain the complete URL of each level to download. As these URLs will most time start with the same characters (the server name + the directory), using alias numbers will make these files much smaller and faster to download. You can define up to 10 aliases.

Example:

• Assume that all your levels are in the directory "http://www.myserver.com/mydirectory/levels".
• Set the alias "2" to "http://www.myserver.com/mydirectory/levels"
• So the complete name for crazyx.zip would be "http://www.myserver.com/mydirectory/levels/crazyx.zip"
• Instead of that you can then write "2/crazyx.zip" at the URL of this level.

Another advantage of using aliases is, that when you switch servers later the only things you have to update are the alias names.

However you are not forced to use Alias names...

As you can also see in the example, values that you don't know (like author name or the release date), can be just left out, by writing another comma directly after the previous one.

Important: the dates must be specified in the form MM/DD/YYYY. So "05/04/1997" would mean the 4th of May, 1997. Invalid values would be "5/4/1997", "05-04-1997", 04.05.1997" and "05/04/97".

Icon Attributes:

Feature Attributes:

You can specify up to about 2.000.000.000 missions, so you don't need to pay attention on letting the list grow too big :)...

DET files are used for extended level information (like the lists of available weapons) and for advanced search queries, like "search all missions with 0 earthshakers and at least 4 anarchy player-starts". DET files have to be in the same directory as the level download file and has to have the same filename. For example crazyx.zip would have a crazyx.det (warning: case-sensitive!) in the same directory. Each mission has its own DET file. In multi-level-missions contain the sum of each item in the levels (so if 2-level-mission has 2 afterburners in level 1 and 1 afterburner in level 2, the value of afterburners would be "3").

DET files are not needed for a DETLEF server. You do not need to support the advanced search queries. You can even decide that some levels have DET files and some not. An example would be letting all Archives levels have no DET file. All levels that do not contain a DET file are simply excluded from advanced search queries.

DET files are automatically made by the LVLREP and soon also LVLREP32 modules of the Descent Manager. For the DOS version LVLREP you need V1.0 Alpha 01 Build 03 or higher, as available with the DETLEF Server Tools. To make DET files specify the /DET switch. For example LVLREP /DET *.MN2 will make DET files for all missions in the current directory. Then just upload the DET files into the directory with your level downloads to enable this feature.

Go to *.DET specs for advanced level information on DETLEF server sites

The recently released Beta 04 of the DETLEF32-client adds some new features, which for which however support from the server-side must be added. It is not required to add support for them on your website, so you can decide yourself, which of them you want to support, and which not.

• List caching
  Updating the mission lists from a server does take some time, updating the lists from all registered servers at once does take a long time. So wouldn't it be good to only let the client download the whole lists from your server if something has changed at all since his last update? DETLEF Beta 04 and higher does this by checking the values in the DETLEF.INF file under [CacheLists]. Each game gets an own entry named "LastUpdate_D1" for D1, "LastUpdate_D2" for D2, and so on. The trick is the following: If the value for a LastUpdate_** key is the same in both the previously downloaded (locally cached) INF file and the just downloaded INF file from the server (the INF file will be downloaded in any case!) this game will be completely skipped. So add the following to your DETLEF.INF:
  
  [CacheLists]
  LastUpdate_D1=1
  LastUpdate_D2=1
  LastUpdate_D3=1
  LastUpdate_F1=1
  LastUpdate_F2=1
  
  Now every time you update one or more lists or the game definition file of a game, increment the value of the appropriate LastUpdate_** key. Alternatively to just numbers you can use the date of the last change or anything else (you are not limited to numerical characters either, you can use any string you want). Just make sure it *changes* each time you change a list to a new value. Note: if either the local version or the online version contains an empty value or does not exist, this feature is turned off for this game or the whole site and the lists are *always* completely downloaded. So you can always turn this feature off on your site if you see later that it takes too much time for you or you forget too often to update it. However you should never forget that this feature can save a lot of time and nerves on the client side and you want that people browse your site often, don't ya :)?

• Compressed Lists
  The above feature lets you minimize the amount of unneccessary list downloads. It however does not speed up when an update happens on the lists (at least not for the one game whose lists were updated). And the first startup list download for a new DETLEF client user still takes a lot of time. This is what the new "Compressed Lists" feature takes care of. The server can provide a compressed file for each game that contains the game definition file (e.g. detlef.d3) and all of its list files (e.g. detlef.d3a to detlef.d3e). This will not only halve the number of downloaded bytes for the lists, it will also speed it up some more since e.g. 5 files of 10 kB take a lot more download over a network than one 50 kB file (because of the file request header overhead).
  
  To support this, all you have to do is to a) add the following to your INF file: [CompressedLists]
  D1=pd1
  D2=pd2
  D3=pd3
  F1=pf1
  F2=n/a
  
  (we have "n/a" for F2, since we don't have F2 missions and lists for now) and b) pack the d1, d1a, d1b, ... files in detlef.pd1, etc. using WinRAR. Note: the contra of this feature is that you will have to update both the list files and the compressed file(s) where a change occured each time you update your lists. So again you may want to evaluate if you want to take this little extra time to provide your visitors some service... You can always take the [CompressedLists] off of your INF file later again, if you decide to not support it any more.

• Installation Points
  While the new features above improve the update speed, this last new feature adds something to the ease of installation of special missions and MODs. Normally DETLEF downloads missions and installs all downloaded missions to a pre-defined installation directory, which is for example the MISSIONS subdirectory in Descent 2 and 3. However some missions/MODs need to be installed somewhere else, e.g. a MOD might be installed right into the games' root dir or one of the other subdirectories of the game. You can now specify for each mission you provide where DETLEF shall extract the files to. Alternatively you can tell DETLEF to not extract the files but to launch them instead after download, like self-extracting EXEcutables that contain a Setup routine which is needed to install the mission/MOD.
  
  Add a new section [Install] to your game definition file, e.g. detlef.d2 for Descent 2. Now list up every mission that needs to be handled specially in the format \={,,...}. For example: d2c\EAF2=OPERATION_EXECUTE lets the mission EAF2 in the list detlef.d2c be installed by just executing the file eaf2.exe. Here is a parameter description: can be * to include all missions in a specific list (e.g. "d3e\*=OPERATION_EXTRACT,$gamerootdir\NETGAMES"). can be OPERATION_EXTRACT for normal extraction the old-style (2nd parameter is the directory then, where $gamerootdir stands for the games' root dir, so that $gamerootdir\MISSIONS for example specifies the MISSIONS subdir of the game), OPERATION_EXECUTE to start the downloaded EXE file (2nd parameters can be command-line switches to be posted to the application) or OPERATION_COMMAND which call a command (2nd parameter, use %f in the command as the variable to be replaced by the mission download file). Also note that *= specifies the default operation for all other missions, which you only need to override if you don't want the hard-coded default (which is MISSIONS dir for D2/D3 and the game's root dir for D1/F1/F2).