FMSel Reference

Fan Mission Selector and Manager for Dark Engine based games

Overview
GETTING STARTED
MAIN WINDOW
TAGS
LOCALIZATION / LANGUAGE

Rev 12

GETTING STARTED
To get the game to run FMSel when it starts, you have to edit cam_mod.ini and uncomment (remove the semi-colon) the line ;fm.
Change

to

; always start the FM Selector (if one is present)

;fm
; always start the FM Selector (if one is present)
fm

This will launch FMSel first when you run the game, and give you the option to select an FM or start the game without an FM.
The default FM path is a directory named FMs in the game directory. For example if the game is installed in C:\Thief2 then you have to create a
directory C:\Thief2\FMs. The FM path can be customized in cam_mod.ini with the fm_path config var, and can be an absolute path to an entirely
different location from where the game is installed.
You are now ready, just run the game and FMSel will start.
When FMSel starts it will scan the FM path for sub-directories and treat them as FMs. Additionally to the readily available FMs it finds in the FM path, it
also supports working with archived (zip/rar/7z) FMs. To enable archive support you need to configure an archive path, a directory which is different
from the FM path, where you store your collection of FM archives. FMSel will scan the archive path recursively, so the archives may be organized in
sub-directories. The archive path is configured in the options menu (see Actions under the MAIN WINDOW chapter).
To play an archived FM it has to be installed first. Installing consists of FMSel extracting the archive into a sub-directory of the FM path. Uninstalling it,
deletes the directory again. Install/Uninstall is done from the context menu in the FM list.
Deleting an FM archive, or the FM dir for a non-archived one, will usually not remove the FM entry from FMSel's database. This ensures that your play
history is preserved, without requiring you to keep the FM on your system.
NOTE: Avoid renaming FM archives after they have been added to FMSel. This will confuse it and usually produce duplicate entries, where the entry
for the old archive name will appear as a deleted FM.

Support for FMs with MP3 files

