[Release] HoN Modification Manager *New Patch*

HoN Modification Manager 1.3.3

__________________________________________________

Table Of Contents:

1. About
2. Download
3. Installation & Usage
4. Troubleshooting
5. The .honmod File Format
6. Changelog
7. Special Thanks

__________________________________________________

1. About

What is this?

This is a program designed to remove mod incompatibilities and the need to update mods every new patch. It is also capable of maintaining a list of installed mods which can be enabled/disabled individually and offers an automatic update feature for mods.

What is the downside?

Compatible mods need to come in a format different from the simple resources*.s2z scheme, which is usually a little more work for modders to create. (There are however facilities implemented allowing simple conversion from .honmod to .s2z)
Incompatibilities with ".s2z mods" will persist as well (unless they are converted to the new format).

What does it look like?

Like this: (shown are three example mods)
[Only registered and activated users can see links. Click Here To Register...]
(click to view full size)

How does it work?

When choosing "Apply Mods" from the program menu the enabled mods are applied to the original files from resources0.s2z and compiled into a single s2z mod named "resources999.s2z".

__________________________________________________

2. Download

[Only registered and activated users can see links. Click Here To Register...]

__________________________________________________

3. Installation & Usage

To install the program download the zip file linked above containing the program. You can place it anywhere you wish. Linux and MacOS users need [Only registered and activated users can see links. Click Here To Register...] to run it.
The program will try to detect the location of your Heroes of Newerth install automatically; if it can't it'll ask you for the folder (usually something like "C:\Program Files\Heroes of Newerth").

To install mods (*.honmod files) put them into the game\mods sub-directory of your HoN install (see below for exact location) or drag them onto the program window (Windows only). Any mod files in that directory that are compatible will automatically show up in the program.
To use installed mods you need to enable them first (e.g. by double-clicking on them), then select "Apply Mods" from the "File" menu. You'll need "Apply Mods" each and every time the game was patched or you have installed/uninstalled/updated any mods. The program will remind you of this.

The default locations for the mods directory are:
Windows: C:\Program Files\Heroes of Newerth\game\mods
Linux: /home/<username>/HoN/game/mods
MacOS: /Applications/Heroes of Newerth.app/game/mods
This directory will be automatically created when you launch the mod manager the first time and can be easily be accessed from the "Open Mod Folder" option in the "File" menu.

Where do I get mods in the correct format?
In the [Only registered and activated users can see links. Click Here To Register...] you will find a pretty complete list of all mods that are currently available in the mod manager's format.

__________________________________________________

4. Troubleshooting

Spoiler

__________________________________________________

5. The .honmod File Format

Spoiler

Just like an ".s2z" a ".honmod" is a renamed ZIP. It contains the following files:

mod.xml: A valid XML file with describing "how the mod is applied", that is where to add/edit/delete code from the original files. There is a very detailed documentation given below, but you might as well just try looking at other mods to understand how this file works.
icon.png: A 48x48 icon to be displayed next to the mod's name in the mod manager. Note that partial transparency may not work or look fugly. This file is optional.
Any supportive files, e.g. new files your mod adds. You need to reference these in mod.xml or they will be ignored.

Elements and Attributes in mod.xml

Code:

[COLOR=Cyan]<?xml[/COLOR] [COLOR=Red]version[/COLOR]="1.0" [COLOR=Red]encoding[/COLOR]="UTF-8"[COLOR=Cyan]?>[/COLOR]
[COLOR=Cyan]<modification[/COLOR]
    [COLOR=Red]application[/COLOR]="Heroes of Newerth"        [COLOR=Lime][I]fixed[/I][/COLOR]
    [COLOR=Red]appversion[/COLOR]="0.3"                       [COLOR=Lime][I]game version requirement (shown is "anything starting with 0.3")[/I][/COLOR]
    [COLOR=Red]mmversion[/COLOR]="1.3"                        [COLOR=Lime][I]fixed, the version of the file format[/I][/COLOR]
    [COLOR=Red]name[/COLOR]="The Mod's Name"                  [COLOR=Lime][I]It is [B]strongly[/B] recommended to keep this name consistent as it will identify the mod.[/I][/COLOR]
    [COLOR=Red]version[/COLOR]="1.0"                          [COLOR=Lime][I]The current version of the mod. Should grow with each new release.[/I][/COLOR]
    [COLOR=Red]description[/COLOR]="blahblahblah"             [COLOR=Lime][I]Explanatory text about the mod to be shown when selected in the Mod Manager (optional)[/I][/COLOR]
    [COLOR=Red]author[/COLOR]="Your Nickname"                 [COLOR=Lime][I]Will be shown below the mod's name. (optional)[/I][/COLOR]
    [COLOR=Red]weblink[/COLOR]="http://www.com/"              [COLOR=Lime][I]A clickable link to be shown below the description text. (optional)[/I][/COLOR]
    [COLOR=Red]updatecheckurl[/COLOR]="http://.../version.txt"[COLOR=Lime][I]A URL to a text file containing the newest version number. (optional)[/I][/COLOR]
    [COLOR=Red]updatedownloadurl[/COLOR]="http://.../m.honmod"[COLOR=Lime][I]A URL to a .honmod file that will be downloaded and replace this mod file when the text file specified above contains a higher version number than this mod currently has. (optional)[/I][/COLOR]
