######################################################################
###                                                                ###
###                    http://retrocast.ch.vu                      ###
###                                                                ###
###                            presents                            ###
###                                                                ###
###                    Modern Loader ver.0.32                      ###
###                                                                ###
######################################################################


1. About

2. Features

3. System Requirements

4. Usage
4.1. Preparing the folders
4.2. The first start
4.3. Options
4.4. Installing and running fan missions
4.5. How to use multiple executables in one installation
4.6. Savegame Backup functionality
4.7. Updating ModernLoader
4.8. ModernLoader under Wine

5. Games
5.1 Thief - Deadly Shadows
5.2. T3Ed - Thief 3's Editor
5.3. T2X


6. Modifying ModernLoader
6.1. Tools-Folder
6.2. Lists-Folder

7. Upcoming features / Todo list





######################################################################
### 1. About                                                       ###
######################################################################

Modern Loader is my personal approach at creating a Thief fan mission
loader. With Garrettloader and Darkloader there are already two 
mature solutions available. However, they didn't offer what I needed,
so there was only one solution: to make my own loader.

Modern Loader's engine works quite a bit different than the other
loaders. It's build around the idea of utilizing hard links to offer
multiple fan mission installs which effectively turn the FMs into 
standalone installations without occupying more space than a mere
extraction of the FM would need.

However, Modern Loader is still pretty new (codebase is less than a
week old at the time of this release). This means it still lacks 
many features which I will hopefully will find the time to implement
in the future.





######################################################################
### 2. Features                                                    ###
######################################################################

- Support for Thief 1, Thief Gold, Thief 2 and Thief 3

- Support for FMs in zip, 7z and arc format

- Installs zipped FMs twice as fast as GarrettLoader and four times
  faster than DarkLoader

- Install T3Ed with one simple click within seconds

- Install T2X with ML and save your Thief 2 directory from clutter

- Import your old GarrettLoader and Darkloader savegames

- Each FM uses individual saves and key bindings

- Installs done via hard and symbolic links

- Auto-recognition of game executables, regardless how they are named

- Support for multiple game executables within one folder

- Each game's FMs can have different source and install folders

- Original game stays playable. Same goes for each FM

- Autoconversion of ogg and mp3-files to wave-format for T1/G/2

- Different install options for each FM. You get to decide which FM 
  will use your currently installed mods and hacks and which won't.





######################################################################
### 3. System Requirements                                         ###
######################################################################

- Windows 2000 and newer supported including x64-systems

- NTFS-formatted HDD





######################################################################
### 4. Options                                                     ###
######################################################################

4.1. Preparing the folders
--------------------------

It is recommended to use >>>fresh<<< installs of the games! DarkLoader
and GarrettLoader dump all file data into the install directory. There 
is no guarantee that this won't lead to complications! For hints on 
dealing with Thief 3 check out section 5!

Sort your FMs by game and put them into seperate folders. ML is not
sophisticated enough to determine the Thief-version the FM is supposed
to work with. If you want to, you can also prepare separate FM install
folders for each game, but this is not required for ML to work 
properly. 

If the game folders are on a different drive than the folder you want 
to install your missions to, then ModernLoader will automatically 
create symlinks instead of hard links. Symlinks are only supported by
Vista and later operating systems, so if you sport XP then both 
folders will have to be located on the same drive.

You can either use the browse buttons to modify the path or do it 
manually. Each change is saved automatically. If you paste your links,
then press enter while the updated input window is focused to save the
change. Don't include the name of the executable in your game paths.
ModernLoader will filter it out if you do, but there's no reason to 
stretch your luck.

To avoid problems, ML does not allow to use the game folder as 
mission install folder. This would lead to many complications so 
ML will throw an error message if it detects such a set up.




4.2. The first start
--------------------

When you run ML for the first time, it will scan for your Thief 
installations. It will fill out the folder paths for the games it
finds. You should check if they are correct, just in case you moved
your game directory in the mean time.

Clicking on a game title above the mission window will load the 
corresponding path settings on the bottom of the window. Check them
all and fill out the path for the mission folder. If you don't specify
an FM-install path, then ML will use the mission folder and extract
the missions into that one.

During first start ML also scans for available executables. It doesn't
matter how the executables are named. ML will check them all. It will 
try to determine whether they were hacked by ddfix, widescreenpatch or
is still in its original state. If you ever need to re-scan for new
executables press the refresh button. It will also refresh the mission
list.

