AngelLoader

A fan mission loader for Thief Gold, Thief II: The Metal Age, and Thief: Deadly Shadows

Official documentation

Table of contents

Getting started

System requirements

Installation

Currently AngelLoader is portable-only, so it must be placed in a non-protected folder (so don't put it in Program Files or Program Files (x86)).

Some examples of good locations might beC:\AngelLoader, C:\Games\AngelLoader, etc.

Initial setup

When you start AngelLoader for the first time, you'll see the initial setup window:

Paths to game executables

Here you can choose the executable files for the Thief games you have installed. These fields are optional - you can set some, all, or none. You will still be able to see and manage all of your fan missions even if you haven't set their corresponding executable, but of course you won't be able to install or play any of them unless their executable is set.

Thief 1 and Thief 2 must be patched with NewDark in order for AngelLoader to be able to use them. Thief 3 must be patched with the Sneaky Upgrade. Version 1.1.9.1 or above is recommended; while versions as far back as 1.1.3 may work, they haven't been tested and are not officially supported.

FM backup path

This is a required field. This is the folder that will be used for backing up saves, screenshots, and/or full differential backups when you uninstall a fan mission.

FM archive paths

Here you can set the directory or directories where your fan mission archives (.zip or .7z files) are located. If you enable "Include subfolders", then all subfolders inside all directories you specify will also be searched for FM archives (this matches NewDarkLoader's behavior). Otherwise, only the exact directories you specify will be searched. A note on fan mission archive directories: Because multiple directories are allowed, there is the potential for duplicate files. In this case, AngelLoader will simply use the first file it finds, and ignore any further files with the same name. It is recommended that you don't put duplicate files in your archive directories, but if you do, then as long as they're exact copies (ie., not different files with the same name) then it will be fine. It's also recommended that your archive directories should only contain fan missions and/or FMSel/NewDarkLoader backup files. While AngelLoader does attempt to reject non-mission archives on scan, it's still best to keep unrelated files out of your FM directories.

Language

If other languages are available, you can choose them here. Changes will take effect immediately.

Main window

Startup scan

Whenever new FMs are detected, they will be quick-scanned for game type only. If you cancel the scan, then the game types will remain blank and will be scanned when selected, similar to DarkLoader. It's recommended that you let the scan finish, especially if you're using game tabs, as it will result in FMs being categorized properly. You can perform a more detailed scan later (see Scan all FMs).

Filter bar

Here you can choose to filter your FM list by game, title, author, release date, last played date, tags, finished status, and rating. If you've chosen to organize your games by tab, then these tabs will take the place of the game filter buttons.

Show junk

This allows archives marked as Unknown () (archives that were rejected as not being FMs) to be displayed in the list. In the extremely unlikely case that AngelLoader has rejected an FM in error, you can then choose to re-scan it. You probably won't need to use this.

Refresh list button

When you edit a mission's data, the list of missions is not refreshed. This is to prevent a mission that no longer fits the filter criteria from being filtered out of the list in the middle of being edited. If you've edited an FM and want to re-filter the list, click this button.

Clear filters button

Clears all filters.

Reset layout button

Resets the main window to its default proportions.

Draggable splitters

You can drag these horizontally or vertically to resize the sections of the window. If you drag at the corner between the two splitters, you can resize all three main sections at once.

Readme area

Here is where the selected FM's readme is displayed. If there are multiple readmes, you will be given a choice of which one to view. The first time you view an FM with multiple readmes, this list will be the only thing displayed in the readme section. This is to prevent a possible spoiler file from being displayed automatically (lootlist, walkthrough, etc). Once you've selected a readme, you will thereafter have the option to select another from a drop-down list that appears in the upper-right corner (see Readme controls).

Readme controls

In the upper-right corner of the readme area, there is a set of controls for choosing a readme; zooming in, zooming out, and resetting zoom; and toggling fullscreen. When you click the fullscreen button, the readme area enlarges to take up the entire window. Click the button again to restore it to normal size. These controls appear when the mouse cursor is over the readme area, and disappear when it moves away. In addition to clicking the zoom buttons, the readme can also be zoomed by pressing Ctrl+-, Ctrl++, and Ctrl-0, or by holding Ctrl and scrolling the mouse wheel while the cursor is over the readme area.

Play FM button

Click this button to play the currently selected FM. If the FM is not installed, it will be installed automatically first.

Install / Uninstall FM button

If the currently selected FM is not installed, this button will install it; otherwise, it will uninstall it.

Play original game button

Click this button to bring up a list of supported games. Only games that you've provided a path to will be enabled; others will be grayed out. Clicking on one of these games will let you play it without loading an FM.

Scan all FMs button

This allows you to scan all the FMs in the list. Clicking it will bring up a window where you can choose what to scan for.

Only the fields you select will be scanned for and overwritten; non-selected fields will not be touched. The exception to overwriting is tags: tags will only ever be kept the same or added to, not overwritten.

Web search button

Click this button to search the web for the selected mission. You can set the search URL in the Settings window.

Import from button

Clicking this button will bring up a list of other loaders you can import data from. Supported loaders are DarkLoader, NewDarkLoader, and FMSel. If you have a large collection of FM data from one of these loaders (comments, ratings, finished statuses, etc.) then you can import that data into AngelLoader, replacing any current data (so be careful).

Settings button

Brings up the Settings window.

Mission list

This is the main area where fan missions are displayed, sorted, and filtered. You can change the columns' size, visibility, and order. Drag a column left or right to change its order. Clicking on a column header will sort by that column. Click once to sort by ascending, and click again to sort by descending. Double-click the size grip to the right of a column to auto-size that column to fit its content.

Right-click on any column header or any blank space in the list to bring up the column header context menu.

Right-click on an FM to bring up the FM context menu.

Double-click on a mission or press Enter when a mission is selected to play that mission. By default you will be asked for confirmation in this case; see Play FM on double-click / Enter.

Columns

Game

Displays an icon based on which game the mission is for. If unknown, it will be blank. The icons are:

- Thief
- Thief II
- Thief: Deadly Shadows
- Unsupported mission or non-mission archive (these only appear when Show junk is enabled).

Installed

Displays a icon if an FM is installed; otherwise remains blank.

Title

Displays an FM's title, taking into account the Move article setting. If no title has been scanned for, or a title otherwise can't be found, this will display the FM's archive name without the extension. If no archive name can be found then it will display the FM's installed folder name.

Archive

Displays the FM's archive name with extension.

Author

Displays the FM's author if one can be found.

Size

Displays the FM's compressed (archived) size if possible. If no archive can be found, then it will display the FM's uncompressed (installed) size.

Rating

Displays the FM's rating using the selected style.

Finished

Displays an icon representing which difficulty or difficulties you've finished an FM on.

- Normal (Easy for Thief: Deadly Shadows)
- Hard (Normal for Thief: Deadly Shadows)
- Expert (Hard for Thief: Deadly Shadows)
- Extreme (Expert for Thief: Deadly Shadows)
- Unknown

See the Finished On submenu for more information about difficulty levels.

Release Date

Displays the FM's release date in the specified format.

Last Played

Displays the FM's last played date in the specified format.

Disabled Mods

Displays the disabled mods, if any, for the FM. If all mods are disabled for the FM, it will display "* [All]".

Comment

Displays the FM's comment, if any, up to the first 100 characters or the first linebreak, whichever comes first.

Column header context menu

Right-clicking on any column header, or any blank space in the main list, will bring up this menu. Here you can choose to hide or show columns, or reset their visibility, width, or positions.

FM context menu

Right-click on a fan mission in the list to bring up this menu.

Play FM

Plays the currently selected FM. If the FM is not installed, it will be installed automatically first.

Install / Uninstall FM

If the currently selected FM is not installed, this will install it; otherwise, it will uninstall it.

Open FM in DromEd

This item will only appear if DromEd.exe was found in the game directory. Clicking it will open the currently selected FM in DromEd, installing it first if necessary.
This option does not apply to Thief: Deadly Shadows.

Scan FM

This will scan the selected FM. If you only want to scan for certain fields, see the Edit FM tab.

Convert audio submenu

This menu contains the same audio conversion options as in the Settings window, but they can be run at any time here.
This option is only available for installed FMs.

Rating submenu

Here you can rate the selected FM. The ratings will appear as they've been set in the Settings window: either 0-10 or 0-5.

Finished On submenu

Here you can set which difficulty or difficulties you've finished the selected mission on.
Unknown - this is mainly for compatibility with imported FMSel data, which doesn't mark difficulties for its Finished value.
For Thief 1 and Thief 2, the other difficulties are Normal, Hard, Expert, and Extreme.
For Thief: Deadly Shadows, they are Easy, Normal, Hard, and Expert.
"Extreme" is not an official Thief difficulty, but is provided for compatibility with imported DarkLoader data, or to use as you see fit (to denote Ghost, etc).

Web search

Click this to search the web for the selected mission. You can set the search URL in the Settings window.

Top-right tabs

These tabs allow you to edit the selected FM's data and to view more detailed information about it. The tabs can be dragged to change their order if you wish.

Collapse / expand button

Click this to collapse (hide) the top-right section. Click it again to expand it.

Statistics tab

Here you can see information on what kind of custom resources a fan mission has. If the FM has not been scanned for custom resources, none will be shown. If the FM is for Thief: Deadly Shadows, none will be shown in any case, as the custom resource scan is not supported for that game.

Edit FM tab

Here you can edit an FM's data. If you want to re-scan for a certain field, click the icon beside the field.

Alternate titles button

Sometimes, multiple different titles will be detected during a scan. If the default title doesn't look correct, try clicking this dropdown button to see if another is available. Clicking an alternate title will change the FM's title to the one that you've selected.

Release date and Last played

If a date hasn't been scanned for or cannot be detected, its checkbox will be unchecked and no date will be shown.

Disabled mods

You can disable certain mods per-mission here. To see which mods you have installed, look at cam_mod.ini in your Thief game folder. This string must be in the format modname1+modname2+modname3 etc. So to disable the Enhancement Pack 2, it should be:

ep2

To disable the Enhancement Pack 2 and the HD mod, it would be:

ep2+hdmod

To disable all mods for the current FM, check the Disable all mods checkbox.

Comment tab

Here you can enter a comment for the FM. This comment will also be displayed in the Comments column (up to the first 100 characters or the first linebreak, whichever comes first), and will update as you type.

Tags tab

Here you can manage the FM's tags. You can click the Add from list... button to choose a tag from the global list (which includes standard presets as well as any other tags that have been found for any other FMs), or you can start typing in the textbox to see a real-time list of tags and categories that match what you've typed. If no matching tag or category is found, a new one is created. The format for creating a new tag is category: tag. If you don't specify a category when creating a new tag, that tag will be placed in the misc category.

Patch & Customize tab

Here you can apply patches and customizations to an FM.

.dml Patches

Some older fan missions don't quite work as they should when played with NewDark. In many cases, patches are available to fix them. If you have any .dml patch files, you can add or remove them from the FM's installed folder here. If you've enabled the "All changed files" backup setting, then these fixes will be backed up and restored the next you install the FM.

Open FM folder

If you want to manually modify the FM's installed folder, you can open it here.
NOTE! FM folders contain a special file, fmsel.inf, which must not be deleted. This file contains metadata and is, due to its nature, not included in differential backups. While AngelLoader will sometimes be able to regenerate it or work without it, deleting it is asking for trouble. Don't do it.

Settings window

Paths section

The settings here are the same as the Initial Setup window, except that Language has been moved to the Other section. See Initial Setup for an explanation of these settings.

FM Display section

Game organization

Here you can choose to either organize games into their own tabs, or to display your FMs as one list and allow filtering by game. When game tabs are enabled, each game will have its own selected FM and set of filters that will be retained between tab switches. Organizing games by tab can make things cleaner, but if you want to filter without regard to game (say, to find all missions by a single author who has released missions for multiple games), then having one list with game filters will work better.

Sorting

Here you can choose to ignore leading articles when sorting FMs. For example, the FM "The Seven Sisters" will be considered to start with an "S". If you choose to move articles to the end of names when displaying them, then "The Seven Sisters" will be displayed as "Seven Sisters, The". The default set of articles is "a, an, the", but you can add more (for example to support other languages). These articles are not part of the normal localization functionality, because they apply to fan mission names, which can be any language; therefore the app-wide language setting doesn't apply to them.

Rating display style

Here you can choose the style in which to display an FM's rating (0-10, 0-5, or 0-5 with stars).

Date format

Here you can choose how to display dates: either in the short or long form of your PC's current culture, or a custom format.

Other section

Convert .wavs to 16 bit on install

Depending on your setup, .wav files that are higher than 16 bit may cause audio problems when played by Thief 1 or Thief 2, such as intermittent or constant static noise. Converting all .wav files to 16 bit will solve this issue, and does not result in a perceptible loss of fidelity. Therefore, this option is turned on by default.
This option has no effect for Thief: Deadly Shadows.

Convert .oggs to .wavs on install

Quoted from the FMSel manual:
The game can play OGG files but it can under some circumstance cause short hiccups, on less powerful computers, performance heavy missions or with large OGG files. In such cases it might help to convert them to WAV files during installation.
This option has no effect for Thief: Deadly Shadows.

Back up data when uninstalling

When an FM is uninstalled, you will normally want to back up its saves and screenshots so they can be restored if you install it again. You can also choose to back up all changed files, in which case the backup will also include all files in the installed folder that have been added, removed, or modified as compared to the files in the archive. This is useful if you have added .dml patches to the FM, or made other modifications such as creating or modifying an fm.cfg file, fixing readables, etc. Because AngelLoader aims to be patch-friendly, this option is the default. You can also choose to always be asked if you want to back up data when uninstalling an FM.

Language

If other languages are available, you can choose them here. Changes will take effect immediately.

Web search

Here you can edit the URL that will be used when searching for FMs on the web. The string $TITLE$ can be placed anywhere in the URL to insert the fan mission's title into the final string. For instance, if the URL was

https://www.google.com/search?q="$TITLE$" site:ttlg.com

and the currently selected FM's title was "Broken Triad", then the final URL actually passed to your web browser would be:

https://www.google.com/search?q="Broken Triad" site:ttlg.com

Play on double-click / Enter

When you double-click on an FM in the list or press Enter when the list is focused, the selected FM will be played. Check this box to enable asking for confirmation in that case, to prevent accidental playing from a stray click or key press.

Appendix

Localization

AngelLoader supports the localization of its user interface. New languages may be defined in language files, which must be placed in the Data\Languages folder. An English.ini file is included in that folder as an example. Language files use a simple ini format, and must be saved with UTF8 encoding in order to guarantee correct display of text.

Most user interface elements will be automatically resized to accommodate translated strings, but a few will not. These include the date and rating filter windows and some of the buttons in the tags filter window. It's up to the translator to ensure everything looks correct.

Supported formats

Archive files

Zip (.zip) and 7-Zip (.7z) files are supported. But see here for a note about 7-Zip files.

Audio files

MP3 (.mp3), Ogg Vorbis (.ogg), and Wave (.wav) files are supported in fan missions. MP3 files will be automatically converted to WAV files on install, as NewDark does not support playing them directly.

Readme files

Plain text (.txt), Rich text (.rtf), HTML (.htm, .html), and GarrettLoader Markup Language (.glml) files are supported. HTML files can be a great deal fancier than any of the other formats, but they must be viewed in a web browser (AngelLoader does not support viewing them in-app, although it provides a button to launch them in the user's web browser).

A note to authors about 7-Zip files (don't use them)

FMSel, the official NewDark fan mission loader, has always supported 7-Zip (.7z) files, and other NewDark FM loaders have followed suit. AngelLoader, too, supports these files, for compatibility with the handful that are out there. However, I propose that 7-Zip is ill-suited as a fan mission archive format, for the following reasons:

7z files do give better compression than zip files, but it's only modestly better, and it's this author's opinion that the modest amount of space savings is not worth the severely degraded user experience of waiting for 7z fan mission archives to be scanned and extracted. So I would personally say that unless you have a really good reason, you shouldn't use 7z files for FMs: the venerable Zip format is still the best balance between size and speed for fan mission purposes.

Thanks and credits

I'd like to thank the following people, in no particular order:

Dahenjo for helping me hunt down some bugs and suggesting features.

EnYB0La for providing the impetus to start writing what became FMScanner, AngelLoader's scanner module. Without it, I never would have attempted to create a standalone NewDark-supporting loader!

Björn Henke and Telliamed for creating DarkLoader, the de facto standard Thief loader for many years, and the original inspiration for AngelLoader's UI and standalone nature.

R Soul for creating NewDarkLoader, a modern loader with the classic DarkLoader UI, and also a source of inspiration for several aspects of AngelLoader.

potterr for creating GarrettLoader, the first loader (as far as I know) to support all three Thief games, the first loader I ever used, and the source of the GLML file format.

Le Corbeau, the mysterious group behind NewDark as well as FMSel, the official NewDark fan mission loader.

All of the above programs were of tremendous help in developing AngelLoader, so thank you all!

I'd also like to thank Looking Glass Studios for creating Thief, the TTLG community for keeping it alive, and my viewers for watching me goof around on YouTube for all those years.

AngelLoader uses the following libraries:

7z.dll
SquidBox.SevenZipSharp
ffmpeg
FFmpeg.NET
GlobalMouseKeyHook
log4net (for error logging)
SimpleHelpers.Net
UDE
Ookii Dialogs
Modified portions of .NET Core's System.IO.Compression code (tuned for scanning performance)

AngelLoader is open-source under the MIT license. You can view the source at AngelLoader's GitHub repository.