FMSel does not support converting MP3 files to WAV by default, in order to steer clear of licensing issues, but this is required to be able to properly
play FMs that contain MP3s. However MP3 conversion can be enabled (during archived FM install only) by downloading the LAME MP3 library
(libmp3lame), in the form of a DLL file.
Links to download locations for the libmp3lame library can be found on http://lame.sourceforge.net/links.php#Binaries. The recommended
download site from there is http://www.rarewares.org/mp3-lame-libraries.php. Download the libmp3lame library (for x86 / 32-bit) and extract the
contained libmp3lame.dll to the same location as your fmsel.dll (i.e. the game directory).
Note that if you install an FM (that contains MP3s) manually, instead of installing it through FMSel, then there will be no conversion done and the game
will fail to play the MP3 files.
Special note to FM authors:
Although this is not directly related to FMSel, this is a good place to issue a recommendation to FM authors. Avoid using MP3 when you create FMs.
There are patent/licensing issues tied to that format, which may put your FMs and especially FM selectors/loaders in a position that is completely
unnecessary. There is nothing gained by using MP3 instead of OGG (http://www.xiph.org/ogg/).

MAIN WINDOW
Filters
Tag Filters

FM List

Actions
FM List
Displays a list, or partial list depending on filter settings, of FMs in the database.

Column

Description

Name

Displays the FM name, rating if set and tags if any (and FMSel is configured to display them). The Name column
header also provides the possibility to sort by Rating.
Some list items may display one of these icons left of the name:
FM is available as an archive, but isn't currently installed.
FM is available as an archive and is currently also installed (ready to be played).
FM isn't available at all (not installed and no archive).
The font and color used for the name also conveys information about status and availability.
Italics - FM isn't installed (may be combined with any of the other styles).
Blue - FM has been launched but hasn't been completed.
Blue Bold - FM has never been played/loaded.
Orange Bold - FM has a playthrough in progress.
Rating is only displayed if an FM has been rated. The rating can range from 0 to 5, in 0.5 steps.
Ex: A 4.5 rating

Pri

Priority. This is a way to flag an FM for importance. The original intent is to use it to flag unplayed FMs that you want
to play more urgently than others, but there's no functionality tied to the priority other than being able to filter and
sort on it, so you may use it for whatever purpose you see fit.
Medium

Status

High

Urgent

Mission has been completed.

Playthrough is in progress.
Either of the above icons may display a number next to the icon like
the number of times that the FM has been completed.

or

where the number indicates

Last Played

Date when the FM was last launched, empty when mission has never been launched.

Release Date

Release date of FM, empty if none has been set.

FMSel will attempt to automatically determine the release date for newly added FMs. Automatically determined
dates are marked as unverified, which are displayed with an italics font in the list.

To change status/rating/priority, install/uninstall, edit other FM properties and more, use the context menu that can be accessed by right-clicking on an
a list entry.
Item

Description

Play

Same as Play FM (see Actions).

Start Playthrough

Same as Start FM (see Actions).

Install

Install an archived FM. Installing means it will extract the archive to a directory in the FM path. If there are
backed up files from a previous uninstall, like savegames, it will ask if those should be restored. Not restoring
the backed up files can result in the backup being lost, if you create a new backup the next time the FM is
uninstalled.

Uninstall

Uninstall an archived FM that is currently installed. The uninstallation process simply consists of deleting the
FM's directory and all its contents from the FM path. It will ask if it should make a backup archive of changed
files or savegames (depending on the Backup Type currently set, see Options menu under Actions). The backup
archive is a ZIP file saved alongside the FM archive, using the same filename with a .FMSelBak suffix. For
example If the FM archive is named TheLargeCampaign.rar then the backup archive will be named
TheLargeCampaign.FMSelBak.zip.

Status

Change status.

Priority

Change priority.

Rating

Change rating.

Edit...

Edit FM properties, like the name displayed in the list, release date, tags, notes and more.

Edit Tags...

Does the same as Edit... but displays the tag editor tab page right away, for quick access.

View Info File...

View the info/readme file associated with the FM, if one is available. The file is open in an external application
like for example Notepad or Wordpad, depending on the file type.

View Summary...

Displays a popup window with a summary sheet for the FM. While the popup is displayed it's possible to cycle
through the FM list with the left and right arrow keys.

The context menu has a few additional items in advanced mode, which can be accessed by holding down CTRL while right-clicking.

Item

Description

Delete from Db

Delete FM entry from database. All associated information, such as rating, notes, tags etc. will be
permanently lost. If the FM exists as an archive and/or in the FM path, it will be re-added from scratch
the next time FMSel runs.

View Archive Contents...

Displays a popup window that lists the files in the archive, for an archived FM. Also lists the files in the
backup archive if one is found.

Actions
Button

Description

Skip FM

Start the game without an FM. Pressing ESC has the same function.

Play FM

Start the game with the selected FM. Pressing Return has the same function.
When running under DromEd this button is named Edit FM instead to better suit editor use.

Start FM

Start the game with the selected FM and automatically change its status to playthrough in progress.
This button isn't available when running under DromEd.
Options/Tasks menu. See table below.

Exit

Quit FMSel and the game.

Contents of the options/tasks menu:

Item

Description

Tag Rows

Number of rows with tags to display per FM entry in the list. When Variable Height is enabled, the number of
rows acts as max number of rows, so if the number of rows is set to 4, and an FM only requires 1, then the list
item height will be adjusted to only display 1 tag row.

Date Format

Set the date display format in the FM list.

UI Theme

UI Theme to use for FMSel.

UI Font Size

Choose between Normal and Large font setting. Changing this will exit FMSel because it requires a restart.

Misc

Return to FMSel

Word Wrap Descr Editor Enable word wrapping in FM description text editor.
Word Wrap Notes Editor Enable word wrapping in FM notes text editor.

Never Does not return back to FMSel after exiting the game(/DromEd).
After FM Returns back to FMSel after exiting the game when an FM was launched.
Always Always returns back to FMSel after exiting the game.

This setting is separate when running under DromEd, so you have to configure it once when running the game
and once when running DromEd.
FM Archive Path...

Optionally set the path(/directory) where FMSel can find your collection of FM archives. This cannot be the same
as, or a sub-directory of, the FM path (the directory where installed FMs are located), or vice versa. FMSel scans
the archive path recursively, so the FM archives my be organized in sub-directories.

Backup Type

When uninstalling (deleting the extracted FM from the FM path) an archived FM, you are asked if you want to
make a backup. A backup is a ZIP archive that FMSel creates, that contains for example savegames. The
Backup Type configures which files will be included in such a backup.
Only Saves and Shots The backup archive only includes savegames and screenshots.
All Changed Files The backup archive includes all files that have been changed*, added or removed**,
compared to the original install (i.e. the archive). Since screenshots and savegames are added files, these will
also be backed up. This option is useful if you modify files in the FM, like customize a config file, add an updated
OSM or even re-process the mission file with improved settings, and want all those changes restored the next
time you install the FM.

* Files whose modified time or size differ from the original file in the archive.
** Removed files are tracked so that when the backup is restored, they are removed again.

Install Options

Options for installing archived FMs.

Convert OGG to WAV Convert OGG sound files to WAV during FM installation. 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.

Tasks

Various less frequently performed tasks.

Auto-fill Release Dates This command will probably never be necessary during normal operation, because
when FMSel comes across an FM it hasn't seen before it will automatically try to determine a release date. If for
some strange reason there are FMs in the list where this hasn't happened, then this command will scan through
all FMs currently visible in the list and try to determine a release date.
Export FM.INI from FM... - Export an fm.ini file for the FM currently selected in the list. FM.INI creation is
primarily for FM authors, so they can create an INI file to include with the FM. The fm.ini is a standardized file
that can include information like mission name, release date, description and a list of tags.
Create New FM.INI... - This is similar to Export FM.INI except it doesn't require an existing FM in the list. It
opens up a dialog where all the data can be entered, which is then saved to an fm.ini.
Export Batched FM.INI... - Export an .ini file for all archived FMs currently visible in the list. The exported file
contains the same data as a regular FM.INI, but for several FMs (identified by their archive name). This can be
useful to share database data with other users. The exported file can only be used by Import Batched FM.INI....
Import Batched FM.INI... - Import a batched FM.INI file. You can select which data you want to import and how
you want it to be applied.

About

About box.

There are a few additional items in advanced mode, which is accessed by holding down CTRL while clicking the button.
No Auto-refresh

Disable automatic refresh of list after editing FM properties. Can be useful when editing a large number of FMs.

Save Db Now

Save database changes immediately. This is normally done when FMSel closes.

Filters
Item

Description

Name

Name filter. Only FMs whose names contain this string will be displayed in the list.

Min Rating

Minimum rating. Only FMs who have this or higher rating will be displayed. An asterisk (*) value means that the
rating filter is disabled.

Min Pri

Minimum priority. Only FMs with this or higher priority will be displayed. An asterisk (*) value means that the priority
filter is disabled.

Status

Status.
Show FMs that have not yet been completed.
Show FMs that have been completed.
Show FMs with a playthrough in progress.

Avail

Availability.
Show FMs that are available as archives but aren't currently installed.
Show FMs that aren't installed and aren't available as archives either.

Rel. Year

Release year (from - to). Only list FMs that have a release date within the specified range. The year is specified as a
two digit number (where 99 would mean 1999, 04 would mean 2004). If both the from and to fields are left empty
then the release date filter is disabled. You can also leave either the 'from' or 'to' field empty. Only specifying a 'from'
year will list all FMs that were released on that year or later, and only specifying a 'to' date will list all FMs that were
released that year or earlier.
Refresh list with regard to sorting and filtering. This can can come in handy after changing the status, rating or
priority of an FM. It doesn't automatically update the list after changing any of those because it may result in the item
disappearing from the list due to filtering, which can be annoying. For example let's say you've hidden all the FMs
that are completed and you just finished playing an FM that you want to rate and mark as completed. If filtering was
updated automatically the FM would disappear the instant you marked it as complete, but you might not be done yet
because you wanted to rate it and maybe add some notes and/or tags.
Reset all filters to default and clear all tag filters.

Tag Filters
Filter FMs based on tags. To add a tag filter click on Add Tag Filter >>, which will display a popup with all existing tags to select from. The popup can
be aborted by pressing ESC or clicking anywhere in the main window, outside of the popup.

The number displayed next to each tag is the total number of FMs in the database that have the tag. By default filters are added as an OR filter, by
holding SHIFT or ALT while clicking on a tag it will add it as an AND or NOT filter. See below for details on the different filter operations. To remove all
tag filters that you've added at once, you can use Reset Tag Filters in the upper right of the popup.

OR filters. Show all FMs that

have any of these tags.

AND filters. Only show FMs

that have all of these tags.

NOT filters. Do not show FMs

that have any of these tags.

TAGS
The tag system is roughly similar to the ones that can be found on various web sites. It allows you to add any number of keywords to an FM, which can
be used to convey basic information or used to find FMs with specific traits in the database. Aside from simple keyword-like tags, FMSel also supports
what it calls tag categories, to group certain categories of tags. To specify a category you just start the tag with the category name followed by a colon,
and then the actual tag keyword.
For example the recommended tag category to use when specifying the FM's author(s), is author, so the tag for an author named Joe Smith would be
author:Joe Smith. If there are multiple authors for an FM, then you can just add multiple author tags.
The tag editor has a couple of tag and category presets, which are recommended in order to standardize the most common tags. The standardization
is useful so fm.ini files by different authors use the same tags for basic information, otherwise the tag database would become messy and make
filtering less useful.
Tag Editor

The tag editor is accessed through Edit Tags... (or Edit...) in the context menu (in the FM list). It provides two methods of adding tags. You can add
existing tags by clicking Add Tag >>, which will display a popup that's nearly identical to the one for adding tag filters, with all existing tags to select
from. The popup can be aborted by pressing ESC or clicking anywhere in the main window, outside of the popup.
The other method is to type it in manually in the input field and then press return (or click the button to the right of the input field). As you type, a
suggestion list may pop up with existing tags that begin with the same string. When you add the typed in tag, the editor will check for illegal characters
and formatting, and adjust the tag if necessary. If it had to adjust the tag it will not add it immediately, instead it will display the updated tag in the input
field, which allows you to review the change and accept it, by pressing return one more time, or to edit it further.
Important note to users of FMSel localized in other languages
Some tags may be localized when they are displayed, but internally they are still maintained in English. As a result, the Add Tag input
field, for manually adding tags, only works in English even if tags have translations. For example if the tag campaign is localized to
goosfraba. If you want to manually add that tag, using the the text input field, you have to type in campaign and not goosfraba.
The editor will attempt to automatically correct the input by translating the tag back to English if it can, but this is not guaranteed.

Below is a brief description of what the tag presets mean and what their intended use is.
Preset

Description / Intended use

author:

Category for FM author(s). If there are multiple authors then add several tags.

contest:

Category for FM contests. Specifies the contest name that an FM is part of, if it is a contest FM.

genre:

Category for genre(s) that an FM specializes in. If the FM does not specialize in any genre, in other words if it
represents typical gameplay of the game, then there's no need to add genre tags. That would only make it harder
for users to filter for specialized FMs.

language:

Category for language(s) supported by an FM. If multiple languages are supported then add several tags.

series:

Category for an FM series that an FM is part of, if it is part of one.

campaign

Specifies that an FM is a multi-mission (consists of more than one mission file) FM.

demo

Specifies that an FM is a feature/tech demo and not a regular gameplay FM.

long

Specifies that an FM is noticably longer than an average mission. No specific numbers will be mentioned, but
think of it from a player's point of view, who feels like playing a mission that takes longer to finish than usual. With
the help of this tag they can filter the database to easily find such FMs.

other protagonist

Specifies that the protagonist/player is a character other than the one of the original game.

short

Specifies that an FM is noticably shorter than an average mission. The intended use for this is based on the same
reasoning as long, see description above.

unknown author

Specifies that the mission author is unknown. Mainly intended for use with contest FMs where the author is
secret.

LOCALIZATION / LANGUAGE
FMSel supports localization, so that the user interface can be translated to other languages. Translations are maintained in separate files (with .po
extension), one per language. If you have obtained such a file for the language of your choice, then place it in the same location as your fmsel.dll (i.e.
the game directory). Make sure it's named fmsel.po (without quotes).
If for some reason your FMSel DLL is named something other than fmsel.dll then the po file must have the same name. For instance if the DLL is
named fmsel-alt.dll then the language file must be named fmsel-alt.po.

Note to translation authors

For instructions and translation rules open the supplied template fmsel.po in a text editor and read the comments.