[COLOR=Cyan]>[/COLOR]
    [COLOR=Lime]<!-- [I]Of the elements being described below each kind may appear any number of times and in any order[/I] -->[/COLOR]

    [COLOR=Cyan]<incompatibility[/COLOR] [COLOR=Red]name[/COLOR]="Other mod" [COLOR=Red]version[/COLOR]="1.0-1.4" [COLOR=Cyan]/>[/COLOR]
    [COLOR=Lime]<!-- [I]States an incompatibility with certain versions of another mod to be abided by the Mod Manager; this mod cannot be enabled when the other mod is enabled.[/I] -->[/COLOR]

    [COLOR=Cyan]<requirement[/COLOR] [COLOR=Red]name[/COLOR]="Other mod" [COLOR=Red]version[/COLOR]="2.5.1-*" [COLOR=Cyan]/>[/COLOR]
    [COLOR=Lime]<!-- [I]States a dependence on another mod to be abided by the Mod Manager; this mod cannot be enabled when the other mod is not present and enabled.[/I] -->[/COLOR]

    [COLOR=Cyan]<applyafter[/COLOR] [COLOR=Red]name[/COLOR]="Other mod" [COLOR=Red]version[/COLOR]="2.5.1-*" [COLOR=Cyan]/>[/COLOR]
    [COLOR=Cyan]<applybefore[/COLOR] [COLOR=Red]name[/COLOR]="Other mod" [COLOR=Red]version[/COLOR]="2.5.1-*" [COLOR=Cyan]/>[/COLOR]
    [COLOR=Lime]<!-- [I]If the specified other mod is enabled, this mod will be applied after/before it.[/I] -->[/COLOR]

    [COLOR=Cyan]<copyfile[/COLOR] [COLOR=Red]name[/COLOR]="path1" [COLOR=Red]source[/COLOR]="path2" [COLOR=Red]overwrite[/COLOR]="newer" [COLOR=Red]version[/COLOR]="1.0" [COLOR=Red]condition[/COLOR]="..." [COLOR=Cyan]/>[/COLOR]
    [COLOR=Lime]<!-- [I]Copies a supportive file from the mod archive. If "path2" is not specified the file "path1" is copied, if it is "path2" is copied and renamed to "path1".
         overwrite specifies a controlled behaviour in case the target file already exists:
         "yes"   -> target file is overwritten
         "no"    -> target file is left as is
         "newer" -> target file is overwritten if its version is lower than the one specified by the [COLOR=Red]version[/COLOR] attribute
        
        If the condition attribute is specified the copying is only performed if the given condition is true. A condition can consist of another mod being enabled or disabled or a boolean expression combining multiple such conditions. Examples of valid condition strings:
        'Tiny UI'
        not 'Tiny UI'
        'Tiny UI[v3.0]' and 'Automatic Ability Learner[v1.1-1.5]'
        ('BardUI' or ('Improved UI by Barter[v1.08]' and 'Improved UI Addon - Juking Map')) and not 'Tiny UI'[/I] -->[/COLOR]

    [COLOR=Cyan]<editfile[/COLOR] [COLOR=Red]name[/COLOR]="path" [COLOR=Red]condition[/COLOR]="..."[COLOR=Cyan]>[/COLOR]
        [COLOR=Lime]<!-- [I]Edits a file from resources0.s2z or one that has already been copied[/I]
            If condition is specified this editfile tag is only executed if the given condition is true; uses the same syntax as for copyfile. -->

        <!-- [I]Files are edited by executing a sequence of steps, each being represented by one of the four elements below.
             All elements need a string as input, which can either be delivered as inner text node (between the <operation></operation> tags) or read from a file in the mod archive specified by a [COLOR=Red]source[/COLOR] attribute.
             Every operation interacts with a "cursor" variable which points to a area in the file and starts out at the beginning of the file.[/I] -->[/COLOR]
        
        [COLOR=Cyan]<find[/COLOR] [COLOR=Red]position[/COLOR]="end" [COLOR=Cyan]/>[/COLOR] [COLOR=Lime]<!-- [I]synonyms for "find" are "seek" and "search"[/I] -->[/COLOR]
        [COLOR=Lime]<!-- [I]Moves the "cursor" to the next occurrence of the source string
             OR as specified by the [COLOR=Red]position[/COLOR] attribute, possible values being:
             "start"     -> Beginning of the file (synonyms: "begin", "head", "before")
             "end"       -> End of the file (synonyms: "tail", "after", "eof")
             any integer -> Move forward the specified number of characters (negative values allowed)[/I] -->[/COLOR]
        [COLOR=Cyan]<findup[/COLOR] [COLOR=Cyan]/>[/COLOR] [COLOR=Lime]<!-- [I]synonyms for "findup" are "seekup" and "searchup"[/I] -->[/COLOR]
        [COLOR=Lime]<!-- [I]Moves the "cursor" to the next occurrence of the source string, but searching backwards.[/I] -->[/COLOR]
        
        [COLOR=Cyan]<insert[/COLOR] [COLOR=Red]position[/COLOR]="after" [COLOR=Cyan]/>[/COLOR] [COLOR=Lime]<!-- [I]synonym for "insert" is "add"[/I] -->[/COLOR]
        [COLOR=Lime]<!-- [I]Inserts the source string at the "cursor", either before or after as the [COLOR=Red]position[/COLOR] attribute specifies.[/I] -->[/COLOR]
        
        [COLOR=Cyan]<replace />[/COLOR]
        [COLOR=Lime]<!-- [I]Replaces the string pointed to by the "cursor" with the source string.[/I] -->[/COLOR]

        [COLOR=Cyan]<delete />[/COLOR]
        [COLOR=Lime]<!-- [I]Deletes the string pointed to by the "cursor". Does not require a source string.[/I] -->[/COLOR]
    [COLOR=Cyan]</editfile>[/COLOR]
