Documentation for UT2004CacheExtractor V1.0 beta2

    Introduction         Features         Requirements         Installation         Program start         Usage         Final words         History    

Introduction

Have you ever played Unreal Tournament 2004 on the internet?
Did you see great custom maps that were downloaded automatically from a gameserver?
Did you ever wish to play such maps locally in your single player games?
Or share them with your friends on a LAN party?

Then this is the tool for you!

With UT2004CacheExtractor, you can extract maps that were downloaded when playing on the internet from your local cache directory.
You can install them into your game directory, for playing at home, and pack them into archives to give them to your friends.
Server admins may even create files in UZ2 format for uploading to their redirect servers!

Features


Requirements

The following software is required to run UT2004CacheExtractor:
Most likely, you don't need to care about any of that.

Installation

You can setup UT2004CacheExtractor in 3 easy steps, whereas only the first one is really necessary. Steps 2 and 3 are just to increase the usage comfort.
  1. Installation
    Short: Extract the downloaded UT2004CacheExtractor Zip file to a directory of your choice.
    Detailed:     Basically, all you have to do is to download UT2004CacheExtractor (with or without SWT, depending of the presence of SWT on your computer - see Requirements above) and extract it to an appropriate location on your harddrive. A directory called UT2004CacheExtractor is included in the archive and all included files are located below that directory, so you will get only one new entry in the destination directory.
    What destination directoy should you choose? You can extract the archive directly to the UT 2004 game directory, if you like. If you don't want to have it there, I'd advice the following (but you can choose any other destination you like, of course):
    Windows: C:\Programs
    Linux: Your home directory ~/ or maybe /usr/share

  2. Batch file creation (optional - will save typing work)
    If you can't start the program by simply double-clicking the file UT2004CacheExtractor.jar (usually only possible under Windows if you use the version, bundeled with SWT), I advice you to create a short batch file in the same directory where the .jar file resides.
    Short: Create a batch file in with the exact starting call in it.
    Detailed:     To save the work of typing the correct call to start UT2004CacheExtractor each time you want to use the program, you should create a batch file where you enter the call one time, so you don't need to remember and type it for later usage. A batch file is a simple text file that can be created with any text editor (type must be .txt) and contains shell commands that are executed one after the other. Here's how to do it:
    Windows: Create a new text file called UT2004CacheExtractor.bat in the directory UT2004CacheExtractor that was created when extracting the downloaded archive. In the editor, type the line that is necessary to start UT2004CacheExtractor. The exact call depends on what variant of the program you downloaded and where the SWT resides on your harddrive. For example, if you have a seperate directory for SWT, what you type could look like this:
    cd C:\Programs\UT2004CacheExtractor java -Djava.library.path=C:\SWT -cp C:\SWT -jar UT2004CacheExtractor.jar
    In this example, the archive was extracted to C:\Programs and the SWT is located in the directory C:\SWT (so it was a non bundeled download).
    Linux: Create a new text file called UT2004CacheExtractor in the directory UT2004CacheExtractor that was created when extracting the downloaded archive. In the editor, type the line that is necessary to start UT2004CacheExtractor. The exact call depends on what variant of the program you downloaded and where the SWT resides on your harddrive. Here's an example what to type if you downloaded the version, bundeled with SWT:
    #!/bin/bash

    cd ~/UT2004CacheExtractor
    java -Djava.library.path=. -jar ./UT2004CacheExtractor.jar
    In this example, the used shell is bash (modify the first line appropiately if you use another shell) and the archive was extracted to the home directory. It was a bundeled download, because the library search path is set to the program directory.
    Important: After you saved the batch file, enter the UT2004CacheExtractor directory and type "chmod 755 UT2004CacheExtractor", so the file can be executed.
    MacOS: I think, it is done similar to the Linux description. Since I have no clue about MacOS, you'll have to find out yourself. Sorry!

  3. Shortcut creation (optional - for easiest program start)
    Furthermore, you can create a shortcut on your desktop for the created batch file or the UT2004CacheExtractor.jar file itself, if it can be started by simply double-clicking.
    Windows: Use the Windows Explorer to drag the file with the right mousebutton to the desktop and select "Create shortcut here" from the context menu showing up. After that, you can start UT2004CacheExtractor by double-clicking the created shortcut on the desktop.
    Linux: Use Konqueror to drag the file with the left mousebutton to the desktop and select "Associate with file" from the context menu showing up. After that, you can start UT2004CacheExtractor by double-clicking the created shortcut on the desktop.
    MacOS: Sorry, I have no idea how to do this under MacOS. I hope, you know it yourself!

