The rules for installed FM directory name mangling

If you look in your installed FMs directory, you may notice that the FM folder names don't always match their archive names. This is a brief list of the ways in which they can differ.

The 30-Character Rule

This is the only hard-and-fast rule per se, and it comes from NewDark's modders_notes.txt:

All filenames and directory names for files used by Dark must be 30 characters or less (excluding extension). FMs/mods containing files or directories with longer names may have worked, but they may as well only appeared to have worked and causing not immediately noticeable problems under the hood. While there some exceptions for certain types of files, it wouldn't be helpful or wise to go into what those are, instead the rule should simply be to NEVER use names longer than 30 characters.

All loaders that I'm aware of obey this rule.

So that's the one actual rule, but there are some other things that one might call "de facto standards". Starting with...

Deduplication

The 30-character rule leads directly to a potential problem: What if you have two FMs whose archive names differ only after the 30 character mark? A real-world example:

2002-12-08_c4FatherHirvakiasPortal1.zip
2002-12-08_c4FatherHirvakiasPortal2.zip

When truncated to 30 characters, both archive names would end up as 2002-12-08_c4FatherHirvakiasPo. So their names need to be deduplicated. In the absence of any explicitly stated rule for how this should be done, loaders generally do what FMSel does, which is to append a number in parentheses - starting with 2 and incrementing as needed - to the end of the name, truncating it enough to stay under the 30 character mark even with the appended number.

Again, a real-world example from AngelLoader's FMData.ini:

Archive=2002-12-08_c4FatherHirvakiasPortal1.zip
InstalledDir=2002-12-08_c4FatherHirvakiasPo
...
Archive=2002-12-08_c4FatherHirvakiasPortal2.zip
InstalledDir=2002-12-08_c4FatherHirvakia(2)
...
Archive=2002-12-08_c4FatherHirvakiasPortal3.zip
InstalledDir=2002-12-08_c4FatherHirvakia(3)
...
Archive=2002-12-08_c4FatherHirvakiasPortal4.zip
InstalledDir=2002-12-08_c4FatherHirvakia(4)

Character replacement

FMSel also does another thing with the folder names. From the source code:

// replace undesired chars with underscore (replace aggressively for cross-platform safety)
const char *illegal_chars = "+;:.,<>?*~| ";

The "cross-platform" comment is a bit of a mystery; the Dark Engine games have never been cross-platform, and while you can run them on other platforms with compatibility layers (Wine etc.), they will act as if on Windows, with Windows' rules about valid filename characters. Perhaps this was done "just in case" for better forward compatibility, or perhaps there were plans to make NewDark cross-platform at some point that never panned out. Regardless, it seems unnecessary, except for the fact that cam_mod.ini uses the + character to separate mod paths, and while those shouldn't conflict with FM folders, it's probably better to be safe than sorry. As for the others, they're either perfectly legal for Windows file and folder names, or else illegal for both. Nevertheless, loaders again tend to copy FMSel here, although NewDarkLoader replaces fewer characters.

It could also be that maybe the game itself doesn't like some of these characters, but without the source code, I can't say for sure. All I can say is that I copy FMSel's logic in AngelLoader because you can't go wrong with official behavior.