Modern Loader depends on you keeping the FM-archives. If you remove an
archive, ML won't be able to detect the installed FM. You can still 
play the FM by going into its folder and starting it manually, but its
out of ML's reach. 



4.3. Options
------------

Game titles:	Above the mission window you will find several game 
		titles. Clicking one will load the corresponding 
		game's missions and path settings.

Mission Window:	It lists the missions that ML detected. Currently, it
		only shows the archive-names of the found FMs. 
		There's a checkbox in front of each FM. If it's ticked
		then the FM is installed. If for some reasons ML can't
		detect the FM's proper installation status, you can
		set it manually by clicking the checkbox.

Install button: ML offers you two install modes - original and full.
		The original mode will only use those files of your
		Thief install directories that shipped with the 
		original versions. This mode also copies the files
		needed for ddfix. Other mods however are not used.
		If you want to run your FM with all your patches,
		texture mods and other enhances, tick the "full"
		checkbox. During install, your entire folder will
		be used as a base to install the FM. 
		To keep problems to a minimum, ML places its own
		install.cfg-files into the FM-install folders.
		
		Once an FM was successfully installed, the button 
		turns into an uninstall-button. It will remove the
		installed FM including the hard links. It will neither
		touch your compressed FMs, nor your original Thief
		folders. Only the selected FM is affected.

Original Binds: ModernLoader not just stores the savegames of FMs, but
		also key bindings. This allows you to set up different
		binds for each FM. 

		If you select this option then ML will use the bindings
		of your original game. This will effectively overwrite
		your saved bindings, because ML will backup these
		upon uninstalling the FM. This option only applies to
		Thief 1, Gold and 2 and can be combined with the "full"
		and "original" install options.
			
Run Button:	Once a selected FM has been installed, the "Run"-
		button becomes available. Depending on the 
		executables that ML recognized, it will allow you
		to run the FM either with a ddfixed, widescreen-hacked 
		or unmodified executable. If your executables have
		non-standard names then you'll need to perform a full
		install to use them.

Refresh List:	This button refreshes the mission list for each game
		and scans for new executables. You will need to 
		push it each time you changed your paths or when
		you deleted, renamed or added executables.

Import Saves:	Makes ModernLoader import savegames of GarrettLoader
		and DarkLoader. ModernLoader will look in the game 
		folders you specified and import all savegames it finds
		regardless of whether you still have the FM or not. 
		This is a very lengthy process, because every save
		is being extracted and re-compressed, so be patient.
		There won't be any progress bar updates during this 
		process and ML won't react to any other clicks. To 
		give the user some feedback about what is going on,
		the info bar will display which savegame of which 
		game is currently processed. Make sure you have 
		enough space on the drive containing your operating 
		system's temp folder.
		
		Imported Saves are recompressed to your preferred 
		compression format. The GL/DL-saves will not be 
		deleted, but only read to create ML-compatible ones, 
		so this won't destroy your GL/DL-setup. If ML finds
		a savegame for an FM that you akready installed with
		ML then ML will also update the saves of the FM.

		There is no function to export savegames to the 
		other loaders and there never will be, so don't ask...

Game Path:	This is where the path to your selected game goes. 
		Say you clicked on Thief Gold, then enter the path
		to your Thief Gold installation folder here. Don't
		include an executable! ML is supposed to ignore it, 
		but no reason to try your luck...

Mission Folder:	Enter the path to your compressed FM missions here.

FM Installation:Enter the path to the folder where you like your FMs 
Folder		to be installed to. If you don't enter one then
		ML will use the Mission Folder and extract the FMs 
		there.

Savegame Folder:Specify the path to a folder where you want to store
		the savegames for each FM. Unlike the other folder 
		paths this one isn't game specific, meaning that one
		path is used for all games. ML will create subfolders
		for each different game in it and store the compressed
		savegames for each FM in a sorted fashion.

		If you don't specify a folder then ML will automatically
		backup your saves to a savegame folder within the ML
		directory. For more information check out section 4.6.


If you're unsure while using ML you can always hover the mouse cursor
over the function in question and wait for a short description via
tooltip. 




4.4. Installing and running fan missions
----------------------------------------

Select a game and then a mission from the mission list. Choose your
install options (details in above section) and click install. ML 
does not have a progress bar yet, so you'll have to be patient 
until it signals the end of the installation with a message window.
If you're not sure that ML is doing something then select a different
mission. If that's not possible, then ML is busy with an installation.