[COLOR=Cyan]</modification>[/COLOR]

Remarks:

Version values may only contain digits and periods. Letters will be ignored!
No two mods with the same name can be loaded at once.
"Requirements" allow mods of mods; such mods will always be applied after the mods they marked as required so that they may edit their code; note that <requirement /> automatically implies <applyafter />.

__________________________________________________

__________________________________________________

6. Changelog

Code:

v1.3.3 [25.03.10]: Fixed a cosmetic bug.
v1.3.2 [25.03.10]: Fixed a bug where version requirement strings were found not to be matching when they really were.


v1.3.1 [22.03.10]:

Fixes
=====
- Fixed a crash when a honmod file could not be copied into the mods folder, and replaced it with an error message.
- Fixed a minor internal bug.


v1.3.0 [21.03.10]:

File Format
===========
  <no changes>

User Interface
==============
- Added an option to display version numbers behind the mod names (as was default pre-1.1).
- Displayed mod names can now be edited, and mods are now always sorted by name.
- Fixed "missing required mod" error messages to properly display the mod name and suggest to visit the mod's website for a link to the required mod.
- Multiple mod selection is now possible.
- Cleaner, less cluttered update reports.

Features
========
- .honmod files can now be "opened with" the mod manager, installing them. Added a prompt on first run to register the file type and options to un/register the file type. [file type association is Windows only]
- Added a feature to export selected enabled mods as s2z file. This can be accessed from the context menu ("right-click menu").
- Hopefully added support for the upcoming FE2 user interface overhaul. This only concerns the automatic reminder to re-apply mods after patching.


v1.2.2 [08.02.10]:

Fixes
=====
- Fixed a bug with dependency cycle detection causing it to be over-cautious.


v1.2.1 [26.01.10]:

Fixes
=====
- Fixes two bugs and a spelling mistake introduced in 1.2. The bugs were concerning ignoring of modification compatibility/ordering instructions if they were placed after a non-empty editfile tag and skipping ahead too far when skipping editfile blocks with unfulfilled conditions.


v1.2.0 [18.01.10]:

File Format
===========
- Added <findup/> operation (synonyms seekup and searchup) which searches backwards.
- Added <applyafter name="modasdf" version="3.0"/> directive setting mod application order in case that other mod is enabled as well (and "applybefore", similary).
- Added an optional "condition" attribute to editfile and copyfile which allows the tags to only have effect if a given condition is true. A condition can consist of another mod being enabled or disabled or a boolean expression combining multiple such conditions. See documentation for examples.
- When the source for an operation is given in place (not via the source attribute) and all the content is in a CDATA node, then surrounding whitespace-only text nodes are ignored; this should allow for nicer mod formatting.

User Interface
==============
- When being automatically prompted to apply mods after a patch successful patching will prompt to start HoN.
- Pressing the Return key will toggle the selected mod's enabledness.
- When choosing "Update Mods" without any updatable mods present it'll say so and not just open a blank window; renamed "Update Mods" to "Download Mod Updates".
- All the letters of "Visit Website" should now be part of the link under Linux/MacOS
- Removed "Large Icons" view, renamed "List" to "Vertical List" and "Small Icons" to "Horizontal List"; added a checkmark next to the active view.