Program start

Once you have extracted the downloaded archive to the desired location, you are at the point where you might want to run the program. Depending on your Operating System and the variant of UT2004CacheExtractor that you have downloaded, this is done in slightly different ways.

  1. If you downloaded UT2004CacheExtractor, bundeled with SWT, do the following:
    Windows: Simply double-click the file UT2004CacheExtractor.jar in the UT2004CacheExtractor directory.
    Linux: In the shell, enter the UT2004CacheExtractor directory and type "java -Djava.library.path=. -jar ./UT2004CacheExtractor.jar"
    Note: A batch file called UT2004CacheExtractor with exactly this call is alreadey included in this version.
    MacOS: Try the windows method. If it doesn't work, try the Linux method. Sorry, but I don't know anyone with MacOS to test it for me!

  2. If you downloaded UT2004CacheExtractor without SWT, do the following:
    Windows: Locate the directory where SWT is installed (a file called swt.jar and some libraries (*.dll) should be inside there. Lets assume, the directory is C:\SWT here. Then open a command prompt, enter the UT2004CacheExtractor directory and type "java -Djava.library.path=C:\SWT -cp C:\SWT -jar UT2004CacheExtractor.jar"
    Linux: Locate the directory where SWT is installed (a file called swt.jar and some libraries (*.so) should be inside there. Lets assume, the directory is /opt/swt here. Then open a shell, enter the UT2004CacheExtractor directory and type "java -Djava.library.path=/opt/swt -cp /opt/swt -jar ./UT2004CacheExtractor.jar"
    MacOS: Locate the directory where SWT is installed (a file called swt.jar and some libraries (*.jnlib) should be inside there. The rest will be similar to the Linux method. Sorry, but I don't know anyone with MacOS to test it for me!

  3. Alternatively, if you want to install SWT for general usage, so any application that uses SWT (including UT2004CacheExtractor) can find it automatically without the need to specify any paths, you can do the following:
    Short: Move the file swt.jar and all library files (*.dll, *.so or *.jnlib respectively) to the ext subdirectory inside the lib subdirectory of the JRE base directory.
    Detailed:     You must move the JAR file and the libraries of SWT to the directory where your current JRE version is installed. The default location of the JRE and the names of the SWT libraries differ from OS to OS, so they are described one by one.
    Windows: The JRE typically resides in C:\Programs\Java and is called something like jre1.5.0_09 (dependant from the number of the version you have installed). Inside there, you'll find a subdiretory called lib and therein another subdirectory called ext. This is the special directory for external Java addons like SWT. You have to move the files swt.jar and all files that end with .dll (either from the SWT distribution you have downloaded from the SWT homepage [see Requirements] or from the bundeled version of UT2004CacheExtractor) to the ext directory. After that, you should be able to start UT2004CacheExtractor by simply double-clicking the file UT2004CacheExtractor.jar.
    Linux: The JRE typically resides in /usr/lib/jvm and is called something like java-1.5.0-sun-1.5.0_09 (dependant from the number of the version you have installed). Inside there, you'll find a subdiretory called lib and therein another subdirectory called ext. This is the special directory for external Java addons like SWT. You have to move the files swt.jar and all files that end with .so (either from the SWT distribution you have downloaded from the SWT homepage [see Requirements] or from the bundeled version of UT2004CacheExtractor) to the ext directory. After that, you should be able to start UT2004CacheExtractor by typing "java -jar UT2004CacheExtractor.jar" in the shell.
    MacOS: This will be similar to the method described for Linux, except that the library files end with .jnlib. Unfortunately, I have no idea where the JRE base directory is located unter MacOS. You'll have to find out yourself. Sorry!
    The tradeoff using this method is that you have to repeat the copying each time you install a new version of the JRE, since the SWT files are only loaded from the current JRE version's ext directory. So if you do it like this and some day get the error message 'Exception in thread "main" java.lang.NoClassDefFoundError: org/eclipse/swt/widgets/Layout' or a message box saying 'Could not find the main class. Program will exit.' then you hopefully remember this and know that you have to copy the described files to the ext directory of your new JRE install.

Usage

DISCLAIMER: YOU USE THIS PROGRAM AT YOUR OWN RISK! DUE TO THE NATURE OF PROGRAMMING, IT IS IMPOSSIBLE TO GUARANTEE 100% ERROR-FREE FUNCTIONALITY FOR A COMPLEX PROGRAM. ALTHOUGH GREAT CARE WAS TAKEN DURING THE DEVELOPMENT OF THIS PROGRAM AND IT HAS BEEN TESTED INTENSIVLY BY THE AUTHOR, THERE MAY STILL EXIST PROGRAM ERRORS THAT LEAD TO UNPREDICTABLE BEHAVIOR UNDER SPECIAL CIRCUMSTANCES THAT MAY NOT HAVE BEEN CONSIDERED. IN THE WORST CASE, THIS MAY LEAD TO DATA LOSS THROUGH DELETION OR CRIPPLING OF FILES OR CAUSED BY A DEADLOCK OR SPONTANEOUS RESET OF THE PC WHEN YOU CAN'T SAVE YOUR UNSAVED WORK IN OTHER APPLICATIONS. NONE OF THESE HAS HAPPENED TO THE KNOWLEDGE OF THE AUTHOR UNTIL NOW. IN FACT, THE PROGRAM IS DESIGNED TO ALTER FILES AS CAUTIOUS AS POSSIBLE (E.G. AN .INI FILE IS WRITTEN AS A DUPLICATE AND ONLY EXCHANGED WITH THE ORIGINAL IF EVERYTHING SUCCEEDED). BUT STILL, YOU MUST BE AWARE THAT ERRORS CAN HAPPEN! SINCE THIS PROGRAM CAN BE CONFIGURED TO DELETE OR OVERWRITE EXISTING FILES, ERRORS MAY LEAD TO DATA LOSS. I SAY IT AGAIN: YOU USE THIS PROGRAM AT YOUR OWN RISK! I CAN NOT BE MADE RESPONSIBLE FOR ANY DATA LOSS CAUSED BY THE USE OF THIS PROGRAM, NOR AM I LIABLE FOR ANY RESULTING FINANCIAL LOSS. BY USING THIS PROGRAM, YOU STATE THAT YOU ARE AWARE OF THE RISK AND USE IT ON YOUR OWN RESPONSIBILITY!

Really important to know, please read this:

If you don't take some care while selecting the files to extract, you may extract too many files for a map that you copy from the cache. Too many files means files that actually don't belong to the map and aren't needed to play it. This is not critical since the map will function for sure, but the redundant files will be copied to the game directory or included in archives, etc. (depending on what operation you choose) and thus waste HD space and pollute your installation of the game by the time.

Here's the explanation:
Since I don't know a method to safely check if a given file is really needed by a specific map, the method I use is the following: When connecting to an internet server for playing and files are being transfered via redirected downloading, the first files that are sent are logos, jingles, mutators and the like. Only if everything has been sent that makes the server special in any aspect, the current map file is being sent and all resources needed by the map are sent afterwards. The order of the downloads is reflected by the cache.ini file that records all files that reside in the cache. So what UT2004CacheExtractor does, is scanning the cache.ini file. When a map file is found, all succeeding files are considered to belong to this map, until a new map file is found. This works fine for one game-session. But if you connect to another server afterwards that sends special files at the beginning, too, then guess what happens? Right, these files become subsequent entries to the last map, recorded in the cache.ini. So if you start UT2004CacheExtractor after that, the files will be displayed as belonging to the last map that was downloaded from the previous game server. Only when a new map file is found after these files, the following entries are considered to belong to the new map.

What can you do to avoid redundant files?
Well, the best is to use UT2004CacheExtractor directly after a gaming session on one server, before connecting to the next. If you use it irregularly every now and then (like I do), then the best you can do is to expand the map entries that you select from the list and validate the names of the files that are considered to belong to the map. In most cases, you can easily see which files have another origin than the map that you want to extract. Further on, it is impossible that a file doesn't belong to the map and files following to this one do. The order of files is important! Simply uncheck all files that don't belong to the map in your opinion. Here is an example:

Files that have been unchecked

How can you be sure that you don't uncheck files that are really needed by the map?
Well, after (or while) extraction, you can install the map to the UT 2004 game directory. Once, it's inside there, you can open the UT 2004 map editor and load the extracted map. If there are any resources missing, you get an appropriate message. If you don't get one, everything is ok.

How to use the program:

First of all, each button has a tooltip help describing it's function or meaning. So you just need to hold the mouse over one of them to get the information. If the information disappears too quickly to read everything (that's a setting of the OS), simple hold the mouse pointer over another button for short and return to the one you're interested in. The information is then displayed again.

  1. Directory selection

    The first thing, you should do after starting UT2004CacheExtractor for the first time, is selecting the Cache directory of your UT 2004 game. It's a subdirectory of the UT 2004 main directory. Only after this, you will see the contents of your local cache. Just use the Select button to open a directory requester to choose from. But, of course, you can also type it in the appropriate text field, if you like.
    Important: Dependant on the UT 2004 game directory configuration, the UT 2004 game directory may be considered to be the parent directory of the one you select here. So if you select a copy of the Cache directory somewhere on your harddrive that is detached from the game itself, you should not choose to copy extracted files to the game directory!

    If you want to copy extracted files to another location but the UT 2004 game directory (or if you want to create archives from the extracted files), you should also select an appropriate destination directory. Simply use the Select button or type the path into the text field to do this.

  2. Modes of operation

    There are basically four things that UT2004CacheExtractor can do:

    1. Copy files from the cache directory to the game directory (installation).
      The selected files are copied to the associated subdirectories of the UT 2004 game directory. That means, map files are copied to Maps/, texture files are copied to Textures/ and so on. Already existing files are only overwritten after confirmation. After copying a map and it's appropriate files to the game directory, the map is immedately ready for playing. You may quit UT2004CacheExtractor afterwards and start the game to try it.

    2. Copy files from the cache directory to any specified destination directory (extraction).
      The selected files are copied to the destination directory that you must previously specify. You can have them grouped, according to the different maps you extract (a single directory is created for each map), create appropriate subdirectories for the different file types, just as they exist in the game directory (for easy map installation by simply copying the contents of a created map directory to the UT 2004 game directory), and create archives with an archiver of your choice (Zip, Rar, 7-Zip, etc.) that may or may not contain the described subdirectories (if they do, you can install a map by simply extracting the archive to the UT 2004 game directory). In archive form, you can easily send the extracted maps to your friends via e-mail, FTP or common instant messengers.

    3. Copy files from the cache directory to the game directory and the specified destination directory.
      This is simply a combination of the modes, described under i. and ii., at the same time. This way, you can very easy install the maps for yourself and create archives to give them to your friends, in one go.

    4. Clear selected files from the cache directory
      In this mode, you can delete all files from the cache directory that you select from the list. This may be useful if you experience any version incompatibilities with mutators stored in your cache directory. You can also simply use this mode to clean up your cache directory. This is very useful if you change the Cache Holding Time of the game itself (configurable with UT2004CacheExtractor as well), especially if you set it to unlimited (0).
      You might see a special node in the selection tree that is entitled "(files that don't belong to a map)". It appears only in this operation mode and offers you the opportunity even to clear files from the cache that are not associated with any map. Usually, these are files that were chronologically downloaded before the first map (e.g. mutators, special files for a server like logos, jingles, etc.). This way, you have complete control over the contents in your cache directory. If you choose "Select all" and start the clearing operation, your cache directory will be empty afterwards.
      Be warned! In this mode, files are being deleted irretrievably from the cache directory. So be careful what you do if you still want to use them.

  3. Options

  4. Settings

    The configured paths, the selected mode of operation, the options that you set and the window size and position are automatically saved in a simple config file when you exit the program (under Windows, it is located in the user's application data directory and under Linux and MacOS, you'll find it in the user's home directory). You can change this behaviour by unchecking the setting "Save settings on exit" in the settings menu. The last saved settings will then be frozen until you check this setting again one time. Besides this general setting, there are two more configuration options that will be described in the following:


Final words


Version history