Once a mission was installed, the "Run"-button will become available.
For Thief 1, Gold and 2 you will have extra options available for 
starting the FM. Refer to 4.3 for more information on those. Some 
T1/G/2-FMs use mp3 or ogg-files as sound format. ML will automatically
convert those to wav if detected because these formats aren't natively
supported by the games.




4.5. How to use multiple executables in one installation
--------------------------------------------------------

ML can detect and distinguish between multiple game executables for 
T1/G/2. This enables you to run each FM with the executable of your 
choice. However, this feature isn't usable right out of the box. It 
requires some leg-work from you. 

The problems start if you want to use a ddfixed exe with an original
one. ddfix checks its own ini for the game's resolution, but also 
cam.cfg. Since both resolutions have to match, cam.cfg has to be
set to the desired (most likely by Thief natively not supported)
resolution. Doing that will allow the ddfixed exe to run, but the 
original will either crash or overwrite the unsupported resolution
with a supported one, which in return will make ddfix complain next
time you start a game with it. This would result in constant cfg-
editing by you.

A better solution is to use two cam.cfg-files. One for each exe.
To do that you'll need a hex-editor. If you don't have one, google 
for XVI32. It's free and sufficient for the job. Rename cam.cfg
while not changing the number of characters in the name, then replace
the cam.cfg-references in the executable with the name you chose.

For this hack to work you also need to hack the original executable.
The reason for that is that regardless of the fact that you changed 
the hard-coded name for the cfg-file in the ddfixed executable, it
will still load cam.cfg by default should it exist. So change its name
and change all cam.cfg-references in the original exe to it.

Here's the setup that I use:

cao.cfg - original cam.cfg, used by original exe

cad.cfg - ddfixed cam.cfg, used by ddfixed exe

caw.cfg - cfg that's loaded by widescreen-patched exe

ML installs all ddfix-files autoamtically for the original install 
should they exist. It will also install cam.cfg, as well as the names
I chose in my example. So, if you want to use different names then 
add them to Thief*orig,txt in the lists-directory. Check out section 
6.2. for more information. Of course using a full installation will
automatically get all needed files.




4.6. Savegame Backup functionality
----------------------------------

Once you uninstall a mission, ML will backup all created saves including
keyboard bindings and game settings (only for T3) automatically. It will
use the compression you chose earlier, but it will use arc by default
since it's more efficient than zip and 7z and less memory consuming than
7z. You can switch the compression format any time. ML will use the newly
chosen format in the next backup process.

The compression format is valid for all games. It's not possible to for
example choose zip for Thief Gold and 7z for TDS. 