Features
========
- Added option to set command line arguments to use when launching HoN.
- When displaying the "String not found" error the first non-empty line of the string is now displayed in the message.
- Any error during mod application now comes with the number of the guilty line in mod.xml.

Fixes
=====
- Fixed a bug with the mod updater where the downloaded new version would become corrupted if its file was smaller than the original version's.
- Fixed several cases of hardcoded backslashes to use normal slashes on unix-based systems which should fix a lot of problems on Linux and Mac OS.
- If a mod's icon cannot be rendered due to missing implementation of that specific format in Mono, it'll no longer crash, but instead ignore the icon.
- "Unapply all mods" now also disables all mods.
- Improved path guessing a bit more.
- Other small fixes and changes.


v1.1.0 [27.11.09]:

File Format
===========
- Added the <findall/> operation tag: applies the following insert, add, replace or delete to all occurrences of the sought string in the file.
- Added attributes updatecheckurl and updatedownloadurl to the modification tag, which specify URLs returning the current mod version in plain text and the current mod file itself, respectively. (only supports HTTP and HTTPS)
- Note that it is strongly recommended to set the mmversion attribute to "1.1" when using either of the format additions above.

User Interface
==============
- Fell back to the default visual style for menus.
- Added the refresh (F5) option as menu entry.
- Added menu entries to change the view mode of the mod list (some may look the same or similar; possibly a few of the options will be removed later).
- Added menu option to open mods folder (also releases all file handles on the mod files).
- Added a context menu to the list view, containing "Enable/Disable", "Check for Updates" and "Delete" (all of which have keyboard shortcuts)
- Added a a command to delete mods directly from the mod manager window (shortcut key: Del)
- Added "unapply all mods" option for people trying to remove their only mod while considering "applying mods" an illogical option.
- Mod versions are no longer cluttering the main list view but are now displayed in the status bar when selecting a mod
- Made some error messages more explanatory; troubleshooting section will be shortened soon!
- Can no longer open multiple instances of the mod manager under Windows.

Features
========
- The long anticipated mod updating features are here! See file format changelog for specifics.
- When a new patch is released users will be reminded to re-apply their mods in HoN's main menu until they do so.
- When launching the mod manager after a new patch has been applied it will suggest to apply mods right away (in case you only started it to do this mandatory reapplying after patches).
- Mod enabled-ness is no longer independent from mod applied-ness! When you open the mod manager only applied mods will be enabled (this information is read from resources999.s2z) and if you don't apply mods after enabling/disabling mods it will prompt you to do so when closing the application.
- Now guesses most common HoN paths on Windows, Linux and Mac; also uses simple heuristics to strip "\game" and "\game\mods" from wrong user-specified paths.
- Now supports retrieving the game version and launching the game on Mac.
- Will now automatically request admin privileges when run on an UAC enabled system!

Fixes
=====
- Incorrect HoN paths are now always properly detected and will cause most functions to disable and the path prompt to appear every time you start the mod manager.
- If multiple mod files with the same mod name are found it will now load the one with the highest version number (previously it loaded the one with the lexicographically smaller file name).
- Incompatibilities are now properly enforced no matter in what order you enabled two incompatible mods when only one of them specifies the incompatibility (only affects visuals, processing was correct before as well).
- Other miscellaneous fixes I forgot about.
- Started commenting the code.

v1.0.3 [30.09.09]: Fixed "Visit Website" linking to wrong websites
                   Fixed some mods not working on Linux due to line break business
                   "game" folder is not created anymore, if it doesn't exist; "mods" folder creation still as before
v1.0.2 [28.09.09]: Fixed ampersands not showing up in the description.
                   Fixed "11/11 mods enabled" field width
                   Added possibility of dropping mod files onto the window to install them (copying them to the game/mods dir)
                   Added option to enter HoN path manually for hidden folder fans.
v1.0.1 [27.09.09]: Features under linux should now match those under Windows. (finding the game path automatically, the "apply mods & run hon" option)
                   Fixed "requirement" and "incompatibility" tags preventing compiling.
                   Window position is now remembered.
v1.0.0 [27.09.09]: Initial release.

__________________________________________________

7. Special Thanks

To theli for miscellaneous .net and vital linux advice.
To MaxGhost for offering a lot of support to people and especially for having converted many many mods to the new format in the big rush in the first hours and days after initial release.
To ss4_link for taking the time to get it working under Mac OS and providing a simple first tutorial for mac users.
To metjm who helped a lot in testing the Mac version, thanks to whom it should not stand back from the Windows and Linux versions.
To Cbrad24 for cleaning up this post.

And to everyone else helping me making this a viable alternative to the s2z mod jungle!
__________________________________________________

Any feedback is welcome!