If you switch your savegame folder then ModernLoader will transfer all
savegames form the old folder automatically. Only "Sav-*.*" files are 
moved and the old directory will not be deleted in case you have custom
files in there (which you shouldn't).

ML uses the name of the FM-archive for the savegames it stores, so if 
you rename your FM-archive you'll also have to rename the savegames,
or else ML won't find them once you play the renamed mission. 

ML uses the following naming convention for Savegame-backups:

Sav-Name_of_FM-Archive.selected_compression_format




It goes without saying that the savegame folder that ML uses to store
all savegames is an active working folder. It is not advised to store
your own data there or to mess with the files. If you plan to keep a 
backup of a savegame in a different format, then don't keep it in this
folder because it will be deleted once ML has performed a savegame
backup.

ML is also capable of importing your old saves from GarrettLoader and
DarkLoader. Check out section 4.3. for more information.




4.7. Updating ModernLoader
--------------------------

Extract the new version into your ModernLoader folder and overwrite 
all files if asked. While this will work, it would be advisable to
extract ML into an empty folder. There are many versions where ML 
used external tools and later abandoned them. Those tools would end
up staying in your ModernLoader directory not being used again.
While this doesn't pose a problem, it does help cluttering up your 
folder. If you clean out your ML folder make sure to not delete
your savegames folder should it be located there.




4.8. ModernLoader under Wine
----------------------------

ModernLoader should work under Wine just as well as under Windows.
I don't have the means to test this though, so this is only based on
experiences by other users. I won't get into Linux or any other 
operating system for that matter, so they are not officially 
supported. 





######################################################################
### 5. Games                                                       ###
######################################################################

5.1. Thief - Deadly Shadows
---------------------------

First of all, ML expects a >>>clean<<< Thief 3 directory >>>without<<<
an installed T3-Editor. If you ignore this and try to use a T3Ed-
folder as source for your FM-installs, then you will not just suffer
extreme installation durations, but also end up with unplayable FMs!

For this game, no executable choices are available. Regardless of 
which executables you have installed, ML will use its own version to
ensure maximal compatibility with FMs.

Each FM has its own saves. Unlike the original game, the FM-saves are
stored in each folder where the FM has been installed to. They can be
found in the root-directory of the FM-folder within the "SaveGames"-
folder. ModernLoader doesn't come with an auto-backup feature, so
you'll have to back them up yourself if you want to keep them, or
else they will be deleted during uninstall.

Do not uninstall FMs by deleting them manually! Always use ML's 
uninstall-button. Sometimes ML can't remove single files, or it
leaves behind empty folders. This is the result of files still 
being locked. It is ok to delete those remaining files manually, 
however, this should only be necessary in rare cases.

There's no telling if certain TDS-enhancements such as texture mods
will work flawlessly with FMs. ML still supports the full install
option, just in case you want to try that out.

TDS-FMs that use IBT-compression such as "Evicted" are currently 
NOT supported!




5.2. T3Ed - Thief 3's Editor
----------------------------

Not much to say. Dump your T3ed-archive into your T3-missions folder
and select it for installation like any other FM. ML will detect it
being the editor and will do all necessary modifications. No more
backups of your original Thief 3 folder, no need for renaming to
get your original Thief 3 running, no need for additional software
to start the editor and of course the best: everything can be used
right away thanks to parallel installs. Build your FM and test it
or play others without the hassle of meddling with your T3Ed-install!

To run T3Ed just click the "Run"-button after it has been installed
successfully. 

ModernLoader doesn't link ini and gmp-files as those seem to be 
edited which would affect the original TDS-installation. Instead they
are copied.




5.3. T2X
--------

ModernLoader can install T2X for you. This allows you to keep your 
Thief 2 directory as slim as possible. Otherwise T2X would be 
hardlinked every time you installed an FM with full install. 

As a positive side effect the installation by ML is about 25% faster 
than using T2X's native installer and that doesn't even take the time
into account you'd need to click yourself through its many sub-menus.

After installation has finished, ML will run the VP3-codec setup that
comes with T2X. If you already have the codec installed, (or a 
compatible equivalent such as ffdshow) then you can just cancel the
setup and you're done.





######################################################################
### 6. Modifying ModernLoader                                      ###
######################################################################

ML gives users limited ways of editing its behavior. In ML's folder
you will find the directory "SysFiles" which in itself contains more
folders.




6.1. Tools-Folder
-----------------

Here you can find all the command-line tools that ML uses. The file
T3Main.7z contains the executable that ML uses for TDS-FMs. If you
have problems with this version or have other reasons for using a
different version, you can do so by placing your own version 
compressed with 7z here. Of course, the archive needs to have the
name T3Main.7z for this to work. Removing the archive will render
ML unable to successfully run TDS-FMs.

While you could replace the commandline tools with other versions,
this isn't recommended or supported. If you do it, don't expect 
support from me. You're on your own then.




6.2. Lists-Folder
-----------------

This folder contains definition files that control MLs FM installation
behavior:


inst.cfg 
~~~~~~~~

This is a general version of install.cfg/darkinst.cfg which ML uses 
for Thief 1, Gold and 2 FMs. If you need a special version to support
certain mods, you can either edit or replace this file. Just note
that this file is used for ALL T1, Gold and T2 FM installations!


*full.txt
~~~~~~~~~

These text-files contain scans of your current Thief installations
and are used for the "full"-install option. You can't do anything 
with them. They are generated during each install. They are merely
kept for error tracing. Editing them won't do anything, since they
are replaced with new versions after each install.


*orig.txt
~~~~~~~~~

These files contain lists of files for the vanilla versions of the
corresponding games. ML uses these lists for the "original" install
option. If you want to add certain mods to your original installs for
every FM then you can add the files manually.


*ddfix.txt
~~~~~~~~~~
These files are used for the ddfix-install options. Above explanations
apply here too.





######################################################################
### 7. Upcoming features / Todo list                               ###
######################################################################

The following list contains features that might get implemented in the
future. It's neither set in stone, nor complete.


- sorting by Date, Name, Completion
- support for mission info
- multilanguage support for FMs and ML including thief non-native languages
- support for stats (played – yes/no, score), exportable (txt-file)
- support for FM-recompression
- support for error reports
- EP-support from several thief installs
- filtering options for mission list(installed/not installed FMs)



Xiaopang, 05